Tianyi Cui
5477d5fb5b
knip: the walker/renderer internals (the closed sets, the heading and marker helpers, the per-lifecycle renderer) have no importer beyond this module — the public surface is rfcRoot, walkRfcTree, and spliceReadme, the three names the generator CLI and the gate consume.
142 lines
6.2 KiB
TypeScript
142 lines
6.2 KiB
TypeScript
/**
|
|
* Shared source of truth for the RFC index: the tree walker (structure rules)
|
|
* and the README table renderer. `gen-rfc-index.ts` writes the generated
|
|
* regions; `verify-rfc-classification.ts` checks structure and asserts the
|
|
* committed regions are fresh. Pure module — no side effects on import.
|
|
*
|
|
* The layout contract ([the classification RFC](../docs/rfc/implemented/process/2026-06-20-rfc-classification.md)):
|
|
* every RFC lives at `docs/rfc/{lifecycle}/{class}/yyyy-mm-dd-topic.md`, the
|
|
* folder IS the label, and both sets are CLOSED — extending either means
|
|
* amending this module AND the README's Classification prose.
|
|
*
|
|
* The README's per-lifecycle tables are GENERATED between marker comments
|
|
* (`<!-- gen-rfc-index:begin {lifecycle} -->` … `end`): section headings and
|
|
* rows are derived from each RFC's path (lifecycle/class), H1 (title, with an
|
|
* optional `RFC: ` prefix stripped), and filename date, sorted by date then
|
|
* filename. Prose outside the markers is curated by hand and never touched.
|
|
*/
|
|
|
|
import { readFileSync } from 'node:fs'
|
|
import { resolve } from 'node:path'
|
|
import { globSync } from 'node:fs'
|
|
|
|
export const rfcRoot = resolve(import.meta.dirname, '../docs/rfc')
|
|
|
|
/** The closed set of RFC lifecycles (top-level folders under docs/rfc/). */
|
|
const LIFECYCLES = ['proposed', 'implemented', 'rejected'] as const
|
|
|
|
/**
|
|
* The closed set of RFC classes (nested folder under each lifecycle). Adding a
|
|
* class is a deliberate act: extend this list AND the README's Classification
|
|
* section. The gate rejects any folder not listed here.
|
|
*/
|
|
const CLASSES = ['feature', 'bug-fix', 'simplification', 'architecture', 'process', 'testing'] as const
|
|
|
|
/** Non-RFC Markdown allowed to sit directly at a lifecycle root. */
|
|
const ROOT_ALLOWLIST = new Set(['AGENTS.md', 'CLAUDE.md'])
|
|
|
|
/** Title-case a class/lifecycle folder name for a README heading. */
|
|
const heading = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)
|
|
|
|
/** One RFC file, as discovered by the walker. */
|
|
export interface Rfc {
|
|
lifecycle: string
|
|
cls: string
|
|
base: string
|
|
/** Path relative to docs/rfc — the README link target. */
|
|
rel: string
|
|
/** H1 text with any `RFC: ` prefix stripped — the README row title. */
|
|
title: string
|
|
/** `yyyy-mm-dd` from the filename — the "First proposed" column. */
|
|
date: string
|
|
}
|
|
|
|
/**
|
|
* Walk the RFC tree, enforcing the structure rules. Returns every valid RFC
|
|
* plus one error string per violation (unknown class folder, bad depth, bad
|
|
* filename, missing/malformed H1). Callers treat a non-empty error list as
|
|
* fatal — the index is only generated from a structurally valid tree.
|
|
*/
|
|
export function walkRfcTree(): { rfcs: Rfc[]; errors: string[] } {
|
|
const rfcs: Rfc[] = []
|
|
const errors: string[] = []
|
|
for (const lifecycle of LIFECYCLES) {
|
|
for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: rfcRoot }).sort()) {
|
|
const segs = match.split('/')
|
|
// Allowlisted file directly at the lifecycle root (e.g. implemented/AGENTS.md).
|
|
if (segs.length === 2 && ROOT_ALLOWLIST.has(segs[1] ?? '')) continue
|
|
// A Chinese counterpart (foo.zh.md, docs/i18n/README.md) is the SAME RFC,
|
|
// indexed via its English filename; the pairing gate owns its consistency.
|
|
if (match.endsWith('.zh.md')) continue
|
|
const cls = segs[1]
|
|
const base = segs[2]
|
|
if (segs.length !== 3 || cls === undefined || base === undefined) {
|
|
errors.push(`structure: ${match} — expected {lifecycle}/{class}/file.md (got depth ${segs.length})`)
|
|
continue
|
|
}
|
|
if (!(CLASSES as readonly string[]).includes(cls)) {
|
|
errors.push(`structure: ${match} — unknown class folder "${cls}" (allowed: ${CLASSES.join(', ')})`)
|
|
continue
|
|
}
|
|
if (!/^\d{4}-\d{2}-\d{2}-.+\.md$/.test(base)) {
|
|
errors.push(`structure: ${match} — filename must be yyyy-mm-dd-topic.md`)
|
|
continue
|
|
}
|
|
const firstLine = readFileSync(resolve(rfcRoot, match), 'utf8').split('\n', 1)[0] ?? ''
|
|
const h1 = /^#\s+(?:RFC:\s+)?(.+?)\s*$/.exec(firstLine)
|
|
if (!h1?.[1]) {
|
|
errors.push(`title: ${match} — first line must be an H1 (\`# RFC: <title>\` or \`# <title>\`), got: ${JSON.stringify(firstLine)}`)
|
|
continue
|
|
}
|
|
rfcs.push({ lifecycle, cls, base, rel: match, title: h1[1], date: base.slice(0, 10) })
|
|
}
|
|
}
|
|
return { rfcs, errors }
|
|
}
|
|
|
|
/** The begin/end marker lines that delimit one lifecycle's generated region. */
|
|
const markers = (lifecycle: string): { begin: string; end: string } => ({
|
|
begin: `<!-- gen-rfc-index:begin ${lifecycle} -->`,
|
|
end: `<!-- gen-rfc-index:end ${lifecycle} -->`,
|
|
})
|
|
|
|
/**
|
|
* Render one lifecycle's generated region body: a `### {Class}` heading plus a
|
|
* `| Title | First proposed |` table for every non-empty class, in CLASSES
|
|
* order, rows sorted by date then filename.
|
|
*/
|
|
function renderLifecycle(rfcs: Rfc[], lifecycle: string): string {
|
|
const sections: string[] = []
|
|
for (const cls of CLASSES) {
|
|
const rows = rfcs
|
|
.filter(r => r.lifecycle === lifecycle && r.cls === cls)
|
|
.sort((a, b) => a.date.localeCompare(b.date) || a.base.localeCompare(b.base))
|
|
if (rows.length === 0) continue
|
|
const table = rows.map(r => `| [${r.title}](${r.rel}) | ${r.date} |`).join('\n')
|
|
sections.push(`### ${heading(cls)}\n\n| Title | First proposed |\n|---|---|\n${table}`)
|
|
}
|
|
return sections.join('\n\n')
|
|
}
|
|
|
|
/**
|
|
* Splice freshly rendered regions into the README text. Throws when a marker
|
|
* pair is missing, duplicated, or out of order — the markers are part of the
|
|
* curated prose and must exist exactly once per lifecycle.
|
|
*/
|
|
export function spliceReadme(readme: string, rfcs: Rfc[]): string {
|
|
let out = readme
|
|
for (const lifecycle of LIFECYCLES) {
|
|
const { begin, end } = markers(lifecycle)
|
|
const beginAt = out.indexOf(begin)
|
|
const endAt = out.indexOf(end)
|
|
if (beginAt === -1 || endAt === -1 || endAt < beginAt) {
|
|
throw new Error(`README.md is missing the ${JSON.stringify(begin)} … ${JSON.stringify(end)} marker pair`)
|
|
}
|
|
if (out.indexOf(begin, beginAt + 1) !== -1 || out.indexOf(end, endAt + 1) !== -1) {
|
|
throw new Error(`README.md has a duplicated ${lifecycle} index marker`)
|
|
}
|
|
out = `${out.slice(0, beginAt + begin.length)}\n${renderLifecycle(rfcs, lifecycle)}\n${out.slice(endAt)}`
|
|
}
|
|
return out
|
|
}
|