@raresportan/marram 0.0.0-stage → 0.2.0

package/src/core/hook.mjs

@@ -0,0 +1,114 @@
+// Runs the gate where work is declared done, so nothing finishes or ships while it's red. Usage:
+//   marram hook pre-push      git's pre-push hook: what's pushed must have passed.
+//   marram hook claude-turn   Claude Code's UserPromptSubmit: notes the code a turn starts from.
+//   marram hook claude-stop   Claude Code's Stop: a turn that changed code ends only once the gate passes, sent back at
+//                           most 3 times a turn.
+//   marram hook finish        An agent's own done-check: a failure exits 1 with what failed, so the
+//                           agent is sent back as many times as its hook allows.
+// Code the gate passed isn't checked again, and a failure is reused for 15 minutes; see gate-state.mjs.
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { git, treeOf, updateState, verdictOf, readState } from "./gate-state.mjs";
+
+const MAX_SENT_BACK = 3;
+const MARRAM = join(import.meta.dirname, "..", "..", "bin", "marram.mjs");
+const stdin = () => readFileSync(0, "utf8");
+
+/** The gate's verdict on `tree`, running the default gate when there is none. `show` sends its progress to the terminal. */
+async function judge(root, tree, show) {
+	const known = verdictOf(root, tree);
+	if (known !== undefined) return { ...known, reused: true };
+	const gate = spawn(process.execPath, [MARRAM, "gate"], { cwd: root, stdio: ["ignore", show ? "inherit" : "ignore", "inherit"] });
+	// A hook that's killed (its timeout) passes it on, so the gate can stop what it started.
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(signal, () => gate.kill(signal));
+	await new Promise((done) => gate.once("close", done));
+	// A gate that changed files as it ran records no pass; it counts as failed with no stage.
+	return verdictOf(root, tree) ?? { passed: false };
+}
+
+/** What an agent is told when the gate fails: where it failed, and the end of that stage's log. */
+function failure(verdict) {
+	if (verdict.stage === undefined) return "The gate didn't pass: files changed while it ran. Run `marram gate` and fix what fails.";
+	// From the first failure line when there is one (a test runner's "not ok", a check's ✗), else the end of the log.
+	let tail = "";
+	try {
+		const lines = readFileSync(verdict.log, "utf8").trimEnd().split("\n");
+		const first = lines.findIndex((line) => /^\s*(not ok|✗)/.test(line));
+		tail = (first === -1 ? lines.slice(-60) : lines.slice(first, first + 60)).join("\n");
+	} catch {}
+	return [
+		`The gate failed at ${verdict.stage}${verdict.reused ? " (the verdict on this exact code, from a run in the last 15 minutes)" : ""}, so this isn't done.`,
+		"Fix the cause, not the check, then finish again. `marram gate` reruns it.",
+		`Log: ${verdict.log}`,
+		...(tail === "" ? [] : ["", tail]),
+	].join("\n");
+}
+
+async function prePush(root) {
+	// stdin: one line per ref pushed, "<local ref> <local sha> <remote ref> <remote sha>".
+	for (const line of stdin().split("\n").filter(Boolean)) {
+		const [ref, sha] = line.split(" ");
+		if (/^0+$/.test(sha)) continue; // a deletion
+		const tree = git(root, ["rev-parse", `${sha}^{tree}`]);
+		if (verdictOf(root, tree)?.passed) continue;
+		if (treeOf(root) !== tree) {
+			console.error(`${ref} hasn't passed the gate, and the working tree isn't that commit, so it can't be checked here.\nCommit or stash your changes, check it out and push again (or \`git push --no-verify\` to skip the gate).`);
+			process.exit(1);
+		}
+		console.error(`Gating ${ref} before it's pushed (\`git push --no-verify\` skips this).`);
+		const verdict = await judge(root, tree, true);
+		if (!verdict.passed) {
+			console.error(failure(verdict));
+			process.exit(1);
+		}
+	}
+}
+
+function claudeTurn(root) {
+	const { session_id: session } = JSON.parse(stdin());
+	const tree = treeOf(root);
+	updateState(root, (state) => { state.sessions[session] = { start: tree, sentBack: 0, at: Date.now() }; });
+}
+
+async function claudeStop(root) {
+	const { session_id: session } = JSON.parse(stdin());
+	const tree = treeOf(root);
+	const turn = readState(root).sessions[session];
+	// A turn that changed no code (a question, a plan) ends without the gate.
+	if (turn?.start === tree) process.exit(0);
+	const verdict = await judge(root, tree, false);
+	if (verdict.passed) process.exit(0);
+	// Counted under the lock, from the state as it is now: the gate may have run for minutes since `turn` was read.
+	const sendBack = updateState(root, (state) => {
+		const now = state.sessions[session];
+		if ((now?.sentBack ?? 0) >= MAX_SENT_BACK) return false;
+		state.sessions[session] = { start: now?.start, sentBack: (now?.sentBack ?? 0) + 1, at: Date.now() };
+		return true;
+	});
+	if (!sendBack) {
+		// Let the turn end so a person can look; say so rather than end quietly.
+		console.log(JSON.stringify({ systemMessage: `The gate is still red after ${MAX_SENT_BACK} tries at ${verdict.stage ?? "an unknown stage"}: ${verdict.log ?? "run marram gate"}` }));
+		process.exit(0);
+	}
+	console.error(failure(verdict));
+	process.exit(2);
+}
+
+async function finish(root) {
+	const verdict = await judge(root, treeOf(root), false);
+	if (!verdict.passed) {
+		console.log(failure(verdict));
+		process.exit(1);
+	}
+}
+
+const modes = { "pre-push": prePush, "claude-turn": claudeTurn, "claude-stop": claudeStop, finish };
+
+export async function hook(root, _config, [mode]) {
+	if (!(mode in modes)) {
+		console.error(`Usage: marram hook ${Object.keys(modes).join(" | ")}`);
+		process.exit(1);
+	}
+	await modes[mode](root);
+}

package/src/core/no-comments.mjs

@@ -0,0 +1,30 @@
+// A comment explaining a workaround reads as permission to work around: agents copy it, and it spreads. So a project can
+// ban comments, as a finder for `restrict`. What stays is what no code can say: a doc comment on a declaration, a license
+// header at the top of a file, and a comment with a link to the outside constraint it explains.
+import ts from "typescript";
+
+const isDoc = (text) => text.startsWith("/**");
+const hasLink = (text) => /https?:\/\//.test(text);
+const isLicense = (text, pos) => pos === 0 && /\b(license|copyright|spdx)\b/i.test(text);
+
+/** The comments in `source` that aren't allowed, as `{ line, what }`, for `restrict`. */
+export function comments(source) {
+	const found = [];
+	const seen = new Set();
+	const look = (ranges) => {
+		for (const { pos, end } of ranges ?? []) {
+			if (seen.has(pos)) continue;
+			seen.add(pos);
+			const text = source.text.slice(pos, end);
+			if (isDoc(text) || hasLink(text) || isLicense(text, pos)) continue;
+			found.push({ line: source.getLineAndCharacterOfPosition(pos).line + 1, what: "has a comment" });
+		}
+	};
+	const visit = (node) => {
+		look(ts.getLeadingCommentRanges(source.text, node.getFullStart()));
+		look(ts.getTrailingCommentRanges(source.text, node.getEnd()));
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	return found;
+}

package/src/core/ratchet.mjs

@@ -0,0 +1,72 @@
+// A ratchet lint: something is done in one owning place, and anywhere else only when listed with why. A fix written
+// as a lint rule stops the bleeding before the cleanup; the list holds what was there already, and only shrinks:
+//   - a site not on the list fails, with what to do instead (the rule's `fix`);
+//   - an entry with no reason fails: the reason is what a reviewer judges;
+//   - an entry that no longer matches (its file is gone, or no longer does it) fails until it's removed, so a cleanup
+//     can't leave room for the next site to slip in under an old excuse.
+//
+// `ratchet` is the list's rules for any kind of site; `restrict` is the common case, sites found per file in a folder.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+
+/**
+ * Problems with `found` sites (`{ key, at, what }`: the entry that would allow it, where it is, what it does) against
+ * the `allowed` list (`{ key: reason }`, kept in `list`). `stale` says why a listed key no longer matches: a phrase, or a
+ * function of the key.
+ */
+export function ratchet({ list, allowed, found, fix, stale }) {
+	const problems = [];
+	const seen = new Set();
+	const why = typeof stale === "function" ? stale : () => stale;
+	for (const site of found) {
+		if (Object.hasOwn(allowed, site.key)) seen.add(site.key);
+		else problems.push(`${site.at} ${site.what}: ${fix}, or list it in ${list} with why`);
+	}
+	for (const [key, reason] of Object.entries(allowed)) {
+		if (typeof reason !== "string" || reason.trim() === "") problems.push(`${key} is listed in ${list} without a reason: say why it's safe`);
+		if (!seen.has(key)) problems.push(`${key} ${why(key)}: remove it from ${list}`);
+	}
+	return problems;
+}
+
+/** The TypeScript files under `folder`, declaration files aside. */
+export function sourceFiles(folder) {
+	return readdirSync(folder, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(folder, entry.name);
+		if (entry.isDirectory()) return sourceFiles(path);
+		return /\.tsx?$/.test(entry.name) && !entry.name.endsWith(".d.ts") ? [path] : [];
+	});
+}
+
+export const parse = (file) => ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true, file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+
+export const lineOf = (source, node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+
+/**
+ * The ratchet over each file under `root`/`folder`: `find(source)` returns the file's sites (`{ line, what }`), and a
+ * file with any is allowed only when `allowed` lists it (by path from the folder), or it's one of `owners`, where the
+ * thing is meant to be done. `stale` says what a listed file no longer does.
+ */
+export function restrict({ root, folder, owners = [], find, allowed, list, fix, stale }) {
+	const base = join(root, folder);
+	const found = [];
+	for (const file of sourceFiles(base)) {
+		const key = relative(base, file);
+		if (owners.includes(key)) continue;
+		const sites = find(parse(file));
+		if (sites.length === 0) continue;
+		const what = [...new Set(sites.map((site) => site.what))].join(", ");
+		found.push({ key, at: `${folder}/${key}:${sites[0].line}`, what });
+	}
+	return ratchet({ list, allowed, found, fix, stale: (key) => (existsSync(join(base, key)) ? stale : "is gone") });
+}
+
+/** Prints the problems and fails, or prints `ok`. */
+export function finish(lint, problems, ok) {
+	if (problems.length > 0) {
+		console.error(`${lint}: ${problems.length} problem(s)\n${problems.map((problem) => `  ✗ ${problem}`).join("\n")}`);
+		process.exit(1);
+	}
+	console.log(`ok: ${ok}`);
+}

package/src/core/until.ts

@@ -0,0 +1,59 @@
+// Waiting in checks. A check with its own `until` has its own bound (10 s to 60 s, or a count of tries) and its own
+// failure ("timed out"), so a wait that fails under the gate's load says neither how long it waited nor what it saw. This one waits a generous minute for everything, and says both.
+//
+// Time bounds the other way, "this ended quickly", are `sooner`: the bound is half the time the broken behaviour takes,
+// so it depends on the check's stand-ins rather than on how loaded the machine is. How work grows with its input is
+// `scales`: a ratio of two timings taken together, which load slows alike.
+import assert from "node:assert/strict";
+import { setTimeout as sleep } from "node:timers/promises";
+
+/** How long a wait lasts before it fails. Generous, as it only decides how long a failing check takes to fail. */
+const LIMIT_MS = 60_000;
+
+const describe = (value: unknown) => (typeof value === "string" ? value : JSON.stringify(value));
+
+/**
+ * Waits until `check` holds, failing after a minute with `what` it waited for and, given `seen`, what it last saw:
+ * pass `seen` whenever the state behind `check` would explain a failure. A minute outlasts many stand-ins (`sleep 30`):
+ * waiting for one to be stopped, follow with `sooner` against its lifetime, or its own exit passes for the stop.
+ */
+export async function until(check: () => boolean | Promise<boolean>, what: string, seen?: () => unknown): Promise<void> {
+	const started = Date.now();
+	while (!(await check())) {
+		if (Date.now() - started > LIMIT_MS) {
+			throw new Error(`Timed out after ${LIMIT_MS / 1000} s waiting for ${what}${seen === undefined ? "" : `; saw ${describe(seen())}`}`);
+		}
+		await sleep(25);
+	}
+}
+
+/**
+ * Asserts that what began at `started` (a `Date.now()`) ended in under half of `brokenMs`: how long it takes when the
+ * behaviour under test is broken, such as a stand-in that hangs for 30 s or a server that answers after 10 s. So the
+ * bound holds on a loaded machine yet fails when the behaviour is broken.
+ */
+export function sooner(started: number, brokenMs: number, what: string): void {
+	const elapsed = Date.now() - started;
+	assert(elapsed < brokenMs / 2, `${what}: took ${elapsed} ms, when broken it takes ${brokenMs} ms`);
+}
+
+/**
+ * Asserts that the work `setup(size)` returns grows no faster than `size ** exponent`: it times the work at `from` and
+ * at `to` (the best of several runs each) and compares. Linear work grows by about `to / from`, quadratic by its
+ * square; an exponent between them tells the two apart on any machine, as both timings share its load.
+ */
+export function scales(what: string, setup: (size: number) => () => void, { from, to, exponent }: { from: number; to: number; exponent: number }): void {
+	const best = (size: number) => {
+		const work = setup(size);
+		let fastest = Infinity;
+		for (let run = 0; run < 5; run++) {
+			const started = performance.now();
+			work();
+			fastest = Math.min(fastest, performance.now() - started);
+		}
+		return Math.max(fastest, 0.01);
+	};
+	const small = best(from), large = best(to);
+	const grown = Math.log(large / small) / Math.log(to / from);
+	assert(grown < exponent, `${what}: from ${from} to ${to} it took ${small.toFixed(2)} ms then ${large.toFixed(2)} ms, growing as size^${grown.toFixed(2)}, above size^${exponent}`);
+}

package/src/electron/feature-map.ts

@@ -0,0 +1,93 @@
+// A feature map is "materialized memory" (Lauren Tan's term): every feature the app has, how a user reaches it, and
+// what verifies it, so an agent can read a vague bug report against it. It stays honest only if checked: every check it
+// cites must exist, and every feature must say how it's verified.
+//
+// Each feature is a `- **Name**` bullet followed by status lines: `✅ <journey> › "<check name>"`, `✅ <journey>` (the
+// whole journey), a project's own citations (`✅ server › <script>.ts`), or `❌ <why it isn't verified>`.
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { JourneySession } from "./session.ts";
+
+type Journeys = Record<string, { readonly run: (session: never) => Promise<void> }>;
+
+/** Another kind of citation: what it looks like, and what's wrong with one (undefined when what it names exists). */
+export interface Citation {
+	readonly pattern: RegExp;
+	readonly broken: (match: RegExpExecArray) => string | undefined;
+}
+
+/** Check names per function in the journey sources (`<session>.check("…")`); `${…}` in a name matches anything. */
+function checksByFunction(folder: string, session: string): Map<string, RegExp[]> {
+	const byFunction = new Map<string, RegExp[]>();
+	const call = new RegExp(`${session}\\.check\\(\\s*(["\`])([\\s\\S]*?)\\1`, "g");
+	for (const file of readdirSync(folder).filter((name) => name.endsWith(".ts"))) {
+		const source = readFileSync(join(folder, file), "utf8");
+		const starts = [...source.matchAll(/^(?:export )?async function (\w+)\(/gm)];
+		starts.forEach((start, index) => {
+			const body = source.slice(start.index, starts[index + 1]?.index ?? source.length);
+			const names = [...body.matchAll(call)].map(([, , name]) => {
+				const pattern = name!.split(/\$\{[^}]*\}/).map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".+");
+				return new RegExp(`^${pattern}$`);
+			});
+			byFunction.set(start[1]!, names);
+		});
+	}
+	return byFunction;
+}
+
+/** What's wrong with a `✅` line's citation, or undefined when it names something that exists. */
+function brokenCitation(cited: string, journeys: Journeys, checksOf: (journey: string) => RegExp[], citations: readonly Citation[]): string | undefined {
+	for (const { pattern, broken } of citations) {
+		const match = pattern.exec(cited);
+		if (match !== null) return broken(match);
+	}
+	const [, journey, check] = /^([\w-]+)(?: › "(.+)")?$/.exec(cited) ?? [];
+	if (journey === undefined || journeys[journey] === undefined) return `no journey in "${cited}"`;
+	if (check !== undefined && !checksOf(journey).some((pattern) => pattern.test(check))) return `${journey} has no check "${check}"`;
+	return undefined;
+}
+
+/**
+ * The map's problems, and how many features it has and how many have gaps. `folder` holds the journey sources, whose
+ * functions not named by a journey are helpers, so their checks count for every journey.
+ */
+export function readFeatureMap({ map, folder, journeys, citations = [], session = "session" }: {
+	map: string;
+	folder: string;
+	journeys: Journeys;
+	citations?: readonly Citation[];
+	session?: string;
+}): { broken: string[]; unmarked: string[]; features: number; gaps: number } {
+	const byFunction = checksByFunction(folder, session);
+	const isJourney = (name: string) => Object.values(journeys).some((journey) => journey.run.name === name);
+	const helpers = [...byFunction].filter(([name]) => !isJourney(name)).flatMap(([, names]) => names);
+	const checksOf = (journey: string) => [...(byFunction.get(journeys[journey]!.run.name) ?? []), ...helpers];
+	const broken: string[] = [];
+	const features: { name: string; statuses: string[] }[] = [];
+	for (const [index, line] of readFileSync(map, "utf8").split("\n").entries()) {
+		const feature = /^\s*- \*\*(.+?)\*\*/.exec(line);
+		const status = /^\s*- (✅|❌) (.*)$/.exec(line);
+		if (feature !== null) features.push({ name: feature[1]!, statuses: [] });
+		else if (status === null) continue;
+		else if (features.length === 0) broken.push(`line ${index + 1}: a status outside any feature`);
+		else {
+			features.at(-1)!.statuses.push(status[1]!);
+			const problem = status[1] === "✅" ? brokenCitation(status[2]!, journeys, checksOf, citations) : undefined;
+			if (problem !== undefined) broken.push(`line ${index + 1}: ${problem}`);
+		}
+	}
+	return {
+		broken,
+		unmarked: features.filter((feature) => feature.statuses.length === 0).map((feature) => feature.name),
+		features: features.length,
+		gaps: features.filter((feature) => feature.statuses.includes("❌")).length,
+	};
+}
+
+/** The feature-map journey's checks: every citation resolves, and every feature says how it's verified. */
+export function checkFeatureMap(session: JourneySession, options: Parameters<typeof readFeatureMap>[0]): void {
+	const { broken, unmarked, features, gaps } = readFeatureMap(options);
+	session.check("Every check the feature map cites exists", broken.length === 0, broken.slice(0, 10).join("; "));
+	session.check("Every feature in the map says how it is verified", unmarked.length === 0, unmarked.slice(0, 10).join(", "));
+	console.log(`  ${features} features: ${features - gaps} verified, ${gaps} with gaps (❌ in ${relative(process.cwd(), options.map)})`);
+}

package/src/electron/frames.ts

@@ -0,0 +1,91 @@
+// Frame rates: whatever the app shows or does, it keeps drawing at 60 frames per second or more. A scenario samples
+// every frame the renderer draws (requestAnimationFrame) while it runs, plus the long animation frames Chromium
+// reports, and checks the average rate and the longest frame. Displays faster than 60 Hz pass as long as no frame takes
+// longer than two 60 Hz frames. A slow frame's details say where its time went: tasks, callbacks, or style and layout.
+import type { JourneySession } from "./session.ts";
+
+/** At least this many frames per second on average; a little under 60 for timer jitter. */
+const MIN_FPS = 58;
+/** No frame longer than this: one dropped frame at 60 Hz is a hitch nobody sees, two in a row are. */
+const MAX_FRAME_MS = 35;
+/** Sample at least this long, so a short action still says something about the rate. */
+const MIN_SAMPLE_MS = 1000;
+
+// Plain script text, so tsx's helpers don't leak into the page.
+export const FRAME_SAMPLER = `globalThis.__fps = {
+	start() {
+		const state = { times: [], slow: [], running: true };
+		const tick = (time) => {
+			if (!state.running) return;
+			state.times.push(time);
+			requestAnimationFrame(tick);
+		};
+		requestAnimationFrame(tick);
+		state.observer = new PerformanceObserver((list) => {
+			for (const entry of list.getEntries()) {
+				const end = entry.startTime + entry.duration;
+				state.slow.push({
+					duration: Math.round(entry.duration),
+					// Where the frame went: tasks before rendering, rAF and observer callbacks, then style and layout.
+					tasks: Math.round((entry.renderStart || end) - entry.startTime),
+					callbacks: Math.round(entry.renderStart ? entry.styleAndLayoutStart - entry.renderStart : 0),
+					layout: Math.round(entry.styleAndLayoutStart ? end - entry.styleAndLayoutStart : 0),
+					scripts: (entry.scripts ?? []).slice(0, 3).map((script) =>
+						\`\${script.invoker || script.invokerType} \${Math.round(script.duration)}ms \${(script.sourceURL ?? "").split("/").pop()}\`),
+				});
+			}
+		});
+		try { state.observer.observe({ type: "long-animation-frame" }); } catch {}
+		this.state = state;
+	},
+	stop() {
+		const state = this.state;
+		state.running = false;
+		state.observer.disconnect();
+		return { times: state.times, slow: state.slow };
+	},
+};`;
+
+export interface Sample {
+	readonly scenario: string;
+	readonly fps: number;
+	readonly longestMs: number;
+	readonly p99Ms: number;
+	readonly frames: number;
+	readonly seconds: number;
+	readonly slowFrames: { duration: number; tasks: number; callbacks: number; layout: number; scripts: string[] }[];
+}
+
+/** Run `action` while sampling frames (the page has run `FRAME_SAMPLER`), record the numbers in `samples`, and check them. */
+export async function measureFrames(session: JourneySession, samples: Sample[], scenario: string, action: () => Promise<unknown>): Promise<void> {
+	const { page } = session;
+	await page.evaluate("globalThis.__fps.start()");
+	const started = Date.now();
+	await action();
+	const left = MIN_SAMPLE_MS - (Date.now() - started);
+	if (left > 0) await session.wait(left);
+	const { times, slow } = (await page.evaluate("globalThis.__fps.stop()")) as { times: number[]; slow: Sample["slowFrames"] };
+	const intervals = times.slice(1).map((time, index) => time - times[index]!);
+	const sorted = [...intervals].sort((a, b) => a - b);
+	const seconds = (times.at(-1)! - times[0]!) / 1000;
+	const sample: Sample = {
+		scenario,
+		fps: Math.round((intervals.length / seconds) * 10) / 10,
+		longestMs: Math.round(sorted.at(-1) ?? Infinity),
+		p99Ms: Math.round(sorted[Math.floor(sorted.length * 0.99)] ?? Infinity),
+		frames: intervals.length,
+		seconds: Math.round(seconds * 10) / 10,
+		slowFrames: slow,
+	};
+	samples.push(sample);
+	const culprit = slow.toSorted((a, b) => b.duration - a.duration)[0];
+	session.check(
+		`${scenario}: at least 60 FPS`,
+		sample.fps >= MIN_FPS && sample.longestMs <= MAX_FRAME_MS,
+		`${sample.fps} fps, longest frame ${sample.longestMs}ms, p99 ${sample.p99Ms}ms over ${sample.seconds}s` +
+			(culprit === undefined
+				? ""
+				: `; slowest: ${culprit.duration}ms (tasks ${culprit.tasks}ms, callbacks ${culprit.callbacks}ms, style and layout ${culprit.layout}ms)` +
+					(culprit.scripts.length === 0 ? "" : ` in ${culprit.scripts.join(", ")}`)),
+	);
+}

package/src/electron/geometry.ts

@@ -0,0 +1,101 @@
+// Layout held as relationships between boxes rather than pixels: this edge meets that one, this box doesn't overlap
+// that one, every control shown can be clicked where it's drawn. Screenshots change with live times, fonts and motion;
+// these hold whatever the content.
+import type { Locator, Page } from "playwright-core";
+
+export interface Box {
+	readonly left: number;
+	readonly top: number;
+	readonly right: number;
+	readonly bottom: number;
+}
+
+/** Half a pixel, for subpixel layout. */
+const SLACK = 0.5;
+
+/** `locator`'s box in the window, or a failure naming `what` when it isn't shown. */
+export async function box(locator: Locator, what: string): Promise<Box> {
+	const found = await locator.boundingBox();
+	if (found === null) throw new Error(`${what} isn't shown`);
+	return { left: found.x, top: found.y, right: found.x + found.width, bottom: found.y + found.height };
+}
+
+export const inside = (inner: Box, outer: Box): boolean =>
+	inner.left >= outer.left - SLACK && inner.right <= outer.right + SLACK && inner.top >= outer.top - SLACK && inner.bottom <= outer.bottom + SLACK;
+
+/** `upper` ends at least `gap` above where `lower` starts. */
+export const above = (upper: Box, lower: Box, gap = 0): boolean => upper.bottom + gap <= lower.top + SLACK;
+
+export const apart = (a: Box, b: Box): boolean => a.right <= b.left + SLACK || b.right <= a.left + SLACK || above(a, b) || above(b, a);
+
+export const near = (a: number, b: number, within = 1): boolean => Math.abs(a - b) <= within;
+
+/** The boxes, rounded, for a failure's details. */
+export const shown = (boxes: Record<string, Box>): string =>
+	JSON.stringify(Object.fromEntries(Object.entries(boxes).map(([name, { left, top, right, bottom }]) => [name, [left, top, right, bottom].map(Math.round)])));
+
+/**
+ * The controls under `root` that are shown but can't be clicked where they're drawn: cut off by a box that clips them
+ * (or by the window), covered by something else at their centre, or letting clicks through to what's beneath. A
+ * control scrolled out of view, or partly out of a box that scrolls that way, is fine; one cut off across the way its
+ * box scrolls (a row wider than a sidebar that only scrolls up and down) is not. Invisible ones (hover actions at
+ * opacity 0) aren't shown.
+ */
+export async function hiddenControls(page: Page, root: string): Promise<string[]> {
+	// tsx names the functions inside, with a helper the page doesn't have.
+	await page.evaluate("globalThis.__name ??= (target) => target;");
+	return page.evaluate((root) => {
+		const name = (element: Element) => {
+			const label = element.getAttribute("aria-label") ?? element.getAttribute("title") ?? element.textContent?.trim().slice(0, 40);
+			return `${element.tagName.toLowerCase()} "${label ?? ""}"`;
+		};
+		const where = (element: Element) => `${element.tagName.toLowerCase()}.${[...element.classList].slice(0, 4).join(".")}`;
+		/** Drawn at all: some size, and neither hidden nor faded out (with its ancestors). */
+		const drawn = (control: Element, rect: DOMRect) => {
+			if (rect.width === 0 || rect.height === 0) return false;
+			let opacity = 1;
+			for (let node: Element | null = control; node !== null; node = node.parentElement) {
+				const style = getComputedStyle(node);
+				if (style.visibility === "hidden" || style.display === "none") return false;
+				opacity *= Number(style.opacity);
+			}
+			return opacity >= 0.05;
+		};
+		/** The boxes that clip `control`, innermost first, each with whether it scrolls up and down; then the window. */
+		const clips = (control: Element) => {
+			const found: Array<{ clip: DOMRect; label: string; scrolls: boolean }> = [];
+			for (let node = control.parentElement; node !== null && node !== document.documentElement; node = node.parentElement) {
+				const style = getComputedStyle(node);
+				if (style.overflowX === "visible" && style.overflowY === "visible") continue;
+				found.push({ clip: node.getBoundingClientRect(), label: where(node), scrolls: style.overflowY === "auto" || style.overflowY === "scroll" });
+			}
+			found.push({ clip: new DOMRect(0, 0, window.innerWidth, window.innerHeight), label: "the window", scrolls: false });
+			return found;
+		};
+		/** "away" when `rect` is scrolled (wholly or partly) out of a box that scrolls, else the box cutting it off, if any. */
+		const cutOff = (rect: DOMRect, control: Element) => {
+			for (const { clip, label, scrolls } of clips(control)) {
+				if (rect.right <= clip.left || rect.left >= clip.right || rect.bottom <= clip.top || rect.top >= clip.bottom) return "away";
+				const across = rect.left < clip.left - 0.5 || rect.right > clip.right + 0.5;
+				const along = rect.top < clip.top - 0.5 || rect.bottom > clip.bottom + 0.5;
+				if (across || (along && !scrolls)) return label;
+				if (along) return "away";
+			}
+			return undefined;
+		};
+		const problem = (control: Element) => {
+			const rect = control.getBoundingClientRect();
+			if (!drawn(control, rect)) return [];
+			const cut = cutOff(rect, control);
+			if (cut === "away") return [];
+			if (cut !== undefined) return [`${name(control)} is cut off by ${cut}`];
+			const hit = document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+			if (hit === null || control.contains(hit)) return [];
+			// Under its own box, a click only reaches an ancestor when the control lets it through (pointer-events: none).
+			return [hit.contains(control) ? `${name(control)} lets clicks through to ${where(hit)}` : `${name(control)} is covered by ${where(hit)}`];
+		};
+		const scope = document.querySelector(root);
+		if (scope === null) return [`${root} isn't shown`];
+		return [...scope.querySelectorAll('button, a[href], input:not([type="hidden"]), textarea, select, [role="tab"], [role="menuitem"]')].flatMap(problem);
+	}, root);
+}

package/src/electron/journey-lint.mjs

@@ -0,0 +1,45 @@
+// A journey's check that reads the app reads it through a function, which the check polls: an `await` inside a plain
+// boolean reads once, racing whatever the app is still doing.
+// A check given a function returns a promise, so it must be awaited, or the journey goes on, and may end, before it's
+// recorded. Whether a check polls is its argument's type (a function, written in place or named), so the type checker
+// decides it, not the syntax.
+import { readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { lineOf } from "../core/ratchet.mjs";
+import ts from "typescript";
+
+const isFunction = (node) => ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node);
+/** Awaits something itself, not in a function it defines. */
+const awaitsHere = (node) => ts.isAwaitExpression(node) || (!isFunction(node) && (ts.forEachChild(node, (child) => (awaitsHere(child) ? true : undefined)) ?? false));
+
+/**
+ * The checks in `source` (calls `<session>.check(label, ok, detail?)`) that read once, or whose polling nobody waits
+ * for, with their lines.
+ */
+export function readOnce(source, checker, session = "session") {
+	const found = [];
+	const visit = (node) => {
+		if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "check" && node.expression.expression.getText(source) === session) {
+			const [, ok, detail] = node.arguments;
+			const polled = ok !== undefined && (ts.isSpreadElement(ok) || checker.getTypeAtLocation(ok).getCallSignatures().length > 0);
+			const line = lineOf(source, node);
+			if (ok !== undefined && !polled && awaitsHere(ok)) found.push(`line ${line}: reads once, inside the check: pass a function, which the check polls until it holds`);
+			if (polled && detail !== undefined && !isFunction(detail) && awaitsHere(detail)) found.push(`line ${line}: reads its details before the check polls: pass them as a function, read on failure`);
+			if (polled && !ts.isAwaitExpression(node.parent)) found.push(`line ${line}: a polled check nobody awaits: the journey goes on, and may end, before it's recorded`);
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	return found;
+}
+
+/** Problems in the journeys (`.ts` files) of `root`/`folder`, type-checked with `tsconfig`'s options; and how many there were. */
+export function lintJourneys({ root, folder, tsconfig, session = "session" }) {
+	const base = join(root, folder);
+	const files = readdirSync(base).filter((name) => name.endsWith(".ts")).map((name) => join(base, name));
+	const config = ts.getParsedCommandLineOfConfigFile(join(root, tsconfig), {}, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => {} });
+	if (config === undefined) throw new Error(`Can't read ${tsconfig}`);
+	const program = ts.createProgram(files, config.options);
+	const checker = program.getTypeChecker();
+	return { files: files.length, problems: files.flatMap((file) => readOnce(program.getSourceFile(file), checker, session).map((problem) => `${relative(root, file)}: ${problem}`)) };
+}