@decohere/ci-tools 0.0.1-dev.109 → 0.0.1-dev.110

package/src/pages/bench-page.mjs

@@ -0,0 +1,313 @@
+/**
+ * The benchmark page on Pages (#660): a trend chart per benchmark and a table of the latest
+ * results, from the version 2 history (../bench/history.mjs). Static HTML and inline SVG, so the
+ * page needs no script and no third-party chart library.
+ */
+
+import { REGRESSION } from "../bench/history.mjs";
+
+const GROUPS = [
+	{ prefix: "flux.serve.", title: "flux serve (real process)" },
+	{ prefix: "flux.load.", title: "flux load (in process)" },
+	{ prefix: "flux.transpile.", title: "Transpile strategies (SWC only)" },
+	{ prefix: "forge.build.", title: "forge build" },
+];
+
+const SERIES_COLORS = [
+	"var(--series-1)",
+	"var(--series-2)",
+	"var(--series-3)",
+	"var(--series-4)",
+];
+
+function escapeHtml(value) {
+	return String(value)
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;");
+}
+
+function fmtMs(ms) {
+	if (typeof ms !== "number" || Number.isNaN(ms)) return "–";
+	if (ms === 0) return "0 ms";
+	if (ms >= 100) return `${Math.round(ms)} ms`;
+	return `${ms.toFixed(1)} ms`;
+}
+
+/** `2026-10-20 03:17 UTC`: when a run happened, to the minute. */
+function fmtDate(iso) {
+	return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+
+function commitLink(repoUrl, sha) {
+	if (sha == null) return "–";
+	return `<a href="${escapeHtml(`${repoUrl}/commit/${sha}`)}"><code>${escapeHtml(sha.slice(0, 7))}</code></a>`;
+}
+
+function machineName(context) {
+	return `${context.benchEnv ?? "unknown"} · ${context.cpu.model} × ${context.cpu.count}`;
+}
+
+/** Contexts with at least one run, most recently run first. */
+function activeContexts(history) {
+	return Object.entries(history.contexts ?? {})
+		.filter(([, entry]) => entry.runs.length > 0)
+		.sort((a, b) => new Date(b[1].runs[0].date) - new Date(a[1].runs[0].date))
+		.map(([id, entry], index) => ({
+			id,
+			context: entry.context,
+			runs: entry.runs,
+			color: SERIES_COLORS[index % SERIES_COLORS.length],
+		}));
+}
+
+/** Every benchmark id seen in any run, with the label from its newest run on any machine. */
+function benchmarkIds(contexts) {
+	const newest = new Map();
+	for (const { runs } of contexts) {
+		for (const run of runs) {
+			const time = new Date(run.date).getTime();
+			for (const result of run.results) {
+				const seen = newest.get(result.id);
+				if (seen == null || time > seen.time)
+					newest.set(result.id, { time, label: result.label });
+			}
+		}
+	}
+	return new Map([...newest].map(([id, { label }]) => [id, label]));
+}
+
+/** Oldest-first points for one benchmark on one machine. */
+function seriesFor(runs, id) {
+	return [...runs]
+		.reverse()
+		.map((run) => ({ run, result: run.results.find((result) => result.id === id) }))
+		.filter((point) => point.result != null)
+		.map(({ run, result }) => ({
+			time: new Date(run.date).getTime(),
+			date: run.date.slice(0, 10),
+			iso: run.date,
+			sha: run.sha,
+			median: result.median,
+			p90: result.p90,
+		}));
+}
+
+/** A line chart of medians over time, one line per machine, with a hover title per point. */
+export function trendSvg(lines) {
+	const width = 560;
+	const height = 180;
+	const pad = { top: 12, right: 12, bottom: 24, left: 56 };
+	const points = lines.flatMap((line) => line.points);
+	if (points.length === 0) return "";
+	const minTime = Math.min(...points.map((p) => p.time));
+	const maxTime = Math.max(...points.map((p) => p.time));
+	const maxValue = Math.max(...points.map((p) => p.p90 ?? p.median)) * 1.1 || 1;
+	const x = (time) =>
+		maxTime === minTime
+			? pad.left + (width - pad.left - pad.right) / 2
+			: pad.left + ((time - minTime) / (maxTime - minTime)) * (width - pad.left - pad.right);
+	const y = (value) => pad.top + (1 - value / maxValue) * (height - pad.top - pad.bottom);
+	const ticks = [0, 0.5, 1].map((fraction) => maxValue * fraction);
+	const grid = ticks
+		.map(
+			(value) =>
+				`<line class="grid" x1="${pad.left}" x2="${width - pad.right}" y1="${y(value)}" y2="${y(value)}"/>` +
+				`<text class="axis" x="${pad.left - 6}" y="${y(value) + 4}" text-anchor="end">${fmtMs(value)}</text>`,
+		)
+		.join("");
+	const dateLabels = [
+		{ time: minTime, anchor: "start" },
+		...(maxTime !== minTime ? [{ time: maxTime, anchor: "end" }] : []),
+	]
+		.map(
+			({ time, anchor }) =>
+				`<text class="axis" x="${x(time)}" y="${height - 6}" text-anchor="${anchor}">${new Date(time).toISOString().slice(0, 10)}</text>`,
+		)
+		.join("");
+	const series = lines
+		.map((line) => {
+			const path = line.points
+				.map((p) => `${x(p.time).toFixed(1)},${y(p.median).toFixed(1)}`)
+				.join(" ");
+			const dots = line.points
+				.map(
+					(p) =>
+						`<circle cx="${x(p.time).toFixed(1)}" cy="${y(p.median).toFixed(1)}" r="3" style="fill:${line.color}"><title>${escapeHtml(
+							`${p.date}${p.sha ? ` · ${p.sha.slice(0, 7)}` : ""} · median ${fmtMs(p.median)}${p.p90 != null ? ` · p90 ${fmtMs(p.p90)}` : ""}`,
+						)}</title></circle>`,
+				)
+				.join("");
+			return `<polyline points="${path}" style="stroke:${line.color}"/>${dots}`;
+		})
+		.join("");
+	return `<svg class="trend" viewBox="0 0 ${width} ${height}" role="img" aria-label="Median over time">${grid}${dateLabels}${series}</svg>`;
+}
+
+function changeText(points) {
+	const last = points.at(-1);
+	const before = points.at(-2);
+	if (last == null || before == null || before.median === 0) return "";
+	const percent = ((last.median - before.median) / before.median) * 100;
+	const direction = percent > 0 ? "slower" : "faster";
+	if (Math.abs(percent) < 0.5) return `<span class="change">no change</span>`;
+	return `<span class="change ${percent > 0 ? "worse" : "better"}">${Math.abs(percent).toFixed(1)}% ${direction}</span>`;
+}
+
+function card(id, label, contexts) {
+	const lines = contexts
+		.map((ctx) => ({
+			color: ctx.color,
+			name: machineName(ctx.context),
+			points: seriesFor(ctx.runs, id),
+		}))
+		.filter((line) => line.points.length > 0);
+	const primary = lines[0];
+	const latest = primary?.points.at(-1);
+	return `<article class="card">
+  <header>
+    <h3>${escapeHtml(label)}</h3>
+    <code>${escapeHtml(id)}</code>
+  </header>
+  <p class="latest"><strong>${fmtMs(latest?.median)}</strong> median${latest?.p90 != null ? ` · p90 ${fmtMs(latest.p90)}` : ""} ${primary ? changeText(primary.points) : ""}</p>
+  <p class="when">${latest != null ? `Last run ${escapeHtml(fmtDate(latest.iso))}` : ""}</p>
+  ${trendSvg(lines)}
+</article>`;
+}
+
+function latestTable(contexts, labels, repoUrl) {
+	const rows = contexts.flatMap((ctx) =>
+		ctx.runs[0].results.map(
+			(result) => `<tr>
+  <td><span class="swatch" style="background:${ctx.color}"></span>${escapeHtml(ctx.context.benchEnv ?? "unknown")}</td>
+  <td>${escapeHtml(fmtDate(ctx.runs[0].date))}</td>
+  <td>${commitLink(repoUrl, ctx.runs[0].sha)}</td>
+  <td>${escapeHtml(labels.get(result.id) ?? result.label)}</td>
+  <td class="num">${fmtMs(result.median)}</td>
+  <td class="num">${fmtMs(result.p90)}</td>
+  <td class="num">${fmtMs(result.min)}</td>
+  <td class="num">${result.files ?? "–"}</td>
+  <td class="num">${result.samples}</td>
+</tr>`,
+		),
+	);
+	return `<div class="table-wrap"><table>
+  <thead><tr><th>Machine</th><th>Run</th><th>Commit</th><th>Benchmark</th><th class="num">Median</th><th class="num">p90</th><th class="num">Min</th><th class="num">Files</th><th class="num">Samples</th></tr></thead>
+  <tbody>${rows.join("\n")}</tbody>
+</table></div>`;
+}
+
+export function buildBenchmarkHtml(
+	history,
+	{ branch = "local", sha = "local", repoUrl = "https://github.com/typesmiths/decohere" } = {},
+) {
+	const contexts = activeContexts(history);
+	const body =
+		contexts.length === 0
+			? `<p class="empty">No benchmark history yet. The nightly bench workflow adds a run each night.</p>`
+			: (() => {
+					const labels = benchmarkIds(contexts);
+					const grouped = GROUPS.map((group) => ({
+						...group,
+						ids: [...labels.keys()].filter((id) => id.startsWith(group.prefix)),
+					}));
+					const other = [...labels.keys()].filter(
+						(id) => !GROUPS.some((group) => id.startsWith(group.prefix)),
+					);
+					if (other.length > 0) grouped.push({ title: "Other", ids: other });
+					const sections = grouped
+						.filter((group) => group.ids.length > 0)
+						.map(
+							(group) => `<section>
+  <h2>${escapeHtml(group.title)}</h2>
+  <div class="cards">${group.ids.map((id) => card(id, labels.get(id), contexts)).join("\n")}</div>
+</section>`,
+						)
+						.join("\n");
+					const legend = contexts
+						.map(
+							(ctx) =>
+								`<li><span class="swatch" style="background:${ctx.color}"></span>${escapeHtml(machineName(ctx.context))} · ${escapeHtml(ctx.context.os.platform)} ${escapeHtml(ctx.context.os.arch)} · ${ctx.context.memoryGb} GB · Node ${escapeHtml(ctx.context.node)} · ${ctx.runs.length} run(s)</li>`,
+						)
+						.join("\n");
+					return `<section class="machines"><h2>Machines</h2><ul>${legend}</ul>
+<p class="note">Each line is one machine type; runs are only compared on the same one. Shared CI runners are noisy, so read the trend, not a single point. Hover a point for its date, commit and p90. A benchmark more than ${Math.round(REGRESSION.threshold * 100)}% slower than its baseline on ${REGRESSION.confirmRuns} nights running gets an issue: <a href="${escapeHtml(`${repoUrl}/issues?q=is%3Aissue+is%3Aopen+%22perf(bench)%22`)}">open benchmark issues</a>.</p></section>
+${sections}
+<section><h2>Latest run</h2>${latestTable(contexts, labels, repoUrl)}</section>`;
+				})();
+	const updated = contexts[0]?.runs[0].date.slice(0, 10) ?? "never";
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Decohere Benchmarks</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <main class="container">
+      <header class="hero">
+        <h1>Decohere benchmarks</h1>
+        <p>Updated ${escapeHtml(updated)} · built from ${escapeHtml(branch)} @ <code>${escapeHtml(sha.slice(0, 12))}</code> · <a href="./data/bench-history.json">raw data</a></p>
+      </header>
+      ${body}
+    </main>
+  </body>
+</html>
+`;
+}
+
+export function buildStylesCss() {
+	return `:root {
+  --bg: #f6f7f9; --surface: #ffffff; --text: #1b1f24; --muted: #59636e; --border: #d8dee4;
+  --accent: #0b6e4f; --better: #1a7f37; --worse: #cf222e;
+  --series-1: #0b6e4f; --series-2: #8250df; --series-3: #bc4c00; --series-4: #0969da;
+  color-scheme: light dark;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #0d1117; --surface: #161b22; --text: #e6edf3; --muted: #9198a1; --border: #30363d;
+    --accent: #3fb68b; --better: #3fb950; --worse: #f85149;
+    --series-1: #3fb68b; --series-2: #a371f7; --series-3: #f0883e; --series-4: #4493f8;
+  }
+}
+:root[data-theme="dark"] {
+  --bg: #0d1117; --surface: #161b22; --text: #e6edf3; --muted: #9198a1; --border: #30363d;
+  --accent: #3fb68b; --better: #3fb950; --worse: #f85149;
+  --series-1: #3fb68b; --series-2: #a371f7; --series-3: #f0883e; --series-4: #4493f8;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+a { color: var(--accent); }
+code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.85em; }
+.container { max-width: 1180px; margin: 0 auto; padding: 24px 16px 64px; }
+.hero h1 { margin: 0 0 4px; font-size: 1.6rem; }
+.hero p, .note, .empty { color: var(--muted); margin: 0; }
+section { margin-top: 32px; }
+h2 { font-size: 1.1rem; margin: 0 0 12px; }
+.machines ul { list-style: none; padding: 0; margin: 0 0 8px; }
+.machines li { margin: 4px 0; }
+.swatch { display: inline-block; width: 10px; height: 10px; border-radius: 2px; margin-right: 8px; vertical-align: baseline; }
+.cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 360px), 1fr)); gap: 16px; }
+.card { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 14px 16px; min-width: 0; }
+.card header { display: flex; flex-direction: column; gap: 2px; }
+.card h3 { font-size: 0.95rem; margin: 0; }
+.card header code { color: var(--muted); }
+.latest { margin: 8px 0 0; }
+.when { margin: 0 0 4px; color: var(--muted); font-size: 0.85rem; }
+.latest strong { font-size: 1.25rem; font-variant-numeric: tabular-nums; }
+.change { margin-left: 6px; font-size: 0.85rem; color: var(--muted); }
+.change.better { color: var(--better); }
+.change.worse { color: var(--worse); }
+.trend { width: 100%; height: auto; display: block; }
+.trend polyline { fill: none; stroke-width: 2; }
+.trend .grid { stroke: var(--border); stroke-width: 1; }
+.trend .axis { fill: var(--muted); font-size: 11px; }
+.table-wrap { overflow-x: auto; }
+table { width: 100%; border-collapse: collapse; background: var(--surface); border: 1px solid var(--border); border-radius: 10px; font-variant-numeric: tabular-nums; }
+th, td { padding: 8px 10px; border-bottom: 1px solid var(--border); text-align: left; white-space: nowrap; }
+th { color: var(--muted); font-weight: 600; }
+.num { text-align: right; }
+`;
+}

package/src/pages/restore-badges.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+// Restore the badges on the live Pages site into dist, so a deploy that does not regenerate
+// them (the nightly bench) keeps them. Pages replaces the whole site on every deploy.
+//
+// The site lists its badges in badges/manifest.json (artifact.mjs). Sites deployed before the
+// manifest existed are read with a fixed list instead. A badge the site does not have (404) is
+// skipped; any other failure stops the job.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const BADGES_DIR = "projects/ci-tools/dist/ci/badges";
+const PAGES_URL = process.env.PAGES_URL ?? "https://typesmiths.github.io/decohere";
+
+const LEGACY_BADGES = [
+	"ci-main.svg",
+	"ci-release.svg",
+	"coverage.svg",
+	...[
+		"ci-tools",
+		"cli",
+		"codex",
+		"cortex",
+		"create",
+		"crucible",
+		"flux",
+		"forge",
+		"mesh",
+		"nexus",
+		"protocol",
+		"scribe",
+		"terminal",
+	].map((project) => `projects/${project}.svg`),
+];
+
+async function fetchOrNull(url) {
+	const response = await fetch(url);
+	if (response.status === 404) return null;
+	if (!response.ok) throw new Error(`GET ${url}: HTTP ${response.status}`);
+	return response;
+}
+
+const manifest = await fetchOrNull(`${PAGES_URL}/badges/manifest.json`);
+const badges = manifest != null ? (await manifest.json()).badges : LEGACY_BADGES;
+
+let restored = 0;
+for (const badge of badges) {
+	const response = await fetchOrNull(`${PAGES_URL}/badges/${badge}`);
+	if (response == null) continue;
+	const file = path.join(BADGES_DIR, badge);
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFile(file, await response.text());
+	restored += 1;
+}
+console.log(
+	`✓ Restored ${restored} badge(s) from Pages (${manifest != null ? "manifest" : "legacy list"})`,
+);

package/src/pages/restore-bench-history.mjs

@@ -1,37 +1,24 @@
 #!/usr/bin/env node
 
-// Restore benchmark history from Pages, or initialize empty if not found
+// Restore benchmark history from Pages. Only a 404 (never published, or cleared) starts an
+// empty history: any other failure stops the job, so a network blip can't wipe the trend on
+// the next save.
 
-import { execSync } from "node:child_process";
-import { writeFileSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 
 const HISTORY_DIR = "projects/ci-tools/dist/ci/bench";
 const HISTORY_FILE = `${HISTORY_DIR}/bench-history.json`;
-const PAGES_URL = "https://typesmiths.github.io/decohere/data/bench-history.json";
+const PAGES_URL = process.env.PAGES_URL ?? "https://typesmiths.github.io/decohere";
 
-try {
-	await mkdir(HISTORY_DIR, { recursive: true });
-
-	try {
-		execSync(`curl -fsSL "${PAGES_URL}" -o "${HISTORY_FILE}"`, {
-			stdio: "pipe",
-		});
-		console.log("✓ Restored benchmark history from Pages");
-	} catch {
-		console.log("No benchmark history on Pages; starting from empty history");
-		writeFileSync(
-			HISTORY_FILE,
-			JSON.stringify(
-				{
-					runs: {},
-				},
-				null,
-				2,
-			),
-		);
-	}
-} catch (error) {
-	console.error("Error restoring benchmark history:", error.message);
+await mkdir(HISTORY_DIR, { recursive: true });
+const response = await fetch(`${PAGES_URL}/data/bench-history.json`);
+if (response.status === 404) {
+	console.log("No benchmark history on Pages; starting from empty history");
+	await writeFile(HISTORY_FILE, `${JSON.stringify({ version: 2, contexts: {} }, null, 2)}\n`);
+} else if (!response.ok) {
+	console.error(`Failed to restore benchmark history: HTTP ${response.status}`);
 	process.exit(1);
+} else {
+	await writeFile(HISTORY_FILE, await response.text());
+	console.log("✓ Restored benchmark history from Pages");
 }

package/tests/bench/history.test.mjs

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+import {
+	appendRun,
+	assertValid,
+	compare,
+	contextId,
+	findRegressions,
+	formatComparison,
+	fromVitest,
+	getContext,
+	normalize,
+	parseResults,
+	previousRun,
+	RESULT_PREFIX,
+} from "../../src/bench/history.mjs";
+
+const fakeOs = {
+	cpus: () => [{ model: " Test CPU " }, { model: "Test CPU" }],
+	platform: () => "linux",
+	arch: () => "x64",
+	totalmem: () => 16 * 1024 ** 3,
+};
+const ctx = getContext(
+	fakeOs,
+	{ BENCH_ENV: "gh-actions" },
+	"v24.1.0",
+	new Date("2026-10-20T03:17:00Z"),
+);
+
+const result = (id, median, extra = {}) => ({
+	id,
+	label: id,
+	unit: "ms",
+	median,
+	p90: median * 1.2,
+	min: median * 0.9,
+	max: median * 1.3,
+	samples: 5,
+	...extra,
+});
+
+const vitestOutput = {
+	files: [
+		{
+			groups: [
+				{
+					benchmarks: [
+						{
+							name: "forge build es6 + types (18 files)",
+							mean: 70,
+							median: 64,
+							min: 60,
+							max: 80,
+							sampleCount: 5,
+						},
+						{
+							name: "forge build es6 only (18 files)",
+							mean: 10,
+							min: 8,
+							max: 12,
+							sampleCount: 5,
+						},
+					],
+				},
+			],
+		},
+	],
+};
+
+describe("getContext / contextId", () => {
+	it("describes the machine and names the CI environment with the Node major", () => {
+		expect(ctx).toEqual({
+			benchEnv: "gh-actions-node24",
+			date: "2026-10-20T03:17:00.000Z",
+			os: { platform: "linux", arch: "x64" },
+			cpu: { model: "Test CPU", count: 2 },
+			memoryGb: 16,
+			node: "v24.1.0",
+		});
+		expect(getContext(fakeOs, {}, "v24.1.0").benchEnv).toBe("(local)");
+	});
+
+	it("gives the same id to the same machine regardless of date or env label", () => {
+		const later = getContext(fakeOs, {}, "v24.1.0", new Date("2027-01-01"));
+		expect(contextId(later)).toBe(contextId(ctx));
+		expect(contextId({ ...ctx, cpu: { ...ctx.cpu, count: 4 } })).not.toBe(contextId(ctx));
+	});
+});
+
+describe("parseResults", () => {
+	it("reads the last result line among other output", () => {
+		const results = [result("flux.load.cold", 250)];
+		const output = `flux load: median 250 ms\n${RESULT_PREFIX}[]\n${RESULT_PREFIX}${JSON.stringify(results)}\n`;
+		expect(parseResults(output, "flux-load")).toEqual(results);
+	});
+
+	it("fails, naming the suite, when there is no result line", () => {
+		expect(() => parseResults("crashed\n", "flux-serve")).toThrow(/flux-serve/);
+	});
+});
+
+describe("fromVitest", () => {
+	it("maps forge benchmarks to stable ids, keeping the file count out of the label", () => {
+		expect(fromVitest(vitestOutput)).toEqual([
+			{
+				id: "forge.build.local",
+				label: "forge build es6 + types",
+				unit: "ms",
+				median: 64,
+				min: 60,
+				max: 80,
+				samples: 5,
+				files: 18,
+			},
+			// No median from vitest: the mean stands in.
+			expect.objectContaining({ id: "forge.build.debug", median: 10, files: 18 }),
+		]);
+	});
+
+	it("fails on a benchmark it has no id for, instead of charting it under a moving name", () => {
+		const output = {
+			files: [{ groups: [{ benchmarks: [{ name: "something new", mean: 1 }] }] }],
+		};
+		expect(() => fromVitest(output)).toThrow(/something new/);
+	});
+});
+
+describe("assertValid", () => {
+	it("passes real results and rejects NaN or empty ones, naming them", () => {
+		expect(() => assertValid([result("a", 1)])).not.toThrow();
+		expect(() =>
+			assertValid([result("a", 1), result("b", Number.NaN), result("c", 2, { samples: 0 })]),
+		).toThrow(/b, c/);
+	});
+});
+
+describe("normalize", () => {
+	it("keeps a version 2 history as it is", () => {
+		const history = { version: 2, contexts: { x: { context: ctx, runs: [] } } };
+		expect(normalize(history)).toBe(history);
+	});
+
+	it("converts version 1 forge runs so their trend carries on", () => {
+		const v1 = {
+			runs: {
+				abc: {
+					context: ctx,
+					runs: [{ date: "2026-08-12T14:18:10Z", context: ctx, vitestOutput }],
+				},
+				empty: { context: ctx, runs: [] },
+			},
+		};
+		const history = normalize(v1);
+		expect(Object.keys(history.contexts)).toEqual(["abc"]);
+		expect(history.contexts.abc.runs[0]).toMatchObject({
+			date: "2026-08-12T14:18:10Z",
+			sha: null,
+			results: [{ id: "forge.build.local" }, { id: "forge.build.debug" }],
+		});
+	});
+
+	it("starts empty when there is no history", () => {
+		expect(normalize(null)).toEqual({ version: 2, contexts: {} });
+	});
+});
+
+describe("appendRun / previousRun", () => {
+	const run = (day) => ({
+		date: `2026-10-${day}T03:17:00Z`,
+		sha: `sha${day}`,
+		results: [result("a", Number(day))],
+	});
+
+	it("puts the new run first, trims to the limit, and leaves the input untouched", () => {
+		const empty = normalize(null);
+		const one = appendRun(empty, ctx, run("18"), 2);
+		const two = appendRun(one, ctx, run("19"), 2);
+		const three = appendRun(two, ctx, run("20"), 2);
+
+		expect(empty.contexts).toEqual({});
+		expect(one.contexts[contextId(ctx)].runs).toHaveLength(1);
+		expect(three.contexts[contextId(ctx)].runs.map((r) => r.sha)).toEqual(["sha20", "sha19"]);
+		expect(previousRun(three, contextId(ctx))?.sha).toBe("sha20");
+		expect(previousRun(three, "other-machine")).toBeUndefined();
+	});
+});
+
+describe("compare / formatComparison", () => {
+	it("reports the change in median against the previous run, and n/a for new benchmarks", () => {
+		const rows = compare([result("a", 120), result("new", 5)], {
+			results: [result("a", 100)],
+		});
+		expect(rows).toEqual([
+			{ id: "a", current: 120, previous: 100, delta: 20, percent: 20 },
+			{ id: "new", current: 5 },
+		]);
+
+		const table = formatComparison(rows).split("\n");
+		expect(table[0]).toMatch(/^Benchmark \| +Median \| Previous \| +Delta \| +%$/);
+		expect(table[2]).toMatch(/^a +\| +120\.0 ms \| +100\.0 ms \| +\+20\.0 ms \| \+20\.0%$/);
+		expect(table[3]).toMatch(/^new +\| +5\.0 ms \| +n\/a \| +n\/a \| +n\/a$/);
+	});
+
+	it("compares against nothing on a machine's first run", () => {
+		expect(compare([result("a", 1)], undefined)).toEqual([{ id: "a", current: 1 }]);
+	});
+});
+
+describe("findRegressions", () => {
+	// Newest first, like the history: one run per night with this median for "a".
+	const nights = (...medians) =>
+		medians.map((median, index) => ({
+			date: `2026-10-${String(30 - index).padStart(2, "0")}T03:17:00Z`,
+			sha: `sha${30 - index}`,
+			results: [result("a", median)],
+		}));
+
+	it("flags a benchmark over the threshold on the last two nights, against the runs before", () => {
+		const [regression] = findRegressions(nights(130, 125, 100, 101, 99, 100, 102));
+		expect(regression).toMatchObject({
+			id: "a",
+			baseline: 100,
+			recent: [
+				{ sha: "sha30", median: 130 },
+				{ sha: "sha29", median: 125 },
+			],
+			lastGood: { sha: "sha28" },
+		});
+		expect(regression.percent).toBeCloseTo(30);
+	});
+
+	it("ignores one slow night, which is as likely the runner as the code", () => {
+		expect(findRegressions(nights(150, 100, 100, 101, 99, 100))).toEqual([]);
+	});
+
+	it("ignores slowdowns within the threshold", () => {
+		expect(findRegressions(nights(115, 118, 100, 100, 100))).toEqual([]);
+	});
+
+	it("waits for enough history to have a baseline", () => {
+		expect(findRegressions(nights(200, 200, 100, 100))).toEqual([]);
+		expect(findRegressions(nights(200))).toEqual([]);
+	});
+
+	it("uses only the baselineRuns runs before the slow ones", () => {
+		// Old runs at 300 would hide the regression if they were in the baseline.
+		const runs = nights(130, 130, 100, 100, 100, 300, 300, 300, 300, 300);
+		const options = { threshold: 0.2, confirmRuns: 2, baselineRuns: 3, minBaseline: 3 };
+		expect(findRegressions(runs, options).map((r) => r.baseline)).toEqual([100]);
+	});
+});