cursedbelt 2.7.0 → 2.8.0

package/src/verifyGraph.spec.ts

@@ -0,0 +1,181 @@
+/**
+ * 🔴 The gate got faster on 2026-09-15. This is the file that stops it getting smaller.
+ *
+ * `bun run verify` was `paths && typecheck && demo:check && build && test && e2e` — six
+ * serial links, 142.0s measured end to end on an idle machine, five of them single-threaded
+ * work queued behind each other on a fourteen-core Mac. It is now a dependency graph
+ * (`scripts/verify.ts`) that runs the same stages concurrently.
+ *
+ * Every speed-up of a gate is one edit away from being a deletion of a gate, and the two
+ * look identical in a diff: dropping `e2e` from the graph makes `verify` four times faster
+ * and every test still passes. This generation's third rule is that a repo's gate proves
+ * that repo, so the SET of stages is pinned here, by name, against the chain that existed
+ * before the change. Adding a stage is free; removing one has to argue with this file.
+ *
+ * The literal list below is deliberate duplication. A test that derived the expectation from
+ * `STAGES` would assert that the graph equals itself.
+ */
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import pkg from '../package.json';
+import { graphFault, jobLimit, ROOT, STAGES, timingTable } from '../scripts/verify';
+
+/**
+ * What `verify` ran before it became a graph, expanded to the leaf scripts.
+ *
+ * `typecheck` was one script running three `tsc` projects serially; it is now three scripts
+ * so they can run at once, and `typecheck` still runs all three for anybody typing it by
+ * hand. `styles` is new — it is the first two steps of `build`, hoisted so that the things
+ * which READ the generated stylesheets can wait on the thing that writes them.
+ */
+const MUST_RUN = [
+	'paths',
+	'typecheck:root',
+	'typecheck:server',
+	'typecheck:specs',
+	'demo:check',
+	'styles',
+	'build',
+	'test',
+	'e2e',
+] as const;
+
+describe('the verify graph', () => {
+	it('still runs every check the serial chain ran', () => {
+		const inGraph = STAGES.map((s) => s.script);
+		const missing = MUST_RUN.filter((script) => !inGraph.includes(script));
+		expect(
+			missing,
+			`\`bun run verify\` no longer runs:\n  ${missing.join('\n  ')}\n` +
+				'A gate that got faster by proving less is not faster. Add the stage back, or — if it ' +
+				'genuinely belongs somewhere else now — say so here and in scripts/verify.ts together.',
+		).toEqual([]);
+	});
+
+	it('names only scripts package.json actually declares', () => {
+		const scripts = pkg.scripts as Record<string, string | undefined>;
+		const undeclared = STAGES.map((s) => s.script).filter((script) => !scripts[script]);
+		expect(undeclared, `verify stages with no script:\n  ${undeclared.join('\n  ')}`).toEqual([]);
+	});
+
+	it('is the thing `bun run verify` actually runs', () => {
+		// Without this the graph can be perfect and unreachable: `verify` could quietly go
+		// back to a chain, and every assertion above would still pass.
+		expect(pkg.scripts.verify).toInclude('scripts/verify.ts');
+	});
+
+	it('has no dangling `needs` and no cycle', () => {
+		expect(graphFault(STAGES)).toBeNull();
+	});
+
+	it('catches a dangling `needs` rather than idling with work left', () => {
+		// The negative control. A typo in `needs` makes a stage that can never become ready,
+		// and a scheduler that simply runs out of ready work would exit 0 having skipped it —
+		// "nothing failed" reported as "everything passed", which is the false green in its
+		// purest form.
+		expect(graphFault([{ script: 'a' }, { script: 'b', needs: ['typo'] }])).toInclude('typo');
+	});
+
+	it('catches a cycle', () => {
+		expect(graphFault([{ script: 'a', needs: ['b'] }, { script: 'b', needs: ['a'] }])).toInclude('cycle');
+	});
+
+	it('catches two stages claiming the same script', () => {
+		expect(graphFault([{ script: 'a' }, { script: 'a' }])).toInclude('same script');
+	});
+});
+
+describe('the two edges the graph rests on', () => {
+	it('keeps everything that reads the generated stylesheets behind `styles`', () => {
+		// `build` regenerates src/styles-static.css and src/styles-utilities.css;
+		// stylesStaticMatches.spec.ts and stylesUtilitiesMatches.spec.ts assert those exact
+		// files are current, and the demo bundle e2e drives is compiled from them. Any of
+		// those three running beside the generators is a writer racing a reader.
+		for (const script of ['build', 'test', 'e2e']) {
+			const stage = STAGES.find((s) => s.script === script);
+			expect(stage?.needs, `\`${script}\` must wait for \`styles\``).toContain('styles');
+		}
+	});
+
+	it('🔴 no spec reads dist/, which is why `build` is a leaf', () => {
+		// The graph runs `build` BESIDE `test` and `e2e` rather than in front of them, and
+		// that is only sound while nothing under test can observe the compiled output. The
+		// build stages into dist.next and swaps, so a reader of `dist/` during a build sees
+		// the previous bytes or — for one `mv` — no directory at all.
+		const offenders: string[] = [];
+		const walk = (dir: string): void => {
+			for (const entry of readdirSync(dir)) {
+				const full = join(dir, entry);
+				if (statSync(full).isDirectory()) {
+					walk(full);
+					continue;
+				}
+				if (!/\.spec\.tsx?$/.test(entry)) continue;
+				// This file states the pattern, so it matches itself — the same self-exemption
+				// `namedSubpathsResolve.spec.ts` needs for the same reason.
+				if (entry === 'verifyGraph.spec.ts') continue;
+				const text = readFileSync(full, 'utf8');
+				// A filesystem read whose path argument mentions dist — not the word in prose,
+				// and not `dist.next` inside buildIsStaged's assertions about the SCRIPT TEXT.
+				if (/(?:readFileSync|readdirSync|existsSync|statSync|Bun\.file|new Glob)\([^)]*['"`][^'"`]*\bdist\b/.test(text)) {
+					offenders.push(full.slice(ROOT.length + 1));
+				}
+			}
+		};
+		walk(resolve(ROOT, 'src'));
+		expect(
+			offenders,
+			`these specs read dist/, so \`build\` is no longer a leaf and the graph is wrong:\n  ${offenders.join('\n  ')}\n` +
+				'Either give them `needs: ["build"]` in scripts/verify.ts, or stop reading dist.',
+		).toEqual([]);
+	});
+});
+
+describe('the job limit', () => {
+	it('defaults to a third of the cores, because a stage is not a process', () => {
+		// e2e alone spawns seven Playwright workers; build spawns two tsc processes. Six
+		// stages is already twenty-odd processes on a machine with fourteen cores.
+		expect(jobLimit({}, 14)).toBe(4);
+		expect(jobLimit({}, 4)).toBe(2);
+		expect(jobLimit({}, 64)).toBe(6);
+	});
+
+	it('honours an explicit override, including 1', () => {
+		// 🔴 `1` is the old serial behaviour, and it must stay reachable without a second
+		// gate script existing for somebody to run instead of this one.
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '1' }, 14)).toBe(1);
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '9' }, 14)).toBe(9);
+	});
+
+	it('ignores nonsense rather than running zero stages at a time', () => {
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: 'lots' }, 14)).toBe(4);
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '0' }, 14)).toBe(4);
+		expect(jobLimit({ CURSEDBELT_VERIFY_JOBS: '-3' }, 14)).toBe(4);
+	});
+});
+
+describe('the timing table', () => {
+	it('reports the overlap, which is the whole point of the change', () => {
+		const table = timingTable(
+			[
+				{ script: 'test', ok: true, ms: 60_000, output: '' },
+				{ script: 'e2e', ok: true, ms: 30_000, output: '' },
+			],
+			60_000,
+		);
+		expect(table).toInclude('1.5× overlap');
+		expect(table).toInclude('test');
+	});
+
+	it('says so plainly when nothing overlapped', () => {
+		const table = timingTable([{ script: 'paths', ok: true, ms: 1_000, output: '' }], 1_000);
+		expect(table).toInclude('No overlap');
+	});
+
+	it('shows a skipped stage as skipped, never as passing', () => {
+		const table = timingTable([{ script: 'e2e', ok: false, ms: 0, output: '', skipped: true }], 1_000);
+		expect(table).toInclude('skipped');
+		expect(table).not.toInclude(' ok');
+	});
+});