@jterrazz/test 10.1.0 → 11.0.0

package/dist/queue.js

@@ -0,0 +1,555 @@
+import { n as Matcher, r as TOKEN_KINDS, t as CaptureScope } from "./match.js";
+//#region src/core/matching/structural.ts
+/**
+* Structural comparison engine shared by every fixture matcher.
+*
+* Handles three kinds of "expected" values:
+* - plain JSON values → strict deep equality
+* - {@link Matcher} instances (code-side `match.*`)
+* - strings containing `{{placeholder}}` forms (file-side fixtures)
+*
+* One unified `{{token}}` grammar (CONVENTIONS D4) — the same vocabulary
+* works in `expected/*.http` (body and headers), `expected/*.json`, and
+* text snapshots (`expected/*.txt`).
+*
+* Ref captures (`match.ref(name)` / `{{type#name}}`) are recorded in the
+* {@link CaptureScope} supplied by the caller.
+*/
+const UUID_SOURCE = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+const ULID_SOURCE = "[0-9A-HJKMNP-TV-Z]{26}";
+const ISO8601_SOURCE = String.raw`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})`;
+const DATE_SOURCE = String.raw`\d{4}-\d{2}-\d{2}`;
+const TIME_SOURCE = String.raw`\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?`;
+const DURATION_SOURCE = String.raw`\d+(?:\.\d+)?(?:ms|s|m|h)`;
+const NUMBER_SOURCE = String.raw`-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?`;
+const INT_SOURCE = String.raw`-?\d+`;
+const FLOAT_SOURCE = String.raw`-?\d+\.\d+`;
+const SEMVER_SOURCE = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?`;
+const SHA_SOURCE = "[0-9a-f]{7,64}";
+const HEX_SOURCE = "[0-9a-fA-F]+";
+const BASE64_SOURCE = "[A-Za-z0-9+/]+={0,2}";
+const PORT_SOURCE = String.raw`(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|\d{1,4})`;
+const IP_OCTET = String.raw`(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)`;
+const IP_SOURCE = String.raw`(?:${IP_OCTET}\.){3}${IP_OCTET}`;
+const URL_SOURCE = String.raw`https?:\/\/[^\s"'<>]+`;
+const EMBEDDED_SOURCES = {
+	base64: BASE64_SOURCE,
+	date: DATE_SOURCE,
+	duration: DURATION_SOURCE,
+	email: String.raw`[^\s@"'<>]+@[^\s@"'<>]+\.[^\s@"'<>]+`,
+	float: FLOAT_SOURCE,
+	hex: HEX_SOURCE,
+	int: INT_SOURCE,
+	ip: IP_SOURCE,
+	iso8601: ISO8601_SOURCE,
+	number: NUMBER_SOURCE,
+	path: String.raw`\.{0,2}\/[^\s"'<>]*`,
+	port: PORT_SOURCE,
+	semver: SEMVER_SOURCE,
+	sha: SHA_SOURCE,
+	time: TIME_SOURCE,
+	ulid: ULID_SOURCE,
+	url: URL_SOURCE,
+	uuid: UUID_SOURCE
+};
+const wholeRe = (source) => new RegExp(`^(?:${source})$`);
+const WHOLE_RES = Object.fromEntries(Object.entries(EMBEDDED_SOURCES).map(([kind, source]) => [kind, wholeRe(source)]));
+const PLACEHOLDER_RE = new RegExp(String.raw`\{\{(?<kind>${[...TOKEN_KINDS].sort((a, b) => b.length - a.length).join("|")})(?:#(?<ref>[\w.-]+))?\}\}`, "g");
+/** Whether a fixture string contains at least one `{{placeholder}}`. */
+function hasPlaceholders(value) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	return PLACEHOLDER_RE.test(value);
+}
+/** Key-order-independent stringification for captured-object comparison. */
+function stableStringify(value) {
+	if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+function capturedEquals(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a === "number" && typeof b === "string" || typeof a === "string" && typeof b === "number") return String(a) === String(b);
+	if (a !== null && b !== null && typeof a === "object" && typeof b === "object") return stableStringify(a) === stableStringify(b);
+	return false;
+}
+function recordRef(name, actual, scope) {
+	if (scope.has(name)) return capturedEquals(scope.get(name), actual);
+	scope.set(name, actual);
+	return true;
+}
+function isPortValue(value) {
+	return Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+function kindMatches(kind, actual, scope) {
+	switch (kind) {
+		case "any": return true;
+		case "float":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.float.test(actual);
+		case "int":
+			if (typeof actual === "number") return Number.isInteger(actual);
+			return typeof actual === "string" && WHOLE_RES.int.test(actual);
+		case "number":
+			if (typeof actual === "number") return Number.isFinite(actual);
+			return typeof actual === "string" && WHOLE_RES.number.test(actual);
+		case "port":
+			if (typeof actual === "number") return isPortValue(actual);
+			return typeof actual === "string" && WHOLE_RES.port.test(actual) && isPortValue(Number(actual));
+		case "string": return typeof actual === "string";
+		case "workdir": return typeof actual === "string" && scope.workdir !== void 0 ? actual === scope.workdir : false;
+		default: {
+			const re = WHOLE_RES[kind];
+			return re !== void 0 && typeof actual === "string" && re.test(actual);
+		}
+	}
+}
+function matcherMatches(matcher, actual, scope) {
+	if (matcher.kind === "includes") return typeof actual === "string" && actual.includes(matcher.includes);
+	if (matcher.kind === "regex") return typeof actual === "string" && matcher.regex.test(actual);
+	if (matcher.kind === "ref") {
+		if (matcher.notRef && scope.has(matcher.notRef) && capturedEquals(scope.get(matcher.notRef), actual)) return false;
+		return recordRef(matcher.refName, actual, scope);
+	}
+	return kindMatches(matcher.kind, actual, scope);
+}
+function placeholderSource(kind, scope) {
+	if (kind === "workdir") return scope.workdir === void 0 ? "(?!)" : escapeRegExp(scope.workdir);
+	const source = EMBEDDED_SOURCES[kind];
+	if (source) return source;
+	return kind === "any" ? String.raw`[\s\S]*?` : String.raw`[^\n]*?`;
+}
+function escapeRegExp(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+function parsePlaceholderString(expected, scope) {
+	PLACEHOLDER_RE.lastIndex = 0;
+	const refs = [];
+	let source = "";
+	let lastIndex = 0;
+	let single = null;
+	let count = 0;
+	for (const found of expected.matchAll(PLACEHOLDER_RE)) {
+		const kind = found.groups.kind;
+		const ref = found.groups.ref;
+		source += escapeRegExp(expected.slice(lastIndex, found.index));
+		source += `(${placeholderSource(kind, scope)})`;
+		refs.push({
+			index: count,
+			kind,
+			ref
+		});
+		count++;
+		lastIndex = found.index + found[0].length;
+		if (found.index === 0 && found[0].length === expected.length) single = {
+			kind,
+			ref
+		};
+	}
+	source += escapeRegExp(expected.slice(lastIndex));
+	return {
+		pattern: new RegExp(`^${source}$`),
+		refs,
+		single,
+		source
+	};
+}
+/**
+* Unanchored regex source matching a fixture string — plain text escaped
+* verbatim, each `{{token}}` expanded to its embedded grammar. Used to route
+* declared `.http` intercept paths (`/articles/{{uuid}}`) as URL patterns.
+*/
+function placeholderPatternSource(expected) {
+	return parsePlaceholderString(expected, new CaptureScope()).source;
+}
+function placeholderStringMatches(expected, actual, scope) {
+	const parsed = parsePlaceholderString(expected, scope);
+	if (parsed.single) {
+		if (!kindMatches(parsed.single.kind, actual, scope)) return false;
+		if (parsed.single.ref) return recordRef(parsed.single.ref, actual, scope);
+		return true;
+	}
+	if (typeof actual !== "string" && typeof actual !== "number") return false;
+	const text = String(actual);
+	const found = parsed.pattern.exec(text);
+	if (!found) return false;
+	for (const entry of parsed.refs) {
+		if (!entry.ref) continue;
+		if (!recordRef(entry.ref, found[entry.index + 1], scope)) return false;
+	}
+	return true;
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Deep structural equality with matcher / placeholder support. Ref captures
+* are recorded in `scope` in traversal order (arrays left-to-right, object
+* keys in expected-key order).
+*/
+function structuralEquals(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralEquals(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		const expectedKeys = Object.keys(expected);
+		const actualKeys = Object.keys(actual);
+		if (expectedKeys.length !== actualKeys.length) return false;
+		return expectedKeys.every((key) => key in actual && structuralEquals(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Deep structural SUBSET match (toMatchObject-style) with matcher /
+* placeholder support. Plain objects match when every expected key is present
+* and recursively subset-matches — the actual value may carry extra keys.
+* Arrays require equal length with each element subset-matched. Leaves fall
+* back to {@link structuralEquals} semantics (matchers, placeholders, strict
+* equality). Used by request-body filters on intercept triggers.
+*/
+function structuralSubset(expected, actual, scope) {
+	if (expected instanceof Matcher) return matcherMatches(expected, actual, scope);
+	if (typeof expected === "string" && hasPlaceholders(expected)) return placeholderStringMatches(expected, actual, scope);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual) || actual.length !== expected.length) return false;
+		return expected.every((item, i) => structuralSubset(item, actual[i], scope));
+	}
+	if (isPlainObject(expected)) {
+		if (!isPlainObject(actual)) return false;
+		return Object.keys(expected).every((key) => key in actual && structuralSubset(expected[key], actual[key], scope));
+	}
+	return Object.is(expected, actual);
+}
+/**
+* Multi-line text comparison with `{{token}}` support — used by text
+* snapshots (`expected/*.txt`). Without placeholders this is strict equality.
+*/
+function textEquals(expected, actual, scope) {
+	if (!hasPlaceholders(expected)) return expected === actual;
+	return placeholderStringMatches(expected, actual, scope);
+}
+/**
+* Render an expected value for failure diffs and serialization: Matcher
+* instances become their placeholder text, everything else is untouched.
+*/
+function renderExpected(value) {
+	if (value instanceof Matcher) return value.toString();
+	if (Array.isArray(value)) return value.map((item) => renderExpected(item));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, renderExpected(item)]));
+	return value;
+}
+/**
+* Substitute the framework-known cwd (`workdir`) for its `{{workdir}}` token in
+* every string leaf of a structured value. The structural mirror of the text
+* path's `actual.replaceAll(workdir, '{{workdir}}')` — so a golden written under
+* `TEST_UPDATE=1` stores the token, not a run-specific temp path (CONVENTIONS
+* D5). A no-op when `workdir` is undefined (no cwd, e.g. api/jobs mode).
+*/
+function substituteWorkdirDeep(value, workdir) {
+	if (typeof value === "string") return value.replaceAll(workdir, "{{workdir}}");
+	if (Array.isArray(value)) return value.map((item) => substituteWorkdirDeep(item, workdir));
+	if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteWorkdirDeep(item, workdir)]));
+	return value;
+}
+/**
+* Update-mode merge: rewrite a fixture from the actual output while
+* preserving every segment of the previous fixture that was covered by a
+* placeholder (and still matches the actual value).
+*
+* Token preservation is symmetric with the text path (CONVENTIONS D5): a
+* previous `{{placeholder}}` (including `{{workdir}}`) that still matches the
+* RAW actual value is kept; every other leaf is taken from the actual output
+* with the framework-known cwd substituted back to `{{workdir}}`.
+*/
+function mergePreservingPlaceholders(previous, actual, workdir) {
+	const scope = new CaptureScope(workdir);
+	const subst = (value) => workdir === void 0 ? value : substituteWorkdirDeep(value, workdir);
+	function merge(prev, act) {
+		if (typeof prev === "string" && hasPlaceholders(prev)) return placeholderStringMatches(prev, act, scope) ? prev : subst(act);
+		if (Array.isArray(prev) && Array.isArray(act)) return act.map((item, i) => i < prev.length ? merge(prev[i], item) : subst(item));
+		if (isPlainObject(prev) && isPlainObject(act)) return Object.fromEntries(Object.entries(act).map(([key, item]) => [key, key in prev ? merge(prev[key], item) : subst(item)]));
+		return subst(act);
+	}
+	return merge(previous, actual);
+}
+/**
+* Update-mode merge for text snapshots: line-by-line, a previous line whose
+* placeholders still match the actual line is preserved; every other line is
+* taken from the actual output. Values the framework knows to be dynamic
+* (`{{workdir}}`) are substituted automatically (CONVENTIONS D5).
+*/
+function mergeTextPreservingPlaceholders(previous, actual, scope) {
+	const substituted = scope.workdir === void 0 ? actual : actual.replaceAll(scope.workdir, "{{workdir}}");
+	if (previous === null) return substituted;
+	const prevLines = previous.split("\n");
+	return substituted.split("\n").map((line, i) => {
+		const prev = prevLines[i];
+		if (prev === void 0 || !hasPlaceholders(prev)) return line;
+		return textEquals(prev, line, new CaptureScope(scope.workdir)) || textEquals(prev, actual.split("\n")[i] ?? line, new CaptureScope(scope.workdir)) ? prev : line;
+	}).join("\n");
+}
+//#endregion
+//#region src/core/contracts/contract.ts
+/**
+* Declare one contract. Identity function — its value is the enforced shape
+* and the naming convention:
+*
+* @example
+*   // specs/api/reports/contracts/openai/classify-article.ts
+*   import { defineContract, openai } from '@jterrazz/test';
+*
+*   export default defineContract({
+*       request: openai.responses({ user: PROMPT, tools: ['classify'] }),
+*       response: openai.reply({ categories: ['TECH'] }),
+*   });
+*
+*   // Dynamic — the response is computed from the observed request:
+*   export default defineContract({
+*       request: http.post('https://api.example.com/echo'),
+*       response: (request) => http.json({ received: request.body }),
+*   });
+*/
+function defineContract(contract) {
+	return contract;
+}
+/** Is this a {@link Contracts} composite (rather than a contract or a list)? */
+function isContracts(value) {
+	return typeof value === "object" && value !== null && Array.isArray(value.contracts) && typeof value.with === "function";
+}
+/** Is this a single {@link Contract} (rather than a bare request half)? */
+function isContract(value) {
+	return typeof value === "object" && value !== null && "request" in value && "response" in value;
+}
+/**
+* The route a contract claims — method + the DECLARED url source. Two
+* contracts share a route when they would be written on the same line of a
+* declaration: same method, same url pattern (`.source` for a RegExp).
+*/
+function routeKeyOf(contract) {
+	const { method, url } = contract.request;
+	return url instanceof RegExp ? `${method} re:${url.source}` : `${method} str:${url}`;
+}
+/** Human-readable route of a contract — used in every failure message. */
+function describeRoute(contract) {
+	const { method, url } = contract.request;
+	return `${method === "*" ? "ANY" : method} ${url instanceof RegExp ? String(url) : url}`;
+}
+/** Flatten contracts, lists, and composites into one ordered list. */
+function flatten(items) {
+	const flat = [];
+	for (const item of items) if (Array.isArray(item)) flat.push(...flatten(item));
+	else if (isContracts(item)) flat.push(...item.contracts);
+	else flat.push(item);
+	return flat;
+}
+/**
+* Compose contracts into the artifact a test imports — it's contracts all the
+* way down: a composite may extend contracts, lists, and other composites,
+* recursively, order preserved.
+*
+* `.with(...)` derives a scenario: contracts whose route the overrides claim
+* are removed from the base, and the overrides are prepended. Under
+* first-match selection a more specific override (`/articles/gone-1`) also
+* wins over a generic base route (`/articles/{{uuid}}`) it does not replace.
+*
+* @example
+*   // contracts/newsroom.contracts.ts
+*   export default defineContracts(events, articleById);
+*   export const withArticleGone = (id: string) =>
+*       newsroom.with(articleGone(id));
+*/
+function defineContracts(...items) {
+	const contracts = Object.freeze(flatten(items));
+	return {
+		contracts,
+		with(...overrides) {
+			const added = flatten(overrides);
+			const claimed = new Set(added.map(routeKeyOf));
+			const kept = contracts.filter((contract) => !claimed.has(routeKeyOf(contract)));
+			return defineContracts([...added, ...kept]);
+		}
+	};
+}
+/** Normalize any accepted input into a flat contract list. */
+function contractsOf(input) {
+	return flatten([input]);
+}
+//#endregion
+//#region src/core/contracts/queue.ts
+/**
+* The ONE contract queue — pure, engine-agnostic (no MSW, no node:http).
+* Both engines consume it: the MSW integration on api/jobs chains, and the
+* declared stub backend on website/mobile chains.
+*
+* Selection: the FIRST contract in declaration order that matches the observed
+* request and is not exhausted. A contract with no `times` is unlimited (a
+* re-render or a retry replays it); `times: n` is spent after n serves, so an
+* ordered sequence is written as finite contracts before an unlimited tail:
+* `[error500 ×3, ok]`.
+*
+* Strictness (CONVENTIONS D7): when nothing matches — including "everything
+* that matches is exhausted" — the engine answers 501, records the request,
+* and the chain fails with {@link ContractQueue.unmatchedError}. A chain that
+* declared zero contracts is not guarded at all (unchanged boundary).
+*/
+/** Base used to parse origin-relative observed URLs (`/events?x=1`). */
+const RELATIVE_BASE = "http://contract.invalid";
+/** Split a declared url into its base (origin+path, or path) and query halves.
+* Never through `new URL()`, which would percent-encode `{{token}}` braces. */
+function splitDeclared(url) {
+	const separator = url.indexOf("?");
+	if (separator === -1) return {
+		base: url,
+		query: new URLSearchParams()
+	};
+	return {
+		base: url.slice(0, separator),
+		query: new URLSearchParams(url.slice(separator + 1))
+	};
+}
+/** Decode percent-escapes, falling back to the raw text on malformed input. */
+function safeDecode(text) {
+	try {
+		return decodeURIComponent(text);
+	} catch {
+		return text;
+	}
+}
+/** Token-aware comparison of one declared value against an observed one. */
+function valueMatches(declared, observed) {
+	return textEquals(declared, observed, new CaptureScope());
+}
+/**
+* Does an observed URL satisfy a declared one? A RegExp tests the full URL; a
+* PATH FORM (`/articles/{{uuid}}`) ignores the origin; an absolute string
+* compares origin+pathname. In both string forms `{{token}}` segments compare
+* structurally and declared query params are a SUBSET of the observed ones.
+*/
+function urlMatches(declared, observed) {
+	if (declared instanceof RegExp) return declared.test(observed);
+	let url;
+	try {
+		url = new URL(observed, RELATIVE_BASE);
+	} catch {
+		return false;
+	}
+	const { base, query } = splitDeclared(declared);
+	const observedBase = base.startsWith("/") ? url.pathname : `${url.origin}${url.pathname}`;
+	const decodedBase = base.startsWith("/") ? safeDecode(url.pathname) : `${url.origin}${safeDecode(url.pathname)}`;
+	if (!valueMatches(base, observedBase) && !valueMatches(base, decodedBase)) return false;
+	for (const key of new Set(query.keys())) {
+		const observedValues = url.searchParams.getAll(key);
+		if (!query.getAll(key).every((value) => observedValues.some((actual) => valueMatches(value, actual)))) return false;
+	}
+	return true;
+}
+/**
+* Does an observed request satisfy a contract? Method (`*` matches any), URL,
+* then the contract's own `match` predicate (headers/query/body filters).
+*/
+function contractMatches(contract, request) {
+	const { match, method, url } = contract.request;
+	if (method !== "*" && method.toUpperCase() !== request.method.toUpperCase()) return false;
+	if (!urlMatches(url, request.url)) return false;
+	return match ? match(request) : true;
+}
+/**
+* The URL pattern an out-of-process router (MSW) must register so the request
+* REACHES the queue. Deliberately no narrower than {@link contractMatches} —
+* the predicate above stays the authority on what actually matches.
+*/
+function routePatternOf(declared) {
+	if (declared instanceof RegExp) return declared;
+	const { base } = splitDeclared(declared);
+	if (base.startsWith("/")) return new RegExp(String.raw`^https?:\/\/[^/?#]+${placeholderPatternSource(base)}(?:\?[^#]*)?(?:#.*)?$`);
+	if (hasPlaceholders(base)) return new RegExp(String.raw`^${placeholderPatternSource(base)}(?:\?[^#]*)?(?:#.*)?$`);
+	return base;
+}
+var ContractQueue = class {
+	contracts;
+	served;
+	constructor(contracts) {
+		this.contracts = contracts;
+		this.served = contracts.map(() => 0);
+	}
+	/** How many contracts the chain declared. */
+	get size() {
+		return this.contracts.length;
+	}
+	/**
+	* Routes to register with an out-of-process router, deduped by pattern —
+	* two contracts on the same URL share one handler and one queue.
+	*/
+	get routes() {
+		const routes = /* @__PURE__ */ new Map();
+		for (const contract of this.contracts) {
+			const url = routePatternOf(contract.request.url);
+			const key = String(url);
+			const route = routes.get(key) ?? {
+				methods: [],
+				url
+			};
+			if (!route.methods.includes(contract.request.method)) route.methods.push(contract.request.method);
+			routes.set(key, route);
+		}
+		return [...routes.values()];
+	}
+	/** The declared routes, in order — the enumeration a 501 body carries. */
+	declaredRoutes() {
+		return this.contracts.map((contract) => describeRoute(contract));
+	}
+	/**
+	* Serve the first contract in declaration order that matches and is not
+	* exhausted, or null when nothing matches (including "everything that
+	* matches is spent") — the strict-violation signal.
+	*/
+	take(request) {
+		for (let i = 0; i < this.contracts.length; i++) {
+			const contract = this.contracts[i];
+			const { times } = contract;
+			if (times !== void 0 && this.served[i] >= times) continue;
+			if (!contractMatches(contract, request)) continue;
+			this.served[i] += 1;
+			return contract;
+		}
+		return null;
+	}
+	/**
+	* The chain-end failure for contracts declared `required: true` that were
+	* never requested (or not exactly `times` times), or null when every
+	* requirement held.
+	*/
+	requiredError() {
+		const unmet = [];
+		for (const [i, contract] of this.contracts.entries()) {
+			if (!contract.required) continue;
+			const served = this.served[i];
+			const { times } = contract;
+			if (times === void 0) {
+				if (served === 0) unmet.push(`  - ${describeRoute(contract)} — declared and required but never requested`);
+			} else if (served !== times) unmet.push(`  - ${describeRoute(contract)} — declared required with times: ${times} but was requested ${served} time(s)`);
+		}
+		if (unmet.length === 0) return null;
+		return /* @__PURE__ */ new Error(`Required contract(s) never satisfied during the chain:\n${unmet.join("\n")}\nA required contract states the call MUST happen — either the code no longer makes it, or the contract no longer describes it.`);
+	}
+	/**
+	* The strict failure for a request that matched no contract (CONVENTIONS
+	* D7): method + URL of the offending request, plus every declared contract
+	* and how often it was served.
+	*/
+	unmatchedError(method, url) {
+		const declared = this.contracts.length === 0 ? "  (no contracts declared)" : this.contracts.map((contract, i) => `  - ${describeRoute(contract)}${this.stateOf(i)}`).join("\n");
+		return /* @__PURE__ */ new Error(`Unmatched outgoing HTTP request during spec: ${method} ${url}\nDeclared contracts:\n${declared}\nEvery outgoing request of a chain that declares contracts must match one — add a contract for it (or raise its \`times\` when it is exhausted).`);
+	}
+	stateOf(index) {
+		const served = this.served[index];
+		const { times } = this.contracts[index];
+		if (times !== void 0 && served >= times) return ` (exhausted after ${times})`;
+		return served === 0 ? "" : ` (served ${served} time(s))`;
+	}
+};
+//#endregion
+export { isContract as a, mergeTextPreservingPlaceholders as c, structuralSubset as d, textEquals as f, defineContracts as i, renderExpected as l, contractsOf as n, isContracts as o, defineContract as r, mergePreservingPlaceholders as s, ContractQueue as t, structuralEquals as u };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "10.1.0",
+    "version": "11.0.0",
     "description": "Declarative testing framework for HTTP APIs, CLIs, and background jobs — one entry point, real infrastructure, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",