@jterrazz/test 12.0.2 → 12.2.0

package/dist/match.js

@@ -1,3 +1,195 @@
+//#region src/core/literate/literate-file.ts
+/** The closed set of header keys. Anything else is an error naming the line. */
+const HEADER_KEYS = [
+	"test",
+	"given",
+	"then",
+	"fixture",
+	"env",
+	"serve"
+];
+/** The separator opening a block's stderr section. */
+const STDERR_MARKER = "--- stderr";
+const HEADER_LINE = /^(?<key>[a-z]+):(?<value>.*)$/;
+const EXIT_LINE = /^exit:\s*(?<code>-?\d+)\s*$/;
+const KEY_SET = new Set(HEADER_KEYS);
+/** A refusal from the grammar, carrying where it happened and which rule it is. */
+var LiterateSyntaxError = class extends Error {
+	defect;
+	line;
+	constructor(fileName, line, message, defect) {
+		super(`${fileName}:${line}: ${message}`);
+		this.defect = defect;
+		this.line = line;
+		this.name = "LiterateSyntaxError";
+	}
+};
+function fail(fileName, line, message, defect = "shape") {
+	throw new LiterateSyntaxError(fileName, line, message, defect);
+}
+/** Is this line the start of a block? `$ cmd`, or a bare `$` (no arguments). */
+function isBlockStart(line) {
+	return line === "$" || line.startsWith("$ ");
+}
+function parseEnvTokens(value, fileName, line) {
+	const tokens = [];
+	for (const token of value.split(/\s+/).filter((part) => part.length > 0)) {
+		const separator = token.indexOf("=");
+		if (separator === -1) {
+			tokens.push({
+				kind: "set",
+				name: token
+			});
+			continue;
+		}
+		const key = token.slice(0, separator);
+		if (key.length === 0) fail(fileName, line, `env: "${token}" has no variable name before the "="`);
+		tokens.push({
+			key,
+			kind: "pair",
+			value: token.slice(separator + 1)
+		});
+	}
+	if (tokens.length === 0) fail(fileName, line, "env: needs at least one KEY=value pair or a registered env-set name");
+	return tokens;
+}
+function parseServeEntry(value, fileName, line) {
+	const parts = value.split(/\s+/).filter((part) => part.length > 0);
+	const name = parts.shift();
+	if (name === void 0) fail(fileName, line, "serve: needs the name of a server registered in specification.cli()");
+	if (name.includes("=")) fail(fileName, line, `serve: "${name}" is a KEY=value pair — the server NAME comes first`);
+	const env = {};
+	for (const part of parts) {
+		const separator = part.indexOf("=");
+		if (separator <= 0) fail(fileName, line, `serve: "${part}" is not a KEY=value pair`);
+		env[part.slice(0, separator)] = part.slice(separator + 1);
+	}
+	return {
+		env,
+		line,
+		name
+	};
+}
+/**
+* Parse the header: every line up to the first blank one. `#` lines are
+* comments; `test:`, `given:` and `then:` are mandatory and single; `fixture:`,
+* `env:` and `serve:` repeat and keep their declaration order.
+*/
+function parseHeader(lines, fileName) {
+	const fixtures = [];
+	const env = [];
+	const serve = [];
+	const singles = /* @__PURE__ */ new Map();
+	let index = 0;
+	for (; index < lines.length; index++) {
+		const raw = lines[index];
+		if (raw.trim() === "") break;
+		const number = index + 1;
+		if (raw.trimStart().startsWith("#")) continue;
+		if (isBlockStart(raw)) fail(fileName, number, "a \"$\" block starts before the header is closed — separate the header from the blocks with a blank line");
+		const found = HEADER_LINE.exec(raw);
+		if (!found?.groups) fail(fileName, number, `"${raw}" is not a header line — expected "<key>: <value>" (keys: ${HEADER_KEYS.join(", ")})`);
+		const key = found.groups.key;
+		const value = found.groups.value.trim();
+		if (!KEY_SET.has(key)) fail(fileName, number, `unknown header key "${key}:" — known keys: ${HEADER_KEYS.join(", ")}`);
+		if (key === "fixture" || key === "env" || key === "serve") {
+			if (value.length === 0) fail(fileName, number, `${key}: is empty`);
+			if (key === "fixture") fixtures.push(value);
+			else if (key === "env") env.push(...parseEnvTokens(value, fileName, number));
+			else serve.push(parseServeEntry(value, fileName, number));
+			continue;
+		}
+		if (singles.has(key)) fail(fileName, number, `${key}: is declared twice — it takes exactly one line`);
+		if (value.length === 0) fail(fileName, number, `${key}: is empty`);
+		singles.set(key, value);
+	}
+	for (const key of [
+		"test",
+		"given",
+		"then"
+	]) if (!singles.has(key)) fail(fileName, 1, `missing "${key}:" in the header — test, given and then are mandatory`, "narrative");
+	const header = {
+		env,
+		fixtures,
+		given: singles.get("given"),
+		serve,
+		test: singles.get("test"),
+		then: singles.get("then")
+	};
+	return {
+		end: index,
+		header
+	};
+}
+/**
+* Split a block's stream section at `--- stderr`, dropping the ONE blank line
+* that separates the block from the next `$` (that line belongs to the
+* separator, not to the stream).
+*/
+function parseStreams(section, trailingSeparator) {
+	const lines = [...section];
+	if (trailingSeparator && lines.at(-1) === "") lines.pop();
+	const marker = lines.indexOf(STDERR_MARKER);
+	if (marker === -1) return {
+		stderr: null,
+		stdout: lines.join("\n")
+	};
+	return {
+		stderr: lines.slice(marker + 1).join("\n"),
+		stdout: lines.slice(0, marker).join("\n")
+	};
+}
+/** Parse the blocks: everything after the header's blank line. */
+function parseBlocks(lines, start, fileName) {
+	const starts = [];
+	for (let index = start; index < lines.length; index++) if (isBlockStart(lines[index])) starts.push(index);
+	if (starts.length === 0) fail(fileName, start + 1, "no \"$ <command>\" block — a literate spec runs at least one command");
+	for (let index = start; index < starts[0]; index++) if (lines[index].trim() !== "") fail(fileName, index + 1, `"${lines[index]}" sits outside a block — the first line after the header must be "$ <command>"`);
+	return starts.map((blockStart, position) => {
+		const next = starts[position + 1] ?? lines.length;
+		const argv = lines[blockStart].slice(1).trim();
+		const exitLine = lines[blockStart + 1];
+		const exit = exitLine === void 0 ? null : EXIT_LINE.exec(exitLine);
+		if (!exit?.groups) fail(fileName, blockStart + 2, `the line after "$ ${argv}" must be "exit: <integer>", got ${exitLine === void 0 ? "(end of file)" : `"${exitLine}"`}`);
+		const streams = parseStreams(lines.slice(blockStart + 2, next), position + 1 < starts.length);
+		return {
+			argv,
+			exitCode: Number(exit.groups.code),
+			line: blockStart + 1,
+			stderr: streams.stderr,
+			stdout: streams.stdout
+		};
+	});
+}
+/**
+* Parse a `<case>.cli` file. `fileName` is used verbatim in error messages, so
+* pass the path the reader would open (`specs/cli/no-estate.cli`).
+*/
+function parseLiterateFile(content, fileName) {
+	const lines = content.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n");
+	const { end, header } = parseHeader(lines, fileName);
+	return {
+		blocks: parseBlocks(lines, end + 1, fileName),
+		header,
+		headerText: `${lines.slice(0, end).join("\n")}\n`
+	};
+}
+/** Render one block back to its source form (the update-mode inverse of the parser). */
+function serializeLiterateBlock(block) {
+	const lines = [`$ ${block.argv}`.trimEnd(), `exit: ${block.exitCode}`];
+	if (block.stdout.length > 0) lines.push(block.stdout);
+	if (block.stderr !== null && block.stderr.length > 0) lines.push(STDERR_MARKER, block.stderr);
+	return lines.join("\n");
+}
+/**
+* Rebuild a `.cli` file from its VERBATIM header text and a fresh set of
+* blocks. Update mode rewrites only what follows each `$` — the header comes
+* back byte-identical, comments and all.
+*/
+function serializeLiterateFile(headerText, blocks) {
+	return `${headerText}\n${blocks.map((block) => serializeLiterateBlock(block)).join("\n\n")}\n`;
+}
+//#endregion
 //#region src/core/matching/match.ts
 /** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
 const TOKEN_KINDS = [
@@ -161,4 +353,4 @@ var CaptureScope = class {
 	}
 };
 //#endregion
-export { match as i, Matcher as n, TOKEN_KINDS as r, CaptureScope as t };
+export { LiterateSyntaxError as a, match as i, Matcher as n, parseLiterateFile as o, TOKEN_KINDS as r, serializeLiterateFile as s, CaptureScope as t };

package/dist/oxlint.cjs

@@ -4,6 +4,7 @@ Object.defineProperties(exports, {
 });
 let node_path = require("node:path");
 let node_fs = require("node:fs");
+let node_url = require("node:url");
 //#region src/lint/fs-cache.ts
 /**
 * Cached filesystem probes for the fs-anchored rules (a9w, c2, c6, c7, i2).
@@ -305,7 +306,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."
@@ -340,7 +341,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."
@@ -452,7 +453,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."
@@ -566,7 +567,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",
@@ -588,6 +589,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.",
@@ -598,7 +615,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",
@@ -1471,6 +1488,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
@@ -1495,6 +1522,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) {
@@ -1539,12 +1584,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"
@@ -2594,22 +2642,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((0, node_path.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 = (0, node_path.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 ?? (0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)))?.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
 			});
@@ -2617,7 +2731,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"
 	}
 };