docs(skills): add nix let review rule
This commit is contained in:
@@ -13,9 +13,19 @@ Do not report preferences unless a loaded rule states them.
|
||||
Use this format for each finding:
|
||||
|
||||
```text
|
||||
`path:line`: Finding title.
|
||||
`code-path:line`
|
||||
> `smallest reviewed-code excerpt that shows the violation`
|
||||
|
||||
`rule-file:line`: Finding title.
|
||||
Summary: why the code breaks the rule
|
||||
Fix: suggested fix
|
||||
```
|
||||
|
||||
Keep the code excerpt to one to three lines when possible.
|
||||
Use a longer excerpt only when the violation needs surrounding context.
|
||||
Use `...` to omit unrelated lines from a multi-line excerpt.
|
||||
Use a skill-relative rule citation, such as `let.md:7`.
|
||||
Make the fix direct.
|
||||
Do not include alternatives when one fix best follows the cited rule.
|
||||
|
||||
It is acceptable to report no findings when the reviewed Nix already follows the loaded rules.
|
||||
|
||||
203
docs/TODO.md
203
docs/TODO.md
@@ -103,120 +103,89 @@
|
||||
- centralize shared system group names, starting with the `storage` group
|
||||
|
||||
## nix refactor
|
||||
```text
|
||||
nixos
|
||||
├── guests
|
||||
│ ├── actualbudget.nix
|
||||
│ ├── copyparty.nix
|
||||
│ ├── reverse-proxy.nix
|
||||
│ └── valheim.nix
|
||||
├── hosts
|
||||
│ ├── neogaia
|
||||
│ │ ├── default.nix
|
||||
│ │ ├── disk.nix
|
||||
│ │ ├── hardware-configuration.nix
|
||||
│ │ ├── ssh_host_ed25519_key.pub
|
||||
│ │ └── ssh_host_rsa_key.pub
|
||||
│ ├── pikachu
|
||||
│ │ ├── default.nix
|
||||
│ │ ├── disk.nix
|
||||
│ │ ├── hardware-configuration.nix
|
||||
│ │ ├── ssh_host_ed25519_key.pub
|
||||
│ │ └── ssh_host_rsa_key.pub
|
||||
│ └── zeus
|
||||
│ ├── default.nix
|
||||
│ ├── disk.nix
|
||||
│ ├── hardware-configuration.nix
|
||||
│ ├── ssh_host_ed25519_key.pub
|
||||
│ └── ssh_host_rsa_key.pub
|
||||
├── modules
|
||||
│ ├── desktop
|
||||
│ │ ├── apps
|
||||
│ │ │ ├── alacritty.nix
|
||||
│ │ │ ├── firefox.nix
|
||||
│ │ │ ├── ghostty.nix
|
||||
│ │ │ ├── obsidian.nix
|
||||
│ │ │ ├── signal.nix
|
||||
│ │ │ ├── steam.nix
|
||||
│ │ │ └── vencord.nix
|
||||
│ │ ├── session
|
||||
│ │ │ ├── hyprland
|
||||
│ │ │ │ ├── default.nix
|
||||
│ │ │ │ ├── hypridle.nix
|
||||
│ │ │ │ └── hyprlock.nix
|
||||
│ │ │ ├── login.nix
|
||||
│ │ │ ├── mako.nix
|
||||
│ │ │ ├── portals.nix
|
||||
│ │ │ ├── rofi.nix
|
||||
│ │ │ └── waybar.nix
|
||||
│ │ ├── utilities
|
||||
│ │ │ ├── audio.nix
|
||||
│ │ │ ├── clipboard.nix
|
||||
│ │ │ ├── osd.nix
|
||||
│ │ │ ├── recording.nix
|
||||
│ │ │ ├── screenshot.nix
|
||||
│ │ │ ├── theming.nix
|
||||
│ │ │ └── userdirs.nix
|
||||
│ │ └── default.nix
|
||||
│ ├── network
|
||||
│ │ ├── ssh.nix
|
||||
│ │ ├── vlans.nix
|
||||
│ │ └── vpn-client.nix
|
||||
│ ├── services
|
||||
│ │ ├── games
|
||||
│ │ │ └── valheim.nix
|
||||
│ │ ├── actualbudget.nix
|
||||
│ │ ├── copyparty.nix
|
||||
│ │ ├── reverse-proxy.nix
|
||||
│ │ └── steamcmd.nix
|
||||
│ ├── shell
|
||||
│ │ ├── direnv
|
||||
│ │ │ ├── default.nix
|
||||
│ │ │ └── repo-flake.sh
|
||||
│ │ ├── fish
|
||||
│ │ │ ├── completions
|
||||
│ │ │ │ └── bazel.fish
|
||||
│ │ │ ├── functions
|
||||
│ │ │ │ ├── copy.fish
|
||||
│ │ │ │ └── deploy-to.fish
|
||||
│ │ │ ├── config.fish
|
||||
│ │ │ └── default.nix
|
||||
│ │ ├── nvim
|
||||
│ │ │ ├── config.lua
|
||||
│ │ │ └── default.nix
|
||||
│ │ ├── pi
|
||||
│ │ │ ├── patches
|
||||
│ │ │ │ ├── pi-flex-spacer.patch
|
||||
│ │ │ │ ├── pi-project-resource-ancestors.patch
|
||||
│ │ │ │ └── pi-tool-lookup-validation.patch
|
||||
│ │ │ └── default.nix
|
||||
│ │ ├── tmux
|
||||
│ │ │ ├── default.nix
|
||||
│ │ │ └── extra.conf
|
||||
│ │ ├── bazel.nix
|
||||
│ │ ├── git.nix
|
||||
│ │ ├── gitea-axi.nix
|
||||
│ │ ├── herdr.nix
|
||||
│ │ ├── python.nix
|
||||
│ │ ├── rust.nix
|
||||
│ │ └── yazi.nix
|
||||
│ ├── default.nix
|
||||
│ ├── guest.nix
|
||||
│ ├── host.nix
|
||||
│ ├── monorepo.nix
|
||||
│ └── zfs.nix
|
||||
├── registry
|
||||
│ ├── address.nix
|
||||
│ ├── env-var.nix
|
||||
│ ├── route.nix
|
||||
│ ├── shell-shortcut.nix
|
||||
│ └── stable-uid.nix
|
||||
├── secrets
|
||||
│ ├── neogaia.yaml
|
||||
│ ├── pikachu.yaml
|
||||
│ ├── shared.yaml
|
||||
│ └── zeus.yaml
|
||||
├── .sops.yaml
|
||||
├── AGENTS.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Review Nix files in entrypoint order:
|
||||
|
||||
- [x] `flake.nix`
|
||||
- [ ] `src/dotfiles/default.nix`
|
||||
- [ ] `src/dotfiles/util.nix`
|
||||
- [ ] `src/dotfiles/formatter.nix`
|
||||
- [ ] `src/dotfiles/apps.nix`
|
||||
- [ ] `src/dotfiles/registry.nix`
|
||||
- [ ] `configs/nixos/registry/address.nix`
|
||||
- [ ] `configs/nixos/registry/env-var.nix`
|
||||
- [ ] `configs/nixos/registry/homepage.nix`
|
||||
- [ ] `configs/nixos/registry/route.nix`
|
||||
- [ ] `configs/nixos/registry/shell-shortcut.nix`
|
||||
- [ ] `configs/nixos/registry/stable-uid.nix`
|
||||
- [ ] `src/dotfiles/modules.nix`
|
||||
- [ ] `configs/nixos/modules/default.nix`
|
||||
- [ ] `configs/nixos/modules/host.nix`
|
||||
- [ ] `configs/nixos/modules/guest.nix`
|
||||
- [ ] `configs/nixos/modules/monorepo.nix`
|
||||
- [ ] `configs/nixos/modules/zfs.nix`
|
||||
- [ ] `configs/nixos/modules/network/ssh.nix`
|
||||
- [ ] `configs/nixos/modules/network/vlans.nix`
|
||||
- [ ] `configs/nixos/modules/network/vpn-client.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/default.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/alacritty.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/firefox.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/ghostty.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/obsidian.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/signal.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/steam.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/apps/vencord.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/hyprland/default.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/hyprland/hypridle.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/hyprland/hyprlock.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/login.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/mako.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/portals.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/rofi.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/session/waybar.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/audio.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/clipboard.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/osd.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/recording.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/screenshot.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/theming.nix`
|
||||
- [ ] `configs/nixos/modules/desktop/utilities/userdirs.nix`
|
||||
- [ ] `configs/nixos/modules/services/actualbudget.nix`
|
||||
- [ ] `configs/nixos/modules/services/copyparty.nix`
|
||||
- [ ] `configs/nixos/modules/services/homepage.nix`
|
||||
- [ ] `configs/nixos/modules/services/navidrome.nix`
|
||||
- [ ] `configs/nixos/modules/services/reverse-proxy.nix`
|
||||
- [ ] `configs/nixos/modules/services/steamcmd.nix`
|
||||
- [ ] `configs/nixos/modules/services/games/palworld.nix`
|
||||
- [ ] `configs/nixos/modules/services/games/valheim.nix`
|
||||
- [ ] `configs/nixos/modules/shell/bazel.nix`
|
||||
- [ ] `configs/nixos/modules/shell/direnv/default.nix`
|
||||
- [ ] `configs/nixos/modules/shell/fish/default.nix`
|
||||
- [ ] `configs/nixos/modules/shell/gitea-axi.nix`
|
||||
- [ ] `configs/nixos/modules/shell/git.nix`
|
||||
- [ ] `configs/nixos/modules/shell/herdr.nix`
|
||||
- [ ] `configs/nixos/modules/shell/nvim/default.nix`
|
||||
- [ ] `configs/nixos/modules/shell/omp.nix`
|
||||
- [ ] `configs/nixos/modules/shell/pi/default.nix`
|
||||
- [ ] `configs/nixos/modules/shell/python.nix`
|
||||
- [ ] `configs/nixos/modules/shell/rust.nix`
|
||||
- [ ] `configs/nixos/modules/shell/tmux/default.nix`
|
||||
- [ ] `configs/nixos/modules/shell/yazi.nix`
|
||||
- [ ] `src/dotfiles/guests.nix`
|
||||
- [ ] `configs/nixos/guests/actualbudget.nix`
|
||||
- [ ] `configs/nixos/guests/copyparty.nix`
|
||||
- [ ] `configs/nixos/guests/homepage.nix`
|
||||
- [ ] `configs/nixos/guests/navidrome.nix`
|
||||
- [ ] `configs/nixos/guests/palworld.nix`
|
||||
- [ ] `configs/nixos/guests/reverse-proxy.nix`
|
||||
- [ ] `configs/nixos/guests/valheim.nix`
|
||||
- [ ] `src/dotfiles/hosts.nix`
|
||||
- [ ] `configs/nixos/hosts/neogaia/default.nix`
|
||||
- [ ] `configs/nixos/hosts/neogaia/disk.nix`
|
||||
- [ ] `configs/nixos/hosts/neogaia/hardware-configuration.nix`
|
||||
- [ ] `configs/nixos/hosts/pikachu/default.nix`
|
||||
- [ ] `configs/nixos/hosts/pikachu/disk.nix`
|
||||
- [ ] `configs/nixos/hosts/pikachu/hardware-configuration.nix`
|
||||
- [ ] `configs/nixos/hosts/zeus/default.nix`
|
||||
- [ ] `configs/nixos/hosts/zeus/disk.nix`
|
||||
- [ ] `configs/nixos/hosts/zeus/hardware-configuration.nix`
|
||||
|
||||
58
src/skills/nix-style/rules/let.md
Normal file
58
src/skills/nix-style/rules/let.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Let rules
|
||||
|
||||
## Prefer explicit dependencies over shared convenience bindings
|
||||
|
||||
### Rule
|
||||
|
||||
Do not add a `let` binding only to let sibling values share one expression.
|
||||
When one sibling value owns the concept, reference that sibling value directly.
|
||||
When a flake output owns the public value, reference that output through `self`.
|
||||
Do not make an output attrset recursive only to reference sibling outputs.
|
||||
Use a `let` binding when it names an internal concept or avoids repeated complex code.
|
||||
|
||||
### Rationale
|
||||
|
||||
Shared convenience bindings hide dependency direction.
|
||||
Explicit references show which value owns a concept and which value consumes it.
|
||||
Minimizing `let` bindings keeps wiring code direct.
|
||||
|
||||
### Examples
|
||||
|
||||
Prefer:
|
||||
|
||||
```nix
|
||||
formatter.${system} = (import ./formatter.nix {
|
||||
inherit inputs system;
|
||||
}).config.build.wrapper;
|
||||
|
||||
apps.${system} = import ./apps.nix {
|
||||
inherit
|
||||
inputs
|
||||
lib
|
||||
system
|
||||
;
|
||||
formatter = self.formatter.${system};
|
||||
};
|
||||
```
|
||||
|
||||
Avoid:
|
||||
|
||||
```nix
|
||||
let
|
||||
formatter = import ./formatter.nix {
|
||||
inherit inputs system;
|
||||
};
|
||||
in
|
||||
{
|
||||
formatter.${system} = formatter.config.build.wrapper;
|
||||
|
||||
apps.${system} = import ./apps.nix {
|
||||
inherit
|
||||
inputs
|
||||
lib
|
||||
formatter
|
||||
system
|
||||
;
|
||||
};
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user