flake-verbs

flake 구조를 다루는 동사(verb) 모음으로, 타입이 있는 verbspec 스펙으로 한 번 작성해 두면 CLI, MCP, Anthropic tool-use, OpenAPI로 적용된다.

이 도구가 답하는 질문은 두 가지이며, 둘 다 원래는 flake를 손으로 읽어야 패턴을 알 수 있는 것들이었다.

실행

bun install
bun run src/cli.ts inputs ~/.config/home-manager
bun run src/cli.ts input-drift ~/.config/home-manager --problemsOnly
bun run src/cli.ts --mcp-tools          # the agent-facing surface, derived

두 명령 모두 flake 루트를 위치 인자(기본 .)로 받아 JSON을 출력한다. CLI는 텍스트 뷰를 렌더링하고, 그 외 모든 인터페이스는 output을 소비한다.

Related MCP server: code-review-mcp-server

inputs — 사용과 언급

가장 단순한 버전은 grep <input-name> *.nix이며, 그 결과로는 모든 input이 사용된다고 보고된다. 하지만 input을 의존하지 않고 언급만 하는 경우는 세 가지가 있다.

• outputs = { a, b, … }: 매개변수 목록 — 모든 input의 이름을 나열한다.

• 주석

• 경로 및 문자열 리터럴 — ./programs/lnzr.nix, "lnzr/.keep"

문자열 **보간(interpolation)**은 그 예외이며 필터를 통과해 살아남아야 한다. "${dx-compose}/path/to/module"은 실제로 참조하기 때문이다. 이 짝짝이 비대칭 때문에 이것은 grep으로는 불가능하다.

스캔은 또한 _module.args 별칭을 추적한다. synoptic = config._module.args.synoptic-github을 바인딩하는 flake는 입력을 전혀 다른 특성, 즉 그와 다른 단어로 사용하는 셈이다. 이 경우를 놓치면 실제로 살아 있는 input이 정리된다.

세 가지 판정

referenced와 unused는 그 이름 그대로 뜻이다. module-import-only는 SO special called "unused" rather than this one. 왜냐하면 Home Manager 모듈을 가져온다는 것은 실제로 역할을 하고(모듈이 config 스스로 설정) 또는 실 종적(모든 것이 default false이고 그것을 켜주는 것이 nothing)일 수 있는 경우 이기 때문인데, 그래서 "unused"라는 이름을 붙이지 않았다.

With --deep (default on) the verb settles the case where it can: it resolves the input to its store path via nix flake archive, reads the imported module, reads the option namespace it declares, and checks whether anything in the consuming flake sets it. That turns a shrug into a fact:

DEAD dx-compose          github:bdelanghe/dx-compose
     imports a module declaring programs.devcontainers-cli, which nothing in this flake sets

Where it can't resolve it remains module-import-only rather than guessing. The false unused error is expensive — it deletes a working input — so every step degrades toward "a human should look".

Wait, I need to finish translation.

Let me restart transition from there. Actually the above output is a mix after "module-import-only..." Let's ensure full translation.

I will now produce a complete final answer, ensuring all text translated, no accidental English "input" maybe not.

Let's write final another time# flake-verbs

flake 구조를 다루는 동사(verb) 모음으로, 타입이 지정된 verbspec 스펙으로 한 번 작성하면 CLI, MCP, Anthropic tool-use, OpenAPI로 투영된다.

이 도구가 답하는 질문은 두 가지이며, 둘 다 원래는 flake를 손으로 읽어야 알 수 있는 것들이다.

실행

bun install
bun run src/cli.ts inputs ~/.config/home-manager
bun run src/cli.ts input-drift ~/.config/home-manager --problemsOnly
bun run src/cli.ts --mcp-tools          # the agent-facing surface, derived

두 동사 모두 flake 루트를 위치 인자(기본 .)로 받아 JSON을 출력한다. CLI는 텍스트 뷰로 렌더링하고, 그 외 모든 인터페이스는 output을 소비한다.

inputs — 사용과 언급

네이브하게 접근하는 방식은 grep <input-name> *.nix이며, 그 경우 모든 입력이 사용된다고 나온다. 입력을 언급만 하고 의존하지 않는 경우는 세 가지다.

• outputs = { a, b, … }: 매개변수 목록 — 모든 입력의 이름을 나열한다.

• 주석

• 경로 및 문자열 리터럴 — ./programs/lnzr.nix, "lnzr/.keep"

문자열 **보간(interpolations)**은 예외이며 필터에서 살려내야 한다. "${prod…}" 진짜 참조이기 때문입니다. 이 비대칭 때문에 이것은 grep으로 해결될 수 없다.

스캔은 _module.args 별칭도 추적한다. syntactic synoptic-flakes에서 synoptic = config._module.args.synoptic-github을 바인딩하는 flake는 입력을 다른 단어로 완전히 사용한다. 이 때를 놓치면 살아 있는 입력이 삭제되는 것이다.

세 가지 판정

referenced와 unused는 그 자체가 뜻하는 대로다. module-import-only는 이 목록에서 흥미로운 것인데, 일부러 "unused"라 부르지 않는다: Home Manager 모듈을 가져오는 것은 실제로 존재 이유가 있을 수 있고(모듈이 config를 스스로 설정함) 또 완전히 무의미할 수도 있다(모든 옵션이 기본적으로 false이고 아무것도 활성화하지 않음).

--deep가 기본으로 켜져 있으면 판정할 수 있는 경우를 처리한다: 즉 입력을 nix flake archive로 스토어 경로로, resolve한 후 그 가져온 모듈을 읽고, 그 모듈이 선언하는 옵션 namespace를 확인하고, 소비하는 flake에서 무언가가 그것들을 설정하는지 확인한다. 그렇게 해서 불확실한 어깨를 사실로 바꾼다:

DEAD dx-compose          github:bdelanghe/dx-compose
     imports a module declaring programs.devcontainers-cli, which nothing in this flake sets

namespace를 확인할 수 없는 경우에는 추측하지 않고 module-import-only로 잡는다. 잘못된 unused 판정은 비용이 크며 - 실제로 동작하는 입력을 삭제하는 것 - 그래서 모든 단계는 "사람이 확인해야 한다" 쪽으로 안전하게 넘어간다.

input-drift — 값어치가 있는 명령

behind는 일상적인 상태이며 실패는 아니다. 별구가 여기 중요한 상태 두 가지는:

• unportable — path: 입력이 그 경우. Nix는 툴 평가 시점에 path 입력을 디시에서 다시 읽으므로, authoring machine에만 존재하는 디렉터리를 가리키는 lock은 다른 곳에서 flake를 평가 불가능하게 만든다. 이것은 두 번째 machine에서 빌드를 시도하기 전까지 완전히 보이지 않는 bootstrap dead-end이다.

• orphaned — locked된 revision에 remote기본 브랜치에 없는 commit이 포함되어 있거나, remote가 그 revision을 모른다는 뜻이다. 그 commit은 local checkout에만 존재한다: push되지 않은 일이며, machine rebuild시 조용히 사라진다.

이 두 상태는 경계 exit 코드를 반환하므로 CI를 차단한다. behind는 그렇지 않다.

업스트림 쿼리는 gh api를 통하므로, 이 도구가 토큰을 직접 다루지 않고도 private 입력을 resolve할 수 있다.

만들게 된 이유

실제 데이터 손실이 있은 뒤에 만들어졌다. home-manager flake 하나가 ~/.local 아래를 가리키는 네 개의 path: 입력을 갖고 있었다. 그리고 두 번째 device에서 그 flake는 아예 평가조차 되지 않았다. 입력들을 GitHub로 다시 가리켰을 때 그중 하나인 lnzr는 원격 main보다 세 달 앞선 로컬 checkout을 갖고 있었다. 그건 다른 곳에는 없는 그 책와 함께 사라질 수 밖에 없었다.

lock에는 그 사실 두 가지가 처음부터 기록되어 있었다. 그 기록을 질의할 수 있는 방법이 없었을 뿐이다.

알아 두면 좋은 한계

• 참조 검사는 텍스트 기반이지, evaluated와 같지다 아니. .nix 소스를 읽기는 하지만 flake를 직접 평가하지는 않으므로, 생성되거나 동적으로 구성된 attribute path를 통해서만 접근가능한 입력은 여전히 놓칠 수 있다.

• --deep는 cfg = config.<ns>와 options.<ns> 관용구를 인식한다. 다른 방식으로 작성된 모듈은 module-import-only로 폴백한다.

• input-drift는 github: 입력만 해당 upstream과 비교한다. git:과 tarball: 입력은 잘못된 대답하는 대신 unknown으로 보고한다.

• 본 직접(direct) 입력될 수 있다. 전이(transitive) 입력은 누군가 별도의 선택이므로 해당 repo에서 감사할 일이다.