@jterrazz/test 15.2.0 → 15.3.0

package/dist/checker.js

@@ -2,7 +2,8 @@
 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 { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
 //#region src/lint/checker-crossfile.ts
 /**
 * The cross-file checker passes — the analyses oxlint cannot express because
@@ -233,6 +234,23 @@ function collectLiterals(text) {
 	}
 	return found;
 }
+const TEMPLATE_WITH_HOLE = /`(?<body>(?:[^`\\]|\\.)*\$\{(?:[^`\\]|\\.)*)`/gu;
+function collectLiteralPatterns(text) {
+	const found = [];
+	for (const match of text.matchAll(TEMPLATE_WITH_HOLE)) {
+		const body = match.groups?.body ?? "";
+		const opens = body.indexOf("${");
+		const closes = body.lastIndexOf("}");
+		if (opens === -1 || closes === -1 || closes < opens) continue;
+		const prefix = body.slice(0, opens);
+		const suffix = body.slice(closes + 1);
+		if (prefix.length > 0 || suffix.length > 0) found.push({
+			prefix,
+			suffix
+		});
+	}
+	return found;
+}
 /**
 * Does the text pass a NON-literal argument to a fixture-ish verb
 * (`.seed`/`.request`/`.fixture`/`toMatch`)? A template with an expression or a
@@ -423,6 +441,7 @@ function checkDockerRunnerAwaitUsing(rootDir) {
 				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)`,
+				rule: "b5",
 				severity: "error"
 			});
 		}
@@ -480,12 +499,14 @@ function checkDatabaseProperty(rootDir) {
 				file: rel,
 				line,
 				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/13-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)`,
+				rule: "a7",
 				severity: "error"
 			});
 		}
@@ -493,7 +514,8 @@ function checkDatabaseProperty(rootDir) {
 	return violations;
 }
 /** Is a top-level ground-subdir entry referenced by any test literal? */
-function entryReferenced(entry, entryIsDir, literals) {
+function entryReferenced(entry, entryIsDir, literals, patterns = []) {
+	for (const pattern of patterns) if (entry.startsWith(pattern.prefix) && entry.endsWith(pattern.suffix)) return true;
 	for (const literal of literals) {
 		if (entryIsDir) {
 			if (literal === entry || literal.startsWith(`${entry}/`) || literal.includes(`/${entry}`)) return true;
@@ -534,11 +556,13 @@ function checkDeadFixtures(rootDir) {
 				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)`,
+				rule: "c9",
 				severity: "error"
 			});
 			continue;
 		}
 		const literals = /* @__PURE__ */ new Set();
+		const patterns = [];
 		let downgrade = false;
 		for (const testFile of testFiles) {
 			if (testFile.endsWith(".spec.yaml")) {
@@ -547,6 +571,7 @@ function checkDeadFixtures(rootDir) {
 			}
 			const text = readSource(testFile);
 			for (const literal of collectLiterals(text)) literals.add(literal);
+			patterns.push(...collectLiteralPatterns(text));
 			downgrade ||= hasNonLiteralFixtureArg(text);
 		}
 		const severity = downgrade ? "warn" : "error";
@@ -554,12 +579,13 @@ function checkDeadFixtures(rootDir) {
 			const subPath = join(dir, sub);
 			for (const entry of readdirSync(subPath, { withFileTypes: true })) {
 				const entryIsDir = entry.isDirectory();
-				if (entryReferenced(entry.name, entryIsDir, literals)) continue;
+				if (entryReferenced(entry.name, entryIsDir, literals, patterns)) continue;
 				const relEntry = relative(rootDir, join(subPath, entry.name));
 				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)`,
+					rule: "c9",
 					severity
 				});
 			}
@@ -585,6 +611,7 @@ function checkPoolFixtures(rootDir) {
 				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)`,
+				rule: "c9",
 				severity: "error"
 			});
 		}
@@ -688,6 +715,7 @@ function checkPoolFixtureSharing(rootDir) {
 			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)`,
+			rule: "c14",
 			severity: "error"
 		};
 	});
@@ -741,6 +769,7 @@ function checkLocalFixtureReach(rootDir) {
 					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)`,
+					rule: "c15",
 					severity: "error"
 				});
 			}
@@ -749,6 +778,330 @@ function checkLocalFixtureReach(rootDir) {
 	return violations;
 }
 //#endregion
+//#region src/lint/checker-member.ts
+/**
+* The MEMBER pass — what a workspace member owes, read from the member itself
+* rather than from a spec tree.
+*
+* The three findings here answer questions no file under `specs/` can: does
+* this member have a vitest config at all, does its config give every test it
+* collects a drawing of a browser, and does it declare a dependency the
+* framework already carries. A member with no `specs/` root is still judged —
+* that is the whole point, since the first of the three is about a member that
+* has tests and no configuration for them.
+*
+* The pass is the toolchain's door: `jterrazz-test-check --member <dir>` runs
+* it for one member, and a path-less `--format json` run at the project root
+* runs it for every member the root manifest declares.
+*/
+/** The two simulated DOMs — the same pair the statique E5b refuses. */
+const SIMULATED_DOM = /\benvironment\s*:\s*['"](?<dom>happy-dom|jsdom)['"]/u;
+/**
+* Dependencies `@jterrazz/test` carries. A member declaring one of these
+* duplicates a transitive it already resolves. Optional peers are not here:
+* `playwright`, `vite`, `react`, `better-sqlite3` and their kin are declared
+* BY the consumer on purpose.
+*/
+const CARRIED = /* @__PURE__ */ new Set(["msw", "vitest-mock-extended"]);
+/**
+* Carried, but only where it can only be the test seam's. `yaml` is a product
+* library as much as a fixture reader: a member that parses YAML at RUNTIME
+* declares it rightly, and a rule that read `dependencies` here would be
+* telling a product to drop a library the framework never ships to it. So the
+* finding is limited to the one declaration that can only mean the seam.
+*/
+const CARRIED_IN_DEV = /* @__PURE__ */ new Set(["yaml"]);
+/**
+* The framework itself. It DECLARES what every other member inherits, so the
+* one manifest F8 must never read is its own — a rule that fired on the
+* package carrying the dependency would be asking it to remove the thing it
+* exists to provide.
+*/
+const FRAMEWORK = "@jterrazz/test";
+const RETIRED = /* @__PURE__ */ new Set([
+	"@playwright/test",
+	"happy-dom",
+	"jsdom",
+	"mockdate"
+]);
+const RETIRED_SCOPES = ["@testing-library/"];
+/** 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"
+];
+/** 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");
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** The member's vitest config, by path, or null. */
+function configOf(dir) {
+	for (const name of CONFIG_NAMES) {
+		const path = join(dir, name);
+		if (existsSync(path)) return path;
+	}
+	return null;
+}
+/**
+* Does this member hold a test file it OWNS?
+*
+* A directory carrying its own `package.json` is another package's tree — a
+* workspace member, a vendored clone — and its tests are its own to configure.
+* A root that only delegates would otherwise be told to write a config for
+* files it never collects, which is the finding read backwards.
+*/
+function holdsTests(dir) {
+	const stack = [dir];
+	let first = true;
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0) break;
+		if (!first && existsSync(join(current, "package.json"))) continue;
+		first = false;
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				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;
+		}
+	}
+	return false;
+}
+/**
+* A `test` script that only hands the work to the members below it. It is not
+* evidence that THIS package runs vitest — `npm run test --workspaces`,
+* `pnpm -r test` and `turbo run test` all read as "ask the members".
+*/
+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) {
+	if (manifest.name === FRAMEWORK) return [];
+	const isRetired = (name) => 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
+	}));
+}
+/** The line a manifest key is written on — a finding points at the declaration, not at `{`. */
+function lineOfKey(dir, key) {
+	try {
+		const found = readFileSync(join(dir, "package.json"), "utf8").split("\n").findIndex((line) => line.includes(`"${key}"`));
+		return found === -1 ? 1 : found + 1;
+	} catch {
+		return 1;
+	}
+}
+/**
+* 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.
+*/
+/** E3 — a member with tests of its own states how they run. */
+function configPresent(manifest, memberDir, label, subject) {
+	const testScript = manifest.scripts?.test;
+	if (!(typeof testScript === "string" && !DELEGATING_TEST.test(testScript) || holdsTests(memberDir))) return [];
+	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)`,
+		rule: "e3",
+		severity: "error"
+	}];
+}
+/** E5b — a config that gives every file it collects a drawing of a browser. */
+function simulatedDom(config, rootDir) {
+	const text = readFileSync(config, "utf8");
+	const found = SIMULATED_DOM.exec(text);
+	if (found?.groups?.dom === void 0) return [];
+	const relConfig = relative(rootDir, config);
+	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)`,
+		rule: "e5b",
+		severity: "error"
+	}];
+}
+/**
+* F8 — a dependency the framework already carries, or a seam it replaced.
+*
+* 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) => ({
+		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)`,
+		rule: "f8",
+		severity: "error"
+	}));
+}
+/**
+* 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.
+*/
+function checkMember(memberDir, rootDir) {
+	const manifest = readManifest(memberDir);
+	if (manifest === null) return [];
+	const label = relative(rootDir, memberDir) || ".";
+	const subject = label === "." ? manifest.name ?? basename(memberDir) : label;
+	const config = configOf(memberDir);
+	return [
+		...config === null ? configPresent(manifest, memberDir, label, subject) : [],
+		...config === null ? [] : simulatedDom(config, rootDir),
+		...seamDependencies(manifest, memberDir, label, subject)
+	];
+}
+/** The glob-ish workspace patterns a root manifest declares. */
+function workspacePatterns(manifest) {
+	const { workspaces } = manifest;
+	if (Array.isArray(workspaces)) return workspaces;
+	return workspaces?.packages ?? [];
+}
+/**
+* A glob over path SEGMENTS — `*` stops at a separator, `**` does not. The
+* same translation `@jterrazz/typescript`'s `lib/workspace-members.js` makes,
+* because the two lists have to be the same list: a member the toolchain runs
+* `--member` over and the path-less run never discovers is a finding the
+* ratchet can neither record nor clear.
+*/
+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.
+*/
+function discoverMembers(rootDir) {
+	const manifest = readManifest(rootDir);
+	if (manifest === null) return [];
+	const patterns = workspacePatterns(manifest).filter((glob) => typeof glob === "string" && !glob.startsWith("!")).map((glob) => toPattern(glob.replace(/\/+$/u, "")));
+	const members = /* @__PURE__ */ new Set([rootDir]);
+	if (patterns.length === 0) return [...members];
+	const walk = (dir, depth) => {
+		if (depth > MEMBER_DEPTH) return;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".") || SKIPPED.has(entry.name)) continue;
+			const child = join(dir, entry.name);
+			const path = relative(rootDir, child).split(sep).join("/");
+			if (patterns.some((pattern) => pattern.test(path)) && readManifest(child) !== null) {
+				members.add(child);
+				continue;
+			}
+			walk(child, depth + 1);
+		}
+	};
+	walk(rootDir, 0);
+	return [...members];
+}
+/** Paths git is told to ignore — the toolchain skips them, so the two lists agree. */
+function ignoredPaths(rootDir, candidates) {
+	if (candidates.length === 0) return /* @__PURE__ */ new Set();
+	try {
+		const answer = spawnSync("git", ["check-ignore", "--stdin"], {
+			cwd: rootDir,
+			encoding: "utf8",
+			input: `${candidates.join("\n")}\n`
+		});
+		if (answer.error !== void 0 || answer.stdout === "") return /* @__PURE__ */ new Set();
+		return new Set(answer.stdout.split("\n").filter(Boolean));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+/** How deep below a member a nested `specs/` may sit before the walk gives up. */
+const SPECS_DEPTH = 6;
+/**
+* Every `specs/` root the tree passes have to walk: the project's own, and
+* each member's — including a member that NESTS its facet tree (`web/specs`).
+* Stated here rather than guessed by the walk, so a path-less run reports
+* exactly what a per-root run would.
+*
+* 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.
+*/
+function discoverSpecRoots(rootDir) {
+	const roots = /* @__PURE__ */ new Set();
+	for (const member of discoverMembers(rootDir)) {
+		const walk = (dir, depth) => {
+			if (depth > SPECS_DEPTH) return;
+			let entries;
+			try {
+				entries = readdirSync(dir, { withFileTypes: true });
+			} catch {
+				return;
+			}
+			for (const entry of entries) {
+				if (!entry.isDirectory() || entry.name.startsWith(".") || SKIPPED.has(entry.name)) continue;
+				const child = join(dir, entry.name);
+				if (entry.name === "specs") {
+					roots.add(child);
+					continue;
+				}
+				if (readManifest(child) !== null) continue;
+				walk(child, depth + 1);
+			}
+		};
+		walk(member, 0);
+	}
+	const found = [...roots].toSorted();
+	const ignored = ignoredPaths(rootDir, found.map((path) => relative(rootDir, path)));
+	return found.filter((path) => !ignored.has(relative(rootDir, path)));
+}
+/** Run the member pass over every member the root declares. */
+function checkMembers(rootDir) {
+	return discoverMembers(rootDir).flatMap((member) => checkMember(member, rootDir));
+}
+//#endregion
+//#region src/lint/rule-code.ts
+/**
+* The convention code a checker pass id carries: `d4b-spec-shape` → `d4b`.
+*
+* It lives alone because BOTH sides need it — the passes that build a finding
+* and the entry that publishes one as `jterrazz-check(<code>)` — and a copy in
+* either would be a second answer to what a finding is called.
+*/
+function codeOf(passId) {
+	return passId.split("-")[0] ?? passId;
+}
+//#endregion
 //#region src/lint/checker-spec.ts
 function finding(rule, line, message, severity = "error") {
 	return {
@@ -1163,6 +1516,7 @@ function checkSpecConventions(text, rel, path) {
 		file: rel,
 		line,
 		message: `${rel}:${line}: ${message} (${rule} — see docs/13-linting.md)`,
+		rule: codeOf(rule),
 		severity
 	}));
 }
@@ -1194,6 +1548,7 @@ function checkSpecDescriptionsUnique(rootDir) {
 			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)`,
+			rule: "j4",
 			severity: "error"
 		});
 	}
@@ -1356,6 +1711,7 @@ function checkSpecFile(text, rel) {
 			file: rel,
 			line: error.line,
 			message: `${error.message} (D4b — see docs/13-linting.md)`,
+			rule: "d4b",
 			severity: "error"
 		}];
 	}
@@ -1366,6 +1722,7 @@ function checkSpecFile(text, rel) {
 			file: rel,
 			line: at,
 			message: `${rel}:${at}: unknown token ${token} — the D4 vocabulary is frozen (known: ${[...TOKEN_KINDS].join(", ")})`,
+			rule: "d4",
 			severity: "error",
 			token
 		});
@@ -1409,12 +1766,14 @@ function checkConventionFiles(rootDir) {
 					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)`,
+					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)`,
+					rule: "d10w",
 					severity: "warn",
 					token
 				});
@@ -1426,12 +1785,14 @@ function checkConventionFiles(rootDir) {
 				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)`,
+				rule: "d4b",
 				severity: "error"
 			});
 			for (const { line, token } of findUnknownTokens(text)) violations.push({
 				file: rel,
 				line,
 				message: `${rel}:${line}: unknown token ${token} — the D4 vocabulary is frozen (known: ${[...TOKEN_KINDS].join(", ")})`,
+				rule: "d4",
 				severity: "error",
 				token
 			});
@@ -1466,13 +1827,27 @@ function formatViolations(violations) {
 /**
 * CLI entry for the conventions checker (bundled as `dist/checker.js`).
 *
-*     node dist/checker.js [rootDir] [--fix]     # default root: cwd
+*     node dist/checker.js [rootDir] [--fix]          # a specs tree
+*     node dist/checker.js --format json              # every root, every member
+*     node dist/checker.js --member <dir>             # one workspace member
 *
-* Runs every checker pass — the token/HTTP grammar (D4 / D4b / D10), the
+* 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
 * fixtures, C14/C15 fixture placement, B5 await-using inference, A7 database
-* property). Exit 1 on any ERROR-level violation; warnings (D10, a downgraded C9
-* feature) are printed but do not fail the run.
+* 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.
+*
+* 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".
+*
+* `--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
@@ -1480,24 +1855,84 @@ function formatViolations(violations) {
 * 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.
 */
-const fix = process.argv.includes("--fix");
-const root = resolve(process.argv.slice(2).find((arg) => !arg.startsWith("--")) ?? ".");
-if (!existsSync(root) || !statSync(root).isDirectory()) {
-	console.error(`conventions checker: no such directory: ${root}`);
-	process.exit(1);
-}
-if (fix) {
-	const written = fixSpecFiles(root);
-	if (written.length > 0) console.log(`conventions checker: rewrote ${written.length} spec document(s)`);
-	for (const move of fixPoolFixtures(root)) console.log(`conventions checker: moved ${move} (C14) — stage the rename`);
-}
-const violations = runAllChecks(root);
-const errors = violations.filter((violation) => violation.severity === "error");
-if (violations.length > 0) (errors.length > 0 ? console.error : console.warn)(formatViolations(violations));
-if (errors.length > 0) {
-	console.error(`\nconventions checker: ${errors.length} error(s) found under ${root}`);
-	process.exit(1);
-}
-console.log(`conventions checker: all passes clean under ${root} (D4/D4b/D10 grammar, spec documents, C9 dead fixtures, C14/C15 fixture placement, B5 await-using, A7 database)${violations.length > 0 ? ` — ${violations.length} warning(s)` : ""}`);
+const argv = process.argv.slice(2);
+const fix = argv.includes("--fix");
+const json = valueOf("--format") === "json";
+const member = valueOf("--member");
+const positional = argv.find((argument, index) => {
+	if (argument.startsWith("--")) return false;
+	const previous = argv[index - 1];
+	return previous !== "--format" && previous !== "--member";
+});
+/** The value of `--flag value` or `--flag=value`, or undefined. */
+function valueOf(flag) {
+	const inline = argv.find((argument) => argument.startsWith(`${flag}=`));
+	if (inline !== void 0) return inline.slice(flag.length + 1);
+	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";
+/** The passes a member run puts over a package. */
+const MEMBER_PASSES = "E3 config-present, E5b no simulated DOM, F8 no seam dependency";
+/**
+* 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
+* telling the reader a `specs/` tree was judged when none was walked.
+*/
+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})`,
+			file: violation.file,
+			line: violation.line,
+			message: violation.message,
+			severity: violation.severity
+		}))));
+		process.exit(errors.length > 0 ? 1 : 0);
+	}
+	if (violations.length > 0) (errors.length > 0 ? console.error : console.warn)(formatViolations(violations));
+	if (errors.length > 0) {
+		console.error(`\nconventions checker: ${errors.length} error(s) found ${what}`);
+		process.exit(1);
+	}
+	console.log(`conventions checker: all passes clean ${what} (${passes})${violations.length > 0 ? ` — ${violations.length} warning(s)` : ""}`);
+	process.exit(0);
+}
+/** A directory that must exist — a typo'd path is operator error, not a clean tree. */
+function requireDirectory(path, what) {
+	const resolved = resolve(path);
+	if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+		console.error(`conventions checker: no such ${what}: ${resolved}`);
+		process.exit(1);
+	}
+	return resolved;
+}
+if (member !== void 0) {
+	const root = resolve(positional ?? ".");
+	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`);
+	}
+	report(runAllChecks(root), `under ${root}`, TREE_PASSES);
+}
+const root = resolve(".");
+const found = [];
+for (const specsRoot of discoverSpecRoots(root)) {
+	const prefix = relative(root, specsRoot);
+	for (const violation of runAllChecks(specsRoot)) found.push({
+		...violation,
+		file: `${prefix}/${violation.file}`
+	});
+}
+found.push(...checkMembers(root));
+report(found, `under ${root}`, `${TREE_PASSES}, ${MEMBER_PASSES}`);
 //#endregion
 export {};