@jterrazz/test 12.1.0 → 12.2.0

package/dist/queue.js

@@ -1,297 +1,5 @@
-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
+import { t as CaptureScope } from "./match.js";
+import { F as textEquals, O as hasPlaceholders, j as placeholderPatternSource } from "./literate.js";
 //#region src/core/contracts/contract.ts
 /**
 * Declare one contract. Identity function — its value is the enforced shape
@@ -552,4 +260,4 @@ var ContractQueue = class {
 	}
 };
 //#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 };
+export { isContract as a, defineContracts as i, contractsOf as n, isContracts as o, defineContract as r, ContractQueue as t };

package/dist/vitest.d.ts

@@ -0,0 +1,41 @@
+//#region src/vitest/literate-plugin.d.ts
+interface LiterateOptions {
+  /**
+   * Globs added to the project's test include. Default: every `.cli` file.
+   * Narrow it when a tree holds `.cli` files that are INPUTS to other specs
+   * (a deliberately-broken header) rather than scenarios to run.
+   */
+  include?: string[];
+  /**
+   * Path to the `*.specification.ts` whose exported `cli` runs the files —
+   * relative to the vite root, or absolute.
+   *
+   * It is stated, never guessed: a repository may declare several cli
+   * runners (different binaries, different service records), and there is no
+   * convention that could pick the right one without silently binding a
+   * scenario to the wrong command.
+   */
+  specification: string;
+}
+/**
+ * The shape vite consumes. Declared structurally rather than imported from
+ * `vite`, so the package's runner coupling stays the one dependency it already
+ * has (CONVENTIONS I1) — the object is assignable to vite's `Plugin`.
+ */
+interface LiteratePlugin {
+  config: () => {
+    test: {
+      include: string[];
+    };
+  };
+  /** Vite hands the resolved root here — what a relative `specification` is resolved against. */
+  configResolved: (resolved: {
+    root: string;
+  }) => void;
+  enforce: 'pre';
+  load: (id: string) => null | string;
+  name: string;
+}
+declare function literate(options: LiterateOptions): LiteratePlugin;
+//#endregion
+export { type LiterateOptions, type LiteratePlugin, literate };

package/dist/vitest.js

@@ -0,0 +1,68 @@
+import { t as literateTitle } from "./literate.js";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+//#region src/vitest/literate-plugin.ts
+/**
+* The `literate()` vite plugin — door one of the literate format.
+*
+* It makes a `<case>.cli` file a TEST FILE: the glob joins the project's test
+* include, and each `.cli` is transformed into a one-test module that runs the
+* file through the registered `cli` runner. The runner shows the `.cli` path as
+* the file and the header's `test:` line as the title, so a failing scenario is
+* opened where it is written — not in a `.test.ts` that merely points at it.
+*
+* ```typescript
+* // vitest.config.ts
+* import { defineConfig } from 'vitest/config';
+* import { literate } from '@jterrazz/test/vitest';
+*
+* export default defineConfig({
+*     plugins: [literate({ specification: './specs/cli/cli.specification.ts' })],
+* });
+* ```
+*/
+/** The `.cli` extension, matched on the id vite hands the plugin. */
+const CLI_FILE = /\.cli(?:\?.*)?$/;
+/**
+* The module a `.cli` file becomes: one `test()` whose title is the header's
+* `test:` line and whose body runs the whole file — header, servers, every
+* block asserted.
+*
+* @internal Exported for unit tests.
+*/
+function literateModule(content, filePath, specificationPath) {
+	const title = literateTitle(content, filePath);
+	return [
+		"import { test } from 'vitest';",
+		`import { cli } from ${JSON.stringify(specificationPath)};`,
+		"",
+		`test(${JSON.stringify(title)}, async () => {`,
+		`    await cli.run(${JSON.stringify(filePath)});`,
+		"});",
+		""
+	].join("\n");
+}
+/** Strip vite's query suffix (`?v=…`) from a module id. */
+function cleanId(id) {
+	return id.split("?")[0];
+}
+function literate(options) {
+	const include = options.include ?? ["**/*.cli"];
+	let root = process.cwd();
+	return {
+		config: () => ({ test: { include } }),
+		configResolved: (resolved) => {
+			root = resolved.root;
+		},
+		enforce: "pre",
+		load: (id) => {
+			if (!CLI_FILE.test(id)) return null;
+			const filePath = cleanId(id);
+			const specificationPath = isAbsolute(options.specification) ? options.specification : resolve(root, options.specification);
+			return literateModule(readFileSync(filePath, "utf8"), filePath, specificationPath);
+		},
+		name: "jterrazz-test:literate"
+	};
+}
+//#endregion
+export { literate };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "12.1.0",
+    "version": "12.2.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",
@@ -35,6 +35,10 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./vitest": {
+            "types": "./dist/vitest.d.ts",
+            "import": "./dist/vitest.js"
+        },
         "./oxlint": {
             "types": "./dist/oxlint.d.ts",
             "import": "./dist/oxlint.js",