Files
autocraft/scripts/gen-docs.ts

93 lines
4.5 KiB
TypeScript

// 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 `<!-- stages:begin NAME ... -->` and
// `<!-- stages:end NAME -->`.
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, () => 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<StageDef["models"][number]["model"], string> = { 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("<br>")];
});
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) => `<!-- stages:begin ${name} (generated by npm run docs; do not edit) -->`;
export const endMarker = (name: string) => `<!-- stages:end ${name} -->`;
const blockRe = (name: string) => new RegExp(`<!-- stages:begin ${name}\\b[^>]*-->\\n(?:[\\s\\S]*?\\n)?<!-- stages:end ${name} -->`, "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);
}