Tianyi Cui
4dafad4db6
Eight proposals grouped by category, each with problem statement, concrete plan, and risks: property-based testing over the protocol-shaped core (chunk streams, event logs, schema DSL); mutation testing as the counterweight to the 100%-coverage gate; deterministic tests + a universal replay-invariant fixture + nightly race stress; architectural conformance (dependency-cruiser rules and the LlmAdapter conformance kit); runtime arg validation at the model boundary with a structured error taxonomy and dev-mode invariants; doc-sync enforcement (typechecked doc snippets, API reports); supply-chain checks and nightly vendor-drift verification against the manifest; and deep-readonly public surfaces (logged-vs-in-flight mutability boundary). AGENTS.md points at docs/adr and docs/rfc.
40 lines
1.7 KiB
Markdown
40 lines
1.7 KiB
Markdown
# RFC 006: Doc-sync enforcement and API reports
|
|
|
|
Status: proposed
|
|
|
|
## Problem
|
|
|
|
AGENTS.md policy says docs and code must stay strictly in sync, but sync is
|
|
verified by eyeball. Review has already caught drift twice (a cookbook
|
|
example contradicting the type policy; a README citing the wrong
|
|
registerAdapter call). Public API changes are similarly invisible — nothing
|
|
makes "this commit changed the public surface" an explicit, reviewable fact.
|
|
|
|
## Proposal
|
|
|
|
1. **Typecheck documentation code blocks.** A script extracts fenced ```ts
|
|
blocks from README.md / docs/architecture.md / packages/*/README.md into a
|
|
temp project resolving workspace packages, and runs tsc. Blocks that are
|
|
intentionally elided get an explicit `ts ignore-check` info string —
|
|
opt-out is visible in the source. (twoslash is the fancier alternative;
|
|
start with plain extraction.)
|
|
2. **Generate or verify the event-taxonomy table.** The table in
|
|
docs/architecture.md duplicates the `Events` declarations. Either generate
|
|
it from source (ts-morph walk over the `declare module 'cordis'` blocks)
|
|
or CI-assert that every declared event name appears in the table and vice
|
|
versa.
|
|
3. **API reports.** api-extractor (or `tsc --emitDeclarationOnly` + a
|
|
normalized public-surface dump) producing a checked-in `etc/<pkg>.api.md`
|
|
per package; CI fails if regeneration differs. Every public-API change
|
|
becomes a diff line a reviewer (or review agent) must see.
|
|
|
|
## Plan
|
|
|
|
1 is a standalone script + CI step. 3 next (it also documents the surface for
|
|
plugin authors). 2 last — verify-don't-generate is likely sufficient.
|
|
|
|
## Risks
|
|
|
|
Doc blocks often show fragments; the ignore-check escape hatch must stay rare
|
|
or the gate is theater — lint the ratio if needed.
|