Context
The same 2026-07-04 docs audit found hand-typed JSON examples on docs.branch-analysis.tsx and docs.scoreability.tsx that didn't match their real backing shapes -- docs.branch-analysis.tsx used a nested repo: {owner, repo} / refs: {base, head} / files: [{added, removed}] / linked_issues shape against the real .strict() Zod schema at src/api/routes.ts (repoFullName, baseRef/headRef, changedFiles with additions/deletions, linkedIssues), and docs.scoreability.tsx used entirely fabricated snake_case fields (risk_adjusted_priority, six scenarios) against the real ScorePreviewResult shape (src/scoring/preview.ts, seven camelCase scenarios, blockedBy, scoreabilityStatus). Both were hand-typed once and never re-validated against the schema as it evolved.
Goal
A test (or CI script) that extracts the JSON literal embedded in a docs page's CodeBlock and validates it against the real Zod schema/type it claims to represent, so this class of drift becomes a build failure instead of a silent, indefinite rot.
Requirements
- A small manifest mapping a docs route file -> the schema it should validate against -> which
CodeBlock in the page holds the example (e.g. by index or a marker comment).
- Start with the two pages already known to have (now-fixed) drift:
docs.branch-analysis.tsx against localBranchAnalysisSchema, docs.scoreability.tsx against a hand-trimmed subset of ScorePreviewResult's required top-level keys (the full type includes internal-only fields like laneMath that the docs intentionally trim for readability -- validate presence/shape of the fields the doc actually claims, not full schema conformance).
- Extend to other request/response examples across the docs site as they're found to drift (this issue seeds the mechanism; it doesn't need to cover every example on day one).
Deliverables
A test file (likely test/unit/docs-examples-schema.test.ts) that imports the real schemas and the docs source files, extracts each mapped example, and asserts it parses/validates.
Expected outcomes
branch-analysis/scoreability-style example drift fails a test the next time the underlying Zod schema changes shape, instead of silently going stale until the next manual audit.
Context
The same 2026-07-04 docs audit found hand-typed JSON examples on
docs.branch-analysis.tsxanddocs.scoreability.tsxthat didn't match their real backing shapes --docs.branch-analysis.tsxused a nestedrepo: {owner, repo}/refs: {base, head}/files: [{added, removed}]/linked_issuesshape against the real.strict()Zod schema atsrc/api/routes.ts(repoFullName,baseRef/headRef,changedFileswithadditions/deletions,linkedIssues), anddocs.scoreability.tsxused entirely fabricated snake_case fields (risk_adjusted_priority, six scenarios) against the realScorePreviewResultshape (src/scoring/preview.ts, seven camelCase scenarios,blockedBy,scoreabilityStatus). Both were hand-typed once and never re-validated against the schema as it evolved.Goal
A test (or CI script) that extracts the JSON literal embedded in a docs page's
CodeBlockand validates it against the real Zod schema/type it claims to represent, so this class of drift becomes a build failure instead of a silent, indefinite rot.Requirements
CodeBlockin the page holds the example (e.g. by index or a marker comment).docs.branch-analysis.tsxagainstlocalBranchAnalysisSchema,docs.scoreability.tsxagainst a hand-trimmed subset ofScorePreviewResult's required top-level keys (the full type includes internal-only fields likelaneMaththat the docs intentionally trim for readability -- validate presence/shape of the fields the doc actually claims, not full schema conformance).Deliverables
A test file (likely
test/unit/docs-examples-schema.test.ts) that imports the real schemas and the docs source files, extracts each mapped example, and asserts it parses/validates.Expected outcomes
branch-analysis/scoreability-style example drift fails a test the next time the underlying Zod schema changes shape, instead of silently going stale until the next manual audit.