@jterrazz/test 16.1.1 → 17.0.0

package/dist/shared-stub-server.js

@@ -0,0 +1,190 @@
+import { n as isStreamBody } from "./shared-exchange.js";
+import { t as pause } from "./shared-pause.js";
+import { n as StubQueue, t as toReadableStream } from "./shared-stream-body.js";
+//#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 recordViolation = (method, url) => {
+		violation ??= queue.unmatchedError(method, url);
+		return msw.HttpResponse.json({ error: `@jterrazz/test strict stubs: unmatched request ${method} ${url}` }, {
+			headers: NEVER_CACHED,
+			status: 501
+		});
+	};
+	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);
+			const response = typeof stub.response === "function" ? stub.response(observed) : stub.response;
+			await pause(response.delay ?? 0);
+			return toMswResponse(msw, response);
+		}));
+	}
+	handlers.push(msw.http.all("*", ({ request }) => bypass?.(request.url) === true ? msw.passthrough() : recordViolation(request.method, request.url)));
+	return {
+		handlers,
+		violation: () => queue.verdict(violation)
+	};
+}
+async function observe(request) {
+	let body = null;
+	const rawText = await request.clone().text();
+	if (rawText) try {
+		body = JSON.parse(rawText);
+	} catch {
+		body = rawText;
+	}
+	return {
+		body,
+		headers: Object.fromEntries(request.headers),
+		method: request.method.toUpperCase(),
+		url: request.url
+	};
+}
+//#endregion
+//#region src/stubs/delivery/same-process/fetch-refusals.ts
+const PROBE = "http://request-init.invalid/";
+const probeOf = (init) => init.body instanceof ReadableStream ? {
+	...init,
+	body: new Blob()
+} : init;
+/**
+* Wraps `underlying` so a RequestInit that fetch itself refuses rejects with fetch's own TypeError, before any stub can serve it.
+* @see https://fetch.spec.whatwg.org/#dom-request
+*/
+function refusingWhatFetchRefuses(underlying) {
+	return async (input, init) => {
+		if (init === void 0) return await underlying(input);
+		const { method } = new Request(PROBE, probeOf(init));
+		return await underlying(input, {
+			...init,
+			method
+		});
+	};
+}
+//#endregion
+//#region src/stubs/delivery/same-process/owned-body.ts
+async function release(reader, reason) {
+	try {
+		await reader.cancel(reason);
+	} catch {}
+}
+function withOwnedBody(response) {
+	const { body } = response;
+	if (body === null) return response;
+	const reader = body.getReader();
+	const owned = new ReadableStream({
+		cancel: (reason) => {
+			release(reader, reason);
+		},
+		pull: async (controller) => {
+			const { done, value } = await reader.read();
+			if (done) controller.close();
+			else controller.enqueue(value);
+		}
+	});
+	const reply = new Response(owned, {
+		headers: response.headers,
+		status: response.status,
+		statusText: response.statusText
+	});
+	Object.defineProperties(reply, {
+		redirected: { value: response.redirected },
+		type: { value: response.type },
+		url: { value: response.url }
+	});
+	return reply;
+}
+function owningBodies(underlying) {
+	return async (input, init) => withOwnedBody(await underlying(input, init));
+}
+//#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 installedFetch = null;
+async function ensureStubServer() {
+	if (serverInstance !== null) return serverInstance;
+	const { setupServer } = await loadMsw();
+	const server = setupServer();
+	server.listen({ onUnhandledRequest: "bypass" });
+	serverInstance = server;
+	installedFetch = globalThis.fetch;
+	globalThis.fetch = owningBodies(refusingWhatFetchRefuses(installedFetch));
+	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, violation } = buildStubHandlers(msw, stubs);
+	server.use(...handlers);
+	return {
+		cleanup: () => {
+			server.resetHandlers();
+		},
+		violation
+	};
+}
+//#endregion
+export { registerStubs };
+
+//# sourceMappingURL=shared-stub-server.js.map

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

@@ -0,0 +1,80 @@
+import { a as EVIDENCE_DIR } from "./shared-artifacts.js";
+import { t as setupEntry } from "./shared-setup-entry.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 isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error instanceof Error && "code" in error && error.code === "EPERM";
+	}
+}
+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 && !isAlive(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 || !isAlive(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

package/dist/shared-testcontainers.adapter.js

@@ -0,0 +1,203 @@
+import { t as isRecord } from "./shared-json-shape.js";
+import { t as invariant } from "./shared-refusal.js";
+import { t as loadPeer } from "./shared-peer.js";
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { text } from "node:stream/consumers";
+import { hostname } from "node:os";
+//#region src/services/containers/run-containers.ts
+function canonical(value) {
+	return isRecord(value) ? Object.fromEntries(Object.entries(value).toSorted(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, canonical(entry)])) : value;
+}
+function keyOf(request) {
+	return JSON.stringify(canonical(request));
+}
+var RunContainers = class {
+	started = /* @__PURE__ */ new Map();
+	create;
+	ready;
+	/** `ready`'s rejection is the one answer every request gets, and no container is created. */
+	constructor(create, ready = async () => {}) {
+		this.create = create;
+		this.ready = ready;
+	}
+	async acquire(request) {
+		const key = keyOf(request);
+		let pending = this.started.get(key);
+		if (pending === void 0) {
+			pending = this.start(key, request);
+			this.started.set(key, pending);
+		}
+		const container = await pending;
+		return {
+			host: container.getHost(),
+			key,
+			port: container.getMappedPort(request.port)
+		};
+	}
+	async logs(key, since) {
+		const pending = this.started.get(key);
+		if (pending === void 0) return "";
+		return await (await pending).getLogs(since);
+	}
+	async stop() {
+		const pending = [...this.started.values()];
+		this.started.clear();
+		await Promise.allSettled(pending.map(async (starting) => {
+			await (await starting).stop();
+		}));
+	}
+	async start(key, request) {
+		try {
+			await this.ready();
+			const container = this.create(request);
+			await container.start();
+			return container;
+		} catch (error) {
+			this.started.delete(key);
+			throw error;
+		}
+	}
+};
+function field(value, name) {
+	if (typeof value !== "object" || value === null) return;
+	return Reflect.get(value, name);
+}
+function isContainerRequest(value) {
+	return typeof field(value, "image") === "string" && typeof field(value, "port") === "number";
+}
+async function respond(containers, request, response) {
+	const url = new URL(request.url ?? "/", "http://run");
+	try {
+		if (request.method === "POST" && url.pathname === "/containers") {
+			const asked = JSON.parse(await text(request));
+			if (!isContainerRequest(asked)) throw invariant(`a worker asked for ${JSON.stringify(asked)}, no container request`);
+			const address = await containers.acquire(asked);
+			response.writeHead(200, { "content-type": "application/json" });
+			response.end(JSON.stringify(address));
+			return;
+		}
+		if (request.method === "GET" && url.pathname === "/logs") {
+			response.writeHead(200, { "content-type": "text/plain" });
+			const key = url.searchParams.get("key") ?? "";
+			const since = url.searchParams.get("since");
+			const moment = since === null ? void 0 : new Date(Number(since));
+			response.end(await containers.logs(key, moment));
+			return;
+		}
+		response.writeHead(404).end();
+	} catch (error) {
+		response.writeHead(500, { "content-type": "application/json" });
+		response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+	}
+}
+async function serveContainers(containers) {
+	const server = createServer((request, response) => {
+		respond(containers, request, response);
+	});
+	server.listen(0, "127.0.0.1");
+	await once(server, "listening");
+	const address = server.address();
+	if (address === null || typeof address === "string") throw invariant("the run containers are served on no port");
+	const { port } = address;
+	return {
+		close: async () => {
+			server.close();
+			await once(server, "close");
+		},
+		url: `http://127.0.0.1:${port}`
+	};
+}
+//#endregion
+//#region src/services/containers/testcontainers.adapter.ts
+const CONTAINER_LABEL = "com.jterrazz.test";
+const REUSED_LABEL = "com.jterrazz.test.reuse";
+/** `<host>:<pid>`: a sweep removes the container once that process is dead, whatever reaper session holds it. */
+const OWNER_LABEL = "com.jterrazz.test.owner";
+function processOwner() {
+	return `${hostname()}:${process.pid}`;
+}
+/** Never on CI, where a run starts from nothing and leaves nothing. */
+function reuseEnabled(env) {
+	const onCi = env.CI !== void 0 && env.CI !== "" && env.CI !== "false";
+	return env.TESTCONTAINERS_REUSE_ENABLE === "true" && !onCi;
+}
+/** A reused container names no owner: its definition hash must not change with the process asking. */
+function containerLabels(reuse, owner) {
+	return reuse ? {
+		[CONTAINER_LABEL]: "true",
+		[REUSED_LABEL]: "true"
+	} : {
+		[CONTAINER_LABEL]: "true",
+		[OWNER_LABEL]: owner
+	};
+}
+async function loadTestcontainers() {
+	return await loadPeer("testcontainers", "a declared service", async () => await import("testcontainers"));
+}
+var TestcontainersAdapter = class {
+	image;
+	containerPort;
+	env;
+	command;
+	tmpfs;
+	reuse;
+	container = null;
+	peer;
+	constructor(options, peer = loadTestcontainers) {
+		this.peer = peer;
+		this.image = options.image;
+		this.containerPort = options.port;
+		this.env = options.env ?? {};
+		this.command = options.command;
+		this.tmpfs = options.tmpfs;
+		this.reuse = options.reuse ?? reuseEnabled(process.env);
+	}
+	async start() {
+		const { GenericContainer, Wait } = await this.peer();
+		let builder = new GenericContainer(this.image).withExposedPorts(this.containerPort).withLabels(containerLabels(this.reuse, processOwner()));
+		for (const [key, value] of Object.entries(this.env)) builder = builder.withEnvironment({ [key]: value });
+		if (this.command !== void 0) builder = builder.withCommand(this.command);
+		if (this.tmpfs !== void 0) builder = builder.withTmpFs(this.tmpfs);
+		if (this.image.startsWith("postgres")) builder = builder.withWaitStrategy(Wait.forLogMessage(/database system is ready to accept connections/u, 2));
+		if (this.reuse) builder = builder.withReuse();
+		this.container = await builder.start();
+	}
+	async stop() {
+		if (this.container && !this.reuse) {
+			await this.container.stop();
+			this.container = null;
+		}
+	}
+	getMappedPort(containerPort) {
+		if (!this.container) throw invariant("a container was read before it started");
+		return this.container.getMappedPort(containerPort);
+	}
+	getHost() {
+		if (!this.container) throw invariant("a container was read before it started");
+		return this.container.getHost();
+	}
+	getConnectionString() {
+		return `${this.getHost()}:${this.getMappedPort(this.containerPort)}`;
+	}
+	async getLogs(since) {
+		if (!this.container) return "";
+		const stream = await this.container.logs(since === void 0 ? void 0 : { since: since.getTime() / 1e3 });
+		return await new Promise((resolve) => {
+			let output = "";
+			stream.on("data", (chunk) => {
+				output += Buffer.isBuffer(chunk) ? chunk.toString() : String(chunk);
+			});
+			stream.on("end", () => {
+				resolve(output);
+			});
+			setTimeout(() => {
+				resolve(output);
+			}, 1e3);
+		});
+	}
+};
+//#endregion
+export { field as a, RunContainers as i, REUSED_LABEL as n, serveContainers as o, TestcontainersAdapter as r, OWNER_LABEL as t };
+
+//# sourceMappingURL=shared-testcontainers.adapter.js.map

package/dist/shared-tokens.js

@@ -0,0 +1,55 @@
+//#region lint/kit/project/tokens.ts
+const TOKEN_KINDS = [
+	"any",
+	"base64",
+	"date",
+	"duration",
+	"email",
+	"float",
+	"hex",
+	"int",
+	"ip",
+	"iso8601",
+	"number",
+	"path",
+	"port",
+	"semver",
+	"sha",
+	"string",
+	"time",
+	"ulid",
+	"url",
+	"uuid",
+	"workdir"
+];
+const VALID_TOKEN = /^[A-Za-z][A-Za-z0-9]*(?:#[\w.-]+)?$/u;
+const BRACE_BLOCK = /\{\{[^{}]*\}\}/gu;
+const LEADING_WORD = /^[A-Za-z][A-Za-z0-9]*/u;
+const KNOWN = new Set(TOKEN_KINDS);
+function verdictOf(inner) {
+	if (VALID_TOKEN.test(inner)) {
+		const [kind = ""] = inner.split("#");
+		return KNOWN.has(kind) ? "known" : "unknown";
+	}
+	const [word = ""] = LEADING_WORD.exec(inner) ?? [];
+	return KNOWN.has(word) ? "malformed" : void 0;
+}
+function tokensOf(text, verdict) {
+	return text.split("\n").flatMap((lineText, index) => [...lineText.matchAll(BRACE_BLOCK)].flatMap(([token]) => verdictOf(token.slice(2, -2)) === verdict ? [{
+		line: index + 1,
+		token
+	}] : []));
+}
+function findUnknownTokens(text) {
+	return tokensOf(text, "unknown");
+}
+function findMalformedRefs(text) {
+	return tokensOf(text, "malformed");
+}
+function findKnownTokens(text) {
+	return tokensOf(text, "known");
+}
+//#endregion
+export { findUnknownTokens as i, findKnownTokens as n, findMalformedRefs as r, TOKEN_KINDS as t };
+
+//# sourceMappingURL=shared-tokens.js.map