flake-verbs

Verbos de estructura de flake, definidos una sola vez como especificaciones tipadas de verbspec y proyectados a CLI, MCP, uso de herramientas de Anthropic y OpenAPI.

Responde a dos preguntas que antes obligaban a leer un flake a mano:

Ejecución

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

Ambos verbos aceptan la raíz del flake como argumento posicional (por defecto .) y emiten JSON; la CLI muestra una vista de texto, cualquier otra superficie consume output.

Related MCP server: code-review-mcp-server

inputs — uso frente a mención

La versión ingenua de esto es grep <input-name> *.nix, y daría como resultado que todas las entradas se usan. Hay tres cosas que mencionan una entrada sin depender de ella:

• la lista de parámetros outputs = { a, b, … }:, que nombra cada entrada

• los comentarios

• los literales de ruta y de cadena — ./programs/lnzfr.nix, "lnzfr/.keep"

Las interpolaciones de cadenas son la excepción y deben sobrevivir al filtro, porque "${dx-compose}/path/door/módulo" es una referencia real. Esa asimetría es por la que esto no puede ser un grep.

El escaneo también sigue los alias de _module.args. Un flake que enlaza synoptic = config._module.args.synoptic-github usa la entrada bajo una palabra completamente distinta; pasar esto por alto es como una entrada activa acaba siendo podada.

Los tres veredictos

referenced y unused significan exactamente eso. module-import-only es el interesante, y deliberadamente no se llama «unused»: importar un módulo de Home Manager puede ser completamente determinante (el propio módulo define la configuración) o un no-op total (todas las opciones tienen por defecto false y nada las activa).

Con --deep (activado por defecto), el verbo resuelve el caso si puede: resuelve la entrada a su ruta en el store mediante nix flake archive, lee el módulo importado, recupera el espacio de nombres que declara y comprueba si algo en el flake que lo consume lo establece. Para saberlo, es un hecho:

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

Cuando no puede resolver el espacio de nombres, se queda en module-import-only en lugar de adivinarlo. Un unused falso es el error caro — elimina una entrada que funciona —, por lo que cada paso se degrada hacia «que lo mire un humano».

input-drift — el que se paga solo

behind es normal y no un fallo. Los estados que sí lo son:

• unportable — una entrada path:. Nix vuelve a leer las entradas de ruta desde el disco en tiempo de evaluación, así que un lock que apunta a un directorio que solo existe en la máquina que lo generó hace que el flake no se pueda evaluar en ningún otro sitio. Es el callejón sin salida que queda invisible hasta que intentas compilar en una segunda máquina.

• orphaned — la revisión bloqueada contiene commits que no están en la rama principal del remoto, o el remoto no la conoce. El commit solo existe en un checkout local: trabajo no entregado que el rebuild de una máquina descarta en silencio.

Ambos terminan con código distinto de cero, así que bloquean CI. behind no.

Las consultas ascendentas hacen mediante gh api, así que las entradas privadas se resuelven sin que esto maneje nunca un token.

Por qué existe

Escrito|or after un pérdida real. Una flake home-manager con cuatro entradas path: situadas bajo ~/.local; en una máquina nueva no se podía evaluar. Al repuntarlas a GitHub se descubrió que uno, lnzr, tenía un check local tres meses por delante de lo remoto — trabajo que no existía en ningún otro lugar y que se fue con el disco.

El lock había registrado los dos hechos durante todo el tiempo. Nada podía preguntárselo.

Limitaciones que conviene conocer

• El escaneo de referencias es textual, no una evaluación. Lee fuentes .nix; no evalúa el flake, por lo que una entrada alcanzada solo a través de rutas de atributo generadas o construidas dinámicamente puede seguir siendoatada perdida.

• --deep reconoce los idioms cfg = config.<ns> y options.<ns>. Un módulo escrito de otra manera cierra en module-import-only.

• input-drift solo compara las entradas github: con su upstream. Las entradas git: y tarball: devuelven unknown en lugar de una respuesta de error.

• Solo se examinan las entradas directas. Una entrada transitiva es una elección ajena; se audita en su propio repositorio.