@jterrazz/test 13.0.2 → 14.0.1

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. Une exception, et une seule : le sol peut être du CODE, et un `<module>.test.ts` posé À CÔTÉ du `<module>.ts` qu’il teste y est légal (c’est la loi I2) ; un test sans module voisin, ou un `*.specification.ts`, reste une violation.",
 		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}).
@@ -1535,6 +1600,14 @@ const TEST_SUFFIX = ".test.ts";
 const SPECIFICATION_SUFFIX = ".specification.ts";
 const DEFAULT_DEPTH = "facet-domain";
 /**
+* Whether a file is the unit test of the module it sits beside — `x.test.ts`
+* next to `x.ts`, which is the whole of I2's pairing. This is what tells a
+* ground MODULE's test from a spec that wandered into the ground.
+*/
+function testsItsNeighbour(filename) {
+	return filename.endsWith(TEST_SUFFIX) && isFile(`${filename.slice(0, -8)}.ts`);
+}
+/**
 * CONVENTIONS C1' — the shape of a spec tree, DECLARED by the consumer.
 *
 * A project states which shape its `specs/` tree has; the rule checks that one.
@@ -1576,7 +1649,18 @@ 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.
+*
+* Ground is not always inert, though: it may be CODE the specs stand on — the
+* build of the subject under test, a harness the runner spawns. A `<module>.ts`
+* there keeps its own unit test under I2's law, `<module>.test.ts` NEXT to it,
+* and the clause lets that one pair through. Nothing else: a test with no module
+* beside it, or a `*.specification.ts`, is a spec that wandered into the ground.
 *
 * Module tests under `src/` follow the neighbour rule (I2) and are out of scope
 * in every mode.
@@ -1584,12 +1668,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) {
+					if (!testsItsNeighbour(context.filename)) 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 +1743,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). Ground that is CODE keeps its own unit test: `<module>.test.ts` NEXT to the `<module>.ts` it tests (I2), and nothing else.",
 			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 +1801,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 +1825,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 +1855,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 +1922,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 +1932,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 +2190,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 +2208,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 +2218,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 +2226,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 +2246,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 +2269,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 +2299,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 +2323,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 +2737,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 +2806,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 +2834,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 +3688,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

@@ -1,4 +1,4 @@
-import { LineCounter, Scalar, Scalar as Scalar$1, isMap, isScalar, isSeq, parseDocument } from "yaml";
+import { LineCounter, Scalar, Scalar as Scalar$1, isMap, isScalar, isSeq, parseDocument, visit } from "yaml";
 //#region src/integrations/yaml/document.ts
 /** A line that opens a mapping key — `  key:` or `  - key:`, never block-scalar text. */
 const KEY_LINE = /^(?<indent> +)(?:- )?[A-Za-z_$'"][^\n]*:/;
@@ -65,7 +65,8 @@ function parseYamlSource(text) {
 			lineCounter
 		}),
 		indent: detectIndent(text),
-		lineAt: (offset) => lineCounter.linePos(offset).line
+		lineAt: (offset) => lineCounter.linePos(offset).line,
+		text
 	};
 }
 /** The YAML parser's own errors, with their line — an empty list when it parsed. */
@@ -88,16 +89,94 @@ function blockScalar(text) {
 	scalar.type = Scalar.BLOCK_LITERAL;
 	return scalar;
 }
+/** The first offset of the line `offset` sits on. */
+function lineStart(text, offset) {
+	return text.lastIndexOf("\n", offset - 1) + 1;
+}
+/** Back over the whitespace before `offset`, to just past the `:` or `-` that owns it. */
+function afterOwner(text, offset) {
+	let at = offset;
+	while (at > 0 && /\s/.test(text[at - 1])) at -= 1;
+	return at;
+}
+/** How many spaces a line opens with. */
+function indentOf(text, offset) {
+	const start = lineStart(text, offset);
+	return /^ */.exec(text.slice(start))[0].length;
+}
+/**
+* Every OUTERMOST flow collection of a document, in source order. A nested one
+* is part of its parent's text and is restored with it, so descending past a
+* flow collection would splice the same span twice.
+*/
+function flowCollections(text) {
+	const found = [];
+	const take = (node) => {
+		if (node.flow !== true || !node.range) return;
+		const from = afterOwner(text, node.range[0]);
+		found.push({
+			ownerIndent: indentOf(text, from === 0 ? 0 : from - 1),
+			range: [from, node.range[1]],
+			text: text.slice(from, node.range[1]),
+			value: JSON.stringify(node.toJSON())
+		});
+		return visit.SKIP;
+	};
+	visit(parseDocument(text), {
+		Map: (_key, node) => take(node),
+		Seq: (_key, node) => take(node)
+	});
+	return found;
+}
+/**
+* Give every flow collection the rewrite did not change back exactly as it was
+* written — padding, quotes and line breaks included.
+*
+* The `yaml` writer has ONE house style for `{ … }` and `[ … ]`, and it is not
+* the repository formatter's: oxfmt pads a flow mapping and not a flow sequence,
+* and explodes a long one over several lines, while the writer emits `[ 'a' ]`
+* on one line whatever its width. Re-emitting an untouched collection therefore
+* hands the formatter something to undo, and `check --fix` and `oxfmt` rewrite
+* each other for ever. A collection nobody touched belongs to its author, not to
+* either tool.
+*
+* A rendered collection is matched to a source one by VALUE and by the
+* INDENTATION of the line that owns it: the same content under the same key is
+* the same collection, and the indentation guard is what keeps the inner lines
+* of a multi-line spelling true where a fix moved that key. Anything unmatched
+* — added, removed, edited — keeps the writer's rendering.
+*/
+function restoreUntouchedFlow(rendered, text) {
+	const sources = flowCollections(text);
+	if (sources.length === 0) return rendered;
+	const taken = /* @__PURE__ */ new Set();
+	const splices = [];
+	for (const target of flowCollections(rendered)) {
+		const at = sources.findIndex((candidate, index) => !taken.has(index) && candidate.value === target.value && candidate.ownerIndent === target.ownerIndent);
+		if (at === -1) continue;
+		taken.add(at);
+		splices.push({
+			range: target.range,
+			text: sources[at].text
+		});
+	}
+	let out = rendered;
+	for (const splice of splices.toReversed()) out = out.slice(0, splice.range[0]) + splice.text + out.slice(splice.range[1]);
+	return out;
+}
 /**
 * Render a document back to text, in the indentation it was read with.
 * `lineWidth: 0` disables the folding of long lines — a golden is compared byte
 * for byte, so nothing may decide on its own where to break one.
+*
+* What the caller did not change comes back as it was written — see
+* {@link restoreUntouchedFlow} for the one construct the writer restyles.
 */
 function renderYamlSource(source) {
-	return source.document.toString({
+	return restoreUntouchedFlow(source.document.toString({
 		indent: source.indent,
 		lineWidth: 0
-	});
+	}), source.text);
 }
 //#endregion
 //#region src/core/literate/spec-document.ts
@@ -385,7 +464,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) {
@@ -543,7 +622,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.2",
+    "version": "14.0.1",
     "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",