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.
This commit is contained in:
Tianyi Cui
151
scripts/doc-typecheck.ts
Normal file
151
scripts/doc-typecheck.ts
Normal file
@@ -0,0 +1,151 @@
|
||||
/**
|
||||
* Doc-sync gate (RFC 006 part 1): typecheck the fenced `ts` code blocks in our
|
||||
* Markdown so documentation can't drift from the API it documents.
|
||||
*
|
||||
* Every ```ts block in README.md, docs/** and packages/* /README.md is
|
||||
* extracted to a temp file and compiled with `tsc --noEmit` against the
|
||||
* workspace sources (resolved through the same `paths` map vitest uses, so no
|
||||
* build is required first). A block that is a deliberate sketch rather than
|
||||
* compilable code opts out with an explicit ` ```ts ignore-check ` info string
|
||||
* — the opt-out is visible in the source, and this script reports the ratio so
|
||||
* the escape hatch can't quietly become the norm.
|
||||
*
|
||||
* Run: `tsx scripts/doc-typecheck.ts`.
|
||||
*/
|
||||
|
||||
import { execFileSync } from 'node:child_process'
|
||||
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { join, relative, resolve } from 'node:path'
|
||||
import { glob } from 'node:fs/promises'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
|
||||
/** One extracted code block. */
|
||||
interface Block {
|
||||
file: string
|
||||
/** 1-based line of the opening fence. */
|
||||
line: number
|
||||
/** `true` when the fence is ` ```ts ignore-check ` (skip compilation). */
|
||||
ignored: boolean
|
||||
code: string
|
||||
}
|
||||
|
||||
/** Extract every ```ts / ```ts ignore-check block from one Markdown file. */
|
||||
function extractBlocks(absPath: string): Block[] {
|
||||
const text = readFileSync(absPath, 'utf8')
|
||||
const lines = text.split('\n')
|
||||
const file = relative(root, absPath)
|
||||
const blocks: Block[] = []
|
||||
let open: { line: number; ignored: boolean; body: string[] } | null = null
|
||||
|
||||
lines.forEach((raw, i) => {
|
||||
const fence = /^```(\s*)(\S.*)?$/.exec(raw)
|
||||
if (!fence) {
|
||||
if (open) open.body.push(raw)
|
||||
return
|
||||
}
|
||||
if (open) {
|
||||
// closing fence
|
||||
blocks.push({ file, line: open.line, ignored: open.ignored, code: open.body.join('\n') })
|
||||
open = null
|
||||
return
|
||||
}
|
||||
// opening fence — only care about ts blocks
|
||||
const info = (fence[2] ?? '').trim()
|
||||
if (info === 'ts' || info === 'ts ignore-check') {
|
||||
open = { line: i + 1, ignored: info === 'ts ignore-check', body: [] }
|
||||
}
|
||||
})
|
||||
return blocks
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the workspace `paths` map from tsconfig.typecheck.json (JSONC). This map
|
||||
* resolves vendored packages to their BUILT declarations (`lib`) and harness
|
||||
* packages to source (`src`) — the same resolution `yarn lint`/`typecheck` use.
|
||||
* Resolving vendor to `lib` (not `src`) is essential: otherwise tsc type-checks
|
||||
* raw vendor source and floods the run with unrelated errors. Requires the
|
||||
* vendor `lib/` to exist (a fresh clone runs `yarn build` first; CI does too).
|
||||
*/
|
||||
function workspacePaths(): Record<string, string[]> {
|
||||
const raw = readFileSync(join(root, 'tsconfig.typecheck.json'), 'utf8')
|
||||
// Strip // line comments and /* */ block comments so JSON.parse accepts it.
|
||||
const stripped = raw
|
||||
.replace(/\/\*[\s\S]*?\*\//g, '')
|
||||
.replace(/(^|[^:])\/\/.*$/gm, '$1')
|
||||
return (JSON.parse(stripped) as { compilerOptions: { paths: Record<string, string[]> } })
|
||||
.compilerOptions.paths
|
||||
}
|
||||
|
||||
/** The standalone tsconfig for the temp project (copies base resolution, no
|
||||
* composite/declaration settings that would fight `--noEmit`). */
|
||||
function tempTsconfig(): string {
|
||||
return JSON.stringify({
|
||||
compilerOptions: {
|
||||
target: 'es2024',
|
||||
module: 'esnext',
|
||||
moduleResolution: 'bundler',
|
||||
allowImportingTsExtensions: true,
|
||||
strict: true,
|
||||
noEmit: true,
|
||||
skipLibCheck: true,
|
||||
types: ['node'],
|
||||
baseUrl: root,
|
||||
ignoreDeprecations: '6.0',
|
||||
paths: workspacePaths(),
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
const markdownGlobs = ['README.md', 'docs/**/*.md', 'packages/*/README.md']
|
||||
|
||||
const files: string[] = []
|
||||
for (const pattern of markdownGlobs) {
|
||||
for await (const match of glob(pattern, { cwd: root })) files.push(resolve(root, match))
|
||||
}
|
||||
files.sort()
|
||||
|
||||
const all = files.flatMap(extractBlocks)
|
||||
const checked = all.filter(b => !b.ignored)
|
||||
const ignored = all.filter(b => b.ignored)
|
||||
|
||||
if (checked.length === 0) {
|
||||
console.log('doc-typecheck: no ts code blocks to check.')
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
const tmp = mkdtempSync(join(root, '.doc-typecheck-'))
|
||||
try {
|
||||
writeFileSync(join(tmp, 'tsconfig.json'), tempTsconfig())
|
||||
const fileForBlock = new Map<string, Block>()
|
||||
checked.forEach((block, i) => {
|
||||
const name = `block-${i}.ts`
|
||||
writeFileSync(join(tmp, name), block.code.endsWith('\n') ? block.code : `${block.code}\n`)
|
||||
fileForBlock.set(name, block)
|
||||
})
|
||||
|
||||
try {
|
||||
execFileSync('node_modules/.bin/tsc', ['-p', join(tmp, 'tsconfig.json')], { cwd: root, stdio: 'pipe' })
|
||||
} catch (error: unknown) {
|
||||
const out = (error as { stdout?: Buffer }).stdout?.toString() ?? ''
|
||||
// Rewrite "block-N.ts(line,col)" to the real "file:fenceLine" for triage.
|
||||
const remapped = out.replace(/block-(\d+)\.ts\((\d+),(\d+)\)/g, (_m, idx: string, ln: string, col: string) => {
|
||||
const block = fileForBlock.get(`block-${idx}.ts`)
|
||||
if (!block) return `block-${idx}.ts(${ln},${col})`
|
||||
return `${block.file} (block at line ${block.line}, +${ln}:${col})`
|
||||
})
|
||||
console.error('doc-typecheck: documentation code blocks failed to compile.\n')
|
||||
console.error(remapped)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
const ratio = ignored.length / all.length
|
||||
console.log(`doc-typecheck: ${checked.length} block(s) compiled, ${ignored.length} ignored (${(ratio * 100).toFixed(0)}% opt-out).`)
|
||||
// Guard against the escape hatch becoming the norm.
|
||||
if (all.length >= 4 && ratio > 0.5) {
|
||||
console.error(`doc-typecheck: too many blocks opt out of checking (${ignored.length}/${all.length}). Make them compile or delete them.`)
|
||||
process.exit(1)
|
||||
}
|
||||
} finally {
|
||||
rmSync(tmp, { recursive: true, force: true })
|
||||
}
|
||||
98
scripts/verify-event-taxonomy.ts
Normal file
98
scripts/verify-event-taxonomy.ts
Normal file
@@ -0,0 +1,98 @@
|
||||
/**
|
||||
* Doc-sync gate (RFC 006 part 2): verify the event-taxonomy table in
|
||||
* docs/architecture.md against the events actually declared in source.
|
||||
*
|
||||
* The table duplicates the `declare module 'cordis' { interface Events }`
|
||||
* blocks across packages/* /src. This script extracts both sets of event names
|
||||
* and asserts they match exactly — every declared event appears in the table,
|
||||
* and the table names no event that isn't declared. Verify, don't generate
|
||||
* (per the RFC): the table keeps its hand-written Mode/Purpose columns; only
|
||||
* the set of names is checked.
|
||||
*
|
||||
* Run: `tsx scripts/verify-event-taxonomy.ts`.
|
||||
*/
|
||||
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { join, relative, resolve } from 'node:path'
|
||||
import { glob } from 'node:fs/promises'
|
||||
|
||||
const root = resolve(import.meta.dirname, '..')
|
||||
|
||||
/**
|
||||
* Event names declared in source: the keys inside every `interface Events`
|
||||
* block under packages/* /src. A declared event is a quoted `'scope/name'(`
|
||||
* method signature at the start of a line within such a block.
|
||||
*/
|
||||
async function declaredEvents(): Promise<Map<string, string>> {
|
||||
const found = new Map<string, string>()
|
||||
for await (const match of glob('packages/*/src/**/*.ts', { cwd: root })) {
|
||||
const abs = resolve(root, match)
|
||||
const text = readFileSync(abs, 'utf8')
|
||||
// Walk `interface Events {` blocks brace-balanced and pull quoted keys.
|
||||
const re = /interface\s+Events\s*\{/g
|
||||
let m: RegExpExecArray | null
|
||||
while ((m = re.exec(text)) !== null) {
|
||||
let depth = 1
|
||||
let i = m.index + m[0].length
|
||||
const start = i
|
||||
while (i < text.length && depth > 0) {
|
||||
const ch = text[i]
|
||||
if (ch === '{') depth++
|
||||
else if (ch === '}') depth--
|
||||
i++
|
||||
}
|
||||
const body = text.slice(start, i - 1)
|
||||
// A declaration is a quoted event name followed by `(` (method form).
|
||||
for (const k of body.matchAll(/['"]([a-z][a-z-]*\/[a-z-]+)['"]\s*\(/g)) {
|
||||
const name = k[1]
|
||||
if (name) found.set(name, relative(root, abs))
|
||||
}
|
||||
}
|
||||
}
|
||||
return found
|
||||
}
|
||||
|
||||
/** Event names referenced in the architecture-doc taxonomy table (in `code`). */
|
||||
function tableEvents(): Set<string> {
|
||||
const text = readFileSync(join(root, 'docs/architecture.md'), 'utf8')
|
||||
const lines = text.split('\n')
|
||||
const heading = lines.findIndex(l => /^###\s+Event taxonomy/.test(l))
|
||||
if (heading === -1) throw new Error('verify-event-taxonomy: "### Event taxonomy" heading not found')
|
||||
const names = new Set<string>()
|
||||
for (let i = heading + 1; i < lines.length; i++) {
|
||||
const line = lines[i] ?? ''
|
||||
if (/^###\s/.test(line)) break // next section ends the table
|
||||
if (!line.includes('|')) continue
|
||||
for (const code of line.matchAll(/`([^`]+)`/g)) {
|
||||
// A cell may read "`a/b` / `c/d` (pkg)" — pull each scoped name.
|
||||
for (const name of (code[1] ?? '').matchAll(/[a-z][a-z-]*\/[a-z-]+/g)) names.add(name[0])
|
||||
}
|
||||
}
|
||||
return names
|
||||
}
|
||||
|
||||
const declared = await declaredEvents()
|
||||
const table = tableEvents()
|
||||
|
||||
const declaredNames = new Set(declared.keys())
|
||||
const missingFromTable = [...declaredNames].filter(n => !table.has(n)).sort()
|
||||
const missingFromSource = [...table].filter(n => !declaredNames.has(n)).sort()
|
||||
|
||||
if (missingFromTable.length === 0 && missingFromSource.length === 0) {
|
||||
console.log(`verify-event-taxonomy: ${declaredNames.size} events match the architecture-doc table.`)
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
if (missingFromTable.length > 0) {
|
||||
console.error('verify-event-taxonomy: declared in source but MISSING from the docs/architecture.md table:')
|
||||
for (const n of missingFromTable) {
|
||||
console.error(` ${n} (declared in ${declared.get(n) ?? '?'})`)
|
||||
}
|
||||
}
|
||||
if (missingFromSource.length > 0) {
|
||||
console.error('verify-event-taxonomy: named in the table but NOT declared in source (stale doc):')
|
||||
for (const n of missingFromSource) {
|
||||
console.error(` ${n}`)
|
||||
}
|
||||
}
|
||||
process.exit(1)
|
||||
Reference in New Issue
Block a user