@jterrazz/test 16.0.0 → 16.1.0

package/dist/checker.js

@@ -688,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/19-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"
 			});
@@ -939,6 +939,13 @@ const SKIPPED$2 = /* @__PURE__ */ new Set([
 	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 {
@@ -1045,6 +1052,7 @@ function checkModuleTestUnderFacet(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({
@@ -1142,6 +1150,14 @@ function checkGroundOwnedByOne(specsRoot) {
 *   (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([
@@ -1229,23 +1245,39 @@ function checkSpecOutsideSpecs(memberDir) {
 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 \`specs/${rel.split(/[/\\]/u)[0] ?? ""}/\` specifies the assembled product — rename it \`.spec.ts\` (fixable: \`jterrazz-test-check <root> --fix\`) (C12 — see docs/19-linting.md)`,
+			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 (parts.length < 2 || facet === void 0 || !FACETS.has(facet)) continue;
+		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({
@@ -1273,6 +1305,16 @@ function movesUnderFacet(specsRoot) {
 * 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;
 /**
@@ -1310,16 +1352,80 @@ const RETIRED_SCOPES = ["@testing-library/"];
 * 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 is read from the member itself — a
-* declared `jest`, a `jest` field, or a `test` script that calls it — so it
-* lapses the day the member stops running jest.
+* 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 this member run jest? */
-function runsJest(manifest) {
+/** 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$1 = [
 	"vitest.config.ts",
@@ -1329,14 +1435,6 @@ const CONFIG_NAMES$1 = [
 	"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");
@@ -1394,9 +1492,8 @@ 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 jestRuns = runsJest(manifest);
 	const isRetired = (name) => {
 		if (name === JEST_ONLY_SEAM && jestRuns) return false;
 		return RETIRED.has(name) || RETIRED_SCOPES.some((scope) => name.startsWith(scope));
@@ -1452,8 +1549,9 @@ 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/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)`,
@@ -1488,7 +1586,13 @@ 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)
 	];
 }
@@ -1509,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.
@@ -1573,7 +1675,8 @@ const SPECS_DEPTH = 6;
 */
 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;
@@ -2219,7 +2322,7 @@ const CLOCK_READ = /'now'|\bCURRENT_(?:TIMESTAMP|DATE|TIME)\b|\bNOW\s*\(\s*\)/iu
 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(text) {
+function withoutComments$1(text) {
 	return text.replaceAll(SQL_BLOCK_COMMENT, (block) => block.replaceAll(/[^\n]/gu, " ")).replaceAll(SQL_LINE_COMMENT, "");
 }
 /**
@@ -2394,7 +2497,7 @@ function checkSeedClockReads(path, rel, name) {
 	const text = decodeText(path);
 	if (text === null) return [];
 	const violations = [];
-	for (const [index, line] of withoutComments(text).split("\n").entries()) {
+	for (const [index, line] of withoutComments$1(text).split("\n").entries()) {
 		const found = CLOCK_READ.exec(line);
 		if (found === null) continue;
 		violations.push({
@@ -2532,23 +2635,33 @@ 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;
@@ -2561,10 +2674,11 @@ function formatViolations(violations) {
 * 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 every include glob of the owning member that
-* still says `.test.ts`. A glob the rename left behind collects nothing, the
-* run stays green with fewer files, and nothing else in the toolchain would
-* have said a word.
+* 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
@@ -2661,7 +2775,10 @@ function fixSpecSuffixes(root) {
 	for (const { from, to } of movesUnderFacet(root)) {
 		if (to === void 0 || existsSync(to)) continue;
 		renameKeepingHistory(from, to);
-		renamed.push(`${relative(root, from)} → ${relative(root, to)}`);
+		renamed.push({
+			from,
+			to
+		});
 	}
 	return renamed;
 }
@@ -2674,53 +2791,145 @@ const CONFIG_NAMES = [
 	"vitest.config.mjs",
 	"vitest.config.cjs"
 ];
-/** Any string in a config that ends in the suffix the mover just retired. */
-const TEST_GLOB = /['"`](?<glob>[^'"`]*\*[^'"`]*\.test\.ts)['"`]/gu;
+/** 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 include globs a rename leaves behind.
+* 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 every glob that
-* still says `.test.ts` in the configs of the member it just moved files
-* under, and the author updates them in the same commit as the rename.
-*/
-function staleIncludes(root) {
+* 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);
-	const found = [];
-	for (const directory of /* @__PURE__ */ new Set([
+	return [.../* @__PURE__ */ new Set([
 		root,
 		owner,
 		dirname(root)
-	])) for (const name of CONFIG_NAMES) {
-		const path = join(directory, name);
-		if (!existsSync(path)) continue;
-		const text = readFileSync(path, "utf8");
-		for (const match of text.matchAll(TEST_GLOB)) {
-			const glob = match.groups?.glob ?? "";
-			if (glob !== "") found.push(`${relative(owner, path)}: ${glob}`);
-		}
-	}
-	return found;
+	])].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 rename of renamed) console.log(`conventions checker: renamed ${rename} (C12)`);
-	for (const glob of renamed.length === 0 ? [] : staleIncludes(root)) console.log(`conventions checker: ${glob} still names \`.test.ts\` — the files it collected are \`.spec.ts\` now, and the project collects nothing until the glob follows (C12)`);
+	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`);
 }
-if (positional !== void 0) {
+/**
+* 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({

package/dist/index.d.ts

@@ -707,8 +707,25 @@ type CallResultOptions = BaseResultOptions & {
  * What `result.value` is, decided by what the call returned: a string reads as
  * a stream, anything else as JSON. `.call<T>()` already knows T, so the test
  * reads one field (`result.value.value.ok`) without narrowing a union first.
+ *
+ * Three answers, because a type has three ways of relating to `string`:
+ *
+ * - EXACTLY a string — a `TextAccessor`, and nothing to narrow;
+ * - it MAY be a string (`string | undefined`, `string | number`, `any`) — the
+ *   UNION, which the test narrows. The type used to read the static type only
+ *   while the accessor was built from the RUNTIME value, so a subject typed
+ *   `string | undefined` was handed back as a `JsonAccessor`: `.value.value`
+ *   compiled, the runtime had built a `TextAccessor`, and the read silently
+ *   answered `undefined`;
+ * - never a string — a `JsonAccessor<Returned>`.
+ *
+ * `Returned` there is what the value CLAIMS, not what survived the crossing:
+ * the accessor is built from `JSON.stringify`, so a `Map`, a `Date` or a class
+ * instance arrives as the plain JSON it serialises to (`{}`, an ISO string, an
+ * object of its own fields). A subject whose answer is one of those is
+ * projected to plain data inside the call, where the test can see it happen.
  */
-type CallValue<Returned> = Returned extends string ? TextAccessor : JsonAccessor<Returned>;
+type CallValue<Returned> = [Returned] extends [string] ? TextAccessor : [Extract<Returned, string>] extends [never] ? JsonAccessor<Returned> : JsonAccessor<Exclude<Returned, string>> | TextAccessor;
 /**
  * The result of an in-process call — the integration facet's whole surface.
  *
@@ -741,10 +758,14 @@ declare class CallResult<Returned = unknown> extends BaseResult {
   /**
    * What the call RETURNED. A string reads as a stream (`<name>.txt`),
    * anything else as JSON (`<name>.json`) — the same two subjects every
-   * other facet's results are built from.
+   * other facet's results are built from, chosen on the value in hand and
+   * typed by {@link CallValue}, which answers for the three ways a type can
+   * relate to `string`.
    *
-   * A call that threw returns the empty value: what it produced is
-   * {@link CallResult.error}.
+   * A call that threw has no value to choose an accessor on, so `value` is
+   * the JSON reading of `null` whatever the declared type promises: what a
+   * refusal produced is {@link CallResult.error}, and that is where a spec
+   * reads it.
    */
   get value(): CallValue<Returned>;
 }
@@ -2883,6 +2904,14 @@ type WebsiteSpecificationOptions<Services extends ServiceRecord = ServiceRecord>
    * API it was started beside.
    */
   services?: Services;
+  /**
+   * Escape hatch: normaliser applied to every compared reading of a result
+   * — the head projection and the json-ld among them — before the
+   * comparison (CONVENTIONS D6). Does NOT mutate the raw `.text` accessor.
+   * Prefer `{{token}}` placeholders in fixtures; this is for what a token
+   * cannot name, a meta a FRAMEWORK owns and the page never asked for.
+   */
+  transform?: ((text: string) => string) | undefined;
 } & ({
   /**
    * Declared stub backend: started BEFORE the server command, its