@jterrazz/test 15.3.0 → 16.1.0

package/dist/checker.js

@@ -1,9 +1,86 @@
 #!/usr/bin/env node
-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 { c as GROUND_EXPECTED, l as GROUND_FIXTURES, o as resolveFixtureSource, r as TOKEN_KINDS, s as GROUND_DIRS, u as GROUND_REQUESTS } from "./match.js";
+import { _ as isSeq, a as DOCUMENT_KEYS, c as SpecSyntaxError, d as readSpecFile, g as isScalar, h as isMap, l as assertedStreams, m as Scalar, o as RUN_KEYS, r as TOKEN_KINDS, s as SPEC_EXTENSION, u as parseSpecDocument, v as renderYamlSource } from "./match.js";
+import { a as GROUND_FIXTURES, i as GROUND_EXPECTED, n as resolveFixtureSource, o as GROUND_REQUESTS, r as GROUND_DIRS, s as GROUND_SEEDS } from "./fixtures.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
+//#region src/lint/fs-cache.ts
+const kinds = /* @__PURE__ */ new Map();
+function kindOf(path) {
+	const cached = kinds.get(path);
+	if (cached !== void 0) return cached;
+	let result;
+	try {
+		result = statSync(path).isDirectory() ? "dir" : "file";
+	} catch {
+		result = "missing";
+	}
+	kinds.set(path, result);
+	return result;
+}
+function isFile(path) {
+	return kindOf(path) === "file";
+}
+//#endregion
+//#region src/lint/ast.ts
+/**
+* The `specs/` directory a file belongs to: the NEAREST ancestor named `specs`,
+* searched no higher than the nearest `package.json`. `undefined` when the file
+* is not under one.
+*
+* One anchor for every specs-aware rule, because two searches are two
+* answers: an innermost match and an outermost one read a nested tree as two
+* different facets, and a bare "is `specs` a segment of this path" test
+* answers about the machine — a checkout living under `~/specs/` would be one
+* whole specs tree, with F2's protection of production code silently off. The
+* package boundary makes the search stop where the project does.
+*/
+function specsAnchor(filename) {
+	const relative = [basename(filename)];
+	let directory = dirname(filename);
+	for (;;) {
+		if (basename(directory) === "specs") return {
+			directory,
+			relative
+		};
+		if (isFile(join(directory, "package.json"))) return;
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		relative.unshift(basename(directory));
+		directory = parent;
+	}
+}
+/** Is this file inside a `specs/` tree? — the predicate form of {@link specsAnchor}. */
+function isUnderSpecs(filename) {
+	return specsAnchor(filename) !== void 0;
+}
+//#endregion
+//#region src/lint/role.ts
+/**
+* The three suffixes that DECLARE tests, as a name-level predicate.
+*
+* `roleOf` is the answer for a rule handed a file; the passes that WALK a tree
+* only ever hold a name, and this is the same vocabulary for them — one place
+* to read, so a tree walk and a rule never disagree on what a test is.
+*/
+function isTestFileName(name) {
+	return name.endsWith(".test.ts") || name.endsWith(".test.tsx") || name.endsWith(".spec.ts");
+}
+/** A test that runs under node's project — a `.test.tsx` renders and is not one. */
+function isNodeTestFileName(name) {
+	return name.endsWith(".test.ts") || name.endsWith(".spec.ts");
+}
+/** The nearest package root at or above a directory, when there is one. */
+function packageRootOf(directory) {
+	let current = directory;
+	for (;;) {
+		if (isFile(join(current, "package.json"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return;
+		current = parent;
+	}
+}
+//#endregion
 //#region src/lint/checker-crossfile.ts
 /**
 * The cross-file checker passes — the analyses oxlint cannot express because
@@ -159,9 +236,10 @@ function blankComments(text) {
 	for (let i = 0; i < text.length; i += 1) {
 		const char = text[i];
 		const next = text[i + 1];
-		if (state === "line") if (char === "\n") state = "";
-		else out[i] = " ";
-		else if (state === "block") {
+		if (state === "line") {
+			if (char === "\n") state = "";
+			else out[i] = " ";
+		} else if (state === "block") {
 			if (char === "*" && next === "/") {
 				out[i] = " ";
 				out[i + 1] = " ";
@@ -201,12 +279,12 @@ function collectSpecLiterals(path) {
 /**
 * Is this a file a leaf's ground may be referenced from?
 *
-* `.test.tsx` counts as much as `.test.ts`: a rendered unit's golden — its ARIA
-* tree — sits in the same `_expected/`, read by a test the suffix alone tells
-* apart.
+* Every test suffix counts, and so does a document: a rendered unit's golden —
+* its ARIA tree — sits in the same `_expected/` as a spec's, read by a file the
+* suffix alone tells apart.
 */
 function isReferrer(name) {
-	return name.endsWith(".test.ts") || name.endsWith(".test.tsx") || name.endsWith(".spec.yaml");
+	return isTestFileName(name) || name.endsWith(".spec.yaml");
 }
 function isDir(path) {
 	try {
@@ -421,7 +499,7 @@ function checkDockerRunnerAwaitUsing(rootDir) {
 		if (model.dockerAware && model.runnerExports.size > 0) dockerSpecs.set(file, model);
 	}
 	if (dockerSpecs.size === 0) return violations;
-	for (const testFile of listFiles(rootDir, (path) => path.endsWith(".test.ts"))) {
+	for (const testFile of listFiles(rootDir, isNodeTestFileName)) {
 		const text = readSource(testFile);
 		const runners = /* @__PURE__ */ new Set();
 		for (const binding of namedImports(text)) {
@@ -440,7 +518,7 @@ function checkDockerRunnerAwaitUsing(rootDir) {
 			violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: result of docker-aware runner "${runner}" must be bound with \`await using\` so its containers are disposed (B5 — see docs/13-linting.md)`,
+				message: `${rel}:${line}: result of docker-aware runner "${runner}" must be bound with \`await using\` so its containers are disposed (B5 — see docs/19-linting.md)`,
 				rule: "b5",
 				severity: "error"
 			});
@@ -473,7 +551,7 @@ function checkDatabaseProperty(rootDir) {
 		if (model.sqlDatabaseCount !== null && model.sqlDatabaseCount >= 1 && model.runnerExports.size > 0) enforced.set(file, model);
 	}
 	if (enforced.size === 0) return violations;
-	for (const testFile of listFiles(rootDir, (path) => path.endsWith(".test.ts"))) {
+	for (const testFile of listFiles(rootDir, isNodeTestFileName)) {
 		const text = readSource(testFile);
 		const applicable = /* @__PURE__ */ new Set();
 		for (const binding of namedImports(text)) {
@@ -498,14 +576,14 @@ function checkDatabaseProperty(rootDir) {
 			if (count >= 2 && !hasDatabase) violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/13-linting.md)`,
+				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/19-linting.md)`,
 				rule: "a7",
 				severity: "error"
 			});
 			else if (count === 1 && hasDatabase) violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: .${verb}() must not pass { database } — a single SQL database is declared (A7 — see docs/13-linting.md)`,
+				message: `${rel}:${line}: .${verb}() must not pass { database } — a single SQL database is declared (A7 — see docs/19-linting.md)`,
 				rule: "a7",
 				severity: "error"
 			});
@@ -527,7 +605,7 @@ function entryReferenced(entry, entryIsDir, literals, patterns = []) {
 /** A child named like a ground subdir but actually a fixture container. */
 function isConventionalSubdir(path) {
 	if (!isDir(path)) return false;
-	if (listFiles(path, (candidate) => candidate.endsWith(".test.ts")).length > 0) return false;
+	if (listFiles(path, isTestFileName).length > 0) return false;
 	let children;
 	try {
 		children = readdirSync(path, { withFileTypes: true });
@@ -555,7 +633,7 @@ function checkDeadFixtures(rootDir) {
 			violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}: domain directory has ground subdirs (${groundSubdirs.join(", ")}) but no *.test.ts(x) or *.spec.yaml (C9 — see docs/13-linting.md)`,
+				message: `${rel}: domain directory has ground subdirs (${groundSubdirs.join(", ")}) but no *.test.ts(x) or *.spec.yaml (C9 — see docs/19-linting.md)`,
 				rule: "c9",
 				severity: "error"
 			});
@@ -584,7 +662,7 @@ function checkDeadFixtures(rootDir) {
 				violations.push({
 					file: relEntry,
 					line: 1,
-					message: `${relEntry}: dead fixture — no test literal in ${feature} references ${sub}/${entry.name} (C9 — see docs/13-linting.md)`,
+					message: `${relEntry}: dead fixture — no test literal in ${feature} references ${sub}/${entry.name} (C9 — see docs/19-linting.md)`,
 					rule: "c9",
 					severity
 				});
@@ -610,7 +688,7 @@ function checkPoolFixtures(rootDir) {
 			violations.push({
 				file: relEntry,
 				line: 1,
-				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot)} references $FIXTURES/${entry.name} (C9 — see docs/13-linting.md)`,
+				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot) || basename(specsRoot)} references $FIXTURES/${entry.name} (C9 — see docs/19-linting.md)`,
 				rule: "c9",
 				severity: "error"
 			});
@@ -714,7 +792,7 @@ function checkPoolFixtureSharing(rootDir) {
 		return {
 			file: relEntry,
 			line: 1,
-			message: `${relEntry}: only ${relLeaf} reaches for this pool fixture — the pool is what SEVERAL leaves share; move it to ${relLeaf}/${GROUND_FIXTURES}/${entry} and reference it as '${entry}' (C14 — see docs/13-linting.md, or run the checker with --fix)`,
+			message: `${relEntry}: only ${relLeaf} reaches for this pool fixture — the pool is what SEVERAL leaves share; move it to ${relLeaf}/${GROUND_FIXTURES}/${entry} and reference it as '${entry}' (C14 — see docs/19-linting.md, or run the checker with --fix)`,
 			rule: "c14",
 			severity: "error"
 		};
@@ -768,7 +846,7 @@ function checkLocalFixtureReach(rootDir) {
 				violations.push({
 					file: rel,
 					line,
-					message: `${rel}:${line}: fixture "${path}" reaches outside ${relative(rootDir, ground)} — a leaf's ground sits beside it; ground several leaves share goes to the $FIXTURES pool at ${relative(rootDir, pool)} (C15 — see docs/13-linting.md)`,
+					message: `${rel}:${line}: fixture "${path}" reaches outside ${relative(rootDir, ground)} — a leaf's ground sits beside it; ground several leaves share goes to the $FIXTURES pool at ${relative(rootDir, pool)} (C15 — see docs/19-linting.md)`,
 					rule: "c15",
 					severity: "error"
 				});
@@ -777,6 +855,439 @@ function checkLocalFixtureReach(rootDir) {
 	}
 	return violations;
 }
+/** The directive, whatever precedes it on the line, and what follows the ids. */
+const DIRECTIVE = /(?<lead>.*?)checker-disable(?:-next-line|-line)\s+(?<rest>.*)$/iu;
+/**
+* A directive is written in a COMMENT — the word inside a string is a test
+* TALKING about suppressions, which is what this package's own suite does.
+*/
+const COMMENT_LEAD = /(?:^|\s)(?:\/\/|\/\*|\*|#)\s*$/u;
+/** The files a directive can be written in — source, documents, goldens. */
+const READABLE = /\.(?:[cm]?[jt]sx?|ya?ml|json|md|sql|http|txt)$/u;
+/** Is this a file a human writes a directive in? */
+function isReadableText(path) {
+	return READABLE.test(path);
+}
+/** A reason: the `--` separator with something after it. */
+const REASON = /--\s*\S/u;
+/**
+* J9 — every checker suppression says WHY.
+*
+* A suppression with no reason is a rule turned off by someone who is no longer
+* here: the next reader cannot tell whether the pass was wrong, the shape was
+* exceptional, or it was simply in the way — so the line survives every review
+* and the convention quietly stops holding. The toolchain's own
+* `suppressions-reason` gate reads `oxlint-disable*` and nothing else, which is
+* why this channel carries its own.
+*/
+function checkSuppressionReason(rootDir) {
+	const violations = [];
+	for (const file of listFiles(rootDir, isReadableText)) {
+		const text = readText$1(file);
+		if (!text.includes("checker-disable")) continue;
+		for (const [index, line] of text.split("\n").entries()) {
+			const match = DIRECTIVE.exec(line);
+			if (match === null || !COMMENT_LEAD.test(match.groups?.lead ?? "") || REASON.test(match.groups?.rest ?? "")) continue;
+			const rel = relative(rootDir, file);
+			violations.push({
+				file: rel,
+				line: index + 1,
+				message: `${rel}:${index + 1}: say why: \`checker-disable-next-line <id> -- <reason>\` (J9 — see docs/19-linting.md)`,
+				rule: "j9-checker-suppression-reason",
+				severity: "error"
+			});
+		}
+	}
+	return violations;
+}
+//#endregion
+//#region src/lint/checker-facets.ts
+/**
+* The FACET passes — what a tree says about itself, read from the tree.
+*
+* A statique rule sees one file; these three need the shape around it: which
+* folder a file sits under, what the specification at that folder's root
+* constructs, which ground lives below it, and who reads that ground. The four
+* hold the one law the fork rests on — **folder = constructor** — from both
+* sides: a facet folder has the runner its name promises (C20), a spec under it
+* reaches that runner (C18), and ground one spec alone reads belongs to that
+* spec (C21w).
+*
+* A first-level folder that is NOT a facet is a repository suite — it covers a
+* tree rather than a product, C1's declared depth judges its shape, and none of
+* these passes reaches it.
+*/
+/** The six facet folders — a first-level name under `specs/` that IS a constructor. */
+const FACETS$1 = [
+	"api",
+	"cli",
+	"integration",
+	"jobs",
+	"mobile",
+	"website"
+];
+/**
+* Directories no facet walk enters.
+*
+* The `$FIXTURES` pool is verbatim material — the reusable apps AND the trees
+* that fail on purpose — never live specs, so every pass prunes it exactly as
+* the token checker does.
+*/
+const SKIPPED$2 = /* @__PURE__ */ new Set([
+	".git",
+	"dist",
+	GROUND_FIXTURES,
+	"node_modules"
+]);
+/**
+* Does this facet-relative path cross ground? A LEADING underscore names it —
+* the four ground directories and nothing else carry one (C13).
+*/
+function isUnderGround(relativePath) {
+	return relativePath.split(/[/\\]/u).some((segment) => segment.startsWith("_"));
+}
+/** `readdirSync` that answers `[]` for anything it cannot read. */
+function entriesOf(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+/** The specification files at a directory's own level. */
+function specificationsIn(dir) {
+	return entriesOf(dir).filter((entry) => entry.isFile() && entry.name.includes(".specification.")).map((entry) => join(dir, entry.name));
+}
+/**
+* Every import SOURCE a file names — static, dynamic, and re-export.
+*
+* The source, not a substring of the file: `../website.specification` carries
+* no extension, so a scan for `.specification.js` read a spec that reaches its
+* runner as a module test parked in a facet tree, and told the author to move
+* the file that specifies the product.
+*/
+const IMPORT_SOURCE = /(?:\bfrom|\bimport|\brequire)\s*\(?\s*['"](?<source>[^'"]+)['"]/gu;
+/** The framework's own entry — a spec may construct the runner itself. */
+const CONSTRUCTS = /\bspecification\.[a-z]+\s*\(/u;
+/**
+* Does this file reach the runner of the facet it sits under?
+*
+* Two shapes answer yes: importing the facet's `*.specification` module
+* (however the import spells the extension), and constructing the runner in
+* the file itself — a refusal spec proves the constructor that must FAIL to
+* start, and has no specification module to import.
+*/
+function reachesRunner(text) {
+	for (const match of text.matchAll(IMPORT_SOURCE)) {
+		const source = match.groups?.source ?? "";
+		if (source === "@jterrazz/test" || source.startsWith("@jterrazz/test/")) return true;
+		if (source.slice(source.lastIndexOf("/") + 1).includes(".specification")) return true;
+	}
+	return CONSTRUCTS.test(text);
+}
+/** Read a file as text, or `null`. */
+function textOf$1(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+/**
+* Every file under `dir`, depth-first.
+*
+* @yields each file path.
+*/
+function* walkFiles(dir) {
+	for (const entry of entriesOf(dir)) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (!SKIPPED$2.has(entry.name)) yield* walkFiles(path);
+			continue;
+		}
+		yield path;
+	}
+}
+/** The facet folders a specs root actually holds. */
+function facetFoldersOf(specsRoot) {
+	return entriesOf(specsRoot).filter((entry) => entry.isDirectory() && FACETS$1.includes(entry.name)).map((entry) => ({
+		facet: entry.name,
+		path: join(specsRoot, entry.name)
+	}));
+}
+/**
+* C20 — a folder named for a facet holds the specification that constructs it.
+*
+* Positive-only: `specs/api/` promises `specification.api()`, and a reader who
+* opens it expecting a runner and finding none has been told something false by
+* the tree itself. Any OTHER first-level name is a repository suite and is
+* judged by C1's declared depth alone — the folder never has to be a facet.
+*/
+function checkFacetFolder(specsRoot) {
+	const violations = [];
+	for (const { facet, path } of facetFoldersOf(specsRoot)) {
+		if (specificationsIn(path).some((file) => (textOf$1(file) ?? "").includes(`specification.${facet}(`))) continue;
+		const rel = relative(specsRoot, path);
+		violations.push({
+			file: rel,
+			line: 1,
+			message: `${rel}:1: \`specs/${facet}/\` is a facet folder with no \`${facet}.specification.ts\` constructing \`specification.${facet}()\` — create it, or rename the folder (C20 — see docs/19-linting.md)`,
+			rule: "c20-facet-folder",
+			severity: "error"
+		});
+	}
+	return violations;
+}
+/**
+* C18 — a spec under a facet folder reaches the runner that folder promises.
+*
+* A test file that imports neither the facet's specification module nor the
+* framework is a MODULE test parked in a facet tree: it runs under the facet's
+* project, pays its budget and its services, and proves something that belongs
+* beside the module it covers.
+*/
+function checkModuleTestUnderFacet(specsRoot) {
+	const violations = [];
+	for (const { facet, path } of facetFoldersOf(specsRoot)) {
+		if (specificationsIn(path).length === 0) continue;
+		for (const file of walkFiles(path)) {
+			if (!isTestFileName(file.slice(file.lastIndexOf("/") + 1))) continue;
+			if (isUnderGround(relative(path, file))) continue;
+			if (reachesRunner(textOf$1(file) ?? "")) continue;
+			const rel = relative(specsRoot, file);
+			violations.push({
+				file: rel,
+				line: 1,
+				message: `${rel}:1: reaches no runner under the \`${facet}\` facet: import \`{ ${facet} }\` from \`${facet}.specification.js\`, or move a module test beside its module (C18 — see docs/19-linting.md)`,
+				rule: "c18-module-test-under-facet",
+				severity: "error"
+			});
+		}
+	}
+	return violations;
+}
+/**
+* Every directory under `dir`, depth-first.
+*
+* @yields each directory path.
+*/
+function* walkDirectories(dir) {
+	for (const entry of entriesOf(dir)) {
+		if (!entry.isDirectory() || SKIPPED$2.has(entry.name)) continue;
+		const path = join(dir, entry.name);
+		yield path;
+		yield* walkDirectories(path);
+	}
+}
+/** The ground names a leaf can hold. */
+const GROUND = new Set(GROUND_DIRS);
+/**
+* A golden named by a TEMPLATE rather than by a literal — `toMatch(`${x}.json`)`.
+*
+* Such a test reads whatever the table hands it, so the names under the ground
+* appear nowhere in its source. It is a reader of every golden in its leaf,
+* and counting it as none made a shared `_expected/` read as one spec's own.
+*/
+const COMPUTED_GOLDEN = /\.toMatch\(\s*(?:`|[A-Za-z_$])/u;
+/**
+* C21w (warning) — ground a single spec reads belongs to that spec.
+*
+* A leaf holding several specs and one `_expected/` that only one of them
+* names reads as shared material: the next author assumes someone else depends
+* on it and nobody dares touch it. The fix is C1's — the spec that stands on
+* its own ground earns its own domain folder.
+*/
+function checkGroundOwnedByOne(specsRoot) {
+	const violations = [];
+	for (const directory of [specsRoot, ...walkDirectories(specsRoot)]) {
+		const entries = entriesOf(directory);
+		const tests = entries.filter((entry) => entry.isFile() && isNodeTestFileName(entry.name)).map((entry) => join(directory, entry.name));
+		if (tests.length < 2) continue;
+		const grounds = entries.filter((entry) => entry.isDirectory() && GROUND.has(entry.name)).map((entry) => entry.name);
+		for (const ground of grounds) {
+			const names = [...walkFiles(join(directory, ground))].map((file) => file.slice(file.lastIndexOf("/") + 1));
+			if (names.length === 0) continue;
+			const readers = tests.filter((test) => {
+				const text = textOf$1(test) ?? "";
+				return names.some((name) => text.includes(name)) || text.includes(`${ground}/`) || COMPUTED_GOLDEN.test(text);
+			});
+			if (readers.length !== 1) continue;
+			const reader = readers[0] ?? "";
+			const rel = relative(specsRoot, join(directory, ground));
+			violations.push({
+				file: rel,
+				line: 1,
+				message: `${rel}:1: \`${ground}/\` here is read by \`${relative(directory, reader)}\` alone — give it its own domain folder (C21 — see docs/19-linting.md)`,
+				rule: "c21w-ground-owned-by-one",
+				severity: "warn"
+			});
+		}
+	}
+	return violations;
+}
+//#endregion
+//#region src/lint/checker-placement.ts
+/**
+* C12 placement — the suffix says the kind, so the tree has to agree with it.
+*
+* `.spec.ts` is the ASSEMBLED product's word: the app met through HTTP, a
+* binary run, a page served, a module put against real services. It lives under
+* `specs/<facet>/`. `.test.ts` is the UNIT's word: it sits beside the module it
+* covers. A file wearing one word in the other's place is the one shape that
+* makes the fork unreadable — a reader cannot tell what a test is FOR without
+* opening it — so both directions are errors with a mechanical fix, and the
+* checker's `--fix` performs the move.
+*
+* Two clauses, and each runs where it can see what it judges:
+*
+* - a `.spec.ts` with no `specs/` ancestor — the MEMBER pass, which walks a
+*   package and is the only run that sees a file outside a specs tree. The
+*   ancestor is read by the one anchor every other pass reads (`specsAnchor`),
+*   so a member whose own root IS the specs tree — a workspace declaring
+*   `packages: ['specs']` — holds specs, not strays;
+* - a `.test.ts` under `specs/<facet>/` where `<facet>` is one of the six
+*   constructors — the TREE pass. A first-level folder that is NOT a facet
+*   (the package's own `specs/lint/`, a repository's consistency suites) is a
+*   repository suite: it covers a tree rather than the assembled product, so
+*   it keeps `.test.ts` and C1's declared depth is what judges its shape.
+*
+* A tree may also be ONE facet's whole, with no `specs/<facet>/` level: the
+* runner sits at the root of `specs/` and the folders below it are domains (the
+* `depth: 'mirror'` shape, where the tree follows a command tree instead of a
+* facet/domain one). Such a tree carries a `*.specification.ts` at its root,
+* and that is what says so — every `.test.ts` below it specifies the assembled
+* product, whatever folder it sits in. Without this clause the whole shape was
+* invisible to C12 and its specs had to be renamed by hand.
+*/
+/** The six facet folders — a first-level name under `specs/` that IS a constructor. */
+const FACETS = /* @__PURE__ */ new Set([
+	"api",
+	"cli",
+	"integration",
+	"jobs",
+	"mobile",
+	"website"
+]);
+/** Directories no placement walk enters. */
+const SKIPPED$1 = /* @__PURE__ */ new Set([
+	".git",
+	"dist",
+	"node_modules"
+]);
+/**
+* Every file under `dir`, depth-first.
+*
+* `stopAtPackages` bounds the walk at the next `package.json`: the member pass
+* judges ONE member, and a nested member is judged by its own run — without the
+* bound, a workspace root reported every finding of every package below it and
+* the same file was named twice.
+*
+* @yields every file path under `dir`, depth-first.
+*/
+function* walk(dir, stopAtPackages = false) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (SKIPPED$1.has(entry.name)) continue;
+			if (stopAtPackages && existsSync(join(path, "package.json"))) continue;
+			yield* walk(path, stopAtPackages);
+			continue;
+		}
+		yield path;
+	}
+}
+/** Read a file as text, or the empty string when it cannot be read. */
+function textOf(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+/**
+* Clause one — a `.spec.ts` that sits outside every `specs/` tree.
+*
+* The facet cannot be guessed (only the author knows whether the file meets the
+* product through HTTP or through a binary), so this clause reports and the
+* mover leaves it alone: `to` is `undefined` and the fix line names the shape.
+*/
+function checkSpecOutsideSpecs(memberDir) {
+	const violations = [];
+	for (const path of walk(memberDir, true)) {
+		if (!path.endsWith(".spec.ts")) continue;
+		if (isUnderSpecs(path)) continue;
+		const rel = relative(memberDir, path);
+		violations.push({
+			file: rel,
+			line: 1,
+			message: `${rel}:1: a \`.spec.ts\` lives under \`specs/<facet>/\` — move it there, or rename it \`.test.ts\` beside the module it covers (C12 — see docs/19-linting.md)`,
+			rule: "c12-spec-file-name",
+			severity: "error"
+		});
+	}
+	return violations;
+}
+/**
+* Clause two — a `.test.ts` under a facet folder of a `specs/` tree.
+*
+* The fix is mechanical and the mover performs it: the facet folder already
+* says what the file specifies, so the only thing missing is the word.
+*
+* A file that reaches no runner is left to C18, whose fix is the opposite move
+* — one file, one finding, and `--fix` never renames a module test into a spec.
+*/
+function checkTestUnderFacet(specsRoot) {
+	return movesUnderFacet(specsRoot).map(({ from }) => {
+		const rel = relative(specsRoot, from);
+		const first = rel.split(/[/\\]/u)[0] ?? "";
+		return {
+			file: rel,
+			line: 1,
+			message: `${rel}:1: a \`.test.ts\` under \`${FACETS.has(first) ? `specs/${first}/` : "specs/"}\` specifies the assembled product — rename it \`.spec.ts\` (fixable: \`jterrazz-test-check <root> --fix\`) (C12 — see docs/19-linting.md)`,
+			rule: "c12-spec-file-name",
+			severity: "error"
+		};
+	});
+}
+/**
+* Is this tree ONE facet's whole, rooted at `specs/`?
+*
+* A `*.specification.ts` at the ROOT of the tree is the statement: the runner
+* is the tree's, so every folder below it is a domain of that one facet and no
+* first level is a repository suite.
+*/
+function isRootedFacetTree(specsRoot) {
+	try {
+		return readdirSync(specsRoot, { withFileTypes: true }).some((entry) => entry.isFile() && entry.name.includes(".specification."));
+	} catch {
+		return false;
+	}
+}
+/** The renames clause two asks for, as absolute from/to pairs. */
+function movesUnderFacet(specsRoot) {
+	const moves = [];
+	const rooted = isRootedFacetTree(specsRoot);
+	for (const path of walk(specsRoot)) {
+		if (!path.endsWith(".test.ts")) continue;
+		const parts = relative(specsRoot, path).split(/[/\\]/u);
+		const facet = parts[0];
+		if (!rooted && (parts.length < 2 || facet === void 0 || !FACETS.has(facet))) continue;
+		if (parts.some((part) => part.startsWith("_"))) continue;
+		if (!reachesRunner(textOf(path))) continue;
+		moves.push({
+			fix: "rename to `.spec.ts`",
+			from: path,
+			to: `${path.slice(0, -8)}.spec.ts`
+		});
+	}
+	return moves;
+}
 //#endregion
 //#region src/lint/checker-member.ts
 /**
@@ -794,6 +1305,16 @@ function checkLocalFixtureReach(rootDir) {
 * it for one member, and a path-less `--format json` run at the project root
 * runs it for every member the root manifest declares.
 */
+/** How deep a member may sit below the root — the toolchain's bound, to the segment. */
+const MEMBER_DEPTH = 6;
+/** Directories the member walk never enters. */
+const SKIPPED = /* @__PURE__ */ new Set([
+	".git",
+	".artifacts",
+	"coverage",
+	"dist",
+	"node_modules"
+]);
 /** The two simulated DOMs — the same pair the statique E5b refuses. */
 const SIMULATED_DOM = /\benvironment\s*:\s*['"](?<dom>happy-dom|jsdom)['"]/u;
 /**
@@ -825,8 +1346,88 @@ const RETIRED = /* @__PURE__ */ new Set([
 	"mockdate"
 ]);
 const RETIRED_SCOPES = ["@testing-library/"];
+/**
+* The one retired seam a member may still declare, and what makes it allowed.
+*
+* React Native renders under jest until the react-native-web answer lands, and
+* where jest is the sanctioned runner `@testing-library/react-native` is the
+* only vocabulary there is: the rule would be asking for a facet that does not
+* reach that runtime yet. The allowance lapses the day jest stops running the
+* member's tests, and it has TWO sources, because jest is not always the
+* member's own: in a workspace where one app owns the only working RN
+* toolchain, the library declares the vocabulary and the app runs the tests
+* that use it.
+*/
+const JEST_ONLY_SEAM = "@testing-library/react-native";
+/** Does the member's OWN manifest say jest runs here? */
+function declaresJest(manifest) {
+	const declares = (name) => name in (manifest.dependencies ?? {}) || name in (manifest.devDependencies ?? {});
+	return declares("jest") || declares("jest-expo") || manifest.jest !== void 0 || /(?:^|[\s/])jest(?:\s|$)/u.test(manifest.scripts?.test ?? "");
+}
+/** The config names jest answers to, whatever a project writes it in. */
+const JEST_CONFIG = /^jest\.config\.[cm]?[jt]s$/u;
+/** The keys of a jest config that name WHERE its tests are. */
+const JEST_REACH = /\b(?:roots|testMatch|testPathDirs|testPathIgnorePatterns)\s*:\s*\[(?<paths>[^\]]*)\]/gu;
+/** One quoted entry of such a list. */
+const JEST_PATH = /['"`](?<path>[^'"`\n]*)['"`]/gu;
+/** Every `jest.config.*` under `rootDir`, by absolute path — read once per root. */
+const jestConfigs = /* @__PURE__ */ new Map();
+/** Find them, bounded by the same skips and depth the member walk uses. */
+function findJestConfigs(rootDir) {
+	const cached = jestConfigs.get(rootDir);
+	if (cached !== void 0) return cached;
+	const found = [];
+	const walk = (dir, depth) => {
+		if (depth > MEMBER_DEPTH) return;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const path = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (!entry.name.startsWith(".") && !SKIPPED.has(entry.name)) walk(path, depth + 1);
+			} else if (JEST_CONFIG.test(entry.name)) found.push(path);
+		}
+	};
+	walk(rootDir, 0);
+	jestConfigs.set(rootDir, found);
+	return found;
+}
+/**
+* Does a jest config ELSEWHERE in the workspace collect this member's tests?
+*
+* jterrazz-design is the shape: the render tests are co-located in
+* `packages/native/src`, and `apps/playground` — which owns the only working
+* React Native toolchain — is what runs them, rooting into the library from its
+* own config. The library's manifest says `vitest --run`, so reading the
+* allowance from the member alone answered "no jest here" and F8 errored on
+* exactly the layout the exemption was written for.
+*
+* `<rootDir>` is jest's own token for the directory its config sits in, so a
+* path is resolved against that, and the member is reached when the result
+* lands inside it.
+*/
+function jestReachesMember(memberDir, rootDir) {
+	return findJestConfigs(rootDir).some((config) => {
+		const from = dirname(config);
+		let text;
+		try {
+			text = readFileSync(config, "utf8");
+		} catch {
+			return false;
+		}
+		return [...text.matchAll(JEST_REACH)].some((list) => [...(list.groups?.paths ?? "").matchAll(JEST_PATH)].some((entry) => {
+			const stated = (entry.groups?.path ?? "").replace("<rootDir>", from);
+			const absolute = resolve(from, stated);
+			return absolute === memberDir || absolute.startsWith(`${memberDir}/`);
+		}));
+	});
+}
 /** Where a member states what it collects, whatever extension it writes it in. */
-const CONFIG_NAMES = [
+const CONFIG_NAMES$1 = [
 	"vitest.config.ts",
 	"vitest.config.mts",
 	"vitest.config.cts",
@@ -834,14 +1435,6 @@ const CONFIG_NAMES = [
 	"vitest.config.mjs",
 	"vitest.config.cjs"
 ];
-/** Directories the member walk never enters. */
-const SKIPPED = /* @__PURE__ */ new Set([
-	".git",
-	".artifacts",
-	"coverage",
-	"dist",
-	"node_modules"
-]);
 /** A member's manifest, or null when it has none (it is then not a member). */
 function readManifest(dir) {
 	const path = join(dir, "package.json");
@@ -854,7 +1447,7 @@ function readManifest(dir) {
 }
 /** The member's vitest config, by path, or null. */
 function configOf(dir) {
-	for (const name of CONFIG_NAMES) {
+	for (const name of CONFIG_NAMES$1) {
 		const path = join(dir, name);
 		if (existsSync(path)) return path;
 	}
@@ -887,7 +1480,7 @@ function holdsTests(dir) {
 				if (!SKIPPED.has(entry.name) && !entry.name.startsWith(".")) stack.push(join(current, entry.name));
 				continue;
 			}
-			if (/\.test\.[cm]?tsx?$/u.test(entry.name)) return true;
+			if (isTestFileName(entry.name)) return true;
 		}
 	}
 	return false;
@@ -899,9 +1492,12 @@ function holdsTests(dir) {
 */
 const DELEGATING_TEST = /--workspaces|(?:^|\s)-r(?:\s|$)|--recursive|turbo\s+run|nx\s+run-many|lerna\s+run/u;
 /** Every seam name this member declares that it should not, and why it should not. */
-function declaredSeams(manifest) {
+function declaredSeams(manifest, jestRuns) {
 	if (manifest.name === FRAMEWORK) return [];
-	const isRetired = (name) => RETIRED.has(name) || RETIRED_SCOPES.some((scope) => name.startsWith(scope));
+	const isRetired = (name) => {
+		if (name === JEST_ONLY_SEAM && jestRuns) return false;
+		return RETIRED.has(name) || RETIRED_SCOPES.some((scope) => name.startsWith(scope));
+	};
 	return [.../* @__PURE__ */ new Set([...Object.keys(manifest.dependencies ?? {}).filter((name) => CARRIED.has(name) || isRetired(name)), ...Object.keys(manifest.devDependencies ?? {}).filter((name) => CARRIED.has(name) || CARRIED_IN_DEV.has(name) || isRetired(name))])].toSorted().map((name) => ({
 		kind: isRetired(name) ? "retired" : "carried",
 		name
@@ -928,7 +1524,7 @@ function configPresent(manifest, memberDir, label, subject) {
 	return [{
 		file: join(label, "package.json"),
 		line: 1,
-		message: `${subject}: no vitest.config.ts — vitest's 5 s budget and an unexcluded \`_fixtures/\` are running your tests; write \`export default defineSpecConfig()\` (E3 — see docs/13-linting.md#e3-config-present)`,
+		message: `${subject}: no vitest.config.ts — vitest's 5 s budget and an unexcluded \`_fixtures/\` are running your tests; write \`export default defineSpecConfig()\` (E3 — see docs/19-linting.md#e3-config-present)`,
 		rule: "e3",
 		severity: "error"
 	}];
@@ -942,7 +1538,7 @@ function simulatedDom(config, rootDir) {
 	return [{
 		file: relConfig,
 		line: text.slice(0, found.index).split("\n").length,
-		message: `${relConfig}: \`environment: '${found.groups.dom}'\` gives every file of this project a drawing of a browser — a rendered thing is a \`.test.tsx\` beside its component, collected by \`component()\` (E5b — see docs/13-linting.md#e5b-no-simulated-dom-config-member)`,
+		message: `${relConfig}: \`environment: '${found.groups.dom}'\` gives every file of this project a drawing of a browser — a rendered thing is a \`.test.tsx\` beside its component, collected by \`component()\` (E5b — see docs/19-linting.md#e5b-no-simulated-dom-config-member)`,
 		rule: "e5b",
 		severity: "error"
 	}];
@@ -953,16 +1549,30 @@ function simulatedDom(config, rootDir) {
 * The two are not the same sentence: removing a transitive changes nothing a
 * test can see, while dropping a retired seam means writing its facet.
 */
-function seamDependencies(manifest, memberDir, label, subject) {
-	return declaredSeams(manifest).map((seam) => ({
+function seamDependencies(member) {
+	const { label, manifest, memberDir, rootDir, subject } = member;
+	return declaredSeams(manifest, declaresJest(manifest) || jestReachesMember(memberDir, rootDir)).map((seam) => ({
 		file: join(label, "package.json"),
 		line: lineOfKey(memberDir, seam.name),
-		message: seam.kind === "carried" ? `${subject}: \`${seam.name}\` is a transitive of \`@jterrazz/test\` — remove the declaration (F8 — see docs/13-linting.md#f8-no-seam-dependency)` : `${subject}: \`${seam.name}\` is a seam \`@jterrazz/test\` replaced — the facet is \`component()\`, \`website()\`, \`clock\` or \`intercept()\`; remove the declaration (F8 — see docs/13-linting.md#f8-no-seam-dependency)`,
+		message: seam.kind === "carried" ? `${subject}: \`${seam.name}\` is a transitive of \`@jterrazz/test\` — remove the declaration (F8 — see docs/19-linting.md#f8-no-seam-dependency)` : `${subject}: \`${seam.name}\` is a seam \`@jterrazz/test\` replaced — the facet is \`component()\`, \`website()\`, \`clock\` or \`intercept()\`; remove the declaration (F8 — see docs/19-linting.md#f8-no-seam-dependency)`,
 		rule: "f8",
 		severity: "error"
 	}));
 }
 /**
+* Re-anchor a member-relative finding on the root the run reports against, so
+* one member's path reads the same alone as inside a whole-workspace run.
+*/
+function anchoredToRoot(violations, label) {
+	if (label === ".") return violations;
+	const anchored = [];
+	for (const violation of violations) anchored.push({
+		...violation,
+		file: join(label, violation.file)
+	});
+	return anchored;
+}
+/**
 * Run E3, E5b and F8 over ONE member. `memberDir` is absolute; `rootDir`
 * anchors the paths the findings report, so a member's finding reads the same
 * whether the pass ran over it alone or over the whole workspace.
@@ -976,7 +1586,14 @@ function checkMember(memberDir, rootDir) {
 	return [
 		...config === null ? configPresent(manifest, memberDir, label, subject) : [],
 		...config === null ? [] : simulatedDom(config, rootDir),
-		...seamDependencies(manifest, memberDir, label, subject)
+		...seamDependencies({
+			label,
+			manifest,
+			memberDir,
+			rootDir,
+			subject
+		}),
+		...anchoredToRoot(checkSpecOutsideSpecs(memberDir), label)
 	];
 }
 /** The glob-ish workspace patterns a root manifest declares. */
@@ -996,8 +1613,6 @@ function toPattern(glob) {
 	const escaped = glob.replaceAll(/[.+^${}()|[\]\\]/gu, String.raw`\$&`).replaceAll("**", " ").replaceAll("*", "[^/]*").replaceAll(" ", ".*");
 	return new RegExp(`^${escaped}$`, "u");
 }
-/** How deep a member may sit below the root — the toolchain's bound, to the segment. */
-const MEMBER_DEPTH = 6;
 /**
 * Every workspace member declared by the root manifest, plus the root itself —
 * a single-package repository IS its own member, and the pass has to reach it.
@@ -1055,11 +1670,14 @@ const SPECS_DEPTH = 6;
 *
 * A `specs/` tree is never descended into (the fixtures under it are not spec
 * roots), and neither is another package's tree: a directory carrying its own
-* `package.json` belongs to whichever member declares it.
+* `package.json` belongs to whichever member declares it. A member DIRECTORY
+* named `specs` is a root of its own — the tree can be the member.
 */
 function discoverSpecRoots(rootDir) {
 	const roots = /* @__PURE__ */ new Set();
-	for (const member of discoverMembers(rootDir)) {
+	const members = discoverMembers(rootDir);
+	for (const member of members.length === 0 ? [rootDir] : members) {
+		if (basename(member) === "specs") roots.add(member);
 		const walk = (dir, depth) => {
 			if (depth > SPECS_DEPTH) return;
 			let entries;
@@ -1301,27 +1919,99 @@ const VOLATILE = [
 	}
 ];
 /**
+* The volatile literal on this line, if it carries one — the reader BOTH halves
+* of d5's reach use, so a document's expected stream and a file under
+* `_expected/` are judged by one list.
+*
+* A `{{token}}` is removed before the test: the token IS the answer the rule
+* asks for, and a path written after one is the token's tail, not a literal.
+*/
+/**
+* The whole word the match sits inside — the string the pinned-value carve-out
+* looks up.
+*
+* A pattern matches the SHAPE that makes a value volatile (`/tmp/`, a loopback
+* origin) and not the value itself, so asking whether the document pinned
+* `/tmp/` would exempt every temp path once any of them was named. The word the
+* match belongs to is what the document either states or does not.
+*/
+function wordAround(text, index) {
+	let start = index;
+	let end = index;
+	while (start > 0 && !/[\s"'(),;=]/u.test(text[start - 1] ?? "")) start -= 1;
+	while (end < text.length && !/[\s"'(),;=]/u.test(text[end] ?? "")) end += 1;
+	return text.slice(start, end);
+}
+function volatileLiteralIn(line) {
+	const bare = line.replaceAll(/\{\{[^}]*\}\}/gu, " ");
+	for (const { pattern, token } of VOLATILE) {
+		const found = pattern.exec(bare);
+		if (found !== null) {
+			const at = found.index + found[0].length - found[0].trimStart().length;
+			return {
+				found: found[0].trim(),
+				token,
+				word: wordAround(bare, at)
+			};
+		}
+	}
+}
+/**
 * 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.
+*
+* Unless the document FIXED it — the same carve-out d5w rests on, for the same
+* reason: a path the command was handed, or one a `fixture:` ships, is a value
+* the document states rather than one the run minted.
 */
-function checkVolatileLiterals(document) {
+function checkVolatileLiterals(document, dir) {
 	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;
+	let fixed = null;
+	for (const stream of assertedStreams(document)) for (const [index, text] of stream.text.split("\n").entries()) {
+		const volatileLiteral = volatileLiteralIn(text);
+		if (volatileLiteral === void 0) continue;
+		fixed ??= fixedData(document, dir);
+		if (fixed.includes(volatileLiteral.word)) continue;
+		findings.push(finding("d5-spec-volatile-literal", stream.line + index, `"${volatileLiteral.found}" is a value the next run will not reproduce — write ${volatileLiteral.token}`));
 	}
 	return findings;
 }
 const ISO8601 = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/u;
 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}/u;
-/** Everything the document itself FIXED: what it feeds in, and what its fixtures hold. */
+/**
+* Everything the document itself FIXED — what it feeds in, what it names, and
+* what its fixtures hold.
+*
+* The first three sources are the document's own words: a literal that appears
+* in a command's arguments or in an `env:`/`serve:` value is one the DOCUMENT
+* put there, not one a run minted — a reader sees it being pinned two lines
+* above the stream that asserts it.
+*
+* The last is the ground beside it. A document's sibling `_fixtures/` is its
+* material whether or not a `fixture:` line names the exact file: the tree is
+* there to be read by the run, and a value it holds is one the repository
+* committed.
+*/
 function fixedData(document, dir) {
-	const parts = document.runs.map((run) => run.stdin ?? "");
+	const parts = document.runs.flatMap((run) => [run.stdin ?? "", run.command]);
+	for (const token of document.env) parts.push(token.kind === "pair" ? `${token.key}=${token.value}` : token.name);
+	for (const entry of document.serve) parts.push(entry.name, ...Object.values(entry.env));
+	const visit = (path) => {
+		let stat;
+		try {
+			stat = statSync(path);
+		} catch {
+			return;
+		}
+		if (!stat.isDirectory()) {
+			parts.push(readText(path));
+			return;
+		}
+		for (const entry of readdirSync(path)) visit(join(path, entry));
+	};
 	for (const fixture of document.fixtures) {
 		let source;
 		try {
@@ -1329,21 +2019,9 @@ function fixedData(document, dir) {
 		} catch {
 			continue;
 		}
-		const visit = (path) => {
-			let stat;
-			try {
-				stat = statSync(path);
-			} catch {
-				return;
-			}
-			if (!stat.isDirectory()) {
-				parts.push(readText(path));
-				return;
-			}
-			for (const entry of readdirSync(path)) visit(join(path, entry));
-		};
 		visit(source);
 	}
+	visit(join(dir, GROUND_FIXTURES));
 	return parts.join("\n");
 }
 /**
@@ -1507,7 +2185,7 @@ function checkSpecConventions(text, rel, path) {
 		...checkBlockScalars(file, (scalar) => lineAt(scalar)),
 		...checkFileName(rel),
 		...checkDescription(file.document),
-		...checkVolatileLiterals(file.document),
+		...checkVolatileLiterals(file.document, dir),
 		...checkPinnedValues(file.document, dir),
 		...checkEmptyAssertions(file.document),
 		...checkSilentRefusals(file.document),
@@ -1515,7 +2193,7 @@ function checkSpecConventions(text, rel, path) {
 	].map(({ line, message, rule, severity }) => ({
 		file: rel,
 		line,
-		message: `${rel}:${line}: ${message} (${rule} — see docs/13-linting.md)`,
+		message: `${rel}:${line}: ${message} (${rule} — see docs/19-linting.md)`,
 		rule: codeOf(rule),
 		severity
 	}));
@@ -1547,7 +2225,7 @@ function checkSpecDescriptionsUnique(rootDir) {
 		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/13-linting.md)`,
+			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/19-linting.md)`,
 			rule: "j4",
 			severity: "error"
 		});
@@ -1623,8 +2301,30 @@ const BRACE_BLOCK = /\{\{(?<inner>[^{}]*)\}\}/gu;
 /** The leading identifier of a brace block, for malformed-ref classification. */
 const LEADING_WORD = /^(?<kind>[A-Za-z][A-Za-z0-9]*)/u;
 const KNOWN = new Set(TOKEN_KINDS);
-/** Directories whose files carry the token grammar (D4). */
-const FIXTURE_DIRS = /* @__PURE__ */ new Set([GROUND_EXPECTED, GROUND_REQUESTS]);
+/** Directories whose files the walk judges, each by its own law. */
+const FIXTURE_DIRS = /* @__PURE__ */ new Set([
+	GROUND_EXPECTED,
+	GROUND_REQUESTS,
+	GROUND_SEEDS
+]);
+/**
+* The ways a seed asks the machine what time it is.
+*
+* Three spellings and nothing else, because each is decidable on sight: the
+* quoted `'now'` argument SQLite's date functions take (`datetime('now')`,
+* `strftime('%s', 'now')`, `julianday('now')`, `date('now', '-1 day')`), the
+* SQL keyword every engine spells the same, and Postgres/MySQL's `NOW()`.
+* The bare word `now` is not one of them — it is a column name as often as a
+* clock read, and a rule that guessed would be refused rather than obeyed.
+*/
+const CLOCK_READ = /'now'|\bCURRENT_(?:TIMESTAMP|DATE|TIME)\b|\bNOW\s*\(\s*\)/iu;
+/** A line comment, and a block comment — a `-- datetime('now')` is prose, not state. */
+const SQL_LINE_COMMENT = /--[^\n]*/gu;
+const SQL_BLOCK_COMMENT = /\/\*[\s\S]*?\*\//gu;
+/** The file with its comments blanked out, line for line so a finding still points. */
+function withoutComments$1(text) {
+	return text.replaceAll(SQL_BLOCK_COMMENT, (block) => block.replaceAll(/[^\n]/gu, " ")).replaceAll(SQL_LINE_COMMENT, "");
+}
 /**
 * Directories the walk never enters. `_fixtures/` trees (the shared pool and
 * the leaf-local ones) are verbatim `.fixture()` cwd material — file STATE, not
@@ -1636,6 +2336,56 @@ const SKIPPED_DIRS = /* @__PURE__ */ new Set([
 	GROUND_FIXTURES,
 	"node_modules"
 ]);
+/** The four ground names — what a document may never sit under (C16). */
+const GROUND_NAMES = new Set(GROUND_DIRS);
+/**
+* The passes a run over a `specs/` TREE puts on it.
+*
+* The three `d4*`/`d10w` ids are sub-scans of {@link checkConventionFiles}; the
+* rest are the cross-file and facet passes. The CLI prints this list when a run
+* is clean, so what the reader is told ran is the registry itself.
+*/
+const TREE_PASS_IDS = [
+	"a7-database-property",
+	"b5-await-using-inference",
+	"c12-spec-file-name",
+	"c14-pool-fixture-shared",
+	"c15-local-fixture-reach",
+	"c16-document-outside-ground",
+	"c18-module-test-under-facet",
+	"c20-facet-folder",
+	"c21w-ground-owned-by-one",
+	"c23-seed-no-clock-read",
+	"c8-spec-registered-name",
+	"c9-dead-fixtures",
+	"d10w-tokens-in-requests",
+	"d11w-spec-silent-refusal",
+	"d4-malformed-ref",
+	"d4-unknown-token",
+	"d4b-http-first-line",
+	"d4b-spec-block-scalar",
+	"d4b-spec-key-order",
+	"d4b-spec-shape",
+	"d5-spec-volatile-literal",
+	"d5w-spec-pinned-value",
+	"j3w-spec-empty-assertion",
+	"j4-spec-description-unique",
+	"j9-checker-suppression-reason",
+	"j5-spec-description"
+];
+/**
+* The passes a run over one workspace MEMBER puts on it — what no file under
+* `specs/` can answer: whether the member states how its tests run, whether its
+* config draws a browser, what it declares, and whether a `.spec.ts` of its own
+* ever reached a specs tree.
+*/
+const MEMBER_PASS_IDS = [
+	"c12-spec-file-name",
+	"e3-config-present",
+	"e5b-no-simulated-dom-config-member",
+	"f8-no-seam-dependency"
+];
+[.../* @__PURE__ */ new Set([...TREE_PASS_IDS, ...MEMBER_PASS_IDS])];
 /**
 * Scan one fixture text for tokens outside the grammar: unknown kinds
 * (`{{userid}}`) and malformed captures of a known kind (`{{iso8601#}}`,
@@ -1710,7 +2460,7 @@ function checkSpecFile(text, rel) {
 		return [{
 			file: rel,
 			line: error.line,
-			message: `${error.message} (D4b — see docs/13-linting.md)`,
+			message: `${error.message} (D4b — see docs/19-linting.md)`,
 			rule: "d4b",
 			severity: "error"
 		}];
@@ -1730,6 +2480,37 @@ function checkSpecFile(text, rel) {
 	return violations;
 }
 /**
+* C23 — a seed states absolute timestamps; it never reads the clock.
+*
+* A `_seeds/*.sql` that writes `datetime('now')` makes the row's date the date
+* the suite happened to run, so a case about "published yesterday" proves
+* something different every day and nothing at all across midnight. Worse under
+* SQLite, where `datetime('now')` writes a space-separated text while an ORM
+* writes ISO `T`: the two sort against each other, and the ordering breaks on
+* the days the values straddle a calendar boundary.
+*
+* The chain already owns the answer — `.clock()` pins what the code under test
+* reads — so the seed has nothing to ask the machine for.
+*/
+function checkSeedClockReads(path, rel, name) {
+	if (!name.endsWith(".sql")) return [];
+	const text = decodeText(path);
+	if (text === null) return [];
+	const violations = [];
+	for (const [index, line] of withoutComments$1(text).split("\n").entries()) {
+		const found = CLOCK_READ.exec(line);
+		if (found === null) continue;
+		violations.push({
+			file: rel,
+			line: index + 1,
+			message: `${rel}:${index + 1}: \`${found[0]}\` reads the clock — a seed states the instant the case is about, and the chain pins the run's with \`.clock()\` (C23 — see docs/19-linting.md)`,
+			rule: "c23-seed-no-clock-read",
+			severity: "error"
+		});
+	}
+	return violations;
+}
+/**
 * Walk `rootDir` and check every fixture file. Paths in the result are relative
 * to `rootDir`. Errors fail the checker; warnings are advisory.
 */
@@ -1752,12 +2533,23 @@ function checkConventionFiles(rootDir) {
 				continue;
 			}
 			if (entry.name.endsWith(".spec.yaml")) {
+				if (rel.split(/[/\\]/u).some((segment) => GROUND_NAMES.has(segment))) violations.push({
+					file: rel,
+					line: 1,
+					message: `${rel}:1: a \`${SPEC_EXTENSION}\` document is a SPEC, not ground — move it beside the test that runs it (C16 — see docs/19-linting.md)`,
+					rule: "c16-document-outside-ground",
+					severity: "error"
+				});
 				const text = decodeText(path);
 				if (text !== null) violations.push(...checkSpecFile(text, rel), ...checkSpecConventions(text, rel, path));
 				continue;
 			}
 			if (inside === null) continue;
 			const depth1 = dir.endsWith(`/${inside}`) || dir.endsWith(`\\${inside}`);
+			if (inside === "_seeds") {
+				violations.push(...checkSeedClockReads(path, rel, entry.name));
+				continue;
+			}
 			if (inside === "_requests") {
 				if (!entry.name.endsWith(".http")) continue;
 				const text = decodeText(path);
@@ -1765,14 +2557,14 @@ function checkConventionFiles(rootDir) {
 				if (depth1 && !REQUEST_LINE.test(firstLine(text))) violations.push({
 					file: rel,
 					line: 1,
-					message: `${rel}:1: a _requests/*.http file must start with a request line "METHOD /path" (D4b — see docs/13-linting.md)`,
+					message: `${rel}:1: a _requests/*.http file must start with a request line "METHOD /path" (D4b — see docs/19-linting.md)`,
 					rule: "d4b",
 					severity: "error"
 				});
 				for (const { line, token } of findKnownTokens(text)) violations.push({
 					file: rel,
 					line,
-					message: `${rel}:${line}: token ${token} in a _requests/ file — requests are inputs, never matched; tokens are not validated here (D10 — see docs/13-linting.md)`,
+					message: `${rel}:${line}: token ${token} in a _requests/ file — requests are inputs, never matched; tokens are not validated here (D10 — see docs/19-linting.md)`,
 					rule: "d10w",
 					severity: "warn",
 					token
@@ -1784,7 +2576,7 @@ function checkConventionFiles(rootDir) {
 			if (depth1 && entry.name.endsWith(".http") && !STATUS_LINE.test(firstLine(text))) violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}:1: an _expected/*.http file must start with a status line "HTTP/1.1 <status>" (D4b — see docs/13-linting.md)`,
+				message: `${rel}:1: an _expected/*.http file must start with a status line "HTTP/1.1 <status>" (D4b — see docs/19-linting.md)`,
 				rule: "d4b",
 				severity: "error"
 			});
@@ -1796,6 +2588,17 @@ function checkConventionFiles(rootDir) {
 				severity: "error",
 				token
 			});
+			for (const [index, line] of text.split("\n").entries()) {
+				const volatileLiteral = volatileLiteralIn(line);
+				if (volatileLiteral === void 0) continue;
+				violations.push({
+					file: rel,
+					line: index + 1,
+					message: `${rel}:${index + 1}: "${volatileLiteral.found}" is a value the next run will not reproduce — write ${volatileLiteral.token} (D5 — see docs/19-linting.md)`,
+					rule: "d5-spec-volatile-literal",
+					severity: "error"
+				});
+			}
 		}
 	};
 	visit(rootDir, null);
@@ -1809,6 +2612,11 @@ function checkConventionFiles(rootDir) {
 */
 function runAllChecks(rootDir) {
 	return [
+		...checkTestUnderFacet(rootDir),
+		...checkFacetFolder(rootDir),
+		...checkModuleTestUnderFacet(rootDir),
+		...checkGroundOwnedByOne(rootDir),
+		...checkSuppressionReason(rootDir),
 		...checkConventionFiles(rootDir),
 		...checkSpecDescriptionsUnique(rootDir),
 		...checkDeadFixtures(rootDir),
@@ -1827,33 +2635,55 @@ function formatViolations(violations) {
 /**
 * CLI entry for the conventions checker (bundled as `dist/checker.js`).
 *
-*     node dist/checker.js [rootDir] [--fix]          # a specs tree
+*     node dist/checker.js [dir] [--fix]              # a specs tree, or a project root
 *     node dist/checker.js --format json              # every root, every member
 *     node dist/checker.js --member <dir>             # one workspace member
 *
-* Three runs, one reporter. With a PATH it walks that tree and runs every
-* checker pass over it — the token/HTTP grammar (D4 / D4b / D10), the
-* `<case>.spec.yaml` document conventions, and the cross-file passes (C9 dead
+* Three runs, one reporter. A PATH is read for what it IS. Name a specs tree
+* — a directory with a `specs` segment in its path — and it walks that tree
+* with every tree pass: the token/HTTP grammar (D4 / D4b / D10), the
+* `<case>.spec.yaml` document conventions, the cross-file passes (C9 dead
 * fixtures, C14/C15 fixture placement, B5 await-using inference, A7 database
-* property). With `--member <dir>` it runs the member pass (E3 config-present,
-* E5b no simulated DOM in a config, F8 no seam dependency) over one workspace
-* member, whether or not that member has a `specs/` root.
+* property) and the facet passes (C12, C18, C20, C21w), which read the first
+* level of the tree and are the reason the anchor has to be right. Name
+* anything else and it is a PROJECT ROOT: the run is the path-less one,
+* anchored there. With `--member <dir>` it runs the member pass (E3
+* config-present, E5b no simulated DOM in a config, F8 no seam dependency)
+* over one workspace member, whether or not that member has a `specs/` root.
 *
 * With NO path it runs both over the whole project: every `specs/` root it
 * discovers from the root manifest's workspaces, and every member. That is the
 * run `@jterrazz/typescript`'s ratchet rests on, so the contract is exactly
 * "a path-less run reports what the per-root and per-member runs report".
 *
+* A NAMED root that turns out to hold no `specs/` tree at all is refused, loud
+* and non-zero. Pointed at a project root, the facet passes used to key on its
+* first level, find no facet folder there and report nothing — `<project>` and
+* `<project>/specs` disagreed on the same tree, and the run that reported
+* nothing was the one a CI line was likelier to be written with.
+*
 * `--format json` prints `[{ code, file, line, severity, message }]` on stdout
 * and nothing else, where `code` is `jterrazz-check(<id>)` — the namespace the
 * ratchet records under. Exit 1 on any ERROR-level violation either way;
 * warnings are reported but never fail the run.
 *
 * `--fix` applies the rewritable passes — the two document ones (key order and
-* block scalars) and C14, which MOVES a single-reader pool fixture beside its
-* leaf and rewrites the literals that named it — then checks what is left, so a
-* run that fixes everything exits 0. The move is a plain rename: the checker
-* never runs git, and the author stages what the working tree now shows.
+* block scalars), C14, which MOVES a single-reader pool fixture beside its leaf
+* and rewrites the literals that named it, and C12, which RENAMES a `.test.ts`
+* under a facet folder to `.spec.ts` — then checks what is left, so a run that
+* fixes everything exits 0. With no path it applies them to every `specs/` root
+* it discovers: `--fix` means the same thing whichever run the operator typed.
+*
+* After a C12 rename it NAMES the entries of the owning member's configs that
+* the rename BROKE — a glob whose prefix covers a file it moved, or a literal
+* naming one — and nothing else. An entry the rename left behind collects
+* nothing, the run stays green with fewer files, and nothing else in the
+* toolchain would have said a word.
+*
+* C12's rename goes through `git mv` where the tree is a git working tree, so
+* the history follows the file across a migration that touches hundreds of
+* them; outside one it falls back to a plain rename. C14's move stays a plain
+* rename and the author stages what the working tree now shows.
 */
 const argv = process.argv.slice(2);
 const fix = argv.includes("--fix");
@@ -1871,10 +2701,17 @@ function valueOf(flag) {
 	const index = argv.indexOf(flag);
 	return index === -1 ? void 0 : argv[index + 1];
 }
-/** The passes a tree run puts over a `specs/` root. */
-const TREE_PASSES = "D4/D4b/D10 grammar, spec documents, C9 dead fixtures, C14/C15 fixture placement, B5 await-using, A7 database";
+/**
+* What a run names when it is clean — the pass REGISTRY, never a sentence
+* written beside it.
+*
+* The hand-written list stopped at the cross-file passes of 15.x while the
+* channel grew four tree passes and a suppression gate, so the summary
+* under-reported exactly what it exists to report.
+*/
+const TREE_PASSES = TREE_PASS_IDS.join(", ");
 /** The passes a member run puts over a package. */
-const MEMBER_PASSES = "E3 config-present, E5b no simulated DOM, F8 no seam dependency";
+const MEMBER_PASSES = MEMBER_PASS_IDS.join(", ");
 /**
 * Print the findings and exit on the first error-level one. `passes` names the
 * ones that ACTUALLY ran: a member run that claimed the tree passes would be
@@ -1884,7 +2721,7 @@ function report(violations, what, passes) {
 	const errors = violations.filter((violation) => violation.severity === "error");
 	if (json) {
 		console.log(JSON.stringify(violations.map((violation) => ({
-			code: `jterrazz-check(${violation.rule})`,
+			code: `jterrazz-check(${codeOf(violation.rule)})`,
 			file: violation.file,
 			line: violation.line,
 			message: violation.message,
@@ -1914,22 +2751,191 @@ if (member !== void 0) {
 	const dir = requireDirectory(member, "member directory");
 	report(checkMember(dir, root), `for member ${relative(root, dir) || "."}`, MEMBER_PASSES);
 }
-if (positional !== void 0) {
-	const root = requireDirectory(positional, "directory");
-	if (fix) {
-		const written = fixSpecFiles(root);
-		if (written.length > 0) console.log(`conventions checker: rewrote ${written.length} spec document(s)`);
-		for (const move of fixPoolFixtures(root)) console.log(`conventions checker: moved ${move} (C14) — stage the rename`);
+/**
+* Rename one file, keeping git's record of it where there is one.
+*
+* `git mv` is tried first and its failure is not an error: a path outside a
+* working tree, or one git does not track yet, renames exactly as well with
+* `renameSync` — what must not happen is a migration that loses the history of
+* every spec it touches because the tool reached for the blunter call.
+*/
+function renameKeepingHistory(from, to) {
+	if (spawnSync("git", [
+		"mv",
+		from,
+		to
+	], {
+		cwd: dirname(from),
+		stdio: "ignore"
+	}).status !== 0) renameSync(from, to);
+}
+/** C12's mover: every `.test.ts` under a facet folder becomes a `.spec.ts`. */
+function fixSpecSuffixes(root) {
+	const renamed = [];
+	for (const { from, to } of movesUnderFacet(root)) {
+		if (to === void 0 || existsSync(to)) continue;
+		renameKeepingHistory(from, to);
+		renamed.push({
+			from,
+			to
+		});
+	}
+	return renamed;
+}
+/** Where a member states what it collects, whatever extension it writes it in. */
+const CONFIG_NAMES = [
+	"vitest.config.ts",
+	"vitest.config.mts",
+	"vitest.config.cts",
+	"vitest.config.js",
+	"vitest.config.mjs",
+	"vitest.config.cjs"
+];
+/** What a config COLLECTS: the two keys whose entries name test files. */
+const COLLECTION = /\b(?:include|exclude)\s*:\s*\[(?<entries>[^\]]*)\]/gu;
+/** One quoted entry of such a list. */
+const ENTRY = /['"`](?<entry>[^'"`\n]*)['"`]/gu;
+/** The quotes a config's entries are written in. */
+const QUOTES = /* @__PURE__ */ new Set([
+	"'",
+	"\"",
+	"`"
+]);
+/** The index of the newline ending the `//` comment that starts at `index`. */
+function endOfLineComment(text, index) {
+	const newline = text.indexOf("\n", index);
+	return newline === -1 ? text.length : newline;
+}
+/** The index just past the block comment that starts at `index`. */
+function endOfBlockComment(text, index) {
+	const close = text.indexOf("*/", index + 2);
+	return close === -1 ? text.length : close + 2;
+}
+/**
+* The config, with what is not code taken out.
+*
+* A notice that read a COMMENT as an include told signews-mobile to follow a
+* glob no project collected on. The scan is character by character because a
+* regex cannot tell the two apart: `specs/api/**` + `/*.test.ts` opens a block
+* comment to any pattern that does not know it is inside a string, and a `://`
+* opens a line comment to one that does not either.
+*/
+function withoutComments(text) {
+	let out = "";
+	let quote = null;
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index] ?? "";
+		const pair = text.slice(index, index + 2);
+		if (quote !== null) {
+			const escaped = char === "\\";
+			out += escaped ? pair : char;
+			quote = char === quote ? null : quote;
+			index += escaped ? 2 : 1;
+		} else if (pair === "//") {
+			out += "\n";
+			index = endOfLineComment(text, index);
+		} else if (pair === "/*") index = endOfBlockComment(text, index);
+		else {
+			quote = QUOTES.has(char) ? char : null;
+			out += char;
+			index += 1;
+		}
 	}
+	return out;
+}
+/**
+* Does this entry of a config sitting in `dir` reach `file`?
+*
+* A glob reaches what its literal PREFIX — everything before the first `*` —
+* contains; an entry with no `*` reaches the one file it names. Both are
+* resolved against the config's own directory, which is what vitest does.
+*/
+function reaches(dir, entry, file) {
+	const star = entry.indexOf("*");
+	if (star === -1) return resolve(dir, entry) === file;
+	const prefix = resolve(dir, entry.slice(0, star));
+	return file === prefix || file.startsWith(`${prefix}/`);
+}
+/** Every entry of every `include`/`exclude` list a config states. */
+function collectedEntries(text) {
+	const entries = [];
+	for (const list of text.matchAll(COLLECTION)) for (const match of (list.groups?.entries ?? "").matchAll(ENTRY)) entries.push(match.groups?.entry ?? "");
+	return entries;
+}
+/** What one broken entry says, glob or literal. */
+function noticeFor(where, entry) {
+	return entry.includes("*") ? `${where}: ${entry} still names \`.test.ts\` — the files it collected are \`.spec.ts\` now, and the project collects nothing until the glob follows (C12)` : `${where}: ${entry} names a file this run renamed — it is \`${entry.slice(0, -8)}.spec.ts\` now, and the entry collects nothing until it follows (C12)`;
+}
+/** The entries of ONE config the renames broke. */
+function staleEntriesIn(path, owner, renamed) {
+	const directory = dirname(path);
+	return collectedEntries(withoutComments(readFileSync(path, "utf8"))).filter((entry) => entry.endsWith(".test.ts")).filter((entry) => renamed.some(({ from }) => reaches(directory, entry, from))).map((entry) => noticeFor(relative(owner, path), entry));
+}
+/**
+* The entries a rename leaves behind.
+*
+* A consumer that names its suffix in an `include` loses the whole suite the
+* moment the mover renames it: vitest collects fewer files, exits 0, and the
+* only trace is a number nobody compares. The mover owns that consequence —
+* it cannot rewrite a config it does not parse, so it NAMES what it broke, and
+* the author updates it in the same commit as the rename.
+*
+* What it names is exactly what it broke: an entry of an `include`/`exclude`
+* list, never a comment, and only where the entry reaches a file this run
+* actually moved. A glob over `src/` collecting module tests the mover never
+* touched is not a stale glob, and four repositories of the wave were told it
+* was — one of them would have emptied its unit project by following the
+* notice.
+*/
+function staleIncludes(root, renamed) {
+	if (renamed.length === 0) return [];
+	const owner = packageRootOf(root) ?? dirname(root);
+	return [.../* @__PURE__ */ new Set([
+		root,
+		owner,
+		dirname(root)
+	])].flatMap((directory) => CONFIG_NAMES.map((name) => join(directory, name)).filter((path) => existsSync(path))).flatMap((path) => staleEntriesIn(path, owner, renamed));
+}
+/** Apply every rewritable pass over one tree, printing what it did. */
+function applyFixes(root) {
+	const renamed = fixSpecSuffixes(root);
+	for (const { from, to } of renamed) console.log(`conventions checker: renamed ${relative(root, from)} → ${relative(root, to)} (C12)`);
+	for (const stale of staleIncludes(root, renamed)) console.log(`conventions checker: ${stale}`);
+	const written = fixSpecFiles(root);
+	if (written.length > 0) console.log(`conventions checker: rewrote ${written.length} spec document(s)`);
+	for (const move of fixPoolFixtures(root)) console.log(`conventions checker: moved ${move} (C14) — stage the rename`);
+}
+/**
+* Is this directory a specs tree?
+*
+* The `specs` SEGMENT is the anchor every other pass reads (`specsAnchor`), so
+* the CLI reads it too: `specs`, `apps/web/specs` and `specs/api` are trees —
+* a subtree of one is still inside it — and everything else is a project root
+* holding zero or more of them.
+*/
+function isSpecsTree(dir) {
+	return dir.split(/[/\\]/u).includes("specs");
+}
+if (positional !== void 0 && isSpecsTree(requireDirectory(positional, "directory"))) {
+	const root = requireDirectory(positional, "directory");
+	if (fix) applyFixes(root);
 	report(runAllChecks(root), `under ${root}`, TREE_PASSES);
 }
-const root = resolve(".");
+const root = positional === void 0 ? resolve(".") : requireDirectory(positional, "directory");
+const specsRoots = discoverSpecRoots(root);
+if (positional !== void 0 && specsRoots.length === 0) {
+	console.error(`conventions checker: no \`specs/\` tree under ${root} — name a specs tree, or a project root that holds one`);
+	process.exit(1);
+}
 const found = [];
-for (const specsRoot of discoverSpecRoots(root)) {
+for (const specsRoot of specsRoots) {
 	const prefix = relative(root, specsRoot);
+	if (fix) applyFixes(specsRoot);
 	for (const violation of runAllChecks(specsRoot)) found.push({
 		...violation,
-		file: `${prefix}/${violation.file}`
+		file: `${prefix}/${violation.file}`,
+		message: `${prefix}/${violation.message}`
 	});
 }
 found.push(...checkMembers(root));