@jterrazz/test 13.0.1 → 14.0.0

package/dist/oxlint.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 * Cached filesystem probes for the fs-anchored rules (a9w, c2, c6, c7, i2).
 *
 * Rules only ever look at directories NEXT TO files oxlint is already
-* visiting (a feature's `requests/`, `seeds/`, `expected/`, a sibling module
+* visiting (a feature's `_requests/`, `_seeds/`, `_expected/`, a sibling module
 * file), so the probe set is small — but several rules probe the same feature
 * directory, and oxlint lints many files per process. A module-level cache
 * keeps each `readdir`/`stat` to one syscall per lint run.
@@ -337,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), `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`.",
+		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`. Dans tous les modes, `off` compris : un dossier à underscore initial est du SOL, jamais un domaine — aucune spec ne vit dedans.",
 		family: "C",
 		id: "C1",
 		rationale: "Une profondeur fixe rend la place de chaque fichier prévisible et détectable statiquement."
@@ -356,9 +356,16 @@ const RULE_DOCS = {
 		id: "C11",
 		rationale: "Une donnée n’existe que servie par un contrat — un fichier sans propriétaire est du poids mort qu’aucun test ne charge."
 	},
+	"c13-underscored-ground": {
+		channel: "statique",
+		convention: "Sous `specs/`, le sol d’une spec porte un underscore initial : `_fixtures/`, `_expected/`, `_requests/`, `_seeds/`. Un dossier `fixtures/`, `expected/`, `requests/` ou `seeds/` est un nom d’avant la 14 — erreur nommant le renommage.",
+		family: "C",
+		id: "C13",
+		rationale: "Aucun résolveur ne lit plus le nom sans underscore : gardé tel quel, l’arbre devient invisible plutôt que faux, et l’échec arrive une étape plus loin que sa cause."
+	},
 	"c2-http-only-requests": {
 		channel: "statique",
-		convention: "`requests/` ne contient que des fichiers `.http` ; toute autre extension est une erreur.",
+		convention: "`_requests/` ne contient que des fichiers `.http` ; toute autre extension est une erreur.",
 		family: "C",
 		id: "C2",
 		rationale: "Une entrée de requête est un `.http` complet — homogénéiser le dossier interdit les formats ad hoc."
@@ -375,11 +382,11 @@ const RULE_DOCS = {
 		convention: "L’argument de `toMatch` porte son extension (`'help.txt'`), sauf pour les snapshots d’arborescence (dossiers) ; un sujet fichier sans extension est une erreur.",
 		family: "C",
 		id: "C6",
-		rationale: "L’extension fait partie du nom du fichier attendu — l’omettre casse la résolution `expected/`."
+		rationale: "L’extension fait partie du nom du fichier attendu — l’omettre casse la résolution `_expected/`."
 	},
 	"c7-seeds-sql-only": {
 		channel: "statique",
-		convention: "`seeds/` ne contient que des `*.sql` ; tout autre fichier est une erreur.",
+		convention: "`_seeds/` ne contient que des `*.sql` ; tout autre fichier est une erreur.",
 		family: "C",
 		id: "C7",
 		rationale: "`.seed()` porte l’état des bases uniquement — pas de seed-handler ni de dispatch par préfixe."
@@ -421,7 +428,7 @@ const RULE_DOCS = {
 	},
 	"d9w-single-use-ref": {
 		channel: "statique",
-		convention: "Une ref de capture (`match.ref`, `{{kind#ref}}`) qui n’apparaît qu’une seule fois dans tout le fichier (code + fixtures `expected/` référencées) porte un nom inutilement → warning.",
+		convention: "Une ref de capture (`match.ref`, `{{kind#ref}}`) qui n’apparaît qu’une seule fois dans tout le fichier (code + fixtures `_expected/` référencées) porte un nom inutilement → warning.",
 		family: "D",
 		id: "D9",
 		rationale: "Une ref ne se justifie que si elle asserte l’égalité sur au moins deux occurrences."
@@ -563,7 +570,7 @@ const RULE_DOCS = {
 const CHECKER_PASSES = [
 	{
 		channel: "checker",
-		convention: "Tout `{{token}}` dans une fixture `expected/` — ou dans un flux attendu d’un document `<cas>.spec.yaml` — appartient au vocabulaire figé ; un token inconnu est une erreur.",
+		convention: "Tout `{{token}}` dans une fixture `_expected/` — ou dans un flux attendu d’un document `<cas>.spec.yaml` — appartient au vocabulaire figé ; un token inconnu est une erreur.",
 		family: "D",
 		id: "D4",
 		name: "d4-unknown-token",
@@ -571,7 +578,7 @@ const CHECKER_PASSES = [
 	},
 	{
 		channel: "checker",
-		convention: "Une ref malformée d’un kind connu (`{{iso8601#}}`, `{{uuid #id}}`) dans un fichier texte sous `expected/` est une erreur.",
+		convention: "Une ref malformée d’un kind connu (`{{iso8601#}}`, `{{uuid #id}}`) dans un fichier texte sous `_expected/` est une erreur.",
 		family: "D",
 		id: "D4",
 		name: "d4-malformed-ref",
@@ -579,7 +586,7 @@ const CHECKER_PASSES = [
 	},
 	{
 		channel: "checker",
-		convention: "La première ligne d’un `.http` de profondeur 1 suit sa grammaire : requête (`MÉTHODE /path`) sous `requests/`, statut (`HTTP/1.1 <status>`) sous `expected/`.",
+		convention: "La première ligne d’un `.http` de profondeur 1 suit sa grammaire : requête (`MÉTHODE /path`) sous `_requests/`, statut (`HTTP/1.1 <status>`) sous `_expected/`.",
 		family: "D",
 		id: "D4b",
 		name: "d4b-http-first-line",
@@ -675,7 +682,7 @@ const CHECKER_PASSES = [
 	},
 	{
 		channel: "checker",
-		convention: "Un token connu dans un fichier sous `requests/` → warning : les requêtes sont des entrées, jamais matchées.",
+		convention: "Un token connu dans un fichier sous `_requests/` → warning : les requêtes sont des entrées, jamais matchées.",
 		family: "D",
 		id: "D10",
 		name: "d10w-tokens-in-requests",
@@ -683,12 +690,28 @@ 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` ni `*.spec.yaml` est orphelin (warning si argument non littéral). Un `<cas>.spec.yaml` référence les fixtures nommées par ses entrées `fixture:`.",
+		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 `*.spec.yaml` est orphelin (warning si argument non littéral). Un `<cas>.spec.yaml` référence les fixtures nommées par ses entrées `fixture:`.",
 		family: "C",
 		id: "C9",
 		name: "c9-dead-fixtures",
 		rationale: "Le miroir de C8 — une fixture que rien ne référence est du poids mort qui trompe le lecteur."
 	},
+	{
+		channel: "checker",
+		convention: "Une fixture du pool est PARTAGÉE, ou elle est locale : un dossier de `<specs>/_fixtures/` référencé (`$FIXTURES/<nom>`) depuis un seul dossier de spec — deux documents d’une même feuille comptent pour un — doit vivre à côté de cette feuille, en `<feuille>/_fixtures/<nom>/`, référencé par la forme relative. Zéro référence reste l’erreur de fixture morte (C9). Corrigé par `--fix` : le dossier est déplacé et les littéraux réécrits.",
+		family: "C",
+		id: "C14",
+		name: "c14-pool-fixture-shared",
+		rationale: "Une fixture d’un seul scénario garée dans le pool se lit comme du sol partagé : chacun suppose qu’un autre en dépend et personne n’ose y toucher."
+	},
+	{
+		channel: "checker",
+		convention: "Une fixture locale ne se lit que depuis son propre dossier : un chemin `fixture:`/`.fixture()` contenant `..`, ou dont la cible sort du `_fixtures/` de la spec qui le nomme, est une erreur — le sol partagé par plusieurs feuilles va dans le pool `$FIXTURES`.",
+		family: "C",
+		id: "C15",
+		name: "c15-local-fixture-reach",
+		rationale: "Une feuille qui pioche dans les fixtures d’une voisine, c’est le pool par une autre porte, sans la visibilité du pool : la voisine casse une spec à deux dossiers de là sans le savoir."
+	},
 	{
 		channel: "checker",
 		convention: "Canal principal de B5 : les runners docker-aware sont inférés de l’option `docker:` du fichier de specification importé, puis chaque résultat `.exec()` lié sans `await using` est signalé.",
@@ -1232,16 +1255,58 @@ const a9wRedundantRoot = {
 	}
 };
 //#endregion
+//#region src/core/specification/shared/ground.ts
+/**
+* The GROUND a row of specs stands on — the naming law of a spec tree.
+*
+* In a row of specs, a MEMBER is a spec: `<aspect>.test.ts`, `<case>.spec.yaml`,
+* `<name>.specification.ts`, and the facet/domain folders that hold them.
+* Everything else in that row is what the members STAND ON — inert material the
+* framework resolves BY PATH, never imported, never executed — and it carries a
+* LEADING UNDERSCORE. A spec's own folder never does.
+*
+* Four names, and only four: `_fixtures/` (file state), `_expected/` (goldens),
+* `_requests/` (inputs), `_seeds/` (database state). `contracts/` is NOT ground —
+* a contract is TypeScript a spec imports, behaviour composed with the spec's own,
+* so it stays a member. `docker/` is not ground either: it sits at the PROJECT
+* root beside `package.json`, outside any row of specs.
+*
+* This module is the single home of those names. Every resolver, matcher, lint
+* rule and checker pass reads them from here, so the runtime and the static
+* channels cannot disagree about where a spec's ground lives.
+*/
+/** Goldens: every expected fixture, flat, extension included. */
+const GROUND_EXPECTED = "_expected";
+/** File state copied into a working directory by `.fixture()`. */
+const GROUND_FIXTURES = "_fixtures";
+/** Inputs: complete `.http` request documents. */
+const GROUND_REQUESTS = "_requests";
+/** Database state: `.sql` fragments loaded by `.seed()`. */
+const GROUND_SEEDS = "_seeds";
+/**
+* The pre-14 name of each ground directory → the name it carries now. Kept for
+* ONE purpose: naming the rename in a diagnostic (`c13-underscored-ground`).
+* Nothing resolves through it — an un-underscored directory is invisible to
+* every resolver, which is exactly why it must be reported rather than tolerated.
+*/
+const RENAMED_GROUND_DIRS = {
+	expected: GROUND_EXPECTED,
+	fixtures: GROUND_FIXTURES,
+	requests: GROUND_REQUESTS,
+	seeds: GROUND_SEEDS
+};
+//#endregion
 //#region src/core/specification/shared/fixtures.ts
 /**
 * Fixture path resolution + copy semantics for the `cli` facet's `.fixture()`.
 *
 * A fixture path is one of two shapes:
 *
-*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/fixtures/<rest>`,
+*  - `$FIXTURES/<rest>` — the shared pool at `<specs-root>/_fixtures/<rest>`,
 *    where `<specs-root>` is the nearest ancestor directory named `specs`.
-*  - `<path>` (no marker) — feature-local, at `<test-dir>/fixtures/<path>`.
+*  - `<path>` (no marker) — feature-local, at `<test-dir>/_fixtures/<path>`.
 *
+* The leading underscore is the ground rule of a spec tree ({@link GROUND_FIXTURES}).
 * Any other `$`-prefixed marker is a usage error (listed against the known
 * markers). Copy semantics mirror rsync's trailing-slash rule (see
 * {@link copyPlan}).
@@ -1576,7 +1641,12 @@ const DEFAULT_DEPTH = "facet-domain";
 * specs root. Specification files are unconstrained: a mirror has no facet
 * level to anchor them to.
 *
-* `depth: 'off'` — no placement check; the tree's shape is guarded elsewhere.
+* `depth: 'off'` — no DEPTH check; the tree's shape is guarded elsewhere.
+*
+* The ground clause holds in every mode, `off` included: a directory whose name
+* carries a LEADING UNDERSCORE is ground — what the specs of a row stand on —
+* and never a domain, so no spec may live inside one. That is not a question of
+* depth, which is why no project's declared shape switches it off.
 *
 * Module tests under `src/` follow the neighbour rule (I2) and are out of scope
 * in every mode.
@@ -1584,12 +1654,23 @@ const DEFAULT_DEPTH = "facet-domain";
 const c1DomainStructure = {
 	create(context) {
 		const depth = context.options[0]?.depth ?? DEFAULT_DEPTH;
-		if (depth === "off") return {};
 		return { Program(node) {
 			const anchor = specsAnchor(context.filename);
 			if (anchor === void 0) return;
 			const base = anchor.relative.at(-1) ?? "";
 			const nesting = anchor.relative.length - 1;
+			if (base.endsWith(TEST_SUFFIX) || base.endsWith(SPECIFICATION_SUFFIX)) {
+				const ground = anchor.relative.slice(0, -1).find((segment) => segment.startsWith("_"));
+				if (ground !== void 0) {
+					context.report({
+						data: { ground },
+						messageId: "specInGround",
+						node
+					});
+					return;
+				}
+			}
+			if (depth === "off") return;
 			if (depth === "facet") {
 				if (base.endsWith(TEST_SUFFIX)) {
 					if (nesting < 1) context.report({
@@ -1648,6 +1729,7 @@ const c1DomainStructure = {
 		defaultOptions: [{ depth: DEFAULT_DEPTH }],
 		docs: RULE_DOCS["c1-domain-structure"],
 		messages: {
+			specInGround: "A spec must not live under \"{{ground}}/\" — a leading underscore marks GROUND (what the specs of a row stand on: _fixtures/, _expected/, _requests/, _seeds/), never a domain (C1 — see docs/10-linting.md).",
 			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (C1 — see docs/10-linting.md).",
 			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).",
@@ -1705,7 +1787,7 @@ const c10ContractsBoundary = {
 };
 //#endregion
 //#region src/lint/rules/c11-contract-data-pairing.ts
-const TEST_FILE$11 = /\.test\.[cm]?[jt]sx?$/;
+const TEST_FILE$12 = /\.test\.[cm]?[jt]sx?$/;
 /** The provider folders that may carry data files. */
 const PROVIDERS$1 = [
 	"anthropic",
@@ -1729,7 +1811,7 @@ function ownerOf(entry) {
 const c11ContractDataPairing = {
 	create(context) {
 		const file = context.physicalFilename;
-		if (!TEST_FILE$11.test(file) || !segments(file).includes("specs")) return {};
+		if (!TEST_FILE$12.test(file) || !segments(file).includes("specs")) return {};
 		return { Program(node) {
 			const contractsDir = join(dirname(file), "contracts");
 			for (const provider of PROVIDERS$1) {
@@ -1759,13 +1841,66 @@ const c11ContractDataPairing = {
 	}
 };
 //#endregion
+//#region src/lint/rules/c13-underscored-ground.ts
+const TEST_FILE$11 = /\.test\.[cm]?[jt]sx?$/;
+/**
+* CONVENTIONS C13 — the ground of a spec carries a leading underscore. A
+* directory named `fixtures/`, `expected/`, `requests/` or `seeds/` under
+* `specs/` is a pre-14 name: since `@jterrazz/test` 14.0.0 the four are
+* `_fixtures/`, `_expected/`, `_requests/` and `_seeds/`, with no compatibility
+* fallback.
+*
+* The catch this rule exists for: a consumer that upgrades and keeps the old
+* names loses nothing loudly. Every resolver — `.fixture()`, `.seed()`,
+* `.request()`, `toMatch()` — looks under the underscored name, finds nothing,
+* and the tree becomes invisible rather than wrong. The failure that follows is
+* "fixture does not exist" on every spec at once, one step removed from the
+* cause; this rule states the cause and the rename.
+*
+* Anchored on the feature's visited test file, exactly as C2/C7/C11 are: the
+* spec's own sibling directories are probed, plus the `$FIXTURES` pool at the
+* nearest specs root. A DOMAIN folder named after the ground it holds
+* (`specs/api/requests/_requests/`) is never a probe target — only what sits
+* beside a spec is.
+*/
+const c13UnderscoredGround = {
+	create(context) {
+		const file = context.physicalFilename;
+		const anchor = specsAnchor(file);
+		if (!TEST_FILE$11.test(file) || anchor === void 0) return {};
+		return { Program(node) {
+			const seen = /* @__PURE__ */ new Set();
+			const probe = (parent, legacy) => {
+				const path = join(parent, legacy);
+				if (seen.has(path) || !isDirectory(path)) return;
+				seen.add(path);
+				context.report({
+					data: {
+						ground: RENAMED_GROUND_DIRS[legacy],
+						legacy
+					},
+					messageId: "notUnderscored",
+					node
+				});
+			};
+			for (const legacy of Object.keys(RENAMED_GROUND_DIRS)) probe(dirname(file), legacy);
+			probe(anchor.directory, "fixtures");
+		} };
+	},
+	meta: {
+		docs: RULE_DOCS["c13-underscored-ground"],
+		messages: { notUnderscored: "The directory \"{{legacy}}/\" is a pre-14 ground name — rename it to \"{{ground}}/\" (`git mv {{legacy}} {{ground}}`). What a spec stands on carries the underscore; a spec's own folder never does, and no resolver reads the un-underscored name (C13 — see docs/10-linting.md)." },
+		type: "problem"
+	}
+};
+//#endregion
 //#region src/lint/rules/c2-http-only-requests.ts
 const TEST_FILE$10 = /\.test\.[cm]?[jt]sx?$/;
 /**
-* CONVENTIONS C2 — `requests/` contains only `.http` files (a request file is
+* CONVENTIONS C2 — `_requests/` contains only `.http` files (a request file is
 * a COMPLETE request: method, path, headers, body). Anchored on the feature's
 * visited test file: when `<feature>/<feature>.test.ts` is linted, its sibling
-* `requests/` directory is probed (cached readdir) and any non-`.http` entry
+* `_requests/` directory is probed (cached readdir) and any non-`.http` entry
 * is reported on the test file.
 */
 const c2HttpOnlyRequests = {
@@ -1773,7 +1908,7 @@ const c2HttpOnlyRequests = {
 		const file = context.physicalFilename;
 		if (!TEST_FILE$10.test(file) || !segments(file).includes("specs")) return {};
 		return { Program(node) {
-			const requestsDir = join(dirname(file), "requests");
+			const requestsDir = join(dirname(file), GROUND_REQUESTS);
 			for (const entry of listDirectory(requestsDir) ?? []) if (!entry.endsWith(".http")) context.report({
 				data: { entry },
 				messageId: "notHttp",
@@ -1783,7 +1918,7 @@ const c2HttpOnlyRequests = {
 	},
 	meta: {
 		docs: RULE_DOCS["c2-http-only-requests"],
-		messages: { notHttp: "requests/{{entry}} is not a .http file — requests/ contains only complete .http request files (C2 — see docs/10-linting.md)." },
+		messages: { notHttp: "_requests/{{entry}} is not a .http file — _requests/ contains only complete .http request files (C2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2041,11 +2176,11 @@ function subjectIsDirectory(toMatchCallee) {
 /**
 * CONVENTIONS C6 — the extension is part of the fixture name and mandatory in
 * `toMatch` (`'help.txt'`, never `'help'`) — except for directory-tree
-* snapshots, which are directories under `expected/`.
+* snapshots, which are directories under `_expected/`.
 *
 * The directory exception is resolved two ways: statically, when the expect
 * subject visibly chains `.directory(…)`; else on disk, when
-* `expected/<name>/` exists next to the spec (cached stat).
+* `_expected/<name>/` exists next to the spec (cached stat).
 */
 const c6ToMatchExtension = {
 	create(context) {
@@ -2059,7 +2194,7 @@ const c6ToMatchExtension = {
 			if (name === void 0 || name.length === 0) return;
 			if ((name.split("/").at(-1) ?? "").includes(".")) return;
 			if (subjectIsDirectory(callee)) return;
-			if (isDirectory(join(dirname(file), "expected", name))) return;
+			if (isDirectory(join(dirname(file), "_expected", name))) return;
 			context.report({
 				data: { name },
 				messageId: "missingExtension",
@@ -2069,7 +2204,7 @@ const c6ToMatchExtension = {
 	},
 	meta: {
 		docs: RULE_DOCS["c6-tomatch-extension"],
-		messages: { missingExtension: "toMatch(\"{{name}}\") is missing its extension — the extension is part of the fixture name (\"help.txt\", never \"help\"); only directory-tree snapshots (expected/<name>/) omit it (C6 — see docs/10-linting.md)." },
+		messages: { missingExtension: "toMatch(\"{{name}}\") is missing its extension — the extension is part of the fixture name (\"help.txt\", never \"help\"); only directory-tree snapshots (_expected/<name>/) omit it (C6 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2077,17 +2212,17 @@ const c6ToMatchExtension = {
 //#region src/lint/rules/c7-seeds-sql-only.ts
 const TEST_FILE$7 = /\.test\.[cm]?[jt]sx?$/;
 /**
-* CONVENTIONS C7 — `.seed()` carries DATABASE state only: `seeds/` contains
+* CONVENTIONS C7 — `.seed()` carries DATABASE state only: `_seeds/` contains
 * nothing but `*.sql` fragments. File state goes through `.fixture()`; there
 * is no seed handler and no prefix dispatch. Anchored on the feature's visited
-* test file (cached readdir of the sibling `seeds/`).
+* test file (cached readdir of the sibling `_seeds/`).
 */
 const c7SeedsSqlOnly = {
 	create(context) {
 		const file = context.physicalFilename;
 		if (!TEST_FILE$7.test(file) || !segments(file).includes("specs")) return {};
 		return { Program(node) {
-			const seedsDir = join(dirname(file), "seeds");
+			const seedsDir = join(dirname(file), GROUND_SEEDS);
 			for (const entry of listDirectory(seedsDir) ?? []) if (!entry.endsWith(".sql")) context.report({
 				data: { entry },
 				messageId: "notSql",
@@ -2097,18 +2232,18 @@ const c7SeedsSqlOnly = {
 	},
 	meta: {
 		docs: RULE_DOCS["c7-seeds-sql-only"],
-		messages: { notSql: "seeds/{{entry}} is not a .sql file — seeds/ carries database state only; file state goes through .fixture() (C7 — see docs/10-linting.md)." },
+		messages: { notSql: "_seeds/{{entry}} is not a .sql file — _seeds/ carries database state only; file state goes through .fixture() (C7 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/c8-referenced-fixture-exists.ts
 const TEST_FILE$6 = /\.test\.[cm]?[jt]sx?$/;
-/** The conventional sibling directory each fixture-referencing verb reads from. */
+/** The ground directory each fixture-referencing verb reads from. */
 const VERB_ROOTS = {
-	request: "requests",
-	seed: "seeds",
-	toMatch: "expected"
+	request: GROUND_REQUESTS,
+	seed: GROUND_SEEDS,
+	toMatch: GROUND_EXPECTED
 };
 /**
 * A fixture reference is a filename/path, never inline content. `.seed()` also
@@ -2120,15 +2255,15 @@ function looksLikePath(value) {
 }
 /** Resolve the on-disk target a `.fixture()` literal points at, if determinable. */
 function resolveFixture(argument, featureDir, specsDir) {
-	if (argument.startsWith("$FIXTURES/")) return join(specsDir, "fixtures", argument.slice(10));
+	if (argument.startsWith("$FIXTURES/")) return join(specsDir, GROUND_FIXTURES, argument.slice(10));
 	if (argument.startsWith("$")) return;
-	return join(featureDir, "fixtures", argument);
+	return join(featureDir, GROUND_FIXTURES, argument);
 }
 /**
 * CONVENTIONS C8 — a fixture referenced by a literal must exist on disk under
-* its conventional root: `.request(x)`→`requests/x`, `.seed(x)`→`seeds/x`,
-* `.fixture(x)`→feature `fixtures/` (or the `$FIXTURES/` pool at the nearest
-* `specs/fixtures/`), `toMatch(x)`→`expected/x` (file or tree snapshot). A typo
+* its ground root: `.request(x)`→`_requests/x`, `.seed(x)`→`_seeds/x`,
+* `.fixture(x)`→the leaf's `_fixtures/` (or the `$FIXTURES/` pool at the nearest
+* `specs/_fixtures/`), `toMatch(x)`→`_expected/x` (file or tree snapshot). A typo
 * that would fail only at runtime is caught statically. Non-literal arguments
 * are out of static reach and skipped.
 */
@@ -2150,7 +2285,7 @@ const c8ReferencedFixtureExists = {
 				if (target !== void 0 && !isFile(target) && !isDirectory(target)) context.report({
 					data: {
 						path: value,
-						root: "fixtures"
+						root: GROUND_FIXTURES
 					},
 					messageId: "missing",
 					node: args[0]
@@ -2174,7 +2309,7 @@ const c8ReferencedFixtureExists = {
 	},
 	meta: {
 		docs: RULE_DOCS["c8-referenced-fixture-exists"],
-		messages: { missing: "Referenced fixture \"{{path}}\" does not exist on disk under its conventional {{root}}/ root (C8 — see docs/10-linting.md). Create it or fix the reference." },
+		messages: { missing: "Referenced fixture \"{{path}}\" does not exist on disk under its ground {{root}}/ root (C8 — see docs/10-linting.md). Create it or fix the reference." },
 		type: "problem"
 	}
 };
@@ -2588,7 +2723,7 @@ const d6wTransformTokenEquivalent = {
 	},
 	meta: {
 		docs: RULE_DOCS["d6w-transform-token-equivalent"],
-		messages: { tokenEquivalent: "This transform only rewrites output into known token literals — write the tokens in the expected/ fixture instead; transform is an escape hatch for uncovered noise (D6 — see docs/10-linting.md)." },
+		messages: { tokenEquivalent: "This transform only rewrites output into known token literals — write the tokens in the _expected/ fixture instead; transform is an escape hatch for uncovered noise (D6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2657,7 +2792,7 @@ function refsInFixture(target) {
 * `{{uuid#order}}`) earns its keep only when it is asserted more than once (the
 * point of a capture is the equality check on later occurrences). Aggregating
 * per file — code `match.ref` literals plus the `{{kind#ref}}` tokens of the
-* `expected/` fixtures the file references — a ref that appears exactly once
+* `_expected/` fixtures the file references — a ref that appears exactly once
 * everywhere is a plain matcher wearing a name.
 */
 const d9wSingleUseRef = {
@@ -2685,7 +2820,7 @@ const d9wSingleUseRef = {
 				if (memberPropertyName(node.callee) === "toMatch") {
 					const name = stringValue(node.arguments?.[0]);
 					if (name !== void 0) {
-						const target = join(featureDir, "expected", name.replace(/\/+$/, ""));
+						const target = join(featureDir, GROUND_EXPECTED, name.replace(/\/+$/, ""));
 						for (const ref of refsInFixture(target)) {
 							bump(ref);
 							if (!fixtureNodes.has(ref)) fixtureNodes.set(ref, node);
@@ -3539,6 +3674,7 @@ const plugin = {
 		"c1-domain-structure": c1DomainStructure,
 		"c10-contracts-boundary": c10ContractsBoundary,
 		"c11-contract-data-pairing": c11ContractDataPairing,
+		"c13-underscored-ground": c13UnderscoredGround,
 		"c2-http-only-requests": c2HttpOnlyRequests,
 		"c4-contract-shape": c4ContractShape,
 		"c6-tomatch-extension": c6ToMatchExtension,

package/dist/spec-document.js

@@ -16,11 +16,51 @@ function detectIndent(text) {
 	}
 	return smallest === 0 ? 2 : smallest;
 }
+/** The tag every string goes out through — key, plain value and block scalar alike. */
+const STRING_TAG = "tag:yaml.org,2002:str";
+/** An indentation indicator is ONE digit, so nine spaces is the deepest step statable. */
+const DEEPEST_STATABLE_STEP = 9;
+/**
+* Restate a block scalar's indentation indicator from the indentation its
+* content is actually written at.
+*
+* A block scalar whose first line opens on a space NEEDS that indicator: without
+* it a reader takes the space for indentation and gives back a string shorter
+* than the one that was written. The `yaml` writer knows when one is called for
+* and adds it — but it always writes the digit `2`, its own default step, never
+* the step it was asked to indent with. In a four-space document (oxfmt formats
+* YAML at four) `|2` puts every line back two spaces short, so the golden update
+* mode just wrote fails on its very next run.
+*
+* The digit belongs to the block, not to the writer's default: content sits one
+* step below its key, so the file's step is what the indicator names — and `1`
+* at the root, which YAML counts from -1.
+*/
+function stateIndentation(written, ctx) {
+	if (!/^[|>][1-9]/.test(written)) return written;
+	const step = ctx.indent === "" ? 1 : ctx.indentStep.length;
+	if (step > DEEPEST_STATABLE_STEP) throw new Error(`A block scalar indented by ${step} spaces cannot state its indentation: YAML writes that indicator as a single digit, so ${DEEPEST_STATABLE_STEP} spaces is the deepest step a document may be written with.`);
+	return `${written[0]}${step}${written.slice(2)}`;
+}
+/** A scalar tag among the schema's, told from a collection one by what it may hold. */
+function isScalarTag(tag) {
+	return typeof tag !== "string" && tag.collection === void 0;
+}
+/** The string tag, wrapped so every block scalar it writes states its own indentation. */
+function statingItsIndentation(tag) {
+	const write = tag.stringify;
+	if (write === void 0) return tag;
+	return {
+		...tag,
+		stringify: (item, ctx, onComment, onChompKeep) => stateIndentation(write(item, ctx, onComment, onChompKeep), ctx)
+	};
+}
 /** Parse a YAML file into its document form, keeping comments and key order. */
 function parseYamlSource(text) {
 	const lineCounter = new LineCounter();
 	return {
 		document: parseDocument(text, {
+			customTags: (tags) => tags.map((tag) => isScalarTag(tag) && tag.tag === STRING_TAG ? statingItsIndentation(tag) : tag),
 			keepSourceTokens: true,
 			lineCounter
 		}),
@@ -38,8 +78,10 @@ function yamlSyntaxErrors(source) {
 /**
 * A literal block scalar. The `yaml` writer picks the chomping indicator from
 * the value itself — `|` when the text ends with a newline, `|-` when it does
-* not — and adds the indentation indicator (`|2`) when the first line starts
-* with a space, which is exactly the byte-exactness the format promises.
+* not — and decides whether an indentation indicator is called for, which is
+* when the first line opens on a space. What that indicator SAYS is restated on
+* the way out by `stateIndentation` above, and together the two are the
+* byte-exactness the format promises.
 */
 function blockScalar(text) {
 	const scalar = new Scalar(text);
@@ -343,7 +385,7 @@ function readSpecFile(content, fileName) {
 /**
 * Every text of a document the `{{token}}` grammar governs: the streams a
 * comparison judges, and the `files:` texts it judges them with. `stdin:` is an
-* INPUT — like a `requests/` fixture, it is never matched — and a description or
+* INPUT — like a `_requests/` fixture, it is never matched — and a description or
 * a command is prose, so neither appears here.
 */
 function assertedStreams(document) {
@@ -501,7 +543,7 @@ const SPEC_SCHEMA = {
 		},
 		fixture: {
 			...STRING_OR_LIST,
-			description: "Fixture paths copied into the working directory, layering in order."
+			description: "Fixture paths copied into the working directory, layering in order. `$FIXTURES/<name>` is the shared pool at `<specs-root>/_fixtures/`; a bare path is the ground beside this document, at `_fixtures/<name>`."
 		},
 		kind: {
 			default: "cli",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "13.0.1",
+    "version": "14.0.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",

package/schema/spec.schema.json

@@ -136,7 +136,7 @@
                     "type": "array"
                 }
             ],
-            "description": "Fixture paths copied into the working directory, layering in order."
+            "description": "Fixture paths copied into the working directory, layering in order. `$FIXTURES/<name>` is the shared pool at `<specs-root>/_fixtures/`; a bare path is the ground beside this document, at `_fixtures/<name>`."
         },
         "kind": {
             "default": "cli",