Generadores de la documentación

Especificado. Los generadores existen y bun run docs:check corre, pero track/docs sigue queued hasta el lock de dec-0124: por la tabla de estados de su §5.1 esta página no sube a implementado antes. Lo que dice obliga a la implementación.

Toda la sección Referencia se genera. Nadie la edita a mano: el esfuerzo va a la fuente (TSDoc, ///, descripciones de contratos y del esquema de configuración), que además mejora el código.

PrincipioCopiar enlace

Todo lo que se puede generar, se genera. Un generador por fuente, y ninguno inventa contenido: proyecta una fuente canónica. La referencia que sale de ahí se versiona (se lee en GitHub sin construir nada) y una comprobación detecta si se ha desviado de su fuente.

bun run docs:gen      # escribe la referencia generada
bun run docs:check    # regenera en memoria y falla si algo difiere o sobra

Qué se genera de quéCopiar enlace

Los scripts viven en scripts/docs/; el extractor de Zig está en native/zig/tools/.

Cómo se garantiza que no hay driftCopiar enlace

• Salida determinista: claves ordenadas, sin fechas, sin rutas absolutas, final de línea fijo. Dos ejecuciones dan los mismos bytes.
• Comparación byte a byte: docs:check no usa una heurística, regenera y compara. Un fichero que falta, difiere o sobra en un directorio que el generador posee es drift.
• inputHash: cada página generada declara en su frontmatter el hash de su entrada. Ese hash no sirve para detectar drift sin ejecutar el generador cuando la entrada es derivada: en gen-roadmap-adrs.ts se calcula sobre la proyección que el propio generador hace del model y de las páginas que citan cada nodo o ADR, no sobre los bytes de un fichero fuente, así que recalcularlo exige ejecutar casi todo el generador. Sirve para ver en un diff qué páginas cambiaron de entrada; la detección de drift es la regeneración completa (scripts/docs/gen-roadmap-adrs.ts --check), que corre en CI dentro de bun run check:roadmap. Un generador nuevo sólo puede ofrecer detección por hash sin regenerar si su hash se recalcula desde los bytes de la fuente, y lo declara.
• Los generadores validan su fuente: una ruta sin esquema de respuesta, un export público sin TSDoc, un pub de Zig sin ///, un protocolo sin schemaVersion o sin política de compatibilidad es una violación del propio generador, no un hueco silencioso.
• Trinquetes: donde ya existe deuda (por ejemplo, exports públicos sin TSDoc) vive en un baseline por generador; ver Trinquetes.

Las vistas de roadmap y decisionesCopiar enlace

gen-roadmap-adrs.ts proyecta styx.model.yml y docs/decisions/ en el sitio:

• una página por nodo de primer nivel, con sus hitos, los items de su gate con su veredicto tal cual, la cola de tickets y qué páginas de la documentación lo citan;
• una página por decisión, con su estado, sus enmiendas y qué páginas y nodos la citan.

No hay contadores agregados ni se copia prosa de docs/decisions/README.md. Las propias páginas generadas citan track/docs y no el nodo o la decisión que describen, para que su existencia no cuente como cobertura de nadie: la cobertura la dan las páginas escritas a mano, que es justo lo que esas vistas hacen visible.

Los dos comandosCopiar enlace

• bun run docs:gen regenera todo y escribe.
• bun run docs:check regenera en memoria y falla (exit 1) si un fichero difiere, falta o sobra, o si algún generador encuentra una violación. Es el mismo patrón que gen:bus / check:bus.
• bun scripts/docs/gen-all.ts --only openapi,bus [--check] limita a unos generadores.

Qué genera cada unoCopiar enlace

TrinquetesCopiar enlace

Un trinquete es un fichero scripts/docs/*.baseline.json con la deuda conocida. Una violación que no está en el baseline es rojo, y una entrada que ya no se da también lo es (hay que borrarla, para que no vuelva a entrar en silencio). Se documenta la fuente y se borra la línea en el mismo cambio.

No es un bloqueo contra la deuda nueva. docs:check compara lo encontrado con el baseline tal como está en el árbol, no con el de la rama base: si el mismo cambio añade la violación y su entrada en el baseline, sale verde. Añadir deuda es un acto visible en el diff del baseline (como el de check-gates o check-consumer), y quien revisa el cambio es quien lo frena.

Estado de las páginas generadasCopiar enlace

Cada página lleva el frontmatter de contrato de dec-0124 §5 con generated: { source, generator, inputHash }. Su status sale del model: implementado si algún nodo citado está in_progress o done, si no especificado. Una página generada nunca es verificado por sí misma.

Añadir un generadorCopiar enlace

1. Define la fuente canónica y por qué es la única.
2. Escribe una función pura sobre esa fuente que devuelva los ficheros, los directorios que posee y sus violaciones. El cargador de disco va aparte para poder probarla sin infraestructura.
3. Emite el frontmatter de contrato con generated: { source, generator, inputHash }. Su estado se hereda del nodo dueño de la fuente y nunca pasa de implementado por sí mismo.
4. Regístralo en el orquestador de docs:gen y docs:check.
5. Escribe los mutantes: cambiar la fuente sin regenerar debe dar rojo, y un fichero de más también.
6. Si la referencia es de una interfaz, la página escrita a mano que la explica enlaza la referencia en lugar de repetirla.