@jterrazz/test 16.1.1 → 18.0.0

package/dist/shared-stub-reply.js

@@ -0,0 +1,167 @@
+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
+async function nextTask() {
+	const { port1, port2 } = new MessageChannel();
+	await new Promise((resolve) => {
+		port1.onmessage = () => {
+			port1.close();
+			resolve();
+		};
+		port2.postMessage(null);
+	});
+}
+/** 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 (index > 0) {
+			await pause(body.delayBetweenChunks);
+			await nextTask();
+		}
+		index += 1;
+		controller.enqueue(encoder.encode(chunk));
+	} });
+}
+//#endregion
+//#region src/stubs/delivery/stub-reply.ts
+/** A request's body as a stub's filter reads it: the parsed JSON, the raw text when it is none, `null` when there is none. */
+function requestBody(raw) {
+	if (raw.length === 0) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+/** The reply a matched stub states for this request, once its delay has passed. */
+async function replyOf(response, observed) {
+	const reply = typeof response === "function" ? response(observed) : response;
+	await pause(reply.delay ?? 0);
+	return reply;
+}
+/** The `error` of the 501 every delivery answers a request it refuses, whichever process serves it. */
+function refusedReply(summary) {
+	return `@jterrazz/test strict stubs: ${summary}`;
+}
+function unmatchedSummary(method, url) {
+	return `unmatched request ${method} ${url}`;
+}
+//#endregion
+export { toReadableStream as a, unmatchedSummary as i, replyOf as n, StubQueue as o, requestBody as r, refusedReply as t };
+
+//# sourceMappingURL=shared-stub-reply.js.map

package/dist/shared-stub-server.js

@@ -0,0 +1,142 @@
+import { n as refusal } from "./shared-refusal.js";
+import { n as isStreamBody } from "./shared-exchange.js";
+import { a as toReadableStream, i as unmatchedSummary, n as replyOf, o as StubQueue, r as requestBody, t as refusedReply } from "./shared-stub-reply.js";
+import { METHODS } from "node:http";
+//#region src/stubs/delivery/msw-handlers.ts
+const NEVER_CACHED = { "cache-control": "no-store" };
+function toMswResponse(msw, response) {
+	const { body, headers, status = 200 } = response;
+	if (response.transport === "network-error") return msw.HttpResponse.error();
+	if (body === null || body === void 0) return new msw.HttpResponse(null, {
+		headers: {
+			...NEVER_CACHED,
+			...headers
+		},
+		status
+	});
+	if (isStreamBody(body)) return new msw.HttpResponse(toReadableStream(body), {
+		headers: {
+			...NEVER_CACHED,
+			"content-type": body.contentType,
+			...headers
+		},
+		status
+	});
+	if (typeof body === "string") return new msw.HttpResponse(body, {
+		headers: {
+			...NEVER_CACHED,
+			"content-type": "text/plain; charset=utf-8",
+			...headers
+		},
+		status
+	});
+	return msw.HttpResponse.json(body, {
+		headers: {
+			...NEVER_CACHED,
+			...headers
+		},
+		status
+	});
+}
+function handlerOf(msw, method) {
+	return {
+		"*": msw.http.all,
+		DELETE: msw.http.delete,
+		GET: msw.http.get,
+		HEAD: msw.http.head,
+		OPTIONS: msw.http.options,
+		PATCH: msw.http.patch,
+		POST: msw.http.post,
+		PUT: msw.http.put
+	}[method.toUpperCase()];
+}
+function buildStubHandlers(msw, stubs, bypass) {
+	const queue = new StubQueue(stubs);
+	let violation = null;
+	const refuse = (error, summary) => {
+		violation ??= error;
+		return msw.HttpResponse.json({ error: refusedReply(summary) }, {
+			headers: NEVER_CACHED,
+			status: 501
+		});
+	};
+	const recordViolation = (method, url) => refuse(queue.unmatchedError(method, url), unmatchedSummary(method, url));
+	const handlers = [];
+	for (const route of queue.routes) for (const method of route.methods) {
+		const handlerFn = handlerOf(msw, method);
+		if (handlerFn === void 0) continue;
+		handlers.push(handlerFn(route.url, async ({ request }) => {
+			const observed = await observe(request);
+			const stub = queue.take(observed);
+			if (!stub) return recordViolation(request.method, request.url);
+			return toMswResponse(msw, await replyOf(stub.response, observed));
+		}));
+	}
+	handlers.push(msw.http.all("*", ({ request }) => bypass?.(request.url) === true ? msw.passthrough() : recordViolation(request.method, request.url)));
+	return {
+		handlers,
+		refuse,
+		violation: () => queue.verdict(violation)
+	};
+}
+async function observe(request) {
+	return {
+		body: requestBody(await request.clone().text()),
+		headers: Object.fromEntries(request.headers),
+		method: request.method.toUpperCase(),
+		url: request.url
+	};
+}
+//#endregion
+//#region src/stubs/delivery/same-process/stub-server.ts
+async function loadMsw() {
+	const [{ setupServer }, msw] = await Promise.all([import("msw/node"), import("msw")]);
+	return {
+		msw,
+		setupServer: () => setupServer()
+	};
+}
+let serverInstance = null;
+let refuseOffTheWire = null;
+function offTheWireError(request) {
+	return new Error(refusal("network-strict-after-first-stub", {
+		fix: "send a method in the capitals the HTTP parser reads (`PATCH`, not `patch`): fetch upper-cases DELETE, GET, HEAD, OPTIONS, POST and PUT, and sends any other as written",
+		found: `an outgoing request the network double cannot read off the wire, ${request.method} ${request.url}: its method is not one of node's \`http.METHODS\`, so no stub could answer it and it would reach the network`
+	}));
+}
+function guardOffTheWireMethods() {
+	const next = globalThis.fetch;
+	globalThis.fetch = async (input, init) => {
+		const request = new Request(input, init);
+		if (refuseOffTheWire !== null && !METHODS.includes(request.method)) return refuseOffTheWire(request);
+		return await next(request);
+	};
+}
+async function ensureStubServer() {
+	if (serverInstance !== null) return serverInstance;
+	const { setupServer } = await loadMsw();
+	const server = setupServer();
+	server.listen({ onUnhandledFrame: "bypass" });
+	guardOffTheWireMethods();
+	serverInstance = server;
+	return server;
+}
+/** The trailing catch-all records any request no stub accepted; the chain's pipeline rethrows it. */
+async function registerStubs(stubs) {
+	const server = await ensureStubServer();
+	const { msw } = await loadMsw();
+	const { handlers, refuse, violation } = buildStubHandlers(msw, stubs);
+	server.use(...handlers);
+	refuseOffTheWire = (request) => refuse(offTheWireError(request), `unreadable request ${request.method} ${request.url}`);
+	return {
+		cleanup: () => {
+			refuseOffTheWire = null;
+			server.resetHandlers();
+		},
+		violation
+	};
+}
+//#endregion
+export { registerStubs };
+
+//# sourceMappingURL=shared-stub-server.js.map

package/dist/shared-temp-root.global-setup.js

@@ -0,0 +1,73 @@
+import { a as EVIDENCE_DIR } from "./shared-artifacts.js";
+import { t as setupEntry } from "./shared-setup-entry.js";
+import { t as processAlive } from "./shared-process-alive.js";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+//#region src/chain/paths/run-folders.ts
+function runOf(entry) {
+	const pid = Number(entry.split("-")[0]);
+	return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+/** Leaves alone every name no run gave: the parent of temp roots is shared with whatever else a user keeps there. */
+function sweepOrphanRoots(parent) {
+	for (const entry of readdirSync(parent)) {
+		const pid = runOf(entry);
+		if (pid !== null && !processAlive(pid)) rmSync(join(parent, entry), {
+			force: true,
+			recursive: true
+		});
+	}
+}
+/** Keeps a living run's evidence alone: a finished run's stays until the next run starts, and nothing else is ever kept. */
+function sweepFinishedEvidence(folder) {
+	if (!existsSync(folder)) return;
+	for (const entry of readdirSync(folder)) {
+		const pid = runOf(entry);
+		if (pid === null || !processAlive(pid)) rmSync(join(folder, entry), {
+			force: true,
+			recursive: true
+		});
+	}
+}
+//#endregion
+//#region src/chain/paths/temp-root.global-setup.ts
+/** Named by uid: a temp directory users share never holds a folder one of them cannot sweep. */
+const TEMP_ROOTS_PARENT = `jterrazz-test-runs-${process.getuid?.() ?? "user"}`;
+const TEMP_VARIABLES = [
+	"TMPDIR",
+	"TMP",
+	"TEMP"
+];
+function setVariables(values) {
+	for (const [name, value] of Object.entries(values)) if (value === void 0) Reflect.deleteProperty(process.env, name);
+	else process.env[name] = value;
+}
+function tempRootSetup() {
+	return setupEntry(import.meta.dirname, "temp-root");
+}
+function joinedRoot() {
+	const current = tmpdir();
+	return basename(dirname(current)) === TEMP_ROOTS_PARENT && basename(current).startsWith(`${process.pid}-`);
+}
+function setup() {
+	if (joinedRoot()) return () => {};
+	const parent = join(tmpdir(), TEMP_ROOTS_PARENT);
+	mkdirSync(parent, { recursive: true });
+	sweepOrphanRoots(parent);
+	sweepFinishedEvidence(resolve(EVIDENCE_DIR));
+	const root = mkdtempSync(join(parent, `${process.pid}-`));
+	const previous = Object.fromEntries(TEMP_VARIABLES.map((name) => [name, process.env[name]]));
+	setVariables(Object.fromEntries(TEMP_VARIABLES.map((name) => [name, root])));
+	return () => {
+		setVariables(previous);
+		rmSync(root, {
+			force: true,
+			recursive: true
+		});
+	};
+}
+//#endregion
+export { setup as n, tempRootSetup as r, TEMP_ROOTS_PARENT as t };
+
+//# sourceMappingURL=shared-temp-root.global-setup.js.map

package/dist/shared-test-baseline.js

@@ -0,0 +1,26 @@
+import { t as TEST_SECTION } from "./shared-test-section.js";
+import { labelOf, sectionOf, writeSection } from "@jterrazz/typescript/rules";
+//#region lint/kit/baseline/test-baseline.ts
+const ROUTES_KEY = "routes/unreached";
+const ROUTES_LEDGER = `${labelOf(TEST_SECTION)} › ${ROUTES_KEY}`;
+const heldOf = (root) => sectionOf(root, "test") ?? {};
+const withoutRoutes = (counts) => Object.fromEntries(Object.entries(counts).filter(([key]) => key !== ROUTES_KEY));
+function writeBaseline(root, counts) {
+	const held = heldOf(root)[ROUTES_KEY];
+	writeSection(root, TEST_SECTION, held === void 0 ? { ...counts } : {
+		...counts,
+		[ROUTES_KEY]: held
+	});
+}
+const heldUnreached = (root) => heldOf(root)[ROUTES_KEY] ?? 0;
+function recordUnreached(root, count) {
+	const others = withoutRoutes(heldOf(root));
+	writeSection(root, TEST_SECTION, count === 0 ? others : {
+		...others,
+		[ROUTES_KEY]: count
+	});
+}
+//#endregion
+export { writeBaseline as i, heldUnreached as n, recordUnreached as r, ROUTES_LEDGER as t };
+
+//# sourceMappingURL=shared-test-baseline.js.map

package/dist/shared-test-section.js

@@ -0,0 +1,58 @@
+import { t as isRecord } from "./shared-json-shape.js";
+import { readSettings, readSettingsSync, refusalBlock } from "@jterrazz/typescript/rules";
+//#region lint/kit/project/test-section.ts
+const TEST_SECTION = "test";
+const UNREAD = Object.freeze({
+	collections: [],
+	methodless: [],
+	production: { allow: {} }
+});
+function wordsOf(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+}
+function reasonsOf(value) {
+	if (!isRecord(value)) return;
+	const reasons = {};
+	for (const [name, reason] of Object.entries(value)) {
+		if (typeof reason !== "string" || reason.trim() === "") return;
+		reasons[name] = reason;
+	}
+	return reasons;
+}
+const BASE_PATH = /^(?:\/[a-z0-9][\w.~-]*)+$/u;
+const isMountPath = (value) => BASE_PATH.test(value);
+function basePathOf(value) {
+	if (typeof value !== "string") return;
+	if (!isMountPath(value)) throw new Error(refusalBlock({
+		fix: "write the path the routes are mounted under from the root, with no slash at its end: test: { basePath: '/api' }",
+		found: `jterrazz.config.ts: test.basePath ${JSON.stringify(value)} is no mount path`,
+		read: "docs/reference/linting.md#test-settings-section",
+		why: "The base path is cut from every route before its subject folder is derived, so it is read as a route prefix is written: one leading slash, lowercase segments, no trailing slash."
+	}));
+	return value;
+}
+/** A key of the wrong shape is read as its default, never half-used: the type check refuses it first; a base path the type lets through and no route can carry is refused here. */
+function testSettingsOf(test) {
+	const section = isRecord(test) ? test : {};
+	const allow = isRecord(section.production) ? reasonsOf(section.production.allow) : void 0;
+	const basePath = basePathOf(section.basePath);
+	return {
+		collections: wordsOf(section.collections) ?? UNREAD.collections,
+		methodless: Object.keys(reasonsOf(section.methodless) ?? {}),
+		production: allow === void 0 ? UNREAD.production : { allow },
+		...typeof section.routes === "string" ? { routes: section.routes } : {},
+		...basePath === void 0 ? {} : { basePath }
+	};
+}
+/** Every pass is sync, so the file is loaded synchronously, once per process; the runtime reads the same resolution, so the run and the checker agree. A file that does not resolve is no settings: the toolchain already reports it. */
+const testSettingsAtSync = (root) => testSettingsOf(readSettingsSync(root).resolved.sections[TEST_SECTION]);
+/** Whether the unit's settings list this package's preset, the one whose checker judges every specs tree under it. */
+const listsTestPreset = (root) => readSettingsSync(root).resolved.presets.some((preset) => preset.package === "@jterrazz/test");
+async function testSettingsAt(root) {
+	const { resolved } = await readSettings(root);
+	return testSettingsOf(resolved.sections[TEST_SECTION]);
+}
+//#endregion
+export { testSettingsAtSync as i, listsTestPreset as n, testSettingsAt as r, TEST_SECTION as t };
+
+//# sourceMappingURL=shared-test-section.js.map