Documentación / Referencia / Arquitectura

Arquitectura

kedgeway es hexagonal: las reglas son puras y todo lo que toca el mundo exterior está detrás de un puerto.

Capa	Archivos	Función
core	`src/core/diagnose.ts`, `src/core/repo-facts.ts`	Funciones puras. `repo-facts` analiza manifiestos y versiones; `diagnose` convierte los datos del repo y un snapshot en hallazgos. Sin E/S.
ports	`src/ports/ecosystem.ts`	`EcosystemPort`: un solo método, `fetchSnapshot()`, que devuelve un snapshot del ecosistema.
adapters	`src/adapters/`	`fs-repo-scanner` recorre el repo. `raven-ecosystem`, `raven-auth` y `raven-parse` son el cliente MCP de Raven, el OAuth y el parser de resultados. `fake-ecosystem` carga fixtures.
cli	`src/cli.ts`, `src/cli/commands.ts`	Comandos, flags, formato del reporte y códigos de salida. Conecta los adaptadores con el núcleo.

Flujo de una ejecución

El escáner produce los datos del repo: dependencias de Rust y JavaScript, más los errores de manifiesto.
Un EcosystemPort (Raven, o el falso a partir de un fixture) produce un snapshot.
diagnose(facts, snapshot) devuelve los hallazgos y un resumen.
La CLI los imprime y calcula el código de salida.

Tests

Los tests están junto al código como *.test.ts y se ejecutan con Vitest (npm test). El desarrollo es test-first: primero escribe el test que falla y luego la regla.

Agregar una regla

Escribe un test que falle en src/core/diagnose.test.ts con los datos y el snapshot que deberían activarla.
Agrega la lógica en src/core/diagnose.ts y devuelve un hallazgo con severidad, código, mensaje, archivo y evidencia que cite la fuente del snapshot.
Si la regla necesita un dato nuevo, primero extiende el parser en src/core/repo-facts.ts, con tests.
Documenta el código en la página Hallazgos.