repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

perf: memoize the-system render pipeline

f2128fe64e97d57b5e1e0843a1d510575f998a66

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Board mutations re-render the whole site; the unified pipeline output
only depends on the markdown source, so memoize processed HTML and
search text per document. Share the markdown parser across documents.
Add bench, profile, and benchstat tasks with a synthetic corpus.

Changed files (4)

extensions/the-system/__bench__/render.bench.ts

Added
new file mode 100644
1 +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
2 +import { tmpdir } from "node:os";
3 +import path from "node:path";
4 +import type {
5 + BoardItemState,
6 + BoardProposal,
7 + BoardState,
8 +} from "../board-state.ts";
9 +import { loadProjectIndex } from "../project-index.ts";
10 +import {
11 + type RenderInput,
12 + renderSystemBoardSite,
13 + renderSystemBookSite,
14 + renderSystemViewSite,
15 +} from "../system-renderer.ts";
17 +const ROUNDS = Number(process.env.SYSTEM_BENCH_ROUNDS ?? 10);
18 +const MINIMUM_ROUND_NS = Number(
19 + process.env.SYSTEM_BENCH_MINIMUM_ROUND_NS ?? 200_000_000,
20 +);
21 +const SCALE = Number(process.env.SYSTEM_BENCH_SCALE ?? 1);
22 +let sink = 0;
24 +const PREFIX = "PX";
25 +const token = (index: number) => `T${`${index}`.padStart(7, "0")}`;
26 +const documentId = (type: string, index: number) =>
27 + `${PREFIX}-${type.toUpperCase()}-${token(index)}`;
28 +const bundlePath = (directory: string, id: string) =>
29 + `.system/${directory}/${id}-${id.slice(-8).toLowerCase()}/index.md`;
30 +const linkTo = (directory: string, id: string) =>
31 + `../../${directory}/${id.slice(0, -8)}${id.slice(-8).toLowerCase()}/index.md`;
33 +const paragraph = (seed: number) =>
34 + `Renders the governed corpus through remark and rehype. The pipeline must survive repeated board mutations without unbounded growth. Round ${seed} covers heading anchors, slug stability, and reference rewrites across every bundle in the project tree with enough prose to exercise the parser. The board rebuilds the whole site whenever a stored signature changes.`;
36 +const body = (seed: number, links: readonly string[]) => `## Overview
38 +${paragraph(seed)}
40 +### Data
42 +| Layer | Cost | Notes |
43 +| ----- | ---- | ----- |
44 +| parse | ${seed} ms | remark tokenizers |
45 +| render | ${seed * 2} ms | rehype plugins |
47 +Inline math $E = mc^${(seed % 9) + 1}$ and display math:
49 +$$\\int_0^1 x^${(seed % 7) + 1} \\, dx = \\frac{1}{${(seed % 7) + 2}}$$
51 +> [!WARNING]
52 +> Renderer output is regenerated on every board mutation.
54 +\`\`\`ts
55 +export const round = (seed: number): number => seed * ${(seed % 13) + 1};
56 +\`\`\`
58 +\`\`\`mermaid
59 +graph LR
60 + A[Parse] --> B[Render]
61 + B --> C[Write]
62 +\`\`\`
64 +### References
66 +${links.map((link) => `- See [${link.slice(0, -9)}](${link})`).join("\n")}
68 +First term
69 +: Governs the pipeline.
71 +[External](https://example.invalid/report)
72 +`;
74 +const frontmatter = (id: string, fields: Record<string, string>) => {
75 + const type = id.split("-")[1]?.toLowerCase();
76 + return `---\n${Object.entries({ id, type, ...fields })
77 + .map(([key, value]) => `${key}: ${value}`)
78 + .join("\n")}\n---\n`;
79 +};
81 +const writeDocument = (
82 + root: string,
83 + directory: string,
84 + id: string,
85 + fields: Record<string, string>,
86 + links: readonly string[],
87 + seed: number,
88 +) => {
89 + const file = path.join(root, bundlePath(directory, id));
90 + mkdirSync(path.dirname(file), { recursive: true });
91 + writeFileSync(file, `${frontmatter(id, fields)}${body(seed, links)}`, "utf8");
92 +};
94 +const createProject = (root: string): void => {
95 + mkdirSync(path.join(root, ".system"), { recursive: true });
96 + writeFileSync(
97 + path.join(root, ".system/config.json"),
98 + JSON.stringify({
99 + prefix: PREFIX,
100 + schemaVersion: 0,
101 + title: "Render Bench",
102 + currentPhase: documentId("phase", 1),
103 + }),
104 + "utf8",
105 + );
106 + writeFileSync(
107 + path.join(root, ".system/board.json"),
108 + JSON.stringify({ schemaVersion: 0, items: {} }),
109 + "utf8",
110 + );
111 + for (const name of ["SYSTEM", "MISSION", "RULES"])
112 + writeFileSync(
113 + path.join(root, `.system/${name}.md`),
114 + `# ${name}\n\n${paragraph(name.length)}\n\n- ${name} law one\n- ${name} law two\n`,
115 + "utf8",
116 + );
117 + for (let index = 1; index <= 2 * SCALE; index++) {
118 + const id = documentId("phase", index);
119 + writeDocument(
120 + root,
121 + "phases",
122 + id,
123 + { title: `Phase ${index}`, label: `P${index}` },
124 + [],
125 + index,
126 + );
128 + for (let index = 1; index <= 8 * SCALE; index++) {
129 + const id = documentId("research", index);
130 + writeDocument(
131 + root,
132 + "research",
133 + id,
134 + { title: `Research ${index}` },
135 + [],
136 + index,
137 + );
139 + for (let index = 1; index <= 12 * SCALE; index++) {
140 + const id = documentId("spec", index);
141 + writeDocument(
142 + root,
143 + "specs",
144 + id,
146 + title: `Spec ${index}`,
147 + research: `[${documentId("research", ((index - 1) % (8 * SCALE)) + 1)}]`,
148 + },
150 + linkTo(
151 + "research",
152 + documentId("research", ((index - 1) % (8 * SCALE)) + 1),
153 + ),
154 + ],
155 + index,
156 + );
158 + for (let index = 1; index <= 16 * SCALE; index++) {
159 + const id = documentId("plan", index);
160 + const dependency = index > 1 ? documentId("plan", index - 1) : undefined;
161 + writeDocument(
162 + root,
163 + "plans",
164 + id,
166 + title: `Plan ${index}`,
167 + spec: documentId("spec", ((index - 1) % (12 * SCALE)) + 1),
168 + status: index % 2 === 0 ? "approved" : "draft",
169 + ...(dependency ? { depends_on: `[${dependency}]` } : {}),
170 + },
171 + [linkTo("specs", documentId("spec", ((index - 1) % (12 * SCALE)) + 1))],
172 + index,
173 + );
175 + for (let index = 1; index <= 16 * SCALE; index++) {
176 + const id = documentId("issue", index);
177 + writeDocument(
178 + root,
179 + "issues",
180 + id,
182 + title: `Issue ${index}`,
183 + specs: `[${documentId("spec", ((index - 1) % (12 * SCALE)) + 1)}]`,
184 + },
185 + [],
186 + index,
187 + );
191 +const root = mkdtempSync(path.join(tmpdir(), "system-bench-"));
192 +createProject(root);
193 +const directories: string[] = [];
195 +const index = loadProjectIndex(root);
196 +const board: BoardState = {
197 + schemaVersion: 0,
198 + items: Object.fromEntries(
199 + index.documents
200 + .filter((document) => document.metadata.type === "issue")
201 + .slice(0, 6)
202 + .map((document) => [
203 + document.metadata.id,
205 + state: "open",
206 + updatedAt: "2025-01-01T00:00:00.000Z",
207 + source: "manual",
208 + } satisfies {
209 + state: BoardItemState;
210 + updatedAt: string;
211 + source: "manual";
212 + },
213 + ]),
214 + ),
216 +const proposals: readonly BoardProposal[] = index.documents
217 + .filter((document) => document.metadata.type === "plan")
218 + .slice(0, 4)
219 + .map((document) => ({
220 + id: document.metadata.id,
221 + state: "done" as const,
222 + rationale: "Benchmark proposal",
223 + }));
225 +const input: RenderInput = index;
226 +const selected = index.documents[0] as RenderInput["documents"][number];
228 +function benchmark(name: string, operation: () => void): void {
229 + for (let index = 0; index < 2; index++) operation();
230 + let iterations = 1;
231 + while (true) {
232 + const started = process.hrtime.bigint();
233 + for (let index = 0; index < iterations; index++) operation();
234 + if (Number(process.hrtime.bigint() - started) >= MINIMUM_ROUND_NS) break;
235 + iterations *= 2;
237 + for (let round = 0; round < ROUNDS; round++) {
238 + const started = process.hrtime.bigint();
239 + for (let index = 0; index < iterations; index++) operation();
240 + const elapsed = Number(process.hrtime.bigint() - started);
241 + console.log(
242 + `Benchmark${name}\t${iterations}\t${(elapsed / iterations).toFixed(0)} ns/op`,
243 + );
244 + for (const directory of directories.splice(0))
245 + rmSync(directory, { recursive: true, force: true });
249 +if (!Number.isInteger(ROUNDS) || ROUNDS < 1)
250 + throw new Error("SYSTEM_BENCH_ROUNDS must be a positive integer");
251 +if (!Number.isFinite(MINIMUM_ROUND_NS) || MINIMUM_ROUND_NS < 1)
252 + throw new Error("SYSTEM_BENCH_MINIMUM_ROUND_NS must be positive");
254 +console.log(`goos: ${process.platform}`);
255 +console.log(`goarch: ${process.arch}`);
256 +console.log("pkg: pi-ext/the-system");
257 +benchmark("LoadProjectIndex", () => {
258 + sink ^= loadProjectIndex(root).documents.length;
259 +});
260 +benchmark("RenderViewSite", () => {
261 + directories.push(renderSystemViewSite(input, selected).directory);
262 +});
263 +benchmark("RenderBookSite", () => {
264 + directories.push(renderSystemBookSite(input).directory);
265 +});
266 +benchmark("RenderBoardSite", () => {
267 + directories.push(
268 + renderSystemBoardSite(input, board, proposals, "bench").directory,
269 + );
270 +});
271 +let coldRevision = 0;
272 +benchmark("RenderBoardSiteCold", () => {
273 + coldRevision += 1;
274 + const marker = `\n<!-- rev ${coldRevision} -->`;
275 + directories.push(
276 + renderSystemBoardSite(
278 + ...input,
279 + documents: input.documents.map((document) => ({
280 + ...document,
281 + markdown: document.markdown + marker,
282 + })),
283 + },
284 + board,
285 + proposals,
286 + "bench",
287 + ).directory,
288 + );
289 +});
290 +rmSync(root, { recursive: true, force: true });
291 +if (sink === 42) console.error(sink);

extensions/the-system/markdown.ts

Modified
52 52 .use(remarkMath)
53 53 .use(remarkGithubAlert);
55 +const markdownParser = createMarkdownParser();
55 57 const unsupported = (message: string): never => {
56 58 throw new MarkdownDocumentError("frontmatter.unsupported", message);
94 96 export function parseRichMarkdown(source: string): RichMarkdownDocument {
95 - const parser = createMarkdownParser();
96 - const tree = parser.runSync(parser.parse(source)) as MarkdownRoot;
97 + const tree = markdownParser.runSync(
98 + markdownParser.parse(source),
99 + ) as MarkdownRoot;
97 100 const blocks = tree.children.filter((node) => node.type === "yaml");
98 101 if (blocks.length === 0)
99 102 throw new MarkdownDocumentError(

extensions/the-system/mise.toml

Modified
1 +[tasks.bench]
2 +description = "Benchmark the-system render pipeline"
3 +depends = ["//:install"]
4 +run = "node --no-warnings --experimental-strip-types __bench__/render.bench.ts"
6 +[tasks.profile]
7 +description = "Profile the-system render pipeline"
8 +depends = ["//:install"]
9 +run = [
10 + '''node -e "require('node:fs').mkdirSync('../../.research/the-system', { recursive: true })"''',
11 + "node --no-warnings --experimental-strip-types --cpu-prof --cpu-prof-dir ../../.research/the-system --cpu-prof-name the-system.cpuprofile __bench__/render.bench.ts",
14 +[tasks.benchstat]
15 +description = "Compare the-system benchmark results"
16 +depends = ["//:install"]
17 +usage = '''
18 +arg "<baseline>"
19 +arg "<candidate>"
20 +'''
21 +run = 'benchstat "{{ usage.baseline }}" "{{ usage.candidate }}"'
1 23 [tasks.fmt]
2 24 description = "Format the-system"
3 25 depends = ["//:install"]

extensions/the-system/system-renderer.ts

Modified
109 109 .use(rehypeHighlight)
110 110 .use(rehypeStringify, { allowDangerousHtml: true });
112 +// Board re-renders process unchanged documents again on every mutation; the
113 +// unified pipeline output only depends on the markdown source, so memoize it.
114 +const PROCESSED_CACHE_LIMIT = 512;
115 +const processedCache = new Map<
116 + string,
117 + Readonly<{ html: string; text: string }>
118 +>();
120 +const processedDocument = (
121 + markdown: string,
122 +): Readonly<{ html: string; text: string }> => {
123 + const cached = processedCache.get(markdown);
124 + if (cached) return cached;
125 + const processed = {
126 + html: rewriteMermaidBlocks(String(processor.processSync(markdown))),
127 + text: textContent(markdown),
128 + };
129 + if (processedCache.size >= PROCESSED_CACHE_LIMIT) processedCache.clear();
130 + processedCache.set(markdown, processed);
131 + return processed;
112 134 export function renderSystemViewSite(
113 135 input: RenderInput,
114 136 selected: RenderDocumentInput,
347 369 outputRoot,
348 370 renderedSources,
372 + const processed = processedDocument(document.markdown);
350 373 return {
351 374 id: document.id,
352 375 title: document.title,
354 377 sourcePath: document.path,
355 378 outputPath,
356 379 article,
357 - text: textContent(document.markdown),
380 + text: processed.text,
358 381 refs: [],
381 404 current: document.metadata.id === input.currentPhase,
382 405 renderedSources,
407 + const processed = processedDocument(document.markdown);
384 408 return {
385 409 id: document.metadata.id,
386 410 title: document.metadata.title,
388 412 sourcePath: document.path,
389 413 outputPath,
390 414 article,
391 - text: `${frontmatterText(document.frontmatter)} ${textContent(document.markdown)}`,
415 + text: `${frontmatterText(document.frontmatter)} ${processed.text}`,
392 416 refs: refsFor(document.metadata),
393 417 ...(document.metadata.type === "phase"
394 418 ? { label: document.metadata.label }
422 446 const backlinks = input.documents
423 447 ? backlinksHtml(input.id, input.documents, input.outputRoot)
449 + const processed = processedDocument(input.markdown);
425 450 const body = prefixHeadingAnchors(
426 451 rewriteLocalRefs(
427 452 rewriteVisualAssetLinks(
428 - rewriteMermaidBlocks(String(processor.processSync(input.markdown))),
453 + processed.html,
429 454 input.sourcePath,
430 455 input.outputRoot,