0 Fork 0

Files

T

Tianyi Cui 4dafad4db6 Add RFCs for the remaining quality-proposal ideas

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.

2026-06-11 15:27:07 +08:00

1.7 KiB

Raw Blame History

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

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.)
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.
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.

1.7 KiB Raw Blame History