// Renders the blocks of docs/pipeline.md and README.md that come from the stage registry // (src/stages/registry.ts). `node scripts/gen-docs.ts` writes them; `--check` exits 1 when a // committed block differs. Each block sits between `` and // ``. import { readFileSync, writeFileSync } from "node:fs"; import { GLOBAL_WAITS, stagesInOrder, type StageDef } from "../src/stages/registry.ts"; export type Target = { file: string; blocks: Record string> }; const cell = (s: string) => s.replace(/\|/g, "\\|"); const table = (head: string[], rows: string[][]) => [`| ${head.join(" | ")} |`, `|${head.map(() => "---").join("|")}|`, ...rows.map((r) => `| ${r.map(cell).join(" | ")} |`)].join("\n"); const lower = (s: string) => s.charAt(0).toLowerCase() + s.slice(1); const MODEL_NAMES: Record = { jev: "Jev", haiku: "Haiku", sonnet: "Sonnet", opus: "Opus", local: "Local embedding model" }; function stageList(): string { return stagesInOrder().map((s) => `${s.order}. ${s.docSection}: ${s.description}`).join("\n"); } function modelTable(): string { const rows = (Object.keys(MODEL_NAMES) as (keyof typeof MODEL_NAMES)[]).filter((m) => m !== "local").map((m) => { const mine = stagesInOrder().flatMap((s) => s.models.filter((x) => x.model === m).map((x) => ({ stage: s.docSection, ...x }))); const uses = mine.map((x) => `${x.stage}: ${lower(x.use)}`); const remarks = mine.flatMap((x) => (x.remark ? [x.remark] : [])); return [MODEL_NAMES[m], [...new Set([...uses, ...remarks])].join("
")]; }); return table(["Model", "Used for"], rows); } function limitsTable(): string { const steps = stagesInOrder().flatMap((s) => s.steps.filter((x) => x.limit !== undefined)); const shown = (x: (typeof steps)[number]) => (x.seeded !== undefined ? String(x.seeded) : typeof x.limit === "number" ? String(x.limit) : x.zeroOnly ? "none (0 pauses it)" : "none"); const rows: string[][] = []; const half = Math.ceil(steps.length / 2); for (let i = 0; i < half; i++) { const a = steps[i]!, b = steps[i + half]; rows.push([a.label ?? a.name, shown(a), b ? (b.label ?? b.name) : "", b ? shown(b) : ""]); } return table(["Step", "Default limit (new database)", "Step", "Default limit (new database)"], rows); } function waits(): string { const all = [...stagesInOrder().flatMap((s) => s.waits), ...GLOBAL_WAITS]; return table(["Wait", "Why", "How long", "Shows as"], all.map((w) => [w.name, w.why, w.howLong, w.showsAs])); } function stageTable(): string { return table(["Stage", "What it does", "Model", "Stops for a person"], stagesInOrder().map((s) => { const models = [...new Set(s.models.map((m) => MODEL_NAMES[m.model]))]; return [s.docSection, s.description, models.length ? models.join(", ") : "none", s.person ? `yes: ${lower(s.person)}` : "no"]; })); } export const TARGETS: Target[] = [ { file: "docs/pipeline.md", blocks: { "stage-list": stageList, "model-table": modelTable, "limits-table": limitsTable, waits } }, { file: "README.md", blocks: { "stage-table": stageTable } }, ]; export const beginMarker = (name: string) => ``; export const endMarker = (name: string) => ``; const blockRe = (name: string) => new RegExp(`\\n(?:[\\s\\S]*?\\n)?`, "g"); /** The file text with every generated block of the target replaced; throws when a marker pair is missing or repeated. */ export function render(text: string, t: Target): string { let out = text; for (const [name, make] of Object.entries(t.blocks)) { const hits = out.match(blockRe(name))?.length ?? 0; if (hits !== 1) throw new Error(`${t.file}: expected one "${name}" marker pair, found ${hits}`); out = out.replace(blockRe(name), () => `${beginMarker(name)}\n${make()}\n${endMarker(name)}`); } return out; } if (import.meta.main) { const root = new URL("../", import.meta.url); const check = process.argv.includes("--check"); let bad = 0; for (const t of TARGETS) { const url = new URL(t.file, root); const now = readFileSync(url, "utf8"); const next = render(now, t); if (next === now) continue; if (check) { for (const name of Object.keys(t.blocks)) if (render(now, { ...t, blocks: { [name]: t.blocks[name]! } }) !== now) console.error(`${t.file}: block "${name}" differs; run npm run docs`); bad++; } else writeFileSync(url, next); } process.exit(bad ? 1 : 0); }