Docs / Reference / Architecture

Architecture

kedgeway is hexagonal: the rules are pure, and everything that touches the outside world sits behind a port.

Layer	Files	Role
core	`src/core/diagnose.ts`, `src/core/repo-facts.ts`	Pure functions. `repo-facts` parses manifests and versions; `diagnose` turns facts and a snapshot into findings. No I/O.
ports	`src/ports/ecosystem.ts`	`EcosystemPort`: one method, `fetchSnapshot()`, returning an ecosystem snapshot.
adapters	`src/adapters/`	`fs-repo-scanner` walks the repo. `raven-ecosystem`, `raven-auth` and `raven-parse` are the Raven MCP client, OAuth and result parser. `fake-ecosystem` loads fixtures.
cli	`src/cli.ts`, `src/cli/commands.ts`	Commands, flags, report formatting and exit codes. Wires adapters to the core.

Flow of one run

The scanner produces repo facts: Rust and JavaScript dependencies plus manifest errors.
An EcosystemPort (Raven, or the fake from a fixture) produces a snapshot.
diagnose(facts, snapshot) returns findings and a summary.
The CLI prints them and computes the exit code.

Tests sit next to the code as *.test.ts and run with Vitest (npm test). Development is test-first: write the failing test, then the rule.

Write a failing test in src/core/diagnose.test.ts with the facts and snapshot that should trigger it.
Add the logic to src/core/diagnose.ts, returning a finding with a severity, code, message, file and evidence that cites the snapshot source.
If the rule needs a new input, extend the parser in src/core/repo-facts.ts first, with tests.
Document the code on the Findings page.