mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Tianyi Cui 6a528be569 build: doc-sync gates — typecheck doc code blocks + verify event taxonomy (RFC 006 pts 1-2)

Two tsx CI gates make doc/code drift fail fast:
- doc-typecheck extracts every fenced ts block from README/docs/package READMEs,
  compiles them with tsc --noEmit against a temp project (vendor->lib, harness->src
  paths from tsconfig.typecheck.json), and fails on errors. Deliberate sketches opt
  out with ```ts ignore-check; the opt-out ratio is reported and capped.
- verify-event-taxonomy asserts the docs/architecture.md taxonomy table names
  exactly the events declared in the interface Events blocks. This surfaced three
  events the table had been missing (tools/change, llm/adapter-change,
  system-prompt/change), now added.

Doc snippets made compilable with stub imports/declares (1 genuine sketch ignored).
Wired into CI after typecheck. API reports (RFC 006 pt 3) deferred. Graduates RFC
006 pts 1-2 -> ADR 0014.

2026-06-14 00:47:38 +08:00

1.8 KiB

Raw Blame History

RFC 006: Doc-sync enforcement and API reports

Status: implemented (parts 1-2) — see ADR 0014. Part 3 (API reports) deferred.

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.8 KiB Raw Blame History