@jterrazz/test 12.0.2 → 12.2.0

package/dist/oxlint.js

@@ -1,5 +1,6 @@
 import { basename, dirname, join, resolve } from "node:path";
 import { readFileSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 //#region src/lint/fs-cache.ts
 /**
 * Cached filesystem probes for the fs-anchored rules (a9w, c2, c6, c7, i2).
@@ -301,7 +302,7 @@ const RULE_DOCS = {
 	},
 	"b4-given-then": {
 		channel: "statique",
-		convention: "Chaque test contient `// Given -` puis `// Then -` (les deux, dans cet ordre) ; Given déclaré après Then est une erreur.",
+		convention: "Chaque test contient `// Given -` puis `// Then -` (les deux, dans cet ordre) ; Given déclaré après Then est une erreur. Dans un spec littéraire `<cas>.cli`, les deux marqueurs sont les lignes `given:` et `then:` de l’en-tête (passe checker `b4-cli-header`).",
 		family: "B",
 		id: "B4",
 		rationale: "La narration Given/Then rend l’intention du test lisible sans lire les assertions."
@@ -336,7 +337,7 @@ const RULE_DOCS = {
 	},
 	"c1-domain-structure": {
 		channel: "statique",
-		convention: "La forme de l’arbre `specs/` se déclare via l’option `depth` : `facet-domain` (défaut — `*.test.ts` à la profondeur facet/domain, `*.specification.ts` au root de la facette), `mirror` (test à toute profondeur ≥ 1, nommé d’après son dossier), `off`.",
+		convention: "La forme de l’arbre `specs/` se déclare via l’option `depth` : `facet-domain` (défaut — `*.test.ts` à la profondeur facet/domain, `*.specification.ts` au root de la facette), `facet` (test au root de la facette OU un dossier domaine plus bas, jamais plus profond), `mirror` (test à toute profondeur ≥ 1, nommé d’après son dossier), `off`.",
 		family: "C",
 		id: "C1",
 		rationale: "Une profondeur fixe rend la place de chaque fichier prévisible et détectable statiquement."
@@ -448,7 +449,7 @@ const RULE_DOCS = {
 	},
 	"f1-no-subpath-import": {
 		channel: "statique",
-		convention: "Tout s’importe depuis `@jterrazz/test` ; un import de `@jterrazz/test/<subpath>` est une erreur, sauf le subpath tool-facing `@jterrazz/test/oxlint` (exempté partout).",
+		convention: "Tout s’importe depuis `@jterrazz/test` ; un import de `@jterrazz/test/<subpath>` est une erreur, sauf les subpaths que la map `exports` du paquet publie — `@jterrazz/test/oxlint` (plugin de lint) et `@jterrazz/test/vitest` (surface de configuration du runner) — exemptés partout. La liste est LUE du manifeste, jamais recopiée dans la règle.",
 		family: "F",
 		id: "F1",
 		rationale: "Un point d’entrée unique garde l’API publique explicite et les subpaths internes invisibles."
@@ -562,7 +563,7 @@ const RULE_DOCS = {
 const CHECKER_PASSES = [
 	{
 		channel: "checker",
-		convention: "Tout `{{token}}` dans une fixture `expected/` appartient au vocabulaire figé ; un token inconnu est une erreur.",
+		convention: "Tout `{{token}}` dans une fixture `expected/` — ou dans les blocs d’un spec littéraire `<cas>.cli` — appartient au vocabulaire figé ; un token inconnu est une erreur.",
 		family: "D",
 		id: "D4",
 		name: "d4-unknown-token",
@@ -584,6 +585,22 @@ const CHECKER_PASSES = [
 		name: "d4b-http-first-line",
 		rationale: "La ligne d’ouverture distingue une requête d’une réponse — la contraindre attrape les fichiers mal placés."
 	},
+	{
+		channel: "checker",
+		convention: "Un spec littéraire `<cas>.cli` respecte sa grammaire : clés d’en-tête fermées (`test`, `given`, `then`, `fixture`, `env`, `serve`), première ligne de corps en `$ <commande>`, `exit: <entier>` juste après.",
+		family: "D",
+		id: "D4b",
+		name: "d4b-cli-shape",
+		rationale: "La grammaire est lue par le parseur du runner lui-même : le fichier que le lint accepte est exactement celui que le runner exécute."
+	},
+	{
+		channel: "checker",
+		convention: "Un spec littéraire `<cas>.cli` porte les trois lignes narratives `test:`, `given:` et `then:` ; il en manque une est une erreur.",
+		family: "B",
+		id: "B4",
+		name: "b4-cli-header",
+		rationale: "Le format littéraire est un test : la narration Given/Then y vit dans l’en-tête, pas dans des commentaires."
+	},
 	{
 		channel: "checker",
 		convention: "Un token connu dans un fichier sous `requests/` → warning : les requêtes sont des entrées, jamais matchées.",
@@ -594,7 +611,7 @@ const CHECKER_PASSES = [
 	},
 	{
 		channel: "checker",
-		convention: "Aucune fixture morte : tout fichier sous `seeds/`/`requests/`/`fixtures/` et toute entrée de premier niveau de `expected/` doit être référencée ; un dossier de feature sans `*.test.ts` est orphelin (warning si argument non littéral).",
+		convention: "Aucune fixture morte : tout fichier sous `seeds/`/`requests/`/`fixtures/` et toute entrée de premier niveau de `expected/` doit être référencée ; un dossier de feature sans `*.test.ts` ni `*.cli` est orphelin (warning si argument non littéral). Un `<cas>.cli` référence les fixtures nommées par ses lignes `fixture:`.",
 		family: "C",
 		id: "C9",
 		name: "c9-dead-fixtures",
@@ -1467,6 +1484,16 @@ const DEFAULT_DEPTH = "facet-domain";
 * - a `*.specification.ts` sits at the facet root — exactly
 *   `specs/<facet>/<file>.specification.ts`, never inside a domain.
 *
+* `depth: 'facet'`
+*
+* The same facet root, one degree looser: the folder follows the assets. A
+* `*.test.ts` sits EITHER at the facet root (`specs/<facet>/<aspect>.test.ts`)
+* or one domain folder down (`specs/<facet>/<domain>/<aspect>.test.ts`) — a
+* test earns a domain folder when it carries assets of its own, and sits
+* beside its siblings when it does not. Anything deeper is rejected, and so is
+* a test loose at the specs root. A `*.specification.ts` sits at the facet
+* root, exactly as in `facet-domain`.
+*
 * `depth: 'mirror'`
 *
 * The tree mirrors something outside itself (a command tree, a source tree), so
@@ -1491,6 +1518,24 @@ const c1DomainStructure = {
 			if (anchor === void 0) return;
 			const base = anchor.relative.at(-1) ?? "";
 			const nesting = anchor.relative.length - 1;
+			if (depth === "facet") {
+				if (base.endsWith(TEST_SUFFIX)) {
+					if (nesting < 1) context.report({
+						messageId: "testOutsideFacet",
+						node
+					});
+					else if (nesting > 2) context.report({
+						messageId: "testTooDeepForFacet",
+						node
+					});
+					return;
+				}
+				if (base.endsWith(SPECIFICATION_SUFFIX) && nesting !== 1) context.report({
+					messageId: "specNotAtFacetRoot",
+					node
+				});
+				return;
+			}
 			if (depth === "mirror") {
 				if (!base.endsWith(TEST_SUFFIX)) return;
 				if (nesting < 1) {
@@ -1535,12 +1580,15 @@ const c1DomainStructure = {
 			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (C1 — see docs/10-linting.md).",
 			testAtSpecsRoot: "A `*.test.ts` must live in a directory under specs/ — with `depth: \"mirror\"` the tree mirrors a structure, and the specs root mirrors nothing (C1 — see docs/10-linting.md).",
 			testNotMirroringDirectory: "A `*.test.ts` must be named after the directory holding it — `{{directory}}/{{directory}}.test.ts` — with `depth: \"mirror\"` (C1 — see docs/10-linting.md).",
-			testTooDeep: "A `*.test.ts` must sit at facet/domain depth: `specs/<facet>/<domain>/<aspect>.test.ts` — no deeper nesting (C1 — see docs/10-linting.md)."
+			testOutsideFacet: "A `*.test.ts` must live in a facet folder — `specs/<facet>/<aspect>.test.ts`, or one domain deeper: with `depth: \"facet\"` the specs root holds facets, not tests (C1 — see docs/10-linting.md).",
+			testTooDeep: "A `*.test.ts` must sit at facet/domain depth: `specs/<facet>/<domain>/<aspect>.test.ts` — no deeper nesting (C1 — see docs/10-linting.md).",
+			testTooDeepForFacet: "A `*.test.ts` must sit at the facet root or one domain folder down — `specs/<facet>/<aspect>.test.ts` or `specs/<facet>/<domain>/<aspect>.test.ts`: with `depth: \"facet\"` nothing nests deeper (C1 — see docs/10-linting.md)."
 		},
 		schema: [{
 			additionalProperties: false,
 			properties: { depth: {
 				enum: [
+					"facet",
 					"facet-domain",
 					"mirror",
 					"off"
@@ -2590,22 +2638,88 @@ const d9wSingleUseRef = {
 	}
 };
 //#endregion
+//#region src/lint/package-exports.ts
+/**
+* The subpaths this package actually publishes, read from its OWN
+* `package.json` `exports` map.
+*
+* Rule F1 forbids importing `@jterrazz/test/<subpath>` — but a subpath the
+* package DECLARES is, by definition, part of its public contract
+* (`/oxlint` for the lint plugin, `/vitest` for the runner-config surface).
+* Deriving the exemption from the manifest rather than listing it in the rule
+* is what keeps the two from drifting: a subpath is exempt the moment it is
+* published, and stops being exempt the moment it is withdrawn — there is
+* nothing to remember to update.
+*
+* The manifest is found by walking up from THIS module, so the answer does not
+* depend on where the linted file sits: `<pkg>/dist/oxlint.js` in an install,
+* `<repo>/src/lint/` when the framework lints itself. `import.meta.url` is
+* safe in both bundle formats — the CJS build shims it to `__filename`.
+*/
+const PACKAGE$2 = "@jterrazz/test";
+/** Manifests are read once per lint process. */
+let cached = null;
+/**
+* Walk up from `startDir` for the `package.json` that declares {@link PACKAGE}.
+* The FIRST manifest found decides: if it names another package, the walk has
+* already left this package's tree and there is nothing to find above it.
+*/
+function findOwnManifest(startDir) {
+	let dir = startDir;
+	for (;;) {
+		const text = readFileCached(join(dir, "package.json"));
+		if (text !== null) try {
+			const manifest = JSON.parse(text);
+			return manifest.name === PACKAGE$2 ? manifest : null;
+		} catch {
+			return null;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/**
+* Every subpath specifier the package publishes — `@jterrazz/test/oxlint`,
+* `@jterrazz/test/vitest`, … The root export (`.`) is not a subpath and is
+* absent from the list.
+*
+* An unreadable manifest yields an EMPTY list: with no contract to read, no
+* subpath can be vouched for, and F1's plain rule applies.
+*
+* @internal Exported for unit tests.
+*/
+function declaredSubpaths(startDir) {
+	if (startDir === void 0 && cached !== null) return cached;
+	const exports = findOwnManifest(startDir ?? dirname(fileURLToPath(import.meta.url)))?.exports;
+	const subpaths = exports !== null && typeof exports === "object" ? Object.keys(exports).filter((key) => key.startsWith("./") && key !== ".").map((key) => `${PACKAGE$2}/${key.slice(2)}`).sort() : [];
+	if (startDir === void 0) cached = subpaths;
+	return subpaths;
+}
+//#endregion
 //#region src/lint/rules/f1-no-subpath-import.ts
 const PACKAGE$1 = "@jterrazz/test";
-const TOOL_SUBPATH$2 = "@jterrazz/test/oxlint";
 /**
-* CONVENTIONS F1 — everything is imported from `@jterrazz/test`; subpaths do
-* not exist. Sanctioned exception: `@jterrazz/test/oxlint`, the tool-facing,
-* zero-runtime plugin entry — exempt from any file (an oxlint config, a shared
-* preset, whatever wires the lint layer).
+* CONVENTIONS F1 — everything a SPEC needs is imported from `@jterrazz/test`;
+* internal subpaths do not exist.
+*
+* The exception is not a list kept here: it is the package's own `exports` map
+* (`/oxlint`, the tool-facing plugin entry; `/vitest`, the runner-config
+* surface `vitest.config.ts` imports). A published subpath IS the public
+* contract, so reading the manifest is what keeps the rule from outlawing an
+* import the package itself prescribes. Each is exempt from any file — an
+* oxlint config, a shared preset, a vitest config.
 */
 const f1NoSubpathImport = {
 	create(context) {
+		const allowed = new Set(declaredSubpaths());
 		return { ...importSourceVisitor(({ node, source }) => {
-			if (!source.startsWith(`${PACKAGE$1}/`)) return;
-			if (source === TOOL_SUBPATH$2) return;
+			if (!source.startsWith(`${PACKAGE$1}/`) || allowed.has(source)) return;
 			context.report({
-				data: { source },
+				data: {
+					published: allowed.size === 0 ? "none" : [...allowed].sort().join(", "),
+					source
+				},
 				messageId: "subpath",
 				node
 			});
@@ -2613,7 +2727,7 @@ const f1NoSubpathImport = {
 	},
 	meta: {
 		docs: RULE_DOCS["f1-no-subpath-import"],
-		messages: { subpath: "Import from \"@jterrazz/test\", not \"{{source}}\" — subpaths do not exist (F1 — see docs/10-linting.md; only the tool-facing @jterrazz/test/oxlint is exempt)." },
+		messages: { subpath: "Import from \"@jterrazz/test\", not \"{{source}}\" — internal subpaths do not exist (F1 — see docs/10-linting.md). Published subpaths, exempt everywhere: {{published}}." },
 		type: "problem"
 	}
 };

package/dist/queue.js

@@ -1,297 +1,5 @@
-import { n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
-//#region src/core/matching/structural.ts
-/**
-* Structural comparison engine shared by every fixture matcher.
-*
-* Handles three kinds of "expected" values:
-* - plain JSON values → strict deep equality
-* - {@link Matcher} instances (code-side `match.*`)
-* - strings containing `{{placeholder}}` forms (file-side fixtures)
-*
-* One unified `{{token}}` grammar (CONVENTIONS D4) — the same vocabulary
-* works in `expected/*.http` (body and headers), `expected/*.json`, and
-* text snapshots (`expected/*.txt`).
-*
-* Ref captures (`match.ref(name)` / `{{type#name}}`) are recorded in the
-* {@link CaptureScope} supplied by the caller.
-*/
-const UUID_SOURCE = "[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}";
-const ULID_SOURCE = "[0-9A-HJKMNP-TV-Z]{26}";
-const ISO8601_SOURCE = String.raw`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})`;
-const DATE_SOURCE = String.raw`\d{4}-\d{2}-\d{2}`;
-const TIME_SOURCE = String.raw`\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?`;
-const DURATION_SOURCE = String.raw`\d+(?:\.\d+)?(?:ms|s|m|h)`;
-const NUMBER_SOURCE = String.raw`-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?`;
-const INT_SOURCE = String.raw`-?\d+`;
-const FLOAT_SOURCE = String.raw`-?\d+\.\d+`;
-const SEMVER_SOURCE = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
-const SHA_SOURCE = "[0-9a-f]{7,64}";
-const HEX_SOURCE = "[0-9a-fA-F]+";
-const BASE64_SOURCE = "[A-Za-z0-9+/]+={0,2}";
-const PORT_SOURCE = String.raw`(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|\d{1,4})`;
-const IP_OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
-const IP_SOURCE = String.raw`(?:${IP_OCTET}\.){3}${IP_OCTET}`;
-const URL_SOURCE = String.raw`https?:\/\/[^\s"'<>]+`;
-const EMBEDDED_SOURCES = {
-	base64: BASE64_SOURCE,
-	date: DATE_SOURCE,
-	duration: DURATION_SOURCE,
-	email: String.raw`[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`,
-	float: FLOAT_SOURCE,
-	hex: HEX_SOURCE,
-	int: INT_SOURCE,
-	ip: IP_SOURCE,
-	iso8601: ISO8601_SOURCE,
-	number: NUMBER_SOURCE,
-	path: String.raw`\.{0,2}\/[^\s"'<>]*`,
-	port: PORT_SOURCE,
-	semver: SEMVER_SOURCE,
-	sha: SHA_SOURCE,
-	time: TIME_SOURCE,
-	ulid: ULID_SOURCE,
-	url: URL_SOURCE,
-	uuid: UUID_SOURCE
-};
-const wholeRe = (source) => new RegExp(`^(?:${source})$`);
-const WHOLE_RES = Object.fromEntries(Object.entries(EMBEDDED_SOURCES).map(([kind, source]) => [kind, wholeRe(source)]));
-const PLACEHOLDER_RE = new RegExp(String.raw`\{\{(?<kind>${[...TOKEN_KINDS].sort((a, b) => b.length - a.length).join("|")})(?:#(?<ref>[\w.-]+))?\}\}`, "g");
-/** Whether a fixture string contains at least one `{{placeholder}}`. */
-function hasPlaceholders(value) {
-	PLACEHOLDER_RE.lastIndex = 0;
-	return PLACEHOLDER_RE.test(value);
-}
-/** Key-order-independent stringification for captured-object comparison. */
-function stableStringify(value) {
-	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
-	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
-	return JSON.stringify(value) ?? "undefined";
-}
-function capturedEquals(a, b) {
-	if (Object.is(a, b)) return true;
-	if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return String(a) === String(b);
-	if (a !== null && b !== null && typeof a === "object" && typeof b === "object") return stableStringify(a) === stableStringify(b);
-	return false;
-}
-function recordRef(name, actual, scope) {
-	if (scope.has(name)) return capturedEquals(scope.get(name), actual);
-	scope.set(name, actual);
-	return true;
-}
-function isPortValue(value) {
-	return Number.isInteger(value) && value >= 0 && value <= 65535;
-}
-function kindMatches(kind, actual, scope) {
-	switch (kind) {
-		case "any": return true;
-		case "float":
-			if (typeof actual === "number") return Number.isFinite(actual);
-			return typeof actual === "string" && WHOLE_RES.float.test(actual);
-		case "int":
-			if (typeof actual === "number") return Number.isInteger(actual);
-			return typeof actual === "string" && WHOLE_RES.int.test(actual);
-		case "number":
-			if (typeof actual === "number") return Number.isFinite(actual);
-			return typeof actual === "string" && WHOLE_RES.number.test(actual);
-		case "port":
-			if (typeof actual === "number") return isPortValue(actual);
-			return typeof actual === "string" && WHOLE_RES.port.test(actual) && isPortValue(Number(actual));
-		case "string": return typeof actual === "string";
-		case "workdir": return typeof actual === "string" && scope.workdir !== void 0 ? actual === scope.workdir : false;
-		default: {
-			const re = WHOLE_RES[kind];
-			return re !== void 0 && typeof actual === "string" && re.test(actual);
-		}
-	}
-}
-function matcherMatches(matcher, actual, scope) {
-	if (matcher.kind === "includes") return typeof actual === "string" && actual.includes(matcher.includes);
-	if (matcher.kind === "regex") return typeof actual === "string" && matcher.regex.test(actual);
-	if (matcher.kind === "ref") {
-		if (matcher.notRef && scope.has(matcher.notRef) && capturedEquals(scope.get(matcher.notRef), actual)) return false;
-		return recordRef(matcher.refName, actual, scope);
-	}
-	return kindMatches(matcher.kind, actual, scope);
-}
-function placeholderSource(kind, scope) {
-	if (kind === "workdir") return scope.workdir === void 0 ? "(?!)" : escapeRegExp(scope.workdir);
-	const source = EMBEDDED_SOURCES[kind];
-	if (source) return source;
-	return kind === "any" ? String.raw`[\s\S]*?` : String.raw`[^\n]*?`;
-}
-function escapeRegExp(text) {
-	return text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
-}
-function parsePlaceholderString(expected, scope) {
-	PLACEHOLDER_RE.lastIndex = 0;
-	const refs = [];
-	let source = "";
-	let lastIndex = 0;
-	let single = null;
-	let count = 0;
-	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
-		const kind = found.groups.kind;
-		const ref = found.groups.ref;
-		source += escapeRegExp(expected.slice(lastIndex, found.index));
-		source += `(${placeholderSource(kind, scope)})`;
-		refs.push({
-			index: count,
-			kind,
-			ref
-		});
-		count++;
-		lastIndex = found.index + found[0].length;
-		if (found.index === 0 && found[0].length === expected.length) single = {
-			kind,
-			ref
-		};
-	}
-	source += escapeRegExp(expected.slice(lastIndex));
-	return {
-		pattern: new RegExp(`^${source}$`),
-		refs,
-		single,
-		source
-	};
-}
-/**
-* Unanchored regex source matching a fixture string — plain text escaped
-* verbatim, each `{{token}}` expanded to its embedded grammar. Used to route
-* declared `.http` intercept paths (`/articles/{{uuid}}`) as URL patterns.
-*/
-function placeholderPatternSource(expected) {
-	return parsePlaceholderString(expected, new CaptureScope()).source;
-}
-function placeholderStringMatches(expected, actual, scope) {
-	const parsed = parsePlaceholderString(expected, scope);
-	if (parsed.single) {
-		if (!kindMatches(parsed.single.kind, actual, scope)) return false;
-		if (parsed.single.ref) return recordRef(parsed.single.ref, actual, scope);
-		return true;
-	}
-	if (typeof actual !== "string" && typeof actual !== "number") return false;
-	const text = String(actual);
-	const found = parsed.pattern.exec(text);
-	if (!found) return false;
-	for (const entry of parsed.refs) {
-		if (!entry.ref) continue;
-		if (!recordRef(entry.ref, found[entry.index + 1], scope)) return false;
-	}
-	return true;
-}
-function isPlainObject(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-/**
-* Deep structural equality with matcher / placeholder support. Ref captures
-* are recorded in `scope` in traversal order (arrays left-to-right, object
-* keys in expected-key order).
-*/
-function structuralEquals(expected, actual, scope) {
-	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
-	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
-	if (Array.isArray(expected)) {
-		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
-		return expected.every((item, i) => structuralEquals(item, actual[i], scope));
-	}
-	if (isPlainObject(expected)) {
-		if (!isPlainObject(actual)) return false;
-		const expectedKeys = Object.keys(expected);
-		const actualKeys = Object.keys(actual);
-		if (expectedKeys.length !== actualKeys.length) return false;
-		return expectedKeys.every((key) => key in actual && structuralEquals(expected[key], actual[key], scope));
-	}
-	return Object.is(expected, actual);
-}
-/**
-* Deep structural SUBSET match (toMatchObject-style) with matcher /
-* placeholder support. Plain objects match when every expected key is present
-* and recursively subset-matches — the actual value may carry extra keys.
-* Arrays require equal length with each element subset-matched. Leaves fall
-* back to {@link structuralEquals} semantics (matchers, placeholders, strict
-* equality). Used by request-body filters on intercept triggers.
-*/
-function structuralSubset(expected, actual, scope) {
-	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
-	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
-	if (Array.isArray(expected)) {
-		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
-		return expected.every((item, i) => structuralSubset(item, actual[i], scope));
-	}
-	if (isPlainObject(expected)) {
-		if (!isPlainObject(actual)) return false;
-		return Object.keys(expected).every((key) => key in actual && structuralSubset(expected[key], actual[key], scope));
-	}
-	return Object.is(expected, actual);
-}
-/**
-* Multi-line text comparison with `{{token}}` support — used by text
-* snapshots (`expected/*.txt`). Without placeholders this is strict equality.
-*/
-function textEquals(expected, actual, scope) {
-	if (!hasPlaceholders(expected)) return expected === actual;
-	return placeholderStringMatches(expected, actual, scope);
-}
-/**
-* Render an expected value for failure diffs and serialization: Matcher
-* instances become their placeholder text, everything else is untouched.
-*/
-function renderExpected(value) {
-	if (value instanceof Matcher) return value.toString();
-	if (Array.isArray(value)) return value.map((item) => renderExpected(item));
-	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, renderExpected(item)]));
-	return value;
-}
-/**
-* Substitute the framework-known cwd (`workdir`) for its `{{workdir}}` token in
-* every string leaf of a structured value. The structural mirror of the text
-* path's `actual.replaceAll(workdir, '{{workdir}}')` — so a golden written under
-* `TEST_UPDATE=1` stores the token, not a run-specific temp path (CONVENTIONS
-* D5). A no-op when `workdir` is undefined (no cwd, e.g. api/jobs mode).
-*/
-function substituteWorkdirDeep(value, workdir) {
-	if (typeof value === "string") return value.replaceAll(workdir, "{{workdir}}");
-	if (Array.isArray(value)) return value.map((item) => substituteWorkdirDeep(item, workdir));
-	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteWorkdirDeep(item, workdir)]));
-	return value;
-}
-/**
-* Update-mode merge: rewrite a fixture from the actual output while
-* preserving every segment of the previous fixture that was covered by a
-* placeholder (and still matches the actual value).
-*
-* Token preservation is symmetric with the text path (CONVENTIONS D5): a
-* previous `{{placeholder}}` (including `{{workdir}}`) that still matches the
-* RAW actual value is kept; every other leaf is taken from the actual output
-* with the framework-known cwd substituted back to `{{workdir}}`.
-*/
-function mergePreservingPlaceholders(previous, actual, workdir) {
-	const scope = new CaptureScope(workdir);
-	const subst = (value) => workdir === void 0 ? value : substituteWorkdirDeep(value, workdir);
-	function merge(prev, act) {
-		if (typeof prev === "string" && hasPlaceholders(prev)) return placeholderStringMatches(prev, act, scope) ? prev : subst(act);
-		if (Array.isArray(prev) && Array.isArray(act)) return act.map((item, i) => i < prev.length ? merge(prev[i], item) : subst(item));
-		if (isPlainObject(prev) && isPlainObject(act)) return Object.fromEntries(Object.entries(act).map(([key, item]) => [key, key in prev ? merge(prev[key], item) : subst(item)]));
-		return subst(act);
-	}
-	return merge(previous, actual);
-}
-/**
-* Update-mode merge for text snapshots: line-by-line, a previous line whose
-* placeholders still match the actual line is preserved; every other line is
-* taken from the actual output. Values the framework knows to be dynamic
-* (`{{workdir}}`) are substituted automatically (CONVENTIONS D5).
-*/
-function mergeTextPreservingPlaceholders(previous, actual, scope) {
-	const substituted = scope.workdir === void 0 ? actual : actual.replaceAll(scope.workdir, "{{workdir}}");
-	if (previous === null) return substituted;
-	const prevLines = previous.split("\n");
-	return substituted.split("\n").map((line, i) => {
-		const prev = prevLines[i];
-		if (prev === void 0 || !hasPlaceholders(prev)) return line;
-		return textEquals(prev, line, new CaptureScope(scope.workdir)) || textEquals(prev, actual.split("\n")[i] ?? line, new CaptureScope(scope.workdir)) ? prev : line;
-	}).join("\n");
-}
-//#endregion
+import { t as CaptureScope } from "./match.js";
+import { F as textEquals, O as hasPlaceholders, j as placeholderPatternSource } from "./literate.js";
 //#region src/core/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape
@@ -552,4 +260,4 @@ var ContractQueue = class {
 	}
 };
 //#endregion
-export { isContract as a, mergeTextPreservingPlaceholders as c, structuralSubset as d, textEquals as f, defineContracts as i, renderExpected as l, contractsOf as n, isContracts as o, defineContract as r, mergePreservingPlaceholders as s, ContractQueue as t, structuralEquals as u };
+export { isContract as a, defineContracts as i, contractsOf as n, isContracts as o, defineContract as r, ContractQueue as t };

package/dist/vitest.d.ts

@@ -0,0 +1,41 @@
+//#region src/vitest/literate-plugin.d.ts
+interface LiterateOptions {
+  /**
+   * Globs added to the project's test include. Default: every `.cli` file.
+   * Narrow it when a tree holds `.cli` files that are INPUTS to other specs
+   * (a deliberately-broken header) rather than scenarios to run.
+   */
+  include?: string[];
+  /**
+   * Path to the `*.specification.ts` whose exported `cli` runs the files —
+   * relative to the vite root, or absolute.
+   *
+   * It is stated, never guessed: a repository may declare several cli
+   * runners (different binaries, different service records), and there is no
+   * convention that could pick the right one without silently binding a
+   * scenario to the wrong command.
+   */
+  specification: string;
+}
+/**
+ * The shape vite consumes. Declared structurally rather than imported from
+ * `vite`, so the package's runner coupling stays the one dependency it already
+ * has (CONVENTIONS I1) — the object is assignable to vite's `Plugin`.
+ */
+interface LiteratePlugin {
+  config: () => {
+    test: {
+      include: string[];
+    };
+  };
+  /** Vite hands the resolved root here — what a relative `specification` is resolved against. */
+  configResolved: (resolved: {
+    root: string;
+  }) => void;
+  enforce: 'pre';
+  load: (id: string) => null | string;
+  name: string;
+}
+declare function literate(options: LiterateOptions): LiteratePlugin;
+//#endregion
+export { type LiterateOptions, type LiteratePlugin, literate };

package/dist/vitest.js

@@ -0,0 +1,68 @@
+import { t as literateTitle } from "./literate.js";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+//#region src/vitest/literate-plugin.ts
+/**
+* The `literate()` vite plugin — door one of the literate format.
+*
+* It makes a `<case>.cli` file a TEST FILE: the glob joins the project's test
+* include, and each `.cli` is transformed into a one-test module that runs the
+* file through the registered `cli` runner. The runner shows the `.cli` path as
+* the file and the header's `test:` line as the title, so a failing scenario is
+* opened where it is written — not in a `.test.ts` that merely points at it.
+*
+* ```typescript
+* // vitest.config.ts
+* import { defineConfig } from 'vitest/config';
+* import { literate } from '@jterrazz/test/vitest';
+*
+* export default defineConfig({
+*     plugins: [literate({ specification: './specs/cli/cli.specification.ts' })],
+* });
+* ```
+*/
+/** The `.cli` extension, matched on the id vite hands the plugin. */
+const CLI_FILE = /\.cli(?:\?.*)?$/;
+/**
+* The module a `.cli` file becomes: one `test()` whose title is the header's
+* `test:` line and whose body runs the whole file — header, servers, every
+* block asserted.
+*
+* @internal Exported for unit tests.
+*/
+function literateModule(content, filePath, specificationPath) {
+	const title = literateTitle(content, filePath);
+	return [
+		"import { test } from 'vitest';",
+		`import { cli } from ${JSON.stringify(specificationPath)};`,
+		"",
+		`test(${JSON.stringify(title)}, async () => {`,
+		`    await cli.run(${JSON.stringify(filePath)});`,
+		"});",
+		""
+	].join("\n");
+}
+/** Strip vite's query suffix (`?v=…`) from a module id. */
+function cleanId(id) {
+	return id.split("?")[0];
+}
+function literate(options) {
+	const include = options.include ?? ["**/*.cli"];
+	let root = process.cwd();
+	return {
+		config: () => ({ test: { include } }),
+		configResolved: (resolved) => {
+			root = resolved.root;
+		},
+		enforce: "pre",
+		load: (id) => {
+			if (!CLI_FILE.test(id)) return null;
+			const filePath = cleanId(id);
+			const specificationPath = isAbsolute(options.specification) ? options.specification : resolve(root, options.specification);
+			return literateModule(readFileSync(filePath, "utf8"), filePath, specificationPath);
+		},
+		name: "jterrazz-test:literate"
+	};
+}
+//#endregion
+export { literate };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "12.0.2",
+    "version": "12.2.0",
     "description": "Declarative testing framework for HTTP APIs, CLIs, and background jobs — one entry point, real infrastructure, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",
@@ -35,6 +35,10 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./vitest": {
+            "types": "./dist/vitest.d.ts",
+            "import": "./dist/vitest.js"
+        },
         "./oxlint": {
             "types": "./dist/oxlint.d.ts",
             "import": "./dist/oxlint.js",