@jterrazz/test 8.0.0 → 9.1.0

package/dist/checker.js

@@ -0,0 +1,741 @@
+#!/usr/bin/env node
+import { r as TOKEN_KINDS } from "./match.js";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+//#region src/lint/checker-crossfile.ts
+/**
+* The cross-file checker passes — the analyses oxlint cannot express because
+* they need to read TWO files at once (a `*.specification.ts` record and the
+* `specs/` test files importing it) or a whole feature tree at once.
+*
+* They live in the checker channel (bundled as `dist/checker.js`) rather than
+* the oxlint plugin, which only ever sees one source file. Each pass follows
+* the checker doctrine: **precision over recall** — a heuristic that cannot
+* decide stays silent (under-reports) so the pass never blocks a legitimate
+* shape. All three are string/scan based (no TS parser in the light lint
+* bundle), matching the token checker's aesthetic.
+*
+* - **C9 dead fixtures** — per feature dir, a fixture file no test literal
+*   references is dead weight; a feature dir with conventional subdirs but no
+*   `<feature>.test.ts` is an orphan.
+* - **B5 await-using (inference)** — the docker-aware runners of a spec file
+*   are derived from its `docker:` option, then every `<runner>….exec()` bound
+*   without `await using` in an importing test is flagged. The primary B5
+*   channel now (the oxlint rule needs the runner names spelled out by hand).
+* - **A7 database property** — a spec's `services:` record fixes how many SQL
+*   databases exist; importing tests must (≥2) or must not (==1) pass
+*   `{ database }` to every `.seed()` / `.table()`.
+*/
+/** Directories the cross-file walks never descend into. */
+const PRUNED = /* @__PURE__ */ new Set([
+	".git",
+	"dist",
+	"node_modules"
+]);
+/** Conventional per-feature subdirectories whose files are assertion fixtures. */
+const CONVENTIONAL_SUBDIRS = /* @__PURE__ */ new Set([
+	"expected",
+	"fixtures",
+	"intercepts",
+	"requests",
+	"seeds"
+]);
+/** Destructured names that are never a runner (so never the A7/B5 subject). */
+const NON_RUNNER_BINDINGS = /* @__PURE__ */ new Set([
+	"cleanup",
+	"docker",
+	"orchestrator"
+]);
+/** The specification constructors whose records/options the passes read. */
+const CONSTRUCTORS = "api|cli|jobs";
+/**
+* A `$FIXTURES` pool (`.../specs/fixtures`) is verbatim fixture material — the
+* reusable apps AND the lint-violation trees that fail on purpose — never live
+* specs. The cross-file walks prune it (like the token checker skips
+* `fixtures/`); {@link checkPoolFixtures} inspects its top level separately.
+*/
+function isPool(dir) {
+	return basename(dir) === "fixtures" && basename(dirname(dir)) === "specs";
+}
+/** Recursively list every file under `dir`, skipping pruned dirs and the pool. */
+function listFiles(dir, predicate) {
+	const out = [];
+	const visit = (current) => {
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const path = join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (!PRUNED.has(entry.name) && !isPool(path)) visit(path);
+			} else if (predicate(path)) out.push(path);
+		}
+	};
+	visit(dir);
+	return out;
+}
+/** Recursively list every directory under `dir` (inclusive), pool pruned. */
+function listDirs(dir) {
+	const out = [];
+	const visit = (current) => {
+		out.push(current);
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const path = join(current, entry.name);
+			if (entry.isDirectory() && !PRUNED.has(entry.name) && !isPool(path)) visit(path);
+		}
+	};
+	visit(dir);
+	return out;
+}
+/** Locate `$FIXTURES` pools (unlike {@link listDirs}, does not prune them). */
+function findPools(dir) {
+	const pools = [];
+	const visit = (current) => {
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory() || PRUNED.has(entry.name)) continue;
+			const path = join(current, entry.name);
+			if (isPool(path)) pools.push(path);
+			else visit(path);
+		}
+	};
+	visit(dir);
+	return pools;
+}
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return "";
+	}
+}
+/**
+* Blank out `//` and block comments (replacing them with spaces, newlines
+* preserved so offsets and line numbers stay intact) while leaving string
+* literals untouched. The regex/scan passes read this so a commented-out
+* `.exec()` or a comma inside a `services:` comment never confuses them.
+*/
+function blankComments(text) {
+	const out = [...text];
+	let state = "";
+	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 (char === "*" && next === "/") {
+				out[i] = " ";
+				out[i + 1] = " ";
+				i += 1;
+				state = "";
+			} else if (char !== "\n") out[i] = " ";
+		} else if (state === "\"" || state === "'" || state === "`") {
+			if (char === "\\") i += 1;
+			else if (char === state) state = "";
+		} else if (char === "/" && next === "/") {
+			out[i] = " ";
+			state = "line";
+		} else if (char === "/" && next === "*") {
+			out[i] = " ";
+			state = "block";
+		} else if (char === "\"" || char === "'" || char === "`") state = char;
+	}
+	return out.join("");
+}
+/** File contents with comments blanked — the parse view for the scan passes. */
+function readSource(path) {
+	return blankComments(readText(path));
+}
+function isDir(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** The 1-based line number of a source offset. */
+function lineAt(text, index) {
+	let line = 1;
+	for (let i = 0; i < index && i < text.length; i += 1) if (text[i] === "\n") line += 1;
+	return line;
+}
+/**
+* Every quoted string and simple template literal in a source. Over-collection
+* only ever *hides* a dead-fixture finding, so a greedy regex is safe here.
+*/
+const STRING_LITERAL = /'(?<single>(?:[^'\\\n]|\\.)*)'|"(?<double>(?:[^"\\\n]|\\.)*)"|`(?<template>(?:[^`$\\]|\\.)*)`/g;
+function collectLiterals(text) {
+	const found = /* @__PURE__ */ new Set();
+	for (const match of text.matchAll(STRING_LITERAL)) {
+		const value = match.groups?.single ?? match.groups?.double ?? match.groups?.template;
+		if (value !== void 0 && value.length > 0) found.add(value);
+	}
+	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
+* variable makes the reference set incomplete, so the feature is reported at
+* warn level instead of error (a false positive would be worse than a miss).
+*/
+const FIXTURE_VERB_ARG = /(?:\.(?:seed|request|fixture)|\btoMatch)\s*\(\s*(?<arg>[^,)]*)/g;
+function hasNonLiteralFixtureArg(text) {
+	for (const match of text.matchAll(FIXTURE_VERB_ARG)) {
+		const arg = (match.groups?.arg ?? "").trim();
+		if (arg.length === 0) continue;
+		if (!(/^'(?:[^'\\\n]|\\.)*'$/.test(arg) || /^"(?:[^"\\\n]|\\.)*"$/.test(arg) || /^`(?:[^`$\\]|\\.)*`$/.test(arg))) return true;
+	}
+	return false;
+}
+/**
+* `// checker-disable-next-line <id>[,<id>] -- reason` suppresses the passes
+* named by id (`a7`, `b5`, `c9`, or `*`) on the next non-blank line;
+* `checker-disable-line` suppresses its own line. Mirrors the oxlint-disable
+* idiom the repo already uses for negative specs.
+*/
+function suppressedLines(text, id) {
+	const suppressed = /* @__PURE__ */ new Set();
+	const lines = text.split("\n");
+	const applies = (raw) => {
+		const ids = raw.replace(/--.*$/, "").trim().split(/[\s,]+/);
+		return ids.includes(id) || ids.includes("*");
+	};
+	for (const [index, line] of lines.entries()) {
+		let match = /checker-disable-next-line\s+(?<ids>.*)$/i.exec(line);
+		if (match !== null && applies(match.groups?.ids ?? "")) {
+			for (let next = index + 1; next < lines.length; next += 1) if (lines[next].trim().length > 0) {
+				suppressed.add(next + 1);
+				break;
+			}
+		}
+		match = /checker-disable-line\s+(?<ids>.*)$/i.exec(line);
+		if (match !== null && applies(match.groups?.ids ?? "")) suppressed.add(index + 1);
+	}
+	return suppressed;
+}
+/** From the `(` at `openIndex`, the substring inside the matching `)`. */
+function balancedParens(text, openIndex) {
+	let depth = 0;
+	for (let i = openIndex; i < text.length; i += 1) {
+		const char = text[i];
+		if (char === "(") depth += 1;
+		else if (char === ")") {
+			depth -= 1;
+			if (depth === 0) return text.slice(openIndex + 1, i);
+		}
+	}
+	return text.slice(openIndex + 1);
+}
+/** From the `{` at `openIndex`, the substring inside the matching `}`. */
+function balancedBraces(text, openIndex) {
+	let depth = 0;
+	for (let i = openIndex; i < text.length; i += 1) {
+		const char = text[i];
+		if (char === "{") depth += 1;
+		else if (char === "}") {
+			depth -= 1;
+			if (depth === 0) return text.slice(openIndex + 1, i);
+		}
+	}
+	return null;
+}
+/** Split an object/argument body on its depth-0 commas. */
+function splitTopLevel(body) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < body.length; i += 1) {
+		const char = body[i];
+		if (char === "{" || char === "(" || char === "[") depth += 1;
+		else if (char === "}" || char === ")" || char === "]") depth -= 1;
+		else if (char === "," && depth === 0) {
+			parts.push(body.slice(start, i));
+			start = i + 1;
+		}
+	}
+	parts.push(body.slice(start));
+	return parts;
+}
+/** The destructured export names of a `= await specification.<ctor>(` binding. */
+function runnerExportsOf(text) {
+	const names = /* @__PURE__ */ new Set();
+	const decl = new RegExp(String.raw`\{(?<names>[^}]*)\}\s*=\s*await\s+specification\.(?:${CONSTRUCTORS})\s*\(`, "g");
+	for (const match of text.matchAll(decl)) for (const raw of (match.groups?.names ?? "").split(",")) {
+		const key = raw.split(":")[0].trim();
+		if (key.length > 0 && !NON_RUNNER_BINDINGS.has(key)) names.add(key);
+	}
+	return names;
+}
+/** The leading callee identifier of an expression (`postgres()` → `postgres`). */
+function leadingCallee(value) {
+	const match = /^(?<callee>[A-Za-z_$][\w$]*)\s*\(/.exec(value.trim());
+	return match === null ? match : match.groups?.callee ?? null;
+}
+/** SQL factory count of a `services:` record, or null if non-literal/absent. */
+function sqlDatabaseCount(text) {
+	const keyword = /\bservices\s*:/.exec(text);
+	if (keyword === null) return null;
+	const braceIndex = text.indexOf("{", keyword.index + keyword[0].length);
+	if (braceIndex === -1 || text.slice(keyword.index + keyword[0].length, braceIndex).trim() !== "") return null;
+	const body = balancedBraces(text, braceIndex);
+	if (body === null) return null;
+	let count = 0;
+	for (const pair of splitTopLevel(body)) {
+		if (pair.trim().length === 0) continue;
+		const colon = pair.indexOf(":");
+		if (colon === -1) return null;
+		const callee = leadingCallee(pair.slice(colon + 1).trim());
+		if (callee === null) return null;
+		if (callee === "postgres" || callee === "sqlite" || callee === "mysql") count += 1;
+	}
+	return count;
+}
+function modelSpecFile(file) {
+	const text = readSource(file);
+	let dockerAware = false;
+	for (const match of text.matchAll(/specification\.cli\s*\(/g)) {
+		const argsOpen = text.indexOf("(", match.index);
+		if (argsOpen !== -1 && /\bdocker\s*:/.test(balancedParens(text, argsOpen))) dockerAware = true;
+	}
+	return {
+		dockerAware,
+		file,
+		runnerExports: runnerExportsOf(text),
+		sqlDatabaseCount: sqlDatabaseCount(text)
+	};
+}
+/** Resolve a relative import specifier to a `.ts` path (else undefined). */
+function resolveRelativeImport(fromFile, specifier) {
+	if (!specifier.startsWith(".")) return;
+	return resolve(dirname(fromFile), specifier).replace(/\.js$/, ".ts");
+}
+/** Every `import { a, b as c } from '…'` binding in a file. */
+function namedImports(text) {
+	const bindings = [];
+	for (const match of text.matchAll(/import\s+(?:type\s+)?\{(?<names>[^}]*)\}\s+from\s+['"](?<source>[^'"]+)['"]/g)) {
+		const source = match.groups?.source ?? "";
+		for (const raw of (match.groups?.names ?? "").split(",")) {
+			const part = raw.trim();
+			if (part.length === 0) continue;
+			const [name, local] = part.split(/\s+as\s+/).map((token) => token.trim());
+			bindings.push({
+				local: local ?? name,
+				name,
+				source
+			});
+		}
+	}
+	return bindings;
+}
+/**
+* Docker-aware runner results must be bound with `await using`. The runner
+* identifiers are inferred from the `docker:` option of imported spec files —
+* no hand-maintained runner list, unlike the oxlint rule.
+*/
+function checkDockerRunnerAwaitUsing(rootDir) {
+	const violations = [];
+	const specFiles = listFiles(rootDir, (path) => path.endsWith(".specification.ts"));
+	const dockerSpecs = /* @__PURE__ */ new Map();
+	for (const file of specFiles) {
+		const model = modelSpecFile(file);
+		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"))) {
+		const text = readSource(testFile);
+		const runners = /* @__PURE__ */ new Set();
+		for (const binding of namedImports(text)) {
+			const target = resolveRelativeImport(testFile, binding.source);
+			if ((target === void 0 ? void 0 : dockerSpecs.get(target))?.runnerExports.has(binding.name) === true) runners.add(binding.local);
+		}
+		if (runners.size === 0) continue;
+		const suppressed = suppressedLines(readText(testFile), "b5");
+		for (const match of text.matchAll(/\b(?<kind>await\s+using|const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*await\s+(?<runner>[A-Za-z_$][\w$]*)\b[^;]*?\.exec\s*\(/g)) {
+			const kind = match.groups?.kind ?? "";
+			const runner = match.groups?.runner ?? "";
+			if (kind.startsWith("await using") || !runners.has(runner)) continue;
+			const line = lineAt(text, match.index);
+			if (suppressed.has(line)) continue;
+			const rel = relative(rootDir, testFile);
+			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/10-linting.md)`,
+				severity: "error"
+			});
+		}
+	}
+	return violations;
+}
+/** Local inline runners a test declares itself (`specification.api(…)`). */
+function localRunnerBindings(text) {
+	const locals = /* @__PURE__ */ new Set();
+	const decl = new RegExp(String.raw`\{(?<names>[^}]*)\}\s*=\s*await\s+specification\.(?:${CONSTRUCTORS})\s*\(`, "g");
+	for (const match of text.matchAll(decl)) for (const raw of (match.groups?.names ?? "").split(",")) {
+		const part = raw.trim();
+		const local = (part.includes(":") ? part.split(":")[1] : part).trim();
+		if (local.length > 0 && !NON_RUNNER_BINDINGS.has(part.split(":")[0].trim())) locals.add(local);
+	}
+	return locals;
+}
+/** The identifier immediately before a `.seed(`/`.table(` member, if any. */
+function memberObjectIdentifier(text, dotIndex) {
+	const before = text.slice(0, dotIndex);
+	const match = /(?<name>[A-Za-z_$][\w$]*)\s*$/.exec(before);
+	return match === null ? match : match.groups?.name ?? null;
+}
+function checkDatabaseProperty(rootDir) {
+	const violations = [];
+	const enforced = /* @__PURE__ */ new Map();
+	for (const file of listFiles(rootDir, (path) => path.endsWith(".specification.ts"))) {
+		const model = modelSpecFile(file);
+		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"))) {
+		const text = readSource(testFile);
+		const applicable = /* @__PURE__ */ new Set();
+		for (const binding of namedImports(text)) {
+			const target = resolveRelativeImport(testFile, binding.source);
+			const model = target === void 0 ? void 0 : enforced.get(target);
+			if (model?.runnerExports.has(binding.name) === true) applicable.add(model);
+		}
+		if (applicable.size !== 1) continue;
+		const count = [...applicable][0].sqlDatabaseCount ?? 0;
+		const locals = localRunnerBindings(text);
+		const suppressed = suppressedLines(readText(testFile), "a7");
+		const rel = relative(rootDir, testFile);
+		for (const match of text.matchAll(/\.(?<verb>seed|table)\s*\(/g)) {
+			const verb = match.groups?.verb ?? "";
+			const object = memberObjectIdentifier(text, match.index);
+			if (object !== null && locals.has(object)) continue;
+			const args = balancedParens(text, text.indexOf("(", match.index));
+			const hasDatabase = /\bdatabase\s*:/.test(args);
+			const line = lineAt(text, match.index);
+			if (suppressed.has(line)) continue;
+			if (count >= 2 && !hasDatabase) violations.push({
+				file: rel,
+				line,
+				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/10-linting.md)`,
+				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/10-linting.md)`,
+				severity: "error"
+			});
+		}
+	}
+	return violations;
+}
+/** Is a top-level conventional-subdir entry referenced by any test literal? */
+function entryReferenced(entry, entryIsDir, literals) {
+	for (const literal of literals) {
+		if (entryIsDir) {
+			if (literal === entry || literal.startsWith(`${entry}/`) || literal.includes(`/${entry}`)) return true;
+		}
+		if (literal === entry || literal.includes(entry)) return true;
+	}
+	return false;
+}
+/** A child named like a conventional 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;
+	let children;
+	try {
+		children = readdirSync(path, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	return !children.some((child) => child.isDirectory() && CONVENTIONAL_SUBDIRS.has(child.name));
+}
+function checkDeadFixtures(rootDir) {
+	const violations = [];
+	for (const dir of listDirs(rootDir)) {
+		if (basename(dir) === "specs") continue;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		const convSubdirs = entries.filter((entry) => entry.isDirectory() && CONVENTIONAL_SUBDIRS.has(entry.name) && isConventionalSubdir(join(dir, entry.name))).map((entry) => entry.name);
+		if (convSubdirs.length === 0) continue;
+		const feature = basename(dir);
+		const testFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".test.ts")).map((entry) => join(dir, entry.name));
+		const rel = relative(rootDir, dir);
+		if (testFiles.length === 0) {
+			violations.push({
+				file: rel,
+				line: 1,
+				message: `${rel}: domain directory has conventional subdirs (${convSubdirs.join(", ")}) but no *.test.ts (C9 — see docs/10-linting.md)`,
+				severity: "error"
+			});
+			continue;
+		}
+		const literals = /* @__PURE__ */ new Set();
+		let downgrade = false;
+		for (const testFile of testFiles) {
+			const text = readSource(testFile);
+			for (const literal of collectLiterals(text)) literals.add(literal);
+			downgrade ||= hasNonLiteralFixtureArg(text);
+		}
+		const severity = downgrade ? "warn" : "error";
+		for (const sub of convSubdirs) {
+			const subPath = join(dir, sub);
+			for (const entry of readdirSync(subPath, { withFileTypes: true })) {
+				const entryIsDir = entry.isDirectory();
+				if (entryReferenced(entry.name, entryIsDir, literals)) 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/10-linting.md)`,
+					severity
+				});
+			}
+		}
+	}
+	violations.push(...checkPoolFixtures(rootDir));
+	return violations;
+}
+/** Unreferenced top-level entries of a `$FIXTURES` pool (`specs/fixtures`). */
+function checkPoolFixtures(rootDir) {
+	const violations = [];
+	for (const pool of findPools(rootDir)) {
+		const specsRoot = dirname(pool);
+		const literals = /* @__PURE__ */ new Set();
+		for (const file of listFiles(specsRoot, (path) => path.endsWith(".ts"))) {
+			if (file.startsWith(`${pool}/`) || file.startsWith(`${pool}\\`)) continue;
+			for (const literal of collectLiterals(readSource(file))) literals.add(literal);
+		}
+		for (const entry of readdirSync(pool, { withFileTypes: true })) if (![...literals].some((literal) => literal.includes(entry.name))) {
+			const relEntry = relative(rootDir, join(pool, entry.name));
+			violations.push({
+				file: relEntry,
+				line: 1,
+				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot)} references $FIXTURES/${entry.name} (C9 — see docs/10-linting.md)`,
+				severity: "error"
+			});
+		}
+	}
+	return violations;
+}
+//#endregion
+//#region src/lint/checker.ts
+/**
+* The conventions checker — the non-oxlint static channel.
+*
+* Oxlint only visits JS/TS sources; the D4 token grammar also constrains the
+* DATA fixtures under `expected/**` and `requests/**`. This module walks a specs
+* tree and reports:
+*
+* - **unknown / malformed tokens** in `expected/` fixtures — any text file, not
+*   just `.http`/`.json`/`.txt` (D4);
+* - the **HTTP first-line grammar** of depth-1 `requests/*.http` (a request line)
+*   and `expected/*.http` (a status line) (D4b);
+* - **tokens leaking into `requests/`** — requests are inputs, never matched, so
+*   a `{{token}}` there is almost always a mistake (D10, warning).
+*
+* It shares TOKEN_KINDS with the runtime matcher so the channels cannot drift.
+*/
+/** A well-formed token: `{{word}}` / `{{word#ref}}`. */
+const VALID_TOKEN = /^[A-Za-z][A-Za-z0-9]*(?:#[\w.-]+)?$/;
+/** Any `{{ … }}` block (no nested braces) — classified by the scanner below. */
+const BRACE_BLOCK = /\{\{(?<inner>[^{}]*)\}\}/g;
+/** The leading identifier of a brace block, for malformed-ref classification. */
+const LEADING_WORD = /^(?<kind>[A-Za-z][A-Za-z0-9]*)/;
+const KNOWN = new Set(TOKEN_KINDS);
+/** Directories whose files carry the token grammar (D4). */
+const FIXTURE_DIRS = /* @__PURE__ */ new Set(["expected", "requests"]);
+/**
+* Directories the walk never enters. `fixtures/` trees (the shared pool and
+* feature-local ones) are verbatim `.fixture()` cwd material — file STATE, not
+* assertion fixtures — so the token grammar has no meaning inside them.
+*/
+const SKIPPED_DIRS = /* @__PURE__ */ new Set([
+	".git",
+	"dist",
+	"fixtures",
+	"node_modules"
+]);
+/**
+* Scan one fixture text for tokens outside the grammar: unknown kinds
+* (`{{userid}}`) and malformed captures of a known kind (`{{iso8601#}}`,
+* `{{uuid #id}}`). Well-formed template noise (`{{.Server.Version}}`,
+* `{{ spaced }}`, `{{123}}`) is structurally out of the grammar and ignored.
+*/
+function findUnknownTokens(text) {
+	const violations = [];
+	const lines = text.split("\n");
+	for (const [index, lineText] of lines.entries()) for (const match of lineText.matchAll(BRACE_BLOCK)) {
+		const inner = match.groups?.inner ?? "";
+		if (VALID_TOKEN.test(inner)) {
+			if (!KNOWN.has(inner.split("#")[0])) violations.push({
+				line: index + 1,
+				token: match[0]
+			});
+			continue;
+		}
+		const kind = LEADING_WORD.exec(inner)?.groups?.kind;
+		if (kind !== void 0 && KNOWN.has(kind) && inner !== kind) violations.push({
+			line: index + 1,
+			token: match[0]
+		});
+	}
+	return violations;
+}
+/** Known tokens present in a text — for the `requests/` leak warning (D10). */
+function findKnownTokens(text) {
+	const found = [];
+	const lines = text.split("\n");
+	for (const [index, lineText] of lines.entries()) for (const match of lineText.matchAll(BRACE_BLOCK)) {
+		const inner = match.groups?.inner ?? "";
+		if (VALID_TOKEN.test(inner) && KNOWN.has(inner.split("#")[0])) found.push({
+			line: index + 1,
+			token: match[0]
+		});
+	}
+	return found;
+}
+/** A binary file is anything that fails to decode cleanly as UTF-8. */
+function decodeText(path) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+	return text.includes("\0") || text.includes("�") ? null : text;
+}
+/** First non-empty line of a text (the HTTP first-line grammar target). */
+function firstLine(text) {
+	for (const line of text.split("\n")) if (line.trim().length > 0) return line.trim();
+	return "";
+}
+const REQUEST_LINE = /^(?<method>GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) \/\S*/;
+const STATUS_LINE = /^HTTP\/\d(?:\.\d)? \d{3}\b/;
+/**
+* Walk `rootDir` and check every fixture file. Paths in the result are relative
+* to `rootDir`. Errors fail the checker; warnings are advisory.
+*/
+function checkConventionFiles(rootDir) {
+	const violations = [];
+	const visit = (dir, inside) => {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const path = join(dir, entry.name);
+			const rel = relative(rootDir, path);
+			if (entry.isDirectory()) {
+				if (SKIPPED_DIRS.has(entry.name)) continue;
+				const next = FIXTURE_DIRS.has(entry.name) ? entry.name : inside;
+				visit(path, next);
+				continue;
+			}
+			if (inside === null) continue;
+			const depth1 = dir.endsWith(`/${inside}`) || dir.endsWith(`\\${inside}`);
+			if (inside === "requests") {
+				if (!entry.name.endsWith(".http")) continue;
+				const text = decodeText(path);
+				if (text === null) continue;
+				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/10-linting.md)`,
+					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/10-linting.md)`,
+					severity: "warn",
+					token
+				});
+				continue;
+			}
+			const text = decodeText(path);
+			if (text === null) continue;
+			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/10-linting.md)`,
+				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(", ")})`,
+				severity: "error",
+				token
+			});
+		}
+	};
+	visit(rootDir, null);
+	return violations;
+}
+/**
+* Run every checker pass over `rootDir`: the token/HTTP grammar passes (D4 /
+* D4b / D10) plus the cross-file passes (C9 dead fixtures, B5 await-using
+* inference, A7 database property). This is the entry the bundled bin drives.
+*/
+function runAllChecks(rootDir) {
+	return [
+		...checkConventionFiles(rootDir),
+		...checkDeadFixtures(rootDir),
+		...checkDockerRunnerAwaitUsing(rootDir),
+		...checkDatabaseProperty(rootDir)
+	];
+}
+/** Render violations the way the lint chain prints them. One line per finding. */
+function formatViolations(violations) {
+	return violations.map(({ message, severity }) => `[${severity}] ${message}`).join("\n");
+}
+//#endregion
+//#region src/lint/checker-cli.ts
+/**
+* CLI entry for the conventions checker (bundled as `dist/checker.js`).
+*
+*     node dist/checker.js [rootDir]     # default: cwd
+*
+* Runs every checker pass — the token/HTTP grammar (D4 / D4b / D10) and the
+* cross-file passes (C9 dead fixtures, B5 await-using inference, A7 database
+* property). Exit 1 on any ERROR-level violation; warnings (D10, a downgraded
+* C9 feature) are printed but do not fail the run.
+*/
+const root = resolve(process.argv[2] ?? ".");
+if (!existsSync(root) || !statSync(root).isDirectory()) {
+	console.error(`conventions checker: no such directory: ${root}`);
+	process.exit(1);
+}
+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, C9 dead fixtures, B5 await-using, A7 database)${violations.length > 0 ? ` — ${violations.length} warning(s)` : ""}`);
+//#endregion
+export {};