Nix 语言服务器与编辑器工具链：补全、格式化与静态检查

① 动态类型：pkgs.foo 是否存在，只有求值那一刻才知道
② 惰性求值：写错的属性可能永远不被求值，直到某条代码路径被触发
③ 属性集即接口：flake.nix 的 inputs/outputs 是运行时结构，不是静态声明
结果：编辑器默认只提供语法高亮，拼写错误零提示。

但要明确边界：语言服务器不会真的去构建，因此无法发现"选项组合非法"这类语义错误，
补全也可能不完整（惰性语言的可达集合无法完全静态推导）。
正确心智模型：LSP 负责"写的时候少犯错"，nix flake check / nix build 负责"提交前兜底"。

怎么选：默认用 nil（启动快、诊断准，日常编辑 flake 与模块足够）；
        写 NixOS / Home Manager 配置时切到 nixd，为的是选项名与文档补全；
        同一编辑器里不要同时挂两个，否则容易产生重复诊断。

nix run nixpkgs#nil -- --version                     # 临时试用
nix profile install nixpkgs#nil nixpkgs#nixd         # 装进用户 profile

# 更好的做法：把工具链与项目绑定，避免"我这儿能补全"
{
  devShells.default = pkgs.mkShell {
    packages = with pkgs; [ nil nixd nixfmt-rfc-style statix deadnix treefmt ];
  };
}

{
  formatter = pkgs.nixfmt-rfc-style;   # nix fmt 使用它
}

nix fmt                # 按 flake 声明的格式化器格式化全仓库
nix fmt -- --check .   # 只检查不修改（CI 用）

// .nixd.json（放在项目根目录；expr 里的 flake 路径必须是绝对路径）
{
  "nixd": {
    "formatting": { "command": [ "nixfmt" ] },
    "options": {
      "nixos": {
        "expr": "(builtins.getFlake \"/abs/path/to/flake\").nixosConfigurations.myhost.options"
      }
    }
  }
}

-- Neovim 0.11+：用 vim.lsp.config / vim.lsp.enable
vim.lsp.config('nil', {})
vim.lsp.enable('nil')
vim.lsp.config('nixd', { settings = { nixd = { formatting = { command = { 'nixfmt' } } } } })
-- 0.10 及以前用 nvim-lspconfig：require('lspconfig').nil_ls.setup({})

{
  "nix.enableLanguageServer": true,
  "nix.serverPath": "nil",
  "nix.serverSettings": { "nil": { "formatting": { "command": [ "nixfmt" ] } } },
  "nix.formatterPath": "nixfmt",
  "editor.formatOnSave": true
}

# ~/.config/helix/languages.toml
[language-server.nil]
command = "nil"

[[language]]
name = "nix"
language-servers = [ "nil" ]
formatter = { command = "nixfmt" }
auto-format = true

;; Emacs：用 eglot 接入 nil
(add-hook 'nix-mode-hook #'eglot-ensure)
(add-to-list 'eglot-server-programs '(nix-mode . ("nil")))

- 保存即格式化（formatOnSave）配合"格式化器与 CI 一致"才有意义
- 大仓库里把 LSP 的索引范围限制在工作区，避免每次打开都全量扫描
- 改动 flake.lock 后重启语言服务器，否则补全仍基于旧输入

NixOS 的 option 不是语法结构，而是模块系统在求值过程中构建出来的：
每个模块通过 options.xxx = lib.mkOption {...} 注册，
最终的选项集合要等模块合并（merge）完成才知道。
因此补全 option 名，必须先对一个真实的 nixosConfiguration 求值，取出它的 options 属性集。

{
  "nixd": {
    "options": {
      "nixos": {
        "expr": "(builtins.getFlake \"/home/me/infra\").nixosConfigurations.web01.options"
      },
      "home-manager": {
        "expr": "(builtins.getFlake \"/home/me/infra\").homeConfigurations.\"me@laptop\".options"
      }
    }
  }
}

配置要点：
  - 键名（nixos / home-manager）是逻辑分组名，需与编辑器侧约定一致
  - expr 必须能求值成功，flake 路径用绝对路径
  - 只想补全某个子树时，可以把 expr 收窄到子属性（如 .options.services）

开销：首次打开时求值一次，nixpkgs 规模下可能需要数秒；
      flake.lock 更新后需要重新求值。
风险：expr 求值失败时补全会静默失效（表现为"没有补全"）；
      排查方法：在终端里手工执行同一表达式，确认它能否求值。
分工：nil 做语法级补全（局部变量、函数参数、属性访问），快且覆盖日常；
      nixd 做语义级补全（options、pkgs 属性），慢但写配置时价值最大。

切换格式化器会让整仓库产生一次巨大的 diff：
  - 单独一个 commit 做纯格式化，并在 .git-blame-ignore-revs 中登记
  - 之后再改逻辑，避免格式化与逻辑改动混在一起难以 review
  - 向 nixpkgs 提交或 fork nixpkgs 时，直接用 nixfmt-rfc-style 对齐上游
多语言仓库里用 treefmt 统一入口，避免为每种语言记一条命令。

statix check .     # 报告问题（退出码非零表示有发现）
statix fix .       # 自动修复可修复项

常见检出项：
  - 手写 inherit 的等价写法（(a = a;) → inherit a;）
  - with 使用导致的隐式作用域（可读性差、易遮蔽）
  - 冗余的 rec、可简化的条件表达式

deadnix .            # 报告未使用的 let 绑定与函数参数
deadnix --edit .     # 自动删除（建议先 review 差异）

典型检出：let 中定义但从未引用的变量、函数形参中未使用的参数
          （如 { lib, pkgs, ... }: 里未用的 pkgs）。
注意：惰性求值下"未使用"是静态判断，若某绑定通过 with 或动态属性访问被使用，
      可能误报——因此自动修复前必须看 diff。
编辑器内联诊断反馈更快，但规则集可能与命令行不完全一致；
最终以 CI 的退出码为唯一标准最稳妥。

# flake.nix 片段
{
  inputs.treefmt-nix.url = "github:numtide/treefmt-nix";

  outputs = { self, nixpkgs, treefmt-nix, ... }:
    let
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      treefmtEval = treefmt-nix.lib.evalModule pkgs {
        projectRootFile = "flake.nix";
        programs.nixfmt.enable = true;
        programs.statix.enable = true;
        programs.deadnix.enable = true;
      };
    in {
      formatter = treefmtEval.config.build.wrapper;
      checks.formatting = treefmtEval.config.build.check self;
    };
}

关键点：projectRootFile 决定 treefmt 从哪里开始向上找根；
        formatter 输出让 `nix fmt` 走 treefmt；
        checks.formatting 让 `nix flake check` 包含格式检查 → CI 免费获得门禁。

{
  pre-commit-check = pre-commit-hooks.lib.x86_64-linux.run {
    src = ./.;
    hooks = {
      nixfmt-rfc-style.enable = true;
      statix.enable = true;
      deadnix.enable = true;
    };
  };
}

pre-commit install    # 在 devShell 的 shellHook 中执行，安装 git 钩子

nix build .#checks.x86_64-linux.formatting   # 先跑快的格式检查
nix flake check -L                           # 再跑完整检查

注意：`nix flake check` 会求值所有输出，在大型 flake 上较慢；
      因此把格式检查单独抽成一个 check，在流水线里优先执行。

① flake 输入的假报错：语言服务器无法解析 inputs.foo 的真实路径，
   于是把 inputs.foo.bar 标成未定义——属于工具限制，不是代码错误。
② nixd 求值开销：在巨大 flake 上首次打开要数秒，可收窄 options.expr 的范围。
③ 格式化器不一致：本地 alejandra、CI nixfmt，导致"本地过了 CI 不过"；
   解决：把格式化器版本与命令写进 devShell，所有人用同一个。
④ flake.lock 变更后补全过期：重启语言服务器。
⑤ statix 的 with 规则争议：团队若不用 with，可在配置里禁掉该规则。
⑥ deadnix 误删：惰性求值下静态判断可能误报，自动修复前看 diff。

☐ devShell 固定 nil/nixd/nixfmt/statix/deadnix 版本
☐ flake 声明 formatter，`nix fmt` 可用
☐ checks.formatting 接入 treefmt，`nix flake check` 覆盖格式
☐ pre-commit 钩子在本地拦截
☐ CI 先跑快的格式检查，再跑完整 flake check
☐ .git-blame-ignore-revs 登记纯格式化 commit