@jterrazz/test 12.2.0 → 13.0.0

package/dist/literate.js

@@ -1,6 +1,7 @@
-import { a as LiterateSyntaxError, n as Matcher, o as parseLiterateFile, r as TOKEN_KINDS, s as serializeLiterateFile, t as CaptureScope } from "./match.js";
+import { i as SpecSyntaxError, l as updateSpecFile, s as readSpecFile } from "./spec-document.js";
+import { a as copyPlan, n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
 import { cpSync, existsSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { execSync, spawn } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
@@ -238,6 +239,20 @@ function textEquals(expected, actual, scope) {
 	return placeholderStringMatches(expected, actual, scope);
 }
 /**
+* Substring comparison with `{{token}}` support — the `contains` half of the
+* `files:` assertions of a spec document. Without placeholders this is
+* `String.includes`; with them the fixture text becomes an UNANCHORED pattern,
+* so `wrote {{path}}` is found inside a larger file, and its `#ref` captures are
+* recorded exactly as a whole-text comparison records them.
+*/
+function textContains(expected, actual, scope) {
+	if (!hasPlaceholders(expected)) return actual.includes(expected);
+	const parsed = parsePlaceholderString(expected, scope);
+	const found = new RegExp(parsed.source).exec(actual);
+	if (!found) return false;
+	return parsed.refs.every((entry) => !entry.ref || recordRef(entry.ref, found[entry.index + 1], scope));
+}
+/**
 * Render an expected value for failure diffs and serialization: Matcher
 * instances become their placeholder text, everything else is untouched.
 */
@@ -1288,77 +1303,6 @@ function shouldUpdateSnapshots() {
 /** Standard hint appended to missing-fixture errors. */
 const UPDATE_HINT = "Run with TEST_UPDATE=1 (or vitest -u) to create it.";
 //#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>`,
-*    where `<specs-root>` is the nearest ancestor directory named `specs`.
-*  - `<path>` (no marker) — feature-local, at `<test-dir>/fixtures/<path>`.
-*
-* Any other `$`-prefixed marker is a usage error (listed against the known
-* markers). Copy semantics mirror rsync's trailing-slash rule (see
-* {@link copyPlan}).
-*/
-/**
-* Markers understood in a `.fixture()` path. Extend here + in
-* {@link resolveFixtureSource}. Exported so the lint layer (rule
-* `jterrazz/b2-known-fixture-marker`) validates literals against the same list.
-*/
-const KNOWN_FIXTURE_MARKERS = ["$FIXTURES"];
-/**
-* Walk up from `startDir` to the nearest ancestor directory named `specs`.
-* Throws with guidance if none is found up to the filesystem root — the
-* `$FIXTURES` marker is meaningless without a specs root.
-*/
-function discoverSpecsRoot(startDir) {
-	let dir = startDir;
-	for (;;) {
-		if (basename(dir) === "specs") return dir;
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
-	}
-	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/fixtures, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local fixtures/ path (no $FIXTURES marker).`);
-}
-/**
-* Resolve the absolute source path of a fixture, applying marker resolution.
-* The trailing slash (spread semantics) is preserved by callers via
-* {@link copyPlan} — it is irrelevant to source resolution.
-*/
-function resolveFixtureSource(path, testDir) {
-	const clean = path.replace(/\/+$/, "");
-	if (clean === "$FIXTURES" || path.startsWith("$FIXTURES/")) {
-		const rest = clean.slice(9).replace(/^\/+/, "");
-		return resolve(discoverSpecsRoot(testDir), "fixtures", rest);
-	}
-	if (path.startsWith("$")) {
-		const marker = clean.split("/")[0];
-		throw new Error(`.fixture("${path}"): unknown marker "${marker}". Known markers: ${KNOWN_FIXTURE_MARKERS.join(", ")}. A path without a marker is feature-local (resolved under <test-dir>/fixtures/).`);
-	}
-	return resolve(testDir, "fixtures", clean);
-}
-/**
-* Compute the source + destination for copying a fixture into the working
-* directory. Copy semantics follow rsync's trailing-slash rule:
-*
-*  - `dir/` (trailing slash) — the CONTENTS are spread into the cwd.
-*  - `dir`  (no slash, a directory) — the directory is copied as `<cwd>/<basename>`.
-*  - `file` — copied as `<cwd>/<basename>`.
-*
-* Chained `.fixture()` calls layer in order: a later fixture overwrites files
-* written by an earlier one.
-*/
-function copyPlan(path, testDir, workDir) {
-	const src = resolveFixtureSource(path, testDir);
-	return {
-		dest: /\/+$/.test(path) ? workDir : resolve(workDir, basename(src)),
-		src
-	};
-}
-//#endregion
 //#region src/core/specification/website/serve.adapter.ts
 /** Grace period between SIGTERM and the SIGKILL escalation. */
 const KILL_GRACE_MS = 2e3;
@@ -1515,21 +1459,14 @@ var ServeAdapter = class {
 //#endregion
 //#region src/core/specification/cli/literate.ts
 /**
-* The form a stream is compared in: ANSI stripped (rule D6), the runner's
-* `transform` applied, and ONE trailing newline dropped — a `.cli` section is
-* written as lines, and a command that ends its output with a newline must not
-* be forced to spell an empty last line.
+* The form a stream is compared in: ANSI stripped (rule D6) and the runner's
+* `transform` applied. Nothing else — a block scalar states its own final
+* newline (`|` keeps it, `|-` drops it), so the comparison is byte-exact and
+* has no normalisation to hide behind.
 */
 function comparable(raw, transform) {
 	const stripped = stripAnsiCodes(raw);
-	return (transform ? transform(stripped) : stripped).replace(/\n$/, "");
-}
-function narrative(spec) {
-	return [
-		`test: ${spec.header.test}`,
-		`given: ${spec.header.given}`,
-		`then: ${spec.header.then}`
-	].join("\n");
+	return transform ? transform(stripped) : stripped;
 }
 /**
 * Line equality AS THE COMPARISON JUDGED IT — a `{{url}}` line that matched is
@@ -1540,85 +1477,133 @@ function narrative(spec) {
 function tokenAwareEquals(scope) {
 	return (expected, actual) => textEquals(expected, actual, new CaptureScope(scope.workdir));
 }
+/** A path under the working directory, refusing anything that would escape it. */
+function resolveUnderWorkDir(path, workDir, context) {
+	const target = resolve(workDir, path);
+	const inside = relative(workDir, target);
+	if (isAbsolute(path) || inside.startsWith("..") || isAbsolute(inside)) throw new Error(`${context.displayPath}: files: "${path}" leaves the working directory — a files: key is a relative path under the cwd`);
+	return target;
+}
+/** A one-line preview of a file's content for the failure rendering. */
+function preview(text) {
+	return JSON.stringify(text.length > 160 ? `${text.slice(0, 160)}…` : text);
+}
+function readIfPresent(path) {
+	try {
+		return statSync(path).isFile() ? readFileSync(path, "utf8") : null;
+	} catch {
+		return null;
+	}
+}
+/** Check one `files:` entry and render its failure, or `null` when it holds. */
+function checkFile(assertion, workDir, context, scope) {
+	const target = resolveUnderWorkDir(assertion.path, workDir, context);
+	let exists;
+	try {
+		exists = statSync(target) !== void 0;
+	} catch {
+		exists = false;
+	}
+	if (assertion.kind === "absent") return exists ? `${assertion.path}: expected absent, got a file` : null;
+	if (!exists) return `${assertion.path}: expected to exist, got nothing at that path`;
+	if (assertion.kind === "exists") return null;
+	const content = readIfPresent(target);
+	if (content === null) return `${assertion.path}: expected a readable file, got a directory`;
+	for (const needle of assertion.contains) if (!textContains(needle.text, content, scope)) return `${assertion.path}: expected to contain ${preview(needle.text)}, got ${preview(content)}`;
+	if (assertion.equals !== null && !textEquals(assertion.equals.text, content, scope)) return `${assertion.path}: expected ${preview(assertion.equals.text)}, got ${preview(content)}`;
+	return null;
+}
 /**
-* The failure a mismatching block throws: the narrative, the command that ran,
-* the diff, and where to open the file. The header is named as never-rewritten
-* so the update hint cannot be read as "this will re-generate my `given:`".
+* The failure a mismatching run throws: the description, the command that ran,
+* every detail the comparison rejected, and where to open the document. The
+* update hint names exactly what a rewrite touches, so it cannot be read as
+* "this will re-generate my `files:`".
 *
-* The stack is REPLACED by the block's own line. Left alone it would carry the
+* The stack is REPLACED by the run's own line. Left alone it would carry the
 * engine's frames and end inside the module the plugin generates — pointing the
-* reader at `<case>.cli:<the $ line of the module>` while the message already
-* names the block. One frame, on the block, is the whole truth here.
+* reader at a line of a file they never wrote. One frame, on the `command:` key,
+* is the whole truth here.
 */
-function failure(spec, run, context, detail) {
-	return atBlock(new Error([
-		`Literate spec mismatch (${context.displayPath}:${run.block.line})`,
+function failure(document, run, context, details) {
+	return atLine(new Error([
+		"Spec mismatch",
 		"",
-		narrative(spec),
+		document.description,
 		"",
-		`$ ${run.block.argv}`,
+		`$ ${run.command}`,
 		"",
-		detail,
+		details.join("\n\n"),
 		"",
-		"Run with TEST_UPDATE=1 to rewrite the blocks (exit code and streams). The header is never rewritten."
-	].join("\n")), context.filePath, run.block.line);
+		`${context.displayPath}:${run.commandLine}`,
+		"Run with TEST_UPDATE=1 to rewrite the runs — the exit code and the streams, and nothing else."
+	].join("\n")), context.filePath, run.commandLine);
 }
 /**
-* Point an error's stack at one frame: the line of the `.cli` file that owns
-* the failure. The framework's own frames carry nothing a reader of a literate
-* spec can act on, and the generated module's frame actively misleads.
+* Point an error's stack at one frame: the line of the `.spec.yaml` that owns
+* the failure. The framework's own frames carry nothing a reader of a spec
+* document can act on, and the generated module's frame actively misleads.
 */
-function atBlock(error, filePath, line) {
+function atLine(error, filePath, line) {
 	error.stack = `${error.name}: ${error.message}\n    at ${filePath}:${line}:1`;
 	return error;
 }
-/** Compare one block against what the command actually did. */
-function assertBlock(spec, run, context, scope) {
-	const { actual, block } = run;
-	const equals = tokenAwareEquals(scope);
-	if (actual.exitCode !== block.exitCode) throw failure(spec, run, context, [
+/** Compare one run against what the command actually did. */
+function assertRun(document, outcome, context, workDir, scope) {
+	const { actual, run } = outcome;
+	if (actual.exitCode !== run.exitCode) throw failure(document, run, context, [[
 		"exit code mismatch",
-		`  expected: ${block.exitCode}`,
+		`  expected: ${run.exitCode}`,
 		`  received: ${actual.exitCode}`,
-		...run.stderr.length > 0 ? [
+		...outcome.stderr.length > 0 ? [
 			"",
 			"stderr was:",
-			run.stderr
+			outcome.stderr.replace(/\n$/, "")
 		] : []
+	].join("\n")]);
+	const equals = tokenAwareEquals(scope);
+	const details = [];
+	for (const [name, expected, received] of [[
+		"stdout",
+		run.stdout?.text ?? "",
+		outcome.stdout
+	], [
+		"stderr",
+		run.stderr?.text ?? "",
+		outcome.stderr
+	]]) if (!textEquals(expected, received, scope)) details.push(formatStdoutDiff(name, expected, received, { equals }));
+	const fileFailures = run.files.map((assertion) => checkFile(assertion, workDir, context, scope)).filter((line) => line !== null);
+	if (fileFailures.length > 0) details.push([
+		"files mismatch",
+		"",
+		...fileFailures.map((line) => `  ${line}`)
 	].join("\n"));
-	if (!textEquals(block.stdout, run.stdout, scope)) throw failure(spec, run, context, formatStdoutDiff("stdout", block.stdout, run.stdout, { equals }));
-	const expectedStderr = block.stderr ?? "";
-	if (!textEquals(expectedStderr, run.stderr, scope)) throw failure(spec, run, context, formatStdoutDiff("stderr", expectedStderr, run.stderr, { equals }));
+	if (details.length > 0) throw failure(document, run, context, details);
 }
 /**
-* The rewritten blocks: exit codes and streams from the run, placeholders of
-* the previous golden preserved by pattern (rule D5). A `--- stderr` section
-* that ends up empty is dropped, so a rewritten file passes the next run.
+* The rewritten runs: exit codes and streams from the run, placeholders of the
+* previous golden preserved by pattern (rule D5). A stream that ends up empty
+* loses its key, so a rewritten document passes the next run.
 */
-function updatedBlocks(runs, scope) {
-	return runs.map(({ actual, block, stderr, stdout }) => {
-		const mergedStderr = mergeTextPreservingPlaceholders(block.stderr, stderr, scope);
-		return {
-			...block,
-			exitCode: actual.exitCode,
-			stderr: mergedStderr.length > 0 ? mergedStderr : null,
-			stdout: mergeTextPreservingPlaceholders(block.stdout, stdout, scope)
-		};
-	});
+function updates(outcomes, scope) {
+	return outcomes.map(({ actual, run, stderr, stdout }) => ({
+		exitCode: actual.exitCode,
+		stderr: mergeTextPreservingPlaceholders(run.stderr?.text ?? null, stderr, scope),
+		stdout: mergeTextPreservingPlaceholders(run.stdout?.text ?? null, stdout, scope)
+	}));
 }
 /**
-* Start every server the header names, in declaration order, before the first
-* block. They all stay live for the whole file and are stopped together — one
-* `.cli` file is one scenario, and its servers are part of its ground.
+* Start every server the document names, in declaration order, before the first
+* run. They all stay live for the whole file and are stopped together — one
+* document is one scenario, and its servers are part of its ground.
 */
-async function startServers(spec, config, displayPath) {
+async function startServers(document, config, displayPath) {
 	const registry = config.serveRegistry ?? {};
 	const started = [];
 	const env = {};
 	const stop = async () => {
 		for (const adapter of started.toReversed()) await adapter.stop();
 	};
-	for (const entry of spec.header.serve) {
+	for (const entry of document.serve) {
 		const registration = registry[entry.name];
 		if (!registration) {
 			await stop();
@@ -1643,16 +1628,16 @@ async function startServers(spec, config, displayPath) {
 		stop
 	};
 }
-/** Resolve the header's `env:` tokens against the registered sets. `$WORKDIR` expands. */
-function headerEnv(spec, config, displayPath) {
+/** Resolve the document's `env:` entries against the registered sets. `$WORKDIR` expands. */
+function documentEnv(document, config, displayPath) {
 	const sets = config.envSets ?? {};
 	const env = {};
-	for (const token of spec.header.env) {
+	for (const token of document.env) {
 		if (token.kind === "set") {
 			const declared = sets[token.name];
 			if (!declared) {
 				const known = Object.keys(sets);
-				throw new Error(`${displayPath}: env: "${token.name}" is not a registered env set — ${known.length === 0 ? "specification.cli() declares no `env` option." : `registered sets: ${known.join(", ")}.`}`);
+				throw new Error(`${displayPath}:${token.line}: env: "${token.name}" is not a registered env set — ${known.length === 0 ? "specification.cli() declares no `env` option." : `registered sets: ${known.join(", ")}.`}`);
 			}
 			Object.assign(env, declared);
 			continue;
@@ -1667,43 +1652,50 @@ function expandWorkdir(env, workDir) {
 	return resolved;
 }
 /**
-* Run one literate spec end to end and resolve with the LAST block's result —
+* Run one spec document end to end and resolve with the LAST run's result —
 * the handle a `.test.ts` adds its own assertion to (a directory golden, a
-* grep) after `cli.run('<case>.cli')`.
+* grep) after `cli.run('<case>.spec.yaml')`.
 *
-* Under `TEST_UPDATE=1` nothing is asserted: every block runs, and what follows
-* each `$` is rewritten from the actual output with the previous golden's
-* placeholders preserved.
+* Under `TEST_UPDATE=1` nothing is asserted: every run executes, and each one's
+* exit code and streams are rewritten from the actual output with the previous
+* golden's placeholders preserved.
 */
-async function runLiterateSpec(options) {
+async function runSpecDocument(options) {
 	const { config, displayPath, filePath, testDir, workDir } = options;
-	if (!config.command) throw new Error(".run(): literate specs require a command adapter (use specification.cli())");
-	let spec;
+	if (!config.command) throw new Error(".run(): spec documents require a command adapter (use specification.cli())");
+	let file;
 	try {
-		spec = parseLiterateFile(readFileSync(filePath, "utf8"), displayPath);
+		file = readSpecFile(readFileSync(filePath, "utf8"), displayPath);
 	} catch (error) {
-		throw error instanceof LiterateSyntaxError ? atBlock(error, filePath, error.line) : error;
+		throw error instanceof SpecSyntaxError ? atLine(error, filePath, error.line) : error;
 	}
+	const document = file.document;
 	const fileDir = filePath.replace(/[/\\][^/\\]*$/, "");
-	for (const path of spec.header.fixtures) {
-		const { dest, src } = copyPlan(path, fileDir, workDir);
+	for (const fixture of document.fixtures) {
+		const { dest, src } = copyPlan(fixture.path, fileDir, workDir);
 		cpSync(src, dest, { recursive: true });
 	}
-	const servers = await startServers(spec, config, displayPath);
+	const servers = await startServers(document, config, displayPath);
 	const scope = new CaptureScope(safeRealpath(workDir));
 	const env = expandWorkdir({
 		...options.baseEnv,
 		...servers.env,
-		...headerEnv(spec, config, displayPath)
+		...documentEnv(document, config, displayPath)
 	}, workDir);
-	let runs;
+	let outcomes;
 	try {
-		runs = [];
-		for (const block of spec.blocks) {
-			const actual = await config.command.exec(block.argv, workDir, env);
-			runs.push({
+		outcomes = [];
+		for (const run of document.runs) {
+			const actual = run.waitFor === null ? await config.command.exec(run.command, workDir, env, {
+				stdin: run.stdin ?? void 0,
+				timeout: run.timeout ?? void 0
+			}) : await config.command.watch(run.command, workDir, {
+				timeout: run.timeout ?? void 0,
+				waitFor: run.waitFor
+			}, env);
+			outcomes.push({
 				actual,
-				block,
+				run,
 				stderr: comparable(actual.stderr, config.transform),
 				stdout: comparable(actual.stdout, config.transform)
 			});
@@ -1711,13 +1703,13 @@ async function runLiterateSpec(options) {
 	} finally {
 		await servers.stop();
 	}
-	if (shouldUpdateSnapshots() && options.frozen !== true) writeFileSync(filePath, serializeLiterateFile(spec.headerText, updatedBlocks(runs, scope)));
-	else for (const run of runs) assertBlock(spec, run, {
+	if (shouldUpdateSnapshots() && options.frozen !== true) writeFileSync(filePath, updateSpecFile(file, updates(outcomes, scope)));
+	else for (const outcome of outcomes) assertRun(document, outcome, {
 		displayPath,
 		filePath
-	}, scope);
+	}, workDir, scope);
 	return new CliResult({
-		commandOutput: runs.at(-1).actual,
+		commandOutput: outcomes.at(-1).actual,
 		config,
 		dockerConfig: config.dockerConfig,
 		testDir,
@@ -1726,9 +1718,9 @@ async function runLiterateSpec(options) {
 		workDir
 	});
 }
-/** The title a transformed `.cli` module runs under — the header's `test:` line. */
-function literateTitle(content, displayPath) {
-	return parseLiterateFile(content, displayPath).header.test;
+/** The title a transformed `.spec.yaml` module runs under — the `description:` line. */
+function specDescription(content, displayPath) {
+	return readSpecFile(content, displayPath).document.description;
 }
 //#endregion
-export { mergeTextPreservingPlaceholders as A, formatDirectoryDiff as C, formatTableDiff as D, formatStdoutDiff as E, textEquals as F, renderExpected as M, structuralEquals as N, hasPlaceholders as O, structuralSubset as P, walkDirectory as S, formatStartupReport as T, text as _, UPDATE_HINT as a, DirectoryAccessor as b, CliResult as c, findContainersByLabel as d, inspectContainer as f, TextAccessor as g, JsonAccessor as h, copyPlan as i, placeholderPatternSource as j, mergePreservingPlaceholders as k, BaseResult as l, TableAccessor as m, runLiterateSpec as n, shouldUpdateSnapshots as o, removeContainers as p, ServeAdapter as r, ContainerAccessor as s, literateTitle as t, validateDatabaseOption as u, getCallerDir as v, formatResponseDiff as w, diffDirectories as x, FilesystemAccessor as y };
+export { placeholderPatternSource as A, formatResponseDiff as C, hasPlaceholders as D, formatTableDiff as E, structuralEquals as M, structuralSubset as N, mergePreservingPlaceholders as O, textEquals as P, formatDirectoryDiff as S, formatStdoutDiff as T, getCallerDir as _, shouldUpdateSnapshots as a, diffDirectories as b, BaseResult as c, inspectContainer as d, removeContainers as f, text as g, TextAccessor as h, UPDATE_HINT as i, renderExpected as j, mergeTextPreservingPlaceholders as k, validateDatabaseOption as l, JsonAccessor as m, specDescription as n, ContainerAccessor as o, TableAccessor as p, ServeAdapter as r, CliResult as s, runSpecDocument as t, findContainersByLabel as u, FilesystemAccessor as v, formatStartupReport as w, walkDirectory as x, DirectoryAccessor as y };