@jterrazz/test 15.2.0 → 16.0.0

package/dist/match.js

@@ -1,113 +1,654 @@
-import { basename, dirname, resolve } from "node:path";
-//#region src/specification/facets/_common/ground.ts
+import { LineCounter, Scalar, Scalar as Scalar$1, isMap, isScalar, isSeq, parseDocument, visit } from "yaml";
+//#region src/seams/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]*:/u;
 /**
-* The GROUND a row of specs stands on — the naming law of a spec tree.
+* The indentation step the file was written with, read from the shallowest
+* mapping key it carries. A rewrite must come back in the author's style — a
+* formatter that indents by four and a writer that indents by two would fight
+* over every updated document. Two is YAML's own default, and the fallback.
+*/
+function detectIndent(text) {
+	let smallest = 0;
+	for (const line of text.split("\n")) {
+		const indent = KEY_LINE.exec(line)?.groups?.indent;
+		if (indent !== void 0 && (smallest === 0 || indent.length < smallest)) smallest = indent.length;
+	}
+	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]/u.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
+		}),
+		indent: detectIndent(text),
+		lineAt: (offset) => lineCounter.linePos(offset).line,
+		text
+	};
+}
+/** The YAML parser's own errors, with their line — an empty list when it parsed. */
+function yamlSyntaxErrors(source) {
+	return source.document.errors.map((error) => ({
+		line: error.linePos?.[0]?.line ?? source.lineAt(error.pos[0]),
+		message: error.message
+	}));
+}
+/**
+* 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 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);
+	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/u.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 /^ */u.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 [start, end] = node.range;
+		if (start === void 0 || end === void 0) return;
+		const from = afterOwner(text, start);
+		found.push({
+			ownerIndent: indentOf(text, from === 0 ? 0 : from - 1),
+			range: [from, end],
+			text: text.slice(from, end),
+			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.
 *
-* 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.
+* 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.
 *
-* 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.
+* 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;
+		const source = sources[at];
+		if (source === void 0) continue;
+		taken.add(at);
+		splices.push({
+			range: target.range,
+			text: source.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.
 *
-* 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.
+* What the caller did not change comes back as it was written — see
+* {@link restoreUntouchedFlow} for the one construct the writer restyles.
 */
-/** 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 four ground directory names, in the order they read. */
-const GROUND_DIRS = [
-	GROUND_EXPECTED,
-	GROUND_FIXTURES,
-	GROUND_REQUESTS,
-	GROUND_SEEDS
-];
+function renderYamlSource(source) {
+	return restoreUntouchedFlow(source.document.toString({
+		indent: source.indent,
+		lineWidth: 0
+	}), source.text);
+}
 //#endregion
-//#region src/specification/facets/_common/fixtures.ts
+//#region src/model/literate/spec-document.ts
 /**
-* Fixture path resolution + copy semantics for the `cli` facet's `.fixture()`.
+* The `<case>.spec.yaml` document — one scenario, written as data.
 *
-* A fixture path is one of two shapes:
+* A spec document states the ground a session stands on (`fixture:`, `env:`,
+* `serve:`) and then the session itself (`runs:`), each run carrying its
+* command, its exit code, its streams and what it left on disk:
 *
-*  - `$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>`.
+*     description: removes a post and names what is gone
+*     fixture: $FIXTURES/posts-stub/
+*     env:
+*       - frozen
+*     runs:
+*       - command: posts rm post-recap --yes
+*         exit: 0
+*         stdout: |
+*           Removed post-recap.
 *
-* 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}).
+* This module owns the grammar and NOTHING else: it resolves no path, runs no
+* command, and knows no filesystem. It is read by the runner and by the lint
+* checker alike, so the document the lint accepts is exactly the document the
+* runner executes. The JSON Schema editors validate against is built from the
+* same constants, a few lines down — one vocabulary, three readers.
 */
+/** The extension that makes a file a spec document. */
+const SPEC_EXTENSION = ".spec.yaml";
 /**
-* 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.
+* The facets a document may describe. `cli` is the only one implemented; the
+* key exists so a second facet can arrive without a second grammar.
 */
-const KNOWN_FIXTURE_MARKERS = ["$FIXTURES"];
+const SPEC_KINDS = ["cli"];
 /**
-* 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.
+* Top-level keys, IN THE ORDER a document is written in: what the session
+* stands on first, the session last. The order is the canonical one the
+* `d4b-spec-key-order` lint pass enforces and rewrites.
 */
-function discoverSpecsRoot(startDir) {
-	let dir = startDir;
-	for (;;) {
-		if (basename(dir) === "specs") return dir;
-		const parent = dirname(dir);
-		if (parent === dir) break;
-		dir = parent;
+const DOCUMENT_KEYS = [
+	"kind",
+	"description",
+	"fixture",
+	"env",
+	"serve",
+	"runs"
+];
+/** The keys of one run, in the canonical order: what is given, then what came back. */
+const RUN_KEYS = [
+	"command",
+	"stdin",
+	"timeout",
+	"waitFor",
+	"exit",
+	"stdout",
+	"stderr",
+	"files"
+];
+/** The keys of a `files:` content assertion. */
+const FILE_CONTENT_KEYS = ["contains", "equals"];
+/** The bare states a `files:` entry may name instead of a content assertion. */
+const FILE_STATES = ["absent", "exists"];
+/** A refusal from the grammar, carrying the line it happened on. */
+var SpecSyntaxError = class extends Error {
+	line;
+	constructor(fileName, line, message) {
+		super(`${fileName}:${line}: ${message}`);
+		this.line = line;
+		this.name = "SpecSyntaxError";
+	}
+};
+function fail(context, node, message) {
+	throw new SpecSyntaxError(context.fileName, lineOf(context, node), message);
+}
+function lineOf(context, node) {
+	const range = node === void 0 || node === null ? void 0 : nodeRange(node);
+	return range === void 0 ? 1 : context.source.lineAt(range[0]);
+}
+function nodeRange(node) {
+	if ("range" in node && Array.isArray(node.range)) return node.range;
+	const { key } = node;
+	return key !== null && typeof key === "object" && "range" in key ? key.range ?? void 0 : void 0;
+}
+/** The line a scalar's CONTENT starts on — one past the `|` for a block scalar. */
+function contentLine(context, node) {
+	const start = lineOf(context, node);
+	return isScalar(node) && String(node.type ?? "").startsWith("BLOCK") ? start + 1 : start;
+}
+function requireMap(context, node, what) {
+	if (!isMap(node)) fail(context, node ?? void 0, `${what} must be a mapping of keys to values`);
+	return node;
+}
+/** The pairs of a mapping, refusing any key outside the closed set. */
+function closedPairs(context, map, allowed, what) {
+	const pairs = [];
+	for (const pair of map.items) {
+		const key = scalarString(pair.key);
+		if (key === null) fail(context, pair, `${what}: a key must be a plain word`);
+		if (!allowed.includes(key)) fail(context, pair, `unknown key "${key}:" in ${what} — known keys: ${allowed.join(", ")}`);
+		if (pairs.some((seen) => scalarString(seen.key) === key)) fail(context, pair, `"${key}:" is declared twice in ${what}`);
+		pairs.push(pair);
+	}
+	return pairs;
+}
+function scalarString(node) {
+	return isScalar(node) && typeof node.value === "string" ? node.value : null;
+}
+function requireString(context, node, what) {
+	const value = scalarString(node);
+	if (value === null) fail(context, node, `${what} must be text`);
+	return value;
+}
+function requireInteger(context, node, what) {
+	if (!isScalar(node) || typeof node.value !== "number" || !Number.isInteger(node.value)) fail(context, node, `${what} must be a literal integer`);
+	return node.value;
+}
+/** A `string | list of strings` field, flattened to its entries with their lines. */
+function stringList(context, node, what) {
+	if (isSeq(node)) return node.items.map((item) => ({
+		line: lineOf(context, item),
+		value: requireString(context, item, `each entry of ${what}`)
+	}));
+	return [{
+		line: lineOf(context, node),
+		value: requireString(context, node, what)
+	}];
+}
+function readStream(context, node, what) {
+	return {
+		line: contentLine(context, node),
+		text: requireString(context, node, what)
+	};
+}
+function readEnv(context, node) {
+	return stringList(context, node, "env:").map(({ line, value }) => {
+		const separator = value.indexOf("=");
+		if (separator === -1) return {
+			kind: "set",
+			line,
+			name: value
+		};
+		if (separator === 0) throw new SpecSyntaxError(context.fileName, line, `env: "${value}" has no variable name before the "="`);
+		return {
+			key: value.slice(0, separator),
+			kind: "pair",
+			line,
+			value: value.slice(separator + 1)
+		};
+	});
+}
+function readServeEntry(context, node) {
+	const name = scalarString(node);
+	if (name !== null) return {
+		env: {},
+		line: lineOf(context, node),
+		name
+	};
+	const map = requireMap(context, node, "a serve: entry");
+	if (map.items.length !== 1) fail(context, node, "a serve: entry names ONE server: `- <name>: { KEY: value }`");
+	const pair = map.items[0];
+	const serverName = scalarString(pair.key);
+	if (serverName === null) fail(context, pair, "a serve: entry must name its server with a plain word");
+	const env = {};
+	const envMap = requireMap(context, pair.value, `serve: ${serverName}`);
+	for (const entry of envMap.items) {
+		const key = scalarString(entry.key);
+		if (key === null) fail(context, entry, `serve: ${serverName} — a variable name must be a plain word`);
+		env[key] = requireString(context, entry.value, `serve: ${serverName}.${key}`);
 	}
-	throw new Error(`.fixture(): the $FIXTURES marker resolves to <specs-root>/${GROUND_FIXTURES}, but no directory named "specs" was found walking up from ${startDir}. Move the specification under a specs/ directory, or use a feature-local ${GROUND_FIXTURES}/ path (no $FIXTURES marker).`);
+	return {
+		env,
+		line: lineOf(context, pair),
+		name: serverName
+	};
+}
+function readServe(context, node) {
+	return (isSeq(node) ? node.items : [node]).map((item) => readServeEntry(context, item));
+}
+function readFiles(context, node) {
+	return requireMap(context, node, "files:").items.map((pair) => {
+		const path = scalarString(pair.key);
+		if (path === null) fail(context, pair, "files: each key is a path relative to the working directory");
+		const line = lineOf(context, pair);
+		const state = scalarString(pair.value);
+		if (state !== null) {
+			if (!FILE_STATES.includes(state)) fail(context, pair, `files: "${path}: ${state}" is not a state — write ${FILE_STATES.join(" or ")}, or a { ${FILE_CONTENT_KEYS.join(", ")} } assertion`);
+			return {
+				kind: state,
+				line,
+				path
+			};
+		}
+		const pairs = closedPairs(context, requireMap(context, pair.value, `files: ${path}`), FILE_CONTENT_KEYS, `files: ${path}`);
+		if (pairs.length === 0) fail(context, pair, `files: ${path} asserts nothing — give it contains: or equals:`);
+		const contains = [];
+		let equals = null;
+		for (const entry of pairs) {
+			if (scalarString(entry.key) === "contains") {
+				if (isSeq(entry.value)) for (const item of entry.value.items) contains.push(readStream(context, item, `files: ${path}.contains`));
+				else contains.push(readStream(context, entry.value, `files: ${path}.contains`));
+				continue;
+			}
+			equals = readStream(context, entry.value, `files: ${path}.equals`);
+		}
+		return {
+			contains,
+			equals,
+			kind: "content",
+			line,
+			path
+		};
+	});
+}
+function readRun(context, node, isLast) {
+	const pairs = closedPairs(context, requireMap(context, node, "each entry of runs:"), RUN_KEYS, "a run");
+	const found = /* @__PURE__ */ new Map();
+	for (const pair of pairs) found.set(scalarString(pair.key), pair);
+	for (const key of ["command", "exit"]) if (!found.has(key)) fail(context, node, `a run is missing "${key}:" — command and exit are mandatory`);
+	const commandPair = found.get("command");
+	const command = requireString(context, commandPair.value, "command:");
+	const waitForPair = found.get("waitFor");
+	if (waitForPair !== void 0 && !isLast) fail(context, waitForPair, "waitFor: is only allowed on the LAST run — a long-running command ends the session");
+	if (waitForPair !== void 0 && found.has("stdin")) fail(context, waitForPair, "waitFor: and stdin: cannot share a run — the pattern is watched on a process nobody closed the input of");
+	const stdout = found.get("stdout");
+	const stderr = found.get("stderr");
+	const stdin = found.get("stdin");
+	const timeout = found.get("timeout");
+	const files = found.get("files");
+	return {
+		command,
+		commandLine: lineOf(context, commandPair),
+		exitCode: requireInteger(context, found.get("exit").value, "exit:"),
+		files: files === void 0 ? [] : readFiles(context, files.value),
+		stderr: stderr === void 0 ? null : readStream(context, stderr.value, "stderr:"),
+		stdin: stdin === void 0 ? null : requireString(context, stdin.value, "stdin:"),
+		stdout: stdout === void 0 ? null : readStream(context, stdout.value, "stdout:"),
+		timeout: timeout === void 0 ? null : requireInteger(context, timeout.value, "timeout:"),
+		waitFor: waitForPair === void 0 ? null : requireString(context, waitForPair.value, "waitFor:")
+	};
+}
+/**
+* Read a `<case>.spec.yaml`. `fileName` is used verbatim in refusals, so pass
+* the path a reader would open. The YAML source comes back beside the document:
+* update mode rewrites THAT, never a re-serialisation of this structure.
+*/
+function readSpecFile(content, fileName) {
+	const source = parseYamlSource(content);
+	const [syntax] = yamlSyntaxErrors(source);
+	if (syntax !== void 0) throw new SpecSyntaxError(fileName, syntax.line, syntax.message);
+	const context = {
+		fileName,
+		source
+	};
+	const root = source.document.contents;
+	if (root === null || isScalar(root) && root.value === null) throw new SpecSyntaxError(fileName, 1, "the document is empty");
+	const map = requireMap(context, root, "a spec document");
+	const pairs = closedPairs(context, map, DOCUMENT_KEYS, "a spec document");
+	const found = /* @__PURE__ */ new Map();
+	for (const pair of pairs) found.set(scalarString(pair.key), pair);
+	for (const key of ["description", "runs"]) if (!found.has(key)) fail(context, map, `missing "${key}:" — description and runs are mandatory`);
+	const kindPair = found.get("kind");
+	const kind = kindPair === void 0 ? "cli" : requireString(context, kindPair.value, "kind:");
+	if (!SPEC_KINDS.includes(kind)) fail(context, kindPair, `kind: "${kind}" is not a facet — known kinds: ${SPEC_KINDS.join(", ")}`);
+	const runsNode = found.get("runs");
+	if (!isSeq(runsNode.value) || runsNode.value.items.length === 0) fail(context, runsNode, "runs: is a list of at least one run");
+	const runItems = runsNode.value.items;
+	const fixturePair = found.get("fixture");
+	const envPair = found.get("env");
+	const servePair = found.get("serve");
+	return {
+		document: {
+			description: requireString(context, found.get("description").value, "description:"),
+			descriptionLine: lineOf(context, found.get("description")),
+			env: envPair === void 0 ? [] : readEnv(context, envPair.value),
+			fixtures: fixturePair === void 0 ? [] : stringList(context, fixturePair.value, "fixture:").map(({ line, value }) => ({
+				line,
+				path: value
+			})),
+			kind,
+			runs: runItems.map((item, index) => readRun(context, item, index === runItems.length - 1)),
+			serve: servePair === void 0 ? [] : readServe(context, servePair.value)
+		},
+		source
+	};
 }
 /**
-* 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.
+* 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
+* a command is prose, so neither appears here.
 */
-function resolveFixtureSource(path, testDir) {
-	const clean = path.replace(/\/+$/u, "");
-	if (clean === "$FIXTURES" || path.startsWith("$FIXTURES/")) {
-		const rest = clean.slice(9).replace(/^\/+/u, "");
-		return resolve(discoverSpecsRoot(testDir), GROUND_FIXTURES, rest);
+function assertedStreams(document) {
+	const streams = [];
+	for (const run of document.runs) {
+		if (run.stdout !== null) streams.push(run.stdout);
+		if (run.stderr !== null) streams.push(run.stderr);
+		for (const assertion of run.files) {
+			if (assertion.kind !== "content") continue;
+			streams.push(...assertion.contains);
+			if (assertion.equals !== null) streams.push(assertion.equals);
+		}
+	}
+	return streams;
+}
+/** Read a `<case>.spec.yaml` for its content alone — the shape passes and C9's scan. */
+function parseSpecDocument(content, fileName) {
+	return readSpecFile(content, fileName).document;
+}
+/** Insert (or replace) a key at its canonical position in a mapping. */
+function setOrdered(map, key, value, order) {
+	const items = map.items;
+	if (items.findIndex((pair) => scalarString(pair.key) === key) !== -1) {
+		map.set(key, value);
+		return;
 	}
-	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>/${GROUND_FIXTURES}/).`);
+	const rank = order.indexOf(key);
+	const at = items.findIndex((pair) => {
+		const seen = scalarString(pair.key);
+		return seen !== null && order.indexOf(seen) > rank;
+	});
+	map.set(key, value);
+	if (at !== -1) {
+		const added = map.items.pop();
+		map.items.splice(at, 0, added);
 	}
-	return resolve(testDir, GROUND_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>`.
+* Rewrite the runs of a spec file from what the commands actually did — exit
+* code and both streams, and nothing else. `files:`, the commands and the
+* header come back byte-identical, comments and key order included, because
+* the YAML DOCUMENT is edited rather than re-emitted from the parsed shape.
 *
-* Chained `.fixture()` calls layer in order: a later fixture overwrites files
-* written by an earlier one.
+* An empty stream removes its key: absence already asserts emptiness, so a
+* rewritten document says the same thing in fewer words and still passes.
 */
-function copyPlan(path, testDir, workDir) {
-	const src = resolveFixtureSource(path, testDir);
-	return {
-		dest: /\/+$/u.test(path) ? workDir : resolve(workDir, basename(src)),
-		src
-	};
+function updateSpecFile(file, updates) {
+	const runs = file.source.document.contents.get("runs", true);
+	if (!isSeq(runs)) return renderYamlSource(file.source);
+	for (const [index, update] of updates.entries()) {
+		const run = runs.items[index];
+		if (!isMap(run)) continue;
+		setOrdered(run, "exit", update.exitCode, RUN_KEYS);
+		for (const [key, text] of [["stdout", update.stdout], ["stderr", update.stderr]]) {
+			if (text.length === 0) {
+				run.delete(key);
+				continue;
+			}
+			setOrdered(run, key, blockScalar(text), RUN_KEYS);
+		}
+	}
+	return renderYamlSource(file.source);
+}
+const STRING_OR_LIST = { oneOf: [{ type: "string" }, {
+	items: { type: "string" },
+	minItems: 1,
+	type: "array"
+}] };
+const SPEC_SCHEMA = {
+	$defs: {
+		fileAssertion: { oneOf: [{
+			enum: FILE_STATES,
+			type: "string"
+		}, {
+			additionalProperties: false,
+			minProperties: 1,
+			properties: {
+				contains: STRING_OR_LIST,
+				equals: { type: "string" }
+			},
+			type: "object"
+		}] },
+		run: {
+			additionalProperties: false,
+			properties: {
+				command: {
+					description: "The argv line, run through the shell.",
+					type: "string"
+				},
+				exit: {
+					description: "The exit code the command must return.",
+					type: "integer"
+				},
+				files: {
+					additionalProperties: { $ref: "#/$defs/fileAssertion" },
+					description: "On-disk assertions, keyed by a path under the working directory.",
+					type: "object"
+				},
+				stderr: {
+					description: "Expected stderr, byte-exact. Absent asserts an empty stream.",
+					type: "string"
+				},
+				stdin: {
+					description: "Written to the child, then closed.",
+					type: "string"
+				},
+				stdout: {
+					description: "Expected stdout, byte-exact. Absent asserts an empty stream.",
+					type: "string"
+				},
+				timeout: {
+					description: "Milliseconds before the run is killed.",
+					type: "integer"
+				},
+				waitFor: {
+					description: "Resolve when this text appears. Only on the last run.",
+					type: "string"
+				}
+			},
+			required: ["command", "exit"],
+			type: "object"
+		},
+		serveEntry: { oneOf: [{ type: "string" }, {
+			additionalProperties: {
+				additionalProperties: { type: "string" },
+				type: "object"
+			},
+			maxProperties: 1,
+			minProperties: 1,
+			type: "object"
+		}] }
+	},
+	$id: "https://jterrazz.com/schema/jterrazz-test/spec.schema.json",
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	additionalProperties: false,
+	description: "One scenario of the @jterrazz/test literate format: the ground a session stands on, then the session itself.",
+	properties: {
+		description: {
+			description: "The vitest test title — one lowercase line, no trailing period.",
+			type: "string"
+		},
+		env: {
+			...STRING_OR_LIST,
+			description: "A bare word names an env set registered in code; KEY=value is inline. $WORKDIR expands."
+		},
+		fixture: {
+			...STRING_OR_LIST,
+			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",
+			description: "The facet this document describes.",
+			enum: [...SPEC_KINDS],
+			type: "string"
+		},
+		runs: {
+			description: "The session: one or more runs, sequential, sharing one working directory.",
+			items: { $ref: "#/$defs/run" },
+			minItems: 1,
+			type: "array"
+		},
+		serve: {
+			description: "Servers registered in code, started once per file.",
+			oneOf: [{ type: "string" }, {
+				items: { $ref: "#/$defs/serveEntry" },
+				minItems: 1,
+				type: "array"
+			}]
+		}
+	},
+	required: ["description", "runs"],
+	title: "@jterrazz/test spec document",
+	type: "object"
+};
+/** {@link SPEC_SCHEMA} in the exact form `schema/spec.schema.json` is committed in. */
+function renderSchema() {
+	return `${JSON.stringify(SPEC_SCHEMA, null, 4)}\n`;
 }
 //#endregion
-//#region src/specification/matching/match.ts
+//#region src/model/matching/match.ts
 /** Every kind usable as a `{{token}}` in fixture files (all but ref/regex/includes). */
 const TOKEN_KINDS = [
 	"any",
@@ -260,4 +801,4 @@ var CaptureScope = class {
 	}
 };
 //#endregion
-export { copyPlan as a, GROUND_EXPECTED as c, GROUND_SEEDS as d, match as i, GROUND_FIXTURES as l, Matcher as n, resolveFixtureSource as o, TOKEN_KINDS as r, GROUND_DIRS as s, CaptureScope as t, GROUND_REQUESTS as u };
+export { isSeq as _, DOCUMENT_KEYS as a, SpecSyntaxError as c, readSpecFile as d, renderSchema as f, isScalar as g, isMap as h, match as i, assertedStreams as l, Scalar$1 as m, Matcher as n, RUN_KEYS as o, updateSpecFile as p, TOKEN_KINDS as r, SPEC_EXTENSION as s, CaptureScope as t, parseSpecDocument as u, renderYamlSource as v };