@jterrazz/test 16.1.1 → 17.0.0

package/dist/shared-spec-document.js

@@ -0,0 +1,365 @@
+import { a as isPair, c as nodeItems, f as yamlSyntaxErrors, i as isNode, l as nodePairs, o as isScalar, r as isMap, s as isSeq, u as parseYamlSource } from "./shared-yaml-document.js";
+import { GROUND_FIXTURES, isGroundFolder } from "@jterrazz/typescript/rules";
+//#region lint/kit/project/relative-path.ts
+function isRelativePath(value) {
+	return value.startsWith("./") || value.startsWith("../");
+}
+//#endregion
+//#region lint/kit/project/dedent.ts
+function indentOf(line) {
+	return /^[\t ]*/u.exec(line)?.[0].length ?? 0;
+}
+/** A text opening on a line break loses that break, the closing line's whitespace and the shared indentation. */
+function dedent(text) {
+	if (!text.startsWith("\n")) return text;
+	const lines = text.slice(1).split("\n");
+	if (lines.at(-1)?.trim() === "") lines[lines.length - 1] = "";
+	const indents = lines.filter((line) => line.trim() !== "").map((line) => indentOf(line));
+	const common = indents.length === 0 ? 0 : Math.min(...indents);
+	return lines.map((line) => line.slice(common)).join("\n");
+}
+//#endregion
+//#region lint/kit/project/spec-grammar.ts
+const SPEC_EXTENSION = ".spec.yaml";
+const DOCUMENT_KEYS = [
+	"description",
+	"fixture",
+	"env",
+	"serve",
+	"runs"
+];
+const RUN_KEYS = [
+	"command",
+	"stdin",
+	"timeout",
+	"waitFor",
+	"exit",
+	"stdout",
+	"stderr",
+	"files"
+];
+const FILE_CONTENT_KEYS = ["contains", "equals"];
+const FILE_STATES = ["absent", "exists"];
+const PRESENCE = {
+	document: [{
+		keys: ["description"],
+		law: "each",
+		refusal: () => "missing \"description:\": every document is one test, and this is its title"
+	}, {
+		keys: ["runs"],
+		law: "each",
+		refusal: () => "missing \"runs:\": description and runs are mandatory"
+	}],
+	files: [{
+		keys: FILE_CONTENT_KEYS,
+		law: "some",
+		refusal: (path) => `files: ${path} asserts nothing: give it contains: or equals:`
+	}],
+	run: [{
+		keys: ["command", "exit"],
+		law: "each",
+		refusal: (_subject, key) => `a run is missing "${key}:": command and exit are mandatory`
+	}, {
+		keys: ["waitFor"],
+		law: "apart",
+		refusal: () => "waitFor: and stdin: cannot share a run: the pattern is watched on a process nobody closed the input of",
+		with: "stdin"
+	}]
+};
+var SpecSyntaxError = class extends Error {
+	line;
+	reason;
+	constructor(fileName, line, message) {
+		super(`${fileName}:${line}: ${message}`);
+		this.line = line;
+		this.reason = message;
+		this.name = "SpecSyntaxError";
+	}
+};
+//#endregion
+//#region lint/kit/project/spec-node.ts
+function fail(context, node, message) {
+	throw new SpecSyntaxError(context.fileName, lineOf(context, node), message);
+}
+/** A pair sits on its key's line; a node the parser never placed, on the first. */
+function lineOf(context, node) {
+	const placed = isPair(node) ? node.key : node;
+	return isNode(placed) && placed.range ? context.source.lineAt(placed.range[0]) : 1;
+}
+function contentLine(context, node) {
+	const start = lineOf(context, node);
+	return isScalar(node) && (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;
+}
+function closedPairs(context, map, allowed, what) {
+	const pairs = [];
+	for (const pair of nodePairs(map)) {
+		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(", ")}`);
+		pairs.push(pair);
+	}
+	return pairs;
+}
+function keyed(pairs) {
+	return new Map(pairs.map((pair) => [scalarString(pair.key) ?? "", pair]));
+}
+function holdPresence(context, found, { line, shape, subject = "" }) {
+	const at = (message, where = line) => {
+		throw new SpecSyntaxError(context.fileName, where, message);
+	};
+	for (const law of PRESENCE[shape]) if (law.law === "each") {
+		const missing = law.keys.find((key) => !found.has(key));
+		if (missing !== void 0) at(law.refusal(subject, missing));
+	} else if (law.law === "some") {
+		if (!law.keys.some((key) => found.has(key))) at(law.refusal(subject));
+	} else if (found.has(law.with)) {
+		const beside = law.keys.find((key) => found.has(key));
+		if (beside !== void 0) at(law.refusal(subject, beside), lineOf(context, found.get(beside)));
+	}
+}
+function held(found, key) {
+	const pair = found.get(key);
+	if (pair === void 0) throw new Error(`"${key}:" is required by a presence law and was not found`);
+	return pair;
+}
+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) {
+	const value = isScalar(node) ? node.value : void 0;
+	if (!Number.isInteger(value)) fail(context, node, `${what} must be a literal integer`);
+	return Number(value);
+}
+function stringList(context, node, what) {
+	if (isSeq(node)) return nodeItems(node).map((item) => ({
+		line: lineOf(context, item),
+		value: requireString(context, item, `each entry of ${what}`)
+	}));
+	return [{
+		line: lineOf(context, node),
+		value: requireString(context, node, what)
+	}];
+}
+//#endregion
+//#region lint/kit/project/spec-fields.ts
+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] = nodePairs(map);
+	if (pair === void 0) fail(context, node, "a serve: entry names ONE server: `- <name>: { KEY: value }`");
+	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 nodePairs(envMap)) {
+		const key = scalarString(entry.key);
+		if (key === null) fail(context, entry, `serve: ${serverName} is no variable name, which must be a plain word`);
+		env[key] = requireString(context, entry.value, `serve: ${serverName}.${key}`);
+	}
+	return {
+		env,
+		line: lineOf(context, pair),
+		name: serverName
+	};
+}
+function readServe(context, node) {
+	return (isSeq(node) ? nodeItems(node) : [node]).map((item) => readServeEntry(context, item));
+}
+function readFiles(context, node) {
+	const map = requireMap(context, node, "files:");
+	return nodePairs(map).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) {
+			const kind = FILE_STATES.find((known) => known === state);
+			if (kind === void 0) fail(context, pair, `files: "${path}: ${state}" is not a state: write ${FILE_STATES.join(" or ")}, or a { ${FILE_CONTENT_KEYS.join(", ")} } assertion`);
+			return {
+				kind,
+				line,
+				path
+			};
+		}
+		const pairs = closedPairs(context, requireMap(context, pair.value, `files: ${path}`), FILE_CONTENT_KEYS, `files: ${path}`);
+		holdPresence(context, keyed(pairs), {
+			line,
+			shape: "files",
+			subject: path
+		});
+		const contains = [];
+		let equals = null;
+		for (const entry of pairs) {
+			if (scalarString(entry.key) === "contains") {
+				if (isSeq(entry.value)) for (const item of nodeItems(entry.value)) 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 found = keyed(closedPairs(context, requireMap(context, node, "each entry of runs:"), RUN_KEYS, "a run"));
+	holdPresence(context, found, {
+		line: lineOf(context, node),
+		shape: "run"
+	});
+	const commandPair = found.get("command");
+	const exitPair = found.get("exit");
+	if (commandPair === void 0 || exitPair === void 0) fail(context, node, "a run states its command: and its exit:");
+	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, since a long-running command ends the session");
+	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, exitPair.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:")
+	};
+}
+function groundOf(path) {
+	return path.split("/").find((segment) => isGroundFolder(segment));
+}
+/** A fixture is laid from `__fixtures__/`, a file or a whole directory. */
+function readFixtures(context, node) {
+	return stringList(context, node, "fixture:").map(({ line, value }) => {
+		if (!isRelativePath(value)) throw new SpecSyntaxError(context.fileName, line, `fixture: "${value}" is not a relative path: name it from this document (./... or ../...)`);
+		const found = groundOf(value);
+		if (found !== GROUND_FIXTURES) {
+			const where = `./${GROUND_FIXTURES}/ beside the document, or in the ${GROUND_FIXTURES}/ of the lowest folder the leaves share (specs/${GROUND_FIXTURES}/ across specifications)`;
+			throw new SpecSyntaxError(context.fileName, line, `fixture: reads ${GROUND_FIXTURES}/, and "${value}" names ${found === void 0 ? `no ${GROUND_FIXTURES}/ folder` : `${found}/`}, so put the file in ${where} (verb-reads-its-ground-folder)`);
+		}
+		return {
+			line,
+			path: value
+		};
+	});
+}
+//#endregion
+//#region lint/kit/project/spec-document.ts
+/** The grammar alone: no path resolution, no command, no filesystem. The runner, the lint checker and the JSON Schema read the same constants. */
+/** `fileName` is used verbatim in refusals. Update mode rewrites the returned YAML source, never a re-serialisation. */
+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 found = keyed(closedPairs(context, map, DOCUMENT_KEYS, "a spec document"));
+	holdPresence(context, found, {
+		line: lineOf(context, map),
+		shape: "document"
+	});
+	return {
+		document: {
+			description: requireString(context, held(found, "description").value, "description:"),
+			descriptionLine: lineOf(context, found.get("description")),
+			...readCliFields(context, found)
+		},
+		source
+	};
+}
+function readCliFields(context, found) {
+	const runsNode = held(found, "runs");
+	if (!isSeq(runsNode.value) || runsNode.value.items.length === 0) fail(context, runsNode, "runs: is a list of at least one run");
+	const runItems = nodeItems(runsNode.value);
+	const fixturePair = found.get("fixture");
+	const envPair = found.get("env");
+	const servePair = found.get("serve");
+	return {
+		env: envPair === void 0 ? [] : readEnv(context, envPair.value),
+		fixtures: fixturePair === void 0 ? [] : readFixtures(context, fixturePair.value),
+		runs: runItems.map((item, index) => readRun(context, item, index === runItems.length - 1)),
+		serve: servePair === void 0 ? [] : readServe(context, servePair.value)
+	};
+}
+/** `stdin:` is an input and a description or command is prose: none appears here. */
+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;
+}
+function documentPaths(document) {
+	return document.fixtures.map(({ line, path }) => ({
+		key: "fixture",
+		kind: path.endsWith("/") ? "directory" : "file",
+		line,
+		path
+	}));
+}
+function parseSpecDocument(content, fileName) {
+	return readSpecFile(content, fileName).document;
+}
+//#endregion
+export { scalarString as a, SPEC_EXTENSION as c, isRelativePath as d, readSpecFile as i, SpecSyntaxError as l, documentPaths as n, DOCUMENT_KEYS as o, parseSpecDocument as r, RUN_KEYS as s, assertedStreams as t, dedent as u };
+
+//# sourceMappingURL=shared-spec-document.js.map

package/dist/shared-specifications.js

@@ -0,0 +1,26 @@
+import { basename } from "node:path";
+//#region lint/kit/project/specifications.ts
+const SPECIFICATIONS = /* @__PURE__ */ new Set([
+	"api",
+	"cli",
+	"integration",
+	"job",
+	"lint",
+	"mobile",
+	"website"
+]);
+const IMPORT_SOURCE = /(?:\bfrom|\bimport|\brequire)\s*\(?\s*['"](?<source>[^'"]+)['"]/gu;
+const CONSTRUCTS = /\bspecification\.[a-z]+\s*\(/u;
+/** Constructing the runner in the file counts: a refusal spec proves the constructor that must fail to start, and has no specification module to import. */
+function reachesRunner(text) {
+	for (const match of text.matchAll(IMPORT_SOURCE)) {
+		const { source = "" } = match.groups ?? {};
+		if (source === "@jterrazz/test" || source.startsWith("@jterrazz/test/")) return true;
+		if (basename(source).includes(".specification")) return true;
+	}
+	return CONSTRUCTS.test(text);
+}
+//#endregion
+export { reachesRunner as n, SPECIFICATIONS as t };
+
+//# sourceMappingURL=shared-specifications.js.map

package/dist/shared-stream-body.js

@@ -0,0 +1,130 @@
+import { n as refusal } from "./shared-refusal.js";
+import { c as urlMatches, o as describeRoute, s as routePatternOf } from "./shared-exchange.js";
+import { t as pause } from "./shared-pause.js";
+//#region src/stubs/matching/stub-queue.ts
+function stubMatches(stub, request) {
+	const { absentHeaders, match, method, url } = stub.request;
+	if (method !== "*" && method.toUpperCase() !== request.method.toUpperCase()) return false;
+	if (!urlMatches(url, request.url)) return false;
+	if ((absentHeaders ?? []).some((name) => request.headers[name.toLowerCase()] !== void 0)) return false;
+	return match ? match(request) : true;
+}
+function isNever({ required, times }) {
+	return required === true && times === 0;
+}
+function stateOf({ stub, served }) {
+	const { times } = stub;
+	if (isNever(stub)) return served === 0 ? " (never)" : ` (never, reached ${served} time(s))`;
+	if (served >= (times ?? Number.POSITIVE_INFINITY)) return ` (exhausted after ${times})`;
+	return served === 0 ? "" : ` (served ${served} time(s))`;
+}
+/** The first unexhausted stub in declaration order answers; `times: n` is spent after n serves. */
+var StubQueue = class {
+	entries;
+	constructor(stubs) {
+		this.entries = stubs.map((stub) => ({
+			reached: [],
+			stub,
+			served: 0
+		}));
+	}
+	/** Deduped by pattern: two stubs on one URL share one handler and one queue. */
+	get routes() {
+		const routes = /* @__PURE__ */ new Map();
+		for (const { stub } of this.entries) {
+			const url = routePatternOf(stub.request.url);
+			const key = String(url);
+			const route = routes.get(key) ?? {
+				methods: [],
+				url
+			};
+			if (!route.methods.includes(stub.request.method)) route.methods.push(stub.request.method);
+			routes.set(key, route);
+		}
+		return [...routes.values()];
+	}
+	declaredRoutes() {
+		return this.entries.map(({ stub }) => describeRoute(stub.request));
+	}
+	/** `null` when nothing unexhausted matches: the strict-violation signal. */
+	take(request) {
+		for (const entry of this.entries) {
+			if (entry.served >= (entry.stub.times ?? Number.POSITIVE_INFINITY) && !isNever(entry.stub) || !stubMatches(entry.stub, request)) continue;
+			entry.served += 1;
+			entry.reached.push(`${request.method} ${request.url}`);
+			return entry.stub;
+		}
+		return null;
+	}
+	verdict(unmatched = null) {
+		const errors = [
+			this.neverError(),
+			unmatched,
+			this.unmetError()
+		].filter((error) => error !== null);
+		if (errors.length <= 1) return errors[0] ?? null;
+		const reports = errors.map(({ message }) => message).join("\n\n");
+		return new AggregateError(errors, refusal({
+			fix: "correct each outcome in turn, by its own fix",
+			found: `${errors.length} outcomes of one action, each with its own refusal:\n\n${reports}`,
+			read: "docs/reference/stubs.md#strict-by-construction",
+			why: "A reached never stub, an unmatched request and an unmet required stub are independent facts about one action, so all are reported at once."
+		}));
+	}
+	neverError() {
+		const reached = this.entries.filter(({ stub, served }) => isNever(stub) && served > 0);
+		if (reached.length === 0) return null;
+		const lines = reached.map(({ reached: calls, stub }) => `  - ${describeRoute(stub.request)}: reached by ${calls.join(", ")}`);
+		return new Error(refusal({
+			fix: "take the call out of the path under test or, if the call is now intended, replace the never stub with one that answers it",
+			found: `a route the chain declared never requested was reached:\n${lines.join("\n")}`,
+			read: "docs/reference/stubs.md#never-a-call-that-must-not-happen",
+			why: "A never stub states the subject must not reach its route within the chain's terminal action, or the `intercept()` scope, it is declared for."
+		}));
+	}
+	unmetError() {
+		const unmet = [];
+		for (const { stub, served } of this.entries) {
+			if (stub.required !== true || isNever(stub)) continue;
+			const { times } = stub;
+			if (times === void 0) {
+				if (served === 0) unmet.push(`  - ${describeRoute(stub.request)}: declared and required but never requested`);
+			} else if (served !== times) unmet.push(`  - ${describeRoute(stub.request)}: declared required with times: ${times} but was requested ${served} time(s)`);
+		}
+		if (unmet.length === 0) return null;
+		return new Error(refusal({
+			fix: "the code no longer makes the call, or the stub no longer describes it: correct the one that drifted",
+			found: `required stub(s) never satisfied during the chain:\n${unmet.join("\n")}`,
+			read: "docs/reference/stubs.md#required-is-verified-per-terminal-action",
+			why: "A required stub states the call MUST happen, within the terminal action it is declared for."
+		}));
+	}
+	unmatchedError(method, url) {
+		const declared = this.entries.length === 0 ? "  (no stubs declared)" : this.entries.map((entry) => `  - ${describeRoute(entry.stub.request)}${stateOf(entry)}`).join("\n");
+		return new Error(refusal("network-strict-after-first-stub", {
+			fix: `declare a stub for ${method} ${url}, or raise the \`times\` of the one it exhausted`,
+			found: `an unmatched outgoing request, ${method} ${url}; declared:\n${declared}`
+		}));
+	}
+};
+//#endregion
+//#region src/stubs/delivery/stream-body.ts
+/** One serialisation for all three deliveries (msw server, msw worker, `node:http` stub). */
+function toReadableStream(body) {
+	const encoder = new TextEncoder();
+	let index = 0;
+	return new ReadableStream({ async pull(controller) {
+		const chunk = body.chunks[index];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		if (body.delayBetweenChunks > 0 && index > 0) await pause(body.delayBetweenChunks);
+		index += 1;
+		controller.enqueue(encoder.encode(chunk));
+	} });
+}
+//#endregion
+export { StubQueue as n, toReadableStream as t };
+
+//# sourceMappingURL=shared-stream-body.js.map