@jterrazz/test 12.1.0 → 13.0.0

package/dist/checker.js

@@ -1,7 +1,497 @@
 #!/usr/bin/env node
-import { r as TOKEN_KINDS } from "./match.js";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { a as assertedStreams, d as isMap, f as isScalar, i as SpecSyntaxError, m as renderYamlSource, n as RUN_KEYS, o as parseSpecDocument, p as isSeq, r as SPEC_EXTENSION, s as readSpecFile, t as DOCUMENT_KEYS, u as Scalar } from "./spec-document.js";
+import { o as resolveFixtureSource, r as TOKEN_KINDS } from "./match.js";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
+//#region src/lint/checker-spec.ts
+function finding(rule, line, message, severity = "error") {
+	return {
+		line,
+		message,
+		rule,
+		severity
+	};
+}
+/** Directories the walks never enter — `fixtures/` holds INPUTS, never scenarios. */
+const PRUNED$1 = /* @__PURE__ */ new Set([
+	".git",
+	"dist",
+	"fixtures",
+	"node_modules"
+]);
+function listSpecFiles(dir) {
+	const out = [];
+	const visit = (current) => {
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const path = join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (!PRUNED$1.has(entry.name)) visit(path);
+			} else if (entry.name.endsWith(".spec.yaml")) out.push(path);
+		}
+	};
+	visit(dir);
+	return out;
+}
+function readText$1(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+function documentMap(file) {
+	const root = file.source.document.contents;
+	return isMap(root) ? root : null;
+}
+function pairsOf(map) {
+	return map.items;
+}
+function keyName(pair) {
+	return isScalar(pair.key) && typeof pair.key.value === "string" ? pair.key.value : null;
+}
+function runMaps(file) {
+	const runs = documentMap(file)?.get("runs", true);
+	return isSeq(runs) ? runs.items.filter((item) => isMap(item)) : [];
+}
+/** The stream scalars of one run — the values the block-scalar rule judges. */
+function streamScalars(run) {
+	const found = [];
+	for (const pair of pairsOf(run)) {
+		const key = keyName(pair);
+		if (key === null) continue;
+		if ([
+			"stderr",
+			"stdin",
+			"stdout"
+		].includes(key) && isScalar(pair.value)) {
+			found.push({
+				key,
+				scalar: pair.value
+			});
+			continue;
+		}
+		if (key !== "files" || !isMap(pair.value)) continue;
+		for (const entry of pairsOf(pair.value)) {
+			if (!isMap(entry.value)) continue;
+			for (const assertion of pairsOf(entry.value)) if (keyName(assertion) === "equals" && isScalar(assertion.value)) found.push({
+				key: `files.${keyName(entry) ?? "?"}.equals`,
+				scalar: assertion.value
+			});
+		}
+	}
+	return found;
+}
+function isBlock(scalar) {
+	return String(scalar.type ?? "").startsWith("BLOCK");
+}
+/**
+* The canonical order, top level and inside a run: the ground a session stands
+* on before the session, what was given to a command before what came back.
+* Two authors ordering differently make an unreadable diff out of an unchanged
+* document; a `runs:` above `env:` makes a reader meet the session before its
+* setup.
+*/
+function checkKeyOrder(file, lineAt) {
+	const findings = [];
+	const inspect = (map, order, where) => {
+		let highest = -1;
+		let highestKey = "";
+		for (const pair of pairsOf(map)) {
+			const key = keyName(pair);
+			const rank = key === null ? -1 : order.indexOf(key);
+			if (rank === -1) continue;
+			if (rank < highest) {
+				findings.push(finding("d4b-spec-key-order", lineAt(pair), `"${key}:" comes after "${highestKey}:" in ${where} — the canonical order is ${order.join(", ")} (fixable: \`node dist/checker.js <root> --fix\`)`));
+				return;
+			}
+			highest = rank;
+			highestKey = key ?? "";
+		}
+	};
+	const map = documentMap(file);
+	if (map !== null) inspect(map, DOCUMENT_KEYS, "a spec document");
+	for (const run of runMaps(file)) inspect(run, RUN_KEYS, "a run");
+	return findings;
+}
+/**
+* A stream is written as a block scalar (`|` or `|-`), never as a quoted string
+* with `\n` escapes. A one-line golden is unreadable, and no diff can show it:
+* the whole point of the format is that the expected output looks like output.
+*/
+function checkBlockScalars(file, lineOf) {
+	const findings = [];
+	for (const run of runMaps(file)) for (const { key, scalar } of streamScalars(run)) {
+		if (isBlock(scalar) || scalar.value === "") continue;
+		findings.push(finding("d4b-spec-block-scalar", lineOf(scalar), `${key} is a ${scalar.type === Scalar.PLAIN ? "plain" : "quoted"} scalar — a stream is written as a block scalar (\`|\` keeps the final newline, \`|-\` drops it) (fixable: \`node dist/checker.js <root> --fix\`)`));
+	}
+	return findings;
+}
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Words the `.spec.yaml` suffix already says — a case name repeating one says nothing. */
+const REDUNDANT_WORDS = /* @__PURE__ */ new Set([
+	"cli",
+	"spec",
+	"test"
+]);
+/**
+* The file is `<case>.spec.yaml`, and `<case>` NAMES the case: kebab-case, no
+* word the suffix already carries, and never the bare name of its directory —
+* a `rm/` folder holding `rm.spec.yaml` says nothing twice, where `removed`,
+* `unattended` and `missing` each say one thing.
+*/
+function checkFileName(rel) {
+	const name = basename(rel);
+	const caseName = name.slice(0, -SPEC_EXTENSION.length);
+	const findings = [];
+	if (!KEBAB.test(caseName)) {
+		findings.push(finding("c12-spec-file-name", 1, `"${name}" — <case> is kebab-case: lowercase words joined by single hyphens`));
+		return findings;
+	}
+	const redundant = caseName.split("-").filter((word) => REDUNDANT_WORDS.has(word));
+	if (redundant.length > 0) findings.push(finding("c12-spec-file-name", 1, `"${name}" repeats "${redundant[0]}" — the .spec.yaml suffix already says it; name the CASE instead`));
+	const folder = basename(dirname(rel));
+	if (caseName === folder) findings.push(finding("c12-spec-file-name", 1, `"${name}" repeats its directory "${folder}/" — name what this case proves, not where it sits`));
+	return findings;
+}
+const MAX_DESCRIPTION = 100;
+/** A first word that is an identifier, not prose — exempt from the lowercase rule. */
+const SYMBOL_WORD = /^[A-Z0-9_]+$/;
+/**
+* The description IS the vitest test title, and it is held to the title rules:
+* one lowercase line of prose, no trailing period, short enough to read in a
+* runner's output. A title that is a paragraph is a comment in the wrong place.
+*/
+function checkDescription(document) {
+	const findings = [];
+	const text = document.description;
+	const line = document.descriptionLine;
+	const at = (message) => finding("j5-spec-description", line, message);
+	if (text.includes("\n")) {
+		findings.push(at("description: is one line — the vitest title, not a paragraph"));
+		return findings;
+	}
+	if (text.length > MAX_DESCRIPTION) findings.push(at(`description: is ${text.length} characters — keep it under ${MAX_DESCRIPTION}`));
+	if (text.endsWith(".")) findings.push(at("description: ends with a period — a title is a fragment, not a sentence"));
+	const first = text.split(/\s+/)[0] ?? "";
+	if (/^[A-Z]/.test(text) && !SYMBOL_WORD.test(first)) findings.push(at("description: starts with a capital — a title is lowercase prose"));
+	return findings;
+}
+/** The literals the update writer must have failed to tokenise, and their token. */
+const VOLATILE = [
+	{
+		pattern: /\b(?:127\.0\.0\.1|localhost|0\.0\.0\.0):\d{2,5}\b/,
+		token: "{{url}} (or {{port}})"
+	},
+	{
+		pattern: /(?:^|[\s"'(=])(?:\/private)?\/tmp\//,
+		token: "{{workdir}}"
+	},
+	{
+		pattern: /(?:^|[\s"'(=])\/var\/folders\//,
+		token: "{{workdir}}"
+	},
+	{
+		pattern: /(?:^|[\s"'(=])\/(?:Users|home)\/[^\s"'/]+\//,
+		token: "{{workdir}} or {{path}}"
+	}
+];
+/**
+* A stream that pins a loopback port, a temp directory or somebody's home is a
+* golden that passed once, on one machine: the port was free that second, the
+* temp path belonged to that run. It is the exact shape of a value the update
+* writer would have tokenised, which is why finding one means a token was
+* overwritten by hand.
+*/
+function checkVolatileLiterals(document) {
+	const findings = [];
+	for (const stream of assertedStreams(document)) for (const [index, text] of stream.text.split("\n").entries()) for (const { pattern, token } of VOLATILE) {
+		const found = pattern.exec(text);
+		if (found === null) continue;
+		findings.push(finding("d5-spec-volatile-literal", stream.line + index, `"${found[0].trim()}" is a value the next run will not reproduce — write ${token}`));
+		break;
+	}
+	return findings;
+}
+const ISO8601 = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/;
+const UUID = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/;
+/** Everything the document itself FIXED: what it feeds in, and what its fixtures hold. */
+function fixedData(document, dir) {
+	const parts = document.runs.map((run) => run.stdin ?? "");
+	for (const fixture of document.fixtures) {
+		let source;
+		try {
+			source = resolveFixtureSource(fixture.path, dir);
+		} catch {
+			continue;
+		}
+		const visit = (path) => {
+			let stat;
+			try {
+				stat = statSync(path);
+			} catch {
+				return;
+			}
+			if (!stat.isDirectory()) {
+				parts.push(readText$1(path));
+				return;
+			}
+			for (const entry of readdirSync(path)) visit(join(path, entry));
+		};
+		visit(source);
+	}
+	return parts.join("\n");
+}
+/**
+* A timestamp or a uuid spelled out in a golden is a value nothing fixed —
+* unless the document DID fix it, by feeding it in through `stdin:` or shipping
+* it in a `fixture:`. That carve-out is the whole rule: the defect is not the
+* literal, it is the literal nobody pinned.
+*/
+function checkPinnedValues(document, dir) {
+	const findings = [];
+	const streams = assertedStreams(document);
+	if (streams.length === 0) return findings;
+	let fixed = null;
+	for (const stream of streams) for (const [index, text] of stream.text.split("\n").entries()) for (const [pattern, token] of [[ISO8601, "{{iso8601}}"], [UUID, "{{uuid}}"]]) {
+		const found = pattern.exec(text);
+		if (found === null) continue;
+		fixed ??= fixedData(document, dir);
+		if (fixed.includes(found[0])) continue;
+		findings.push(finding("d5w-spec-pinned-value", stream.line + index, `"${found[0]}" is not fixed by any fixture: or stdin: of this document — write ${token}`, "warn"));
+	}
+	return findings;
+}
+/**
+* A stream whose entire content is `{{any}}` states that the command printed
+* something, or nothing, of any shape — which is what a stream does anyway. The
+* run happens and proves nothing.
+*/
+function checkEmptyAssertions(document) {
+	const findings = [];
+	for (const stream of assertedStreams(document)) if (stream.text.replaceAll("{{any}}", "").trim() === "" && stream.text.includes("{{any}}")) findings.push(finding("j3w-spec-empty-assertion", stream.line, "a stream that is only {{any}} asserts nothing — golden what the command actually printed", "warn"));
+	return findings;
+}
+/**
+* A non-zero exit with neither stream is a CLI that failed without a word — or,
+* far more often, a golden whose author forgot that the words went to stderr.
+* Either way the document does not say WHY the command refused.
+*/
+function checkSilentRefusals(document) {
+	return document.runs.filter((run) => run.exitCode !== 0 && run.stdout === null && run.stderr === null).map((run) => finding("d11w-spec-silent-refusal", run.commandLine, `exit: ${run.exitCode} with no stdout: and no stderr: — golden the words the refusal printed`, "warn"));
+}
+/** The top-level keys of an object literal, read by depth, not by parsing. */
+function objectKeys(source, from) {
+	const keys = [];
+	let depth = 0;
+	let quote = "";
+	for (let index = from; index < source.length; index += 1) {
+		const char = source[index];
+		if (quote !== "") {
+			if (char === quote && source[index - 1] !== "\\") quote = "";
+			continue;
+		}
+		if (char === "'" || char === "\"" || char === "`") {
+			quote = char;
+			continue;
+		}
+		if (char === "{" || char === "[" || char === "(") {
+			depth += 1;
+			continue;
+		}
+		if (char === "}" || char === "]" || char === ")") {
+			depth -= 1;
+			if (depth === 0) return {
+				end: index,
+				keys
+			};
+			continue;
+		}
+		if (depth === 1 && /[A-Za-z_$'"]/.test(char)) {
+			const rest = /^(?<quote>['"]?)(?<name>[A-Za-z_$][\w$]*)\k<quote>\s*:/.exec(source.slice(index));
+			if (rest?.groups) {
+				keys.push(rest.groups.name);
+				index += rest[0].length - 1;
+			}
+		}
+	}
+	return {
+		end: source.length,
+		keys
+	};
+}
+/**
+* The `env` and `serve` names registered by the `specification.cli(…)` calls of
+* the nearest directory holding a `*.specification.ts`, read as literals. A
+* directory may declare several runners, and nothing in a document says which
+* one runs it, so their registries are read as a UNION: a name known to any
+* neighbouring runner passes, and only a name known to none is a typo.
+*/
+function registeredNames(dir) {
+	let current = dir;
+	for (;;) {
+		let entries;
+		try {
+			entries = readdirSync(current).filter((name) => name.endsWith(".specification.ts"));
+		} catch {
+			entries = [];
+		}
+		if (entries.length > 0) {
+			const env = /* @__PURE__ */ new Set();
+			const serve = /* @__PURE__ */ new Set();
+			for (const entry of entries) {
+				const text = readText$1(join(current, entry));
+				for (const call of text.matchAll(/specification\.cli\s*\(/g)) {
+					const open = text.indexOf("{", call.index + call[0].length);
+					if (open === -1) continue;
+					const options = objectKeys(text, open);
+					for (const [key, into] of [["env", env], ["serve", serve]]) {
+						const marker = new RegExp(String.raw`\b${key}\s*:\s*\{`).exec(text.slice(open, options.end));
+						if (marker === null) continue;
+						const at = open + marker.index + marker[0].length - 1;
+						for (const name of objectKeys(text, at).keys) into.add(name);
+					}
+				}
+			}
+			return {
+				env,
+				serve
+			};
+		}
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+/**
+* Every bare word of `env:` and every `serve:` name must be a key of a runner
+* registered above the document. A typo (`serve: dashbord`) is a refusal at
+* run time today, one test file into a suite; here it is a line in a lint run.
+*/
+function checkRegisteredNames(document, dir) {
+	if (document.env.length === 0 && document.serve.length === 0) return [];
+	const registered = registeredNames(dir);
+	if (registered === null) return [];
+	const findings = [];
+	for (const token of document.env) if (token.kind === "set" && !registered.env.has(token.name)) findings.push(finding("c8-spec-registered-name", token.line, `env: "${token.name}" is not a registered env set${registered.env.size === 0 ? "" : ` — registered: ${[...registered.env].sort().join(", ")}`}`));
+	for (const entry of document.serve) if (!registered.serve.has(entry.name)) findings.push(finding("c8-spec-registered-name", entry.line, `serve: "${entry.name}" is not a registered server${registered.serve.size === 0 ? "" : ` — registered: ${[...registered.serve].sort().join(", ")}`}`));
+	return findings;
+}
+/**
+* Run every document-conventions pass over one `<case>.spec.yaml`. A document
+* the grammar refuses yields NOTHING here: `d4b-spec-shape` already reported
+* it, and a second cascade of findings about a file nobody can parse only
+* buries the one line that matters.
+*/
+function checkSpecConventions(text, rel, path) {
+	let file;
+	try {
+		file = readSpecFile(text, rel);
+	} catch {
+		return [];
+	}
+	const lineAt = (node) => {
+		const range = "range" in node && Array.isArray(node.range) ? node.range : void 0;
+		const key = node.key;
+		const target = range ?? (isScalar(key) && Array.isArray(key.range) ? key.range : void 0);
+		return target === void 0 ? 1 : file.source.lineAt(target[0]);
+	};
+	const dir = dirname(path);
+	return [
+		...checkKeyOrder(file, (pair) => lineAt(pair.key)),
+		...checkBlockScalars(file, (scalar) => lineAt(scalar)),
+		...checkFileName(rel),
+		...checkDescription(file.document),
+		...checkVolatileLiterals(file.document),
+		...checkPinnedValues(file.document, dir),
+		...checkEmptyAssertions(file.document),
+		...checkSilentRefusals(file.document),
+		...checkRegisteredNames(file.document, dir)
+	].map(({ line, message, rule, severity }) => ({
+		file: rel,
+		line,
+		message: `${rel}:${line}: ${message} (${rule} — see docs/10-linting.md)`,
+		severity
+	}));
+}
+/**
+* J4-spec-description-unique — the description is the test title, and two
+* documents in one directory sharing it make a failing run ambiguous: the
+* reporter names the title, and the reader has two files to open.
+*/
+function checkSpecDescriptionsUnique(rootDir) {
+	const byDirectory = /* @__PURE__ */ new Map();
+	const violations = [];
+	for (const path of listSpecFiles(rootDir)) {
+		let document;
+		try {
+			document = readSpecFile(readText$1(path), path).document;
+		} catch {
+			continue;
+		}
+		const dir = dirname(path);
+		const seen = byDirectory.get(dir) ?? /* @__PURE__ */ new Map();
+		byDirectory.set(dir, seen);
+		const first = seen.get(document.description);
+		const rel = relative(rootDir, path);
+		if (first === void 0) {
+			seen.set(document.description, rel);
+			continue;
+		}
+		violations.push({
+			file: rel,
+			line: document.descriptionLine,
+			message: `${rel}:${document.descriptionLine}: "${document.description}" is already the description of ${first} — two documents of one directory cannot share a title (j4-spec-description-unique — see docs/10-linting.md)`,
+			severity: "error"
+		});
+	}
+	return violations;
+}
+/**
+* Apply the two fixable passes to one document: reorder its keys, and re-style
+* every stream as a block scalar. Returns `null` when nothing moved — the
+* caller writes only what changed, so a clean tree keeps its mtimes.
+*/
+function fixSpecDocument(text, rel) {
+	let file;
+	try {
+		file = readSpecFile(text, rel);
+	} catch {
+		return null;
+	}
+	const reorder = (map, order) => {
+		const sorted = [...pairsOf(map).filter((pair) => order.includes(keyName(pair) ?? ""))].sort((a, b) => order.indexOf(keyName(a)) - order.indexOf(keyName(b)));
+		let cursor = 0;
+		map.items = pairsOf(map).map((pair) => order.includes(keyName(pair) ?? "") ? sorted[cursor++] : pair);
+	};
+	const map = documentMap(file);
+	if (map === null) return null;
+	reorder(map, DOCUMENT_KEYS);
+	for (const run of runMaps(file)) {
+		reorder(run, RUN_KEYS);
+		for (const { scalar } of streamScalars(run)) if (!isBlock(scalar) && scalar.value !== "") scalar.type = Scalar.BLOCK_LITERAL;
+	}
+	const next = renderYamlSource(file.source);
+	return next === text ? null : next;
+}
+/** Fix every `<case>.spec.yaml` under `rootDir`; returns the paths rewritten. */
+function fixSpecFiles(rootDir) {
+	const written = [];
+	for (const path of listSpecFiles(rootDir)) {
+		const next = fixSpecDocument(readText$1(path), relative(rootDir, path));
+		if (next !== null) {
+			writeFileSync(path, next);
+			written.push(relative(rootDir, path));
+		}
+	}
+	return written;
+}
+//#endregion
 //#region src/lint/checker-crossfile.ts
 /**
 * The cross-file checker passes — the analyses oxlint cannot express because
@@ -17,7 +507,9 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 *
 * - **C9 dead fixtures** — per feature dir, a fixture file no test literal
 *   references is dead weight; a feature dir with conventional subdirs but no
-*   `<feature>.test.ts` is an orphan.
+*   `<feature>.test.ts` is an orphan. A `<case>.spec.yaml` counts as a test
+*   AND as a referrer: the paths of its `fixture:` entries keep those trees
+*   alive exactly as a `.fixture('…')` literal does.
 * - **B5 await-using (inference)** — the docker-aware runners of a spec file
 *   are derived from its `docker:` option, then every `<runner>….exec()` bound
 *   without `await using` in an importing test is flagged. The primary B5
@@ -160,6 +652,23 @@ function blankComments(text) {
 function readSource(path) {
 	return blankComments(readText(path));
 }
+/**
+* The fixture paths a `<case>.spec.yaml` names — its referrer literals. The
+* runner's own parser reads them, so the two channels cannot disagree about
+* what the document says; an unparseable file vouches for nothing (the
+* `d4b-spec-shape` pass is what reports it).
+*/
+function collectSpecLiterals(path) {
+	try {
+		return new Set(parseSpecDocument(readText(path), path).fixtures.map((fixture) => fixture.path));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+/** Is this a file a domain's assets may be referenced from? */
+function isReferrer(name) {
+	return name.endsWith(".test.ts") || name.endsWith(".spec.yaml");
+}
 function isDir(path) {
 	try {
 		return statSync(path).isDirectory();
@@ -478,13 +987,13 @@ function checkDeadFixtures(rootDir) {
 		const convSubdirs = entries.filter((entry) => entry.isDirectory() && CONVENTIONAL_SUBDIRS.has(entry.name) && isConventionalSubdir(join(dir, entry.name))).map((entry) => entry.name);
 		if (convSubdirs.length === 0) continue;
 		const feature = basename(dir);
-		const testFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".test.ts")).map((entry) => join(dir, entry.name));
+		const testFiles = entries.filter((entry) => entry.isFile() && isReferrer(entry.name)).map((entry) => join(dir, entry.name));
 		const rel = relative(rootDir, dir);
 		if (testFiles.length === 0) {
 			violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}: domain directory has conventional subdirs (${convSubdirs.join(", ")}) but no *.test.ts (C9 — see docs/10-linting.md)`,
+				message: `${rel}: domain directory has conventional subdirs (${convSubdirs.join(", ")}) but no *.test.ts or *.spec.yaml (C9 — see docs/10-linting.md)`,
 				severity: "error"
 			});
 			continue;
@@ -492,6 +1001,10 @@ function checkDeadFixtures(rootDir) {
 		const literals = /* @__PURE__ */ new Set();
 		let downgrade = false;
 		for (const testFile of testFiles) {
+			if (testFile.endsWith(".spec.yaml")) {
+				for (const literal of collectSpecLiterals(testFile)) literals.add(literal);
+				continue;
+			}
 			const text = readSource(testFile);
 			for (const literal of collectLiterals(text)) literals.add(literal);
 			downgrade ||= hasNonLiteralFixtureArg(text);
@@ -521,9 +1034,10 @@ function checkPoolFixtures(rootDir) {
 	for (const pool of findPools(rootDir)) {
 		const specsRoot = dirname(pool);
 		const literals = /* @__PURE__ */ new Set();
-		for (const file of listFiles(specsRoot, (path) => path.endsWith(".ts"))) {
+		for (const file of listFiles(specsRoot, (path) => path.endsWith(".ts") || path.endsWith(".spec.yaml"))) {
 			if (file.startsWith(`${pool}/`) || file.startsWith(`${pool}\\`)) continue;
-			for (const literal of collectLiterals(readSource(file))) literals.add(literal);
+			const found = file.endsWith(".spec.yaml") ? collectSpecLiterals(file) : collectLiterals(readSource(file));
+			for (const literal of found) literals.add(literal);
 		}
 		for (const entry of readdirSync(pool, { withFileTypes: true })) if (![...literals].some((literal) => literal.includes(entry.name))) {
 			const relEntry = relative(rootDir, join(pool, entry.name));
@@ -551,7 +1065,12 @@ function checkPoolFixtures(rootDir) {
 * - the **HTTP first-line grammar** of depth-1 `requests/*.http` (a request line)
 *   and `expected/*.http` (a status line) (D4b);
 * - **tokens leaking into `requests/`** — requests are inputs, never matched, so
-*   a `{{token}}` there is almost always a mistake (D10, warning).
+*   a `{{token}}` there is almost always a mistake (D10, warning);
+* - the **`<case>.spec.yaml` grammar** wherever a scenario document sits: its
+*   shape (D4b), read through the runner's own parser, plus the token
+*   vocabulary of its streams (D4);
+* - the **document conventions** — key order, naming, description, block
+*   scalars, pinned values, registered names — bundled in `checker-spec.ts`.
 *
 * It shares TOKEN_KINDS with the runtime matcher so the channels cannot drift.
 */
@@ -632,6 +1151,41 @@ function firstLine(text) {
 const REQUEST_LINE = /^(?<method>GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) \/\S*/;
 const STATUS_LINE = /^HTTP\/\d(?:\.\d)? \d{3}\b/;
 /**
+* Check one `<case>.spec.yaml` — D4b's shape through the SAME parser the runner
+* uses (one grammar, no drift), then D4's token vocabulary over the STREAMS
+* only: a `{{token}}` in a description or a command is text, never a
+* placeholder, and `stdin:` is an input the comparison never reads.
+*
+* Precision over recall, as everywhere in this channel: the parser refuses at
+* the first defect, so one document reports one grammar violation per run.
+*/
+function checkSpecFile(text, rel) {
+	let document;
+	try {
+		document = readSpecFile(text, rel).document;
+	} catch (error) {
+		if (!(error instanceof SpecSyntaxError)) throw error;
+		return [{
+			file: rel,
+			line: error.line,
+			message: `${error.message} (D4b — see docs/10-linting.md)`,
+			severity: "error"
+		}];
+	}
+	const violations = [];
+	for (const stream of assertedStreams(document)) for (const { line, token } of findUnknownTokens(stream.text)) {
+		const at = stream.line + line - 1;
+		violations.push({
+			file: rel,
+			line: at,
+			message: `${rel}:${at}: unknown token ${token} — the D4 vocabulary is frozen (known: ${[...TOKEN_KINDS].join(", ")})`,
+			severity: "error",
+			token
+		});
+	}
+	return violations;
+}
+/**
 * Walk `rootDir` and check every fixture file. Paths in the result are relative
 * to `rootDir`. Errors fail the checker; warnings are advisory.
 */
@@ -653,6 +1207,14 @@ function checkConventionFiles(rootDir) {
 				visit(path, next);
 				continue;
 			}
+			if (entry.name.endsWith(".spec.yaml")) {
+				const text = decodeText(path);
+				if (text !== null) {
+					violations.push(...checkSpecFile(text, rel));
+					violations.push(...checkSpecConventions(text, rel, path));
+				}
+				continue;
+			}
 			if (inside === null) continue;
 			const depth1 = dir.endsWith(`/${inside}`) || dir.endsWith(`\\${inside}`);
 			if (inside === "requests") {
@@ -702,6 +1264,7 @@ function checkConventionFiles(rootDir) {
 function runAllChecks(rootDir) {
 	return [
 		...checkConventionFiles(rootDir),
+		...checkSpecDescriptionsUnique(rootDir),
 		...checkDeadFixtures(rootDir),
 		...checkDockerRunnerAwaitUsing(rootDir),
 		...checkDatabaseProperty(rootDir)
@@ -716,18 +1279,27 @@ function formatViolations(violations) {
 /**
 * CLI entry for the conventions checker (bundled as `dist/checker.js`).
 *
-*     node dist/checker.js [rootDir]     # default: cwd
+*     node dist/checker.js [rootDir] [--fix]     # default root: cwd
 *
-* Runs every checker pass — the token/HTTP grammar (D4 / D4b / D10) and the
-* cross-file passes (C9 dead fixtures, B5 await-using inference, A7 database
-* property). Exit 1 on any ERROR-level violation; warnings (D10, a downgraded
-* C9 feature) are printed but do not fail the run.
+* Runs every checker pass — the token/HTTP grammar (D4 / D4b / D10), the
+* `<case>.spec.yaml` document conventions, and the cross-file passes (C9 dead
+* fixtures, B5 await-using inference, A7 database property). Exit 1 on any
+* ERROR-level violation; warnings (D10, a downgraded C9 feature) are printed
+* but do not fail the run.
+*
+* `--fix` first applies the two rewritable document passes (key order and block
+* scalars), then checks what is left — so a run that fixes everything exits 0.
 */
-const root = resolve(process.argv[2] ?? ".");
+const fix = process.argv.includes("--fix");
+const root = resolve(process.argv.slice(2).find((arg) => !arg.startsWith("--")) ?? ".");
 if (!existsSync(root) || !statSync(root).isDirectory()) {
 	console.error(`conventions checker: no such directory: ${root}`);
 	process.exit(1);
 }
+if (fix) {
+	const written = fixSpecFiles(root);
+	if (written.length > 0) console.log(`conventions checker: rewrote ${written.length} spec document(s)`);
+}
 const violations = runAllChecks(root);
 const errors = violations.filter((violation) => violation.severity === "error");
 if (violations.length > 0) (errors.length > 0 ? console.error : console.warn)(formatViolations(violations));
@@ -735,6 +1307,6 @@ if (errors.length > 0) {
 	console.error(`\nconventions checker: ${errors.length} error(s) found under ${root}`);
 	process.exit(1);
 }
-console.log(`conventions checker: all passes clean under ${root} (D4/D4b/D10 grammar, C9 dead fixtures, B5 await-using, A7 database)${violations.length > 0 ? ` — ${violations.length} warning(s)` : ""}`);
+console.log(`conventions checker: all passes clean under ${root} (D4/D4b/D10 grammar, spec documents, C9 dead fixtures, B5 await-using, A7 database)${violations.length > 0 ? ` — ${violations.length} warning(s)` : ""}`);
 //#endregion
 export {};