v0.4.0 — generated architecture documentation

Sonde can now generate the architecture documentation for the repository it indexes.

npm install -g @cheppulabs/sonde
cd your-project
sonde init      # or `sonde init --resolve` for Python
sonde doc

That writes an ARCHITECTURE.md describing your modules, how they depend on each other, and what each one exposes — derived from the graph, so it reports what the code does rather than what someone remembered. Sonde's own is committed in this repository.

What makes it different from other doc generators

It reports its own staleness. The header names the commit it describes and warns when files have changed since. Generated documentation usually fails one way — it is a snapshot, the code moves, and a stale document is worse than none because people trust it. Sonde already tracks drift, so the document can say when it has gone out of date.

It regenerates byte-identically. The stamp is a commit SHA, never a timestamp, so an unchanged repository produces an unchanged file. That is what stops a generated file from churning every diff until someone gitignores it. sonde doc --check fails a CI build when the committed document no longer matches the code.

It refuses to assert a dependency it cannot evidence. This is the part worth reading about.

The bug this release is really about

The first generated document put src/adapters/swift → src/adapters/typescript as the second-heaviest dependency in the entire codebase, backed by 62 references.

Those modules do not import each other at all.

They share the filenames symbols.ts, parser.ts and references.ts, so they share function names, and heuristic name-matching manufactured 62 references out of coincidence. The design document had argued that "fifty heuristic edges is strong evidence of coupling." It is not: modules with parallel structure produce the most name-match noise, not the least, so ranking by volume puts the most spurious relationships at the top.

Dependencies now rank by resolved references, and a module pair with no resolved reference between them is not drawn at all — it is counted and disclosed instead. The same fix cleaned up module surfaces, which had been listing add, value, child and node as public API.

Honest limitations

• The diagram is a summary, not the whole graph. It draws the heaviest dependencies and states how many it omitted. A diagram containing every dependency is unreadable and therefore shows nothing — this repository's complete graph is 615 arrows.
• Nothing exhaustive is committed. Dependency tables and module surfaces are capped with disclosure; sonde doc --module <path> has the complete data.
• Test modules are excluded by default. --include-tests opts them back in.
• It took three attempts. The first two generated documents were rejected at their own readability gate — 1,307 lines, then 363 with fabricated dependencies — before this one. Both rejections are recorded in the design document.

Also in this release

sonde doc --module <path> for symbol-level detail, --stdout, --check, and --include-tests.

---

Full detail in CHANGELOG.md.