@classytic/arc-testkit 0.4.0 → 0.6.0

package/dist/conformance.mjs

@@ -0,0 +1,831 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { expect, it } from "vitest";
+import { isDeepStrictEqual } from "node:util";
+// src/conformance/shared.ts
+/**
+* Shared seams of the conformance suites: a structural view of a booted app (a Fastify instance
+* satisfies it), the `Caller` a suite sends requests through, the route table, and the exception
+* lists every guard takes (an exception that no longer matches anything fails the guard).
+*/
+async function resolve(source) {
+	return typeof source === "function" ? await source() : source;
+}
+function registryEntries(app) {
+	const arc = app.arc;
+	const getAll = arc?.registry?.getAll;
+	if (typeof getAll !== "function") throw new Error("the app has no `app.arc.registry.getAll()`: pass an app booted by @classytic/arc");
+	return getAll.call(arc?.registry);
+}
+/** A `Caller` over `app.inject`, JSON in and out, sending `headers` (an auth token) with every request. */
+function injectCaller(app, headers = {}) {
+	const request = async (method, path, body) => {
+		const res = await app.inject({
+			method,
+			url: path,
+			headers: body === void 0 ? headers : {
+				"content-type": "application/json",
+				...headers
+			},
+			...body === void 0 ? {} : { payload: JSON.stringify(body) }
+		});
+		let parsed = res.body;
+		try {
+			parsed = res.body === "" ? void 0 : JSON.parse(res.body);
+		} catch {}
+		return {
+			status: res.statusCode,
+			body: parsed,
+			headers: res.headers
+		};
+	};
+	return {
+		request,
+		get: (path) => request("GET", path),
+		post: (path, body = {}) => request("POST", path, body),
+		put: (path, body = {}) => request("PUT", path, body),
+		patch: (path, body = {}) => request("PATCH", path, body),
+		delete: (path) => request("DELETE", path)
+	};
+}
+/** The app's route table as `{ path, methods }` rows, read from Fastify's radix-tree dump. */
+function routeTable(app) {
+	const dump = app.printRoutes({
+		commonPrefix: false,
+		includeHooks: false
+	});
+	const rows = [];
+	const stack = [];
+	for (const line of dump.split("\n")) {
+		const match = /^([│ ]*)[├└]── (.*?)(?: \(([A-Z, ]+)\))?$/.exec(line);
+		if (!match) continue;
+		const depth = (match[1] ?? "").length / 4;
+		stack.length = depth;
+		stack[depth] = match[2] ?? "";
+		const methods = (match[3] ?? "").split(",").map((m) => m.trim()).filter(Boolean);
+		if (methods.length === 0) continue;
+		const path = stack.join("").replace(/\/{2,}/g, "/").replace(/(.)\/$/, "$1");
+		rows.push({
+			path,
+			methods
+		});
+	}
+	return rows;
+}
+/** Methods a route table reports beside the real ones; never part of a contract. */
+const IMPLICIT_METHODS = /* @__PURE__ */ new Set(["HEAD", "OPTIONS"]);
+/** `/a/{id}/b`, `/a/:id|:other/b` and `/a/:id/b/` are one shape: `/a/:x/b`. */
+function shapeOf(path) {
+	return path.replace(/\{[^}]+\}/g, ":x").replace(/:[A-Za-z0-9_]+(?:\|:[A-Za-z0-9_]+)*/g, ":x").replace(/(.)\/+$/, "$1");
+}
+function exceptionKeys(list) {
+	if (list === void 0) return [];
+	if (typeof list[Symbol.iterator] === "function") return [...list];
+	return Object.keys(list);
+}
+/** Which of `declared` never matched anything: a stale exception hides nothing and must go. */
+function staleOf(declared, used) {
+	return declared.filter((key) => !used.has(key));
+}
+/** The failure text of a guard: problems, one per line. */
+function report(what, problems) {
+	return problems.length === 0 ? "" : `${what}:\n  ${problems.join("\n  ")}`;
+}
+/** Fails with the problems listed, one per line; passes when there are none. Use it with the `check*` functions inside a host's own tests. */
+function expectClean(what, problems) {
+	expect(problems, report(what, problems)).toEqual([]);
+}
+// src/conformance/client-drift.ts
+/**
+* Client-route drift: every route a client can emit exists in the OpenAPI document the real server
+* generates, and the body fields a client relies on appear in that document's schemas. The host
+* supplies what the client can emit (`{ method, path }` rows; a path may be a concrete URL or a
+* `{param}` / `:param` template). `dumpOpenApi` / `loadOpenApiDump` carry the document from the
+* server's test run to the client's, and refuse a dump older than the sources it describes.
+*/
+/** Spec path templates as matchers: `/api/x/{id}/y` accepts `/api/x/anything/y` and `/api/x/:id/y`. */
+function specMatcher(spec) {
+	const byMethod = /* @__PURE__ */ new Map();
+	for (const [path, item] of Object.entries(spec.paths ?? {})) {
+		const re = new RegExp(`^${path.split(/\{[^}]+\}/).map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[^/]+")}/?$`);
+		for (const method of Object.keys(item)) {
+			const list = byMethod.get(method.toUpperCase()) ?? [];
+			list.push({
+				path,
+				re
+			});
+			byMethod.set(method.toUpperCase(), list);
+		}
+	}
+	return (method, concrete) => {
+		const path = concrete.replace(/\?.*$/, "").replace(/:[A-Za-z0-9_]+/g, "x");
+		return byMethod.get(method.toUpperCase())?.find(({ re }) => re.test(path))?.path;
+	};
+}
+/** Client routes the document does not have (sorted, deduplicated, with their source). */
+function missingClientRoutes(spec, routes) {
+	const find = specMatcher(spec);
+	const missing = routes.filter((r) => !find(r.method, r.path)).map((r) => `${r.method.toUpperCase()} ${r.path}${r.source ? `   (${r.source})` : ""}`);
+	return [...new Set(missing)].sort();
+}
+function resolveRef(spec, schema) {
+	if (!schema?.$ref) return schema;
+	return spec.components?.schemas?.[schema.$ref.replace("#/components/schemas/", "")];
+}
+/** Every property name a schema offers, through refs and unions. */
+function propertyNames(spec, schema, depth = 0) {
+	const out = /* @__PURE__ */ new Set();
+	const resolved = resolveRef(spec, schema);
+	if (!resolved || depth > 6) return out;
+	for (const name of Object.keys(resolved.properties ?? {})) out.add(name);
+	for (const branch of [
+		...resolved.oneOf ?? [],
+		...resolved.allOf ?? [],
+		...resolved.anyOf ?? []
+	]) for (const name of propertyNames(spec, branch, depth + 1)) out.add(name);
+	return out;
+}
+function bodyFieldProblems(spec, check) {
+	const label = check.name ?? `${check.method.toUpperCase()} ${check.path}`;
+	const op = spec.paths?.[check.path]?.[check.method.toLowerCase()];
+	if (!op) return [`${label}: not in the document`];
+	const names = propertyNames(spec, check.in === "response" ? op.responses?.[check.status ?? "200"]?.content?.["application/json"]?.schema : op.requestBody?.content?.["application/json"]?.schema);
+	if (names.size === 0) return [`${label}: the document declares no ${check.in ?? "request"} schema`];
+	return check.fields.filter((f) => !names.has(f)).map((f) => `${label}: field "${f}" is not in the schema`);
+}
+async function checkClientDrift(opts) {
+	const spec = await resolve(opts.spec);
+	const routes = await resolve(opts.routes);
+	const problems = [];
+	const min = opts.minRoutes ?? 1;
+	if (routes.length < min) problems.push(`only ${routes.length} client routes supplied, expected at least ${min}`);
+	for (const m of missingClientRoutes(spec, routes)) problems.push(`client route missing from the document: ${m}`);
+	for (const check of opts.bodyFields ?? []) problems.push(...bodyFieldProblems(spec, check));
+	return problems;
+}
+/** Registers the drift guard as vitest tests. */
+function registerClientDriftGuard(opts) {
+	it("every route the client can emit exists in the OpenAPI document", async () => {
+		const spec = await resolve(opts.spec);
+		const routes = await resolve(opts.routes);
+		const problems = missingClientRoutes(spec, routes);
+		expect(problems, report("client routes missing from the document", problems)).toEqual([]);
+		expect(routes.length, "client routes supplied").toBeGreaterThanOrEqual(opts.minRoutes ?? 1);
+	});
+	if ((opts.bodyFields ?? []).length > 0) it("the body fields the client relies on are declared in the document", async () => {
+		const spec = await resolve(opts.spec);
+		const problems = (opts.bodyFields ?? []).flatMap((c) => bodyFieldProblems(spec, c));
+		expect(problems, report("body field drift", problems)).toEqual([]);
+	});
+}
+/** Write the document to `file` (the server side of the dump: `npm run openapi:dump`). */
+function dumpOpenApi(spec, file) {
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify({
+		...spec,
+		"x-generated-at": (/* @__PURE__ */ new Date()).toISOString()
+	}, null, 1)}\n`);
+}
+function newestSource(dir) {
+	let best = {
+		file: dir,
+		mtime: 0
+	};
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		const found = entry.isDirectory() ? newestSource(path) : /\.[cm]?tsx?$/.test(entry.name) ? {
+			file: path,
+			mtime: statSync(path).mtimeMs
+		} : best;
+		if (found.mtime > best.mtime) best = found;
+	}
+	return best;
+}
+/**
+* Read a dumped document. Throws when the dump is missing or older than any `.ts` file under
+* `sources`, so a stale document can never pass for the current API. `regenerate` names the command
+* in the message.
+*/
+function loadOpenApiDump(file, opts = {}) {
+	const how = opts.regenerate ?? "regenerate the OpenAPI dump on the server";
+	if (!existsSync(file)) throw new Error(`The OpenAPI dump is missing: ${file}\n${how}, then run this test again.`);
+	const dumped = statSync(file).mtimeMs;
+	for (const dir of opts.sources ?? []) {
+		const newest = newestSource(dir);
+		if (newest.mtime > dumped) throw new Error(`The OpenAPI dump is older than the sources it describes.\n  dump:  ${new Date(dumped).toISOString()}\n  newer: ${newest.file} (${new Date(newest.mtime).toISOString()})\n${how}.`);
+	}
+	return JSON.parse(readFileSync(file, "utf8"));
+}
+// src/conformance/collection-routes.ts
+/**
+* Collection routes and the trailing slash. A client addresses a collection by its bare path
+* (`GET /api/things?limit=5`, never `/api/things/?limit=5`), so the server must register the bare
+* form with the verbs the client sends, and serve it.
+*/
+async function checkCollectionRoutes(opts) {
+	const table = routeTable(await resolve(opts.app));
+	const problems = [];
+	for (const { path, methods } of opts.collections) {
+		if (path.length > 1 && path.endsWith("/")) {
+			problems.push(`${path}: a collection is addressed by its bare path`);
+			continue;
+		}
+		const row = table.find((r) => r.path === path);
+		if (!row) {
+			problems.push(`${path} is not registered`);
+			continue;
+		}
+		for (const method of methods) if (!row.methods.includes(method.toUpperCase())) problems.push(`${method.toUpperCase()} ${path} is not registered`);
+	}
+	if (opts.served) {
+		const caller = await resolve(opts.served.caller);
+		for (const path of opts.served.paths) {
+			const res = await caller.get(path);
+			if (res.status !== 200) problems.push(`GET ${path} answered ${res.status}`);
+		}
+	}
+	return problems;
+}
+/** Registers the collection route guard as a vitest test. */
+function registerCollectionRoutesGuard(opts) {
+	it("collection routes are registered bare, with the verbs the client sends", async () => {
+		const problems = await checkCollectionRoutes(opts);
+		expect(problems, report("collection route violations", problems)).toEqual([]);
+	});
+}
+// src/conformance/errors.ts
+/**
+* Every class of error response, provoked through the real app, is a `@classytic/repo-core`
+* `ErrorContract`: `{ code, message, status, details?, correlationId?, meta? }` with nothing else
+* on the body. The host supplies one `provoke` per class (it knows which request fails how); the
+* guard asserts the status, the code and the contract. `unknownRoute` has a built-in probe.
+*/
+const ERROR_CLASSES = [
+	"validation",
+	"unauthorized",
+	"forbidden",
+	"notFound",
+	"unknownRoute",
+	"conflict",
+	"duplicateKey"
+];
+const DEFAULT_STATUS = {
+	validation: 400,
+	unauthorized: 401,
+	forbidden: 403,
+	notFound: 404,
+	unknownRoute: 404,
+	conflict: 409,
+	duplicateKey: 409
+};
+const CONTRACT_KEYS = [
+	"code",
+	"message",
+	"status",
+	"details",
+	"correlationId",
+	"meta"
+];
+const DETAIL_KEYS = [
+	"path",
+	"code",
+	"message",
+	"meta"
+];
+/** The reasons a reply is not the expected `ErrorContract` (empty: it is one). */
+function errorContractProblems(reply, expected, allowedKeys = CONTRACT_KEYS) {
+	const problems = [];
+	if (reply.status !== expected.status) problems.push(`status ${reply.status}, expected ${expected.status}`);
+	const body = reply.body;
+	if (typeof body !== "object" || body === null || Array.isArray(body)) return [...problems, `body is not an object: ${JSON.stringify(body)}`];
+	const rec = body;
+	const foreign = Object.keys(rec).filter((k) => !allowedKeys.includes(k));
+	if (foreign.length > 0) problems.push(`foreign keys on the body: ${foreign.join(", ")}`);
+	if (typeof rec.code !== "string" || rec.code.length === 0) problems.push("`code` is not a non-empty string");
+	else if (typeof expected.code === "string" && rec.code !== expected.code) problems.push(`code "${rec.code}", expected "${expected.code}"`);
+	else if (expected.code instanceof RegExp && !expected.code.test(rec.code)) problems.push(`code "${rec.code}" does not match ${expected.code}`);
+	if (typeof rec.message !== "string" || rec.message.length === 0) problems.push("`message` is not a non-empty string");
+	if (rec.status !== expected.status) problems.push(`body.status is ${String(rec.status)}, expected ${expected.status}`);
+	if (rec.correlationId !== void 0 && typeof rec.correlationId !== "string") problems.push("`correlationId` is not a string");
+	if (rec.meta !== void 0 && (typeof rec.meta !== "object" || rec.meta === null)) problems.push("`meta` is not an object");
+	const details = rec.details;
+	if (details !== void 0 && !Array.isArray(details)) problems.push("`details` is not an array");
+	if (expected.details === "some" && !(Array.isArray(details) && details.length > 0)) problems.push("`details` is empty, expected field details");
+	if (expected.details === "none" && details !== void 0) problems.push("`details` present, expected none");
+	for (const detail of Array.isArray(details) ? details : []) {
+		const d = detail ?? {};
+		const odd = Object.keys(d).filter((k) => !DETAIL_KEYS.includes(k));
+		if (odd.length > 0) problems.push(`foreign keys on a detail: ${odd.join(", ")}`);
+		if (typeof d.code !== "string") problems.push("a detail has no string `code`");
+		if (typeof d.message !== "string") problems.push("a detail has no string `message`");
+		if (d.path !== void 0 && typeof d.path !== "string") problems.push("a detail `path` is not a string");
+		if (expected.detailCode !== void 0 && d.code !== expected.detailCode) problems.push(`a detail has code "${String(d.code)}", expected "${expected.detailCode}"`);
+	}
+	return problems;
+}
+/** Throws unless the reply is the expected `ErrorContract`; returns the body. */
+function expectErrorContract(reply, expected) {
+	const problems = errorContractProblems(reply, expected);
+	expect(problems, `${report("not an ErrorContract", problems)}\n  body: ${JSON.stringify(reply.body)}`).toEqual([]);
+	return reply.body;
+}
+async function checkErrorContracts(opts) {
+	const problems = [];
+	const probes = { ...opts.probes };
+	if (probes.unknownRoute === void 0 && opts.caller !== void 0) {
+		const caller = await resolve(opts.caller);
+		probes.unknownRoute = { provoke: () => caller.get("/__no_such_route__?token=secret") };
+	}
+	for (const cls of opts.require ?? ERROR_CLASSES) if (probes[cls] === void 0) problems.push(`${cls}: no probe supplied`);
+	for (const cls of ERROR_CLASSES) {
+		const entry = probes[cls];
+		if (entry === void 0) continue;
+		for (const probe of Array.isArray(entry) ? entry : [entry]) {
+			const reply = await probe.provoke();
+			const details = probe.details ?? (cls === "validation" || cls === "duplicateKey" ? "some" : void 0);
+			const detailCode = probe.detailCode ?? (cls === "duplicateKey" ? "duplicate_key" : void 0);
+			const found = errorContractProblems(reply, {
+				status: probe.status ?? DEFAULT_STATUS[cls],
+				...probe.code === void 0 ? {} : { code: probe.code },
+				...details === void 0 ? {} : { details },
+				...detailCode === void 0 ? {} : { detailCode }
+			}, opts.allowedKeys);
+			for (const p of found) problems.push(`${cls}: ${p}`);
+			if (cls === "unknownRoute" && JSON.stringify(reply.body).includes("secret")) problems.push("unknownRoute: the query string is echoed in the body");
+		}
+	}
+	return problems;
+}
+/** Registers the error contract guard as vitest tests. */
+function registerErrorContractGuard(opts) {
+	it("every error class is an ErrorContract body", async () => {
+		const problems = await checkErrorContracts(opts);
+		expect(problems, report("error contract violations", problems)).toEqual([]);
+	});
+}
+// src/conformance/filter-declarations.ts
+/**
+* UI filters, search and sorts against the list route's declared query contract. The host lists what
+* each screen sends (`{ route, filters: [{ queryField, op }], search, sorts }`); each must be allowed by
+* the list operation in the OpenAPI document: a query parameter `field` / `field[op]`, or the arc
+* `x-arc-query` extension (`filterFields`, `operators`, `sortFields`).
+*/
+/** The URL operators a filter really sends: `between` is `gte` + `lte`. */
+function wireOps(op) {
+	return op === "between" ? ["gte", "lte"] : [op];
+}
+async function checkFilterDeclarations(opts) {
+	const spec = await resolve(opts.spec);
+	const find = specMatcher(spec);
+	const problems = [];
+	for (const decl of await resolve(opts.declarations)) {
+		const path = find("GET", decl.route);
+		const op = path ? spec.paths?.[path]?.get : void 0;
+		if (!op) {
+			problems.push(`${decl.route}: no GET operation in the document`);
+			continue;
+		}
+		const params = new Set((op["parameters"] ?? []).map((p) => p.name));
+		const contract = op["x-arc-query"];
+		for (const { queryField, op: filterOp = "eq" } of decl.filters ?? []) for (const wire of wireOps(filterOp)) {
+			const name = wire === "eq" ? queryField : `${queryField}[${wire}]`;
+			if (!(params.has(name) || contract?.filterFields?.includes(queryField) === true && (wire === "eq" || !contract.operators || contract.operators.includes(wire)))) problems.push(`${decl.route}: filter ${name} is not declared by the route`);
+		}
+		if (decl.search && !params.has("search")) problems.push(`${decl.route}: search is not declared by the route`);
+		for (const sort of decl.sorts ?? []) {
+			const field = sort.replace(/^[+-]/, "");
+			if (!params.has("sort") && !contract?.sortFields) problems.push(`${decl.route}: sort ${field} is not declared by the route`);
+			else if (contract?.sortFields && !contract.sortFields.includes(field)) problems.push(`${decl.route}: sort ${field} is not an allowed sort field`);
+		}
+	}
+	return problems;
+}
+/** Registers the declaration check as a vitest test. */
+function registerFilterDeclarationsGuard(opts) {
+	it("every UI filter, search and sort is allowed by its list route", async () => {
+		const problems = await checkFilterDeclarations(opts);
+		expect(problems, report("undeclared list queries", problems)).toEqual([]);
+	});
+}
+// src/conformance/list-envelope.ts
+/**
+* Every list route answers one canonical `@classytic/repo-core` envelope. The route table is read
+* from the running app: each parameterless GET under `prefix` is called as `caller` and, when it
+* answers a list, the answer must be an offset page (`method: 'offset'` with its page numbers), a
+* keyset page, or a bare `{ data: [...] }`. Old shapes (`{ docs, total }`, `{ data, pagination }`,
+* a bare array, `rows`) fail. A GET that is not a list is named in `notLists` with the reason, so a
+* new route (or a deviating list) is a decision somebody has to make.
+*/
+const DEFAULT_SKIP = /\/(stream|export|content|download)(\/|$)/;
+const DEFAULT_FORBIDDEN = [
+	"docs",
+	"rows",
+	"items",
+	"pagination",
+	"totalPages"
+];
+const OFFSET_NUMBERS = [
+	"page",
+	"limit",
+	"total",
+	"pages"
+];
+/** The reasons a body is not a canonical list (empty: it is one). */
+function listEnvelopeProblems(body, methods = ["offset", "keyset"], forbidden = DEFAULT_FORBIDDEN) {
+	const keys = Object.keys(body);
+	const problems = [];
+	const old = forbidden.filter((k) => keys.includes(k));
+	if (old.length > 0) problems.push(`carries ${old.join(", ")}`);
+	const rec = body;
+	if (!("method" in rec)) {
+		if (keys.length !== 1) problems.push(`a list with paging numbers but no method (${keys.join(", ")})`);
+		return problems;
+	}
+	const method = rec.method;
+	if (typeof method !== "string" || !methods.includes(method)) problems.push(`method "${String(method)}" is not one of ${methods.join(", ")}`);
+	else if (method === "offset") {
+		for (const k of OFFSET_NUMBERS) if (typeof rec[k] !== "number") problems.push(`offset page: \`${k}\` is not a number`);
+		for (const k of ["hasNext", "hasPrev"]) if (typeof rec[k] !== "boolean") problems.push(`offset page: \`${k}\` is not a boolean`);
+	} else {
+		if (typeof rec.limit !== "number") problems.push("keyset page: `limit` is not a number");
+		if (typeof rec.hasMore !== "boolean") problems.push("keyset page: `hasMore` is not a boolean");
+		if (rec.next !== null && typeof rec.next !== "string") problems.push("keyset page: `next` is not a string or null");
+	}
+	return problems;
+}
+async function checkListEnvelopes(opts) {
+	const app = await resolve(opts.app);
+	const caller = await resolve(opts.caller);
+	const skip = opts.skip ?? DEFAULT_SKIP;
+	const notLists = exceptionKeys(opts.notLists);
+	const custom = exceptionKeys(opts.customShapes);
+	const known = /* @__PURE__ */ new Set();
+	const getPaths = /* @__PURE__ */ new Set();
+	for (const { path, methods } of routeTable(app)) {
+		if (!methods.some((m) => m === "GET")) continue;
+		known.add(path);
+		if (path.includes(":") || path.includes("*") || skip.test(path)) continue;
+		if (opts.prefix !== void 0 && !path.startsWith(opts.prefix)) continue;
+		getPaths.add(path);
+	}
+	const probed = [...getPaths].sort();
+	const problems = [];
+	const lists = [];
+	for (const path of probed) {
+		if (notLists.includes(path) || custom.includes(path)) continue;
+		const res = await caller.get(path);
+		if (res.status !== 200) continue;
+		const body = res.body;
+		if (Array.isArray(body)) {
+			problems.push(`${path}: a bare array`);
+			continue;
+		}
+		const data = body?.data;
+		if (typeof body !== "object" || body === null || !Array.isArray(data)) {
+			const shape = typeof body === "object" && body !== null ? Object.keys(body).join(", ") : typeof body;
+			problems.push(`${path}: not a list and not in notLists (${shape})`);
+			continue;
+		}
+		lists.push(path);
+		for (const p of listEnvelopeProblems(body, opts.methods, opts.forbiddenKeys)) problems.push(`${path}: ${p}`);
+	}
+	for (const key of staleOf([...notLists, ...custom], known)) problems.push(`stale exception ${key}: no such GET route is registered`);
+	const min = opts.minRoutes ?? 1;
+	if (probed.length < min) problems.push(`only ${probed.length} GET routes probed, expected at least ${min}`);
+	for (const path of opts.expectLists ?? []) if (!lists.includes(path)) problems.push(`${path} was expected to answer a list and did not`);
+	return {
+		problems,
+		lists,
+		probed
+	};
+}
+/** Registers the list envelope guard as vitest tests. */
+function registerListEnvelopeGuard(opts) {
+	it("every GET list route answers the canonical envelope", async () => {
+		const { problems } = await checkListEnvelopes(opts);
+		expect(problems, report("list envelope violations", problems)).toEqual([]);
+	});
+}
+// src/conformance/naming.ts
+/**
+* Route naming conventions, read from the running app so a new route cannot drift:
+*   - the verbs of the action router (`POST /<resource>/:id/action`) match `verbPattern`;
+*   - each path rule names a family of routes (e.g. every path containing `sweep`) and the exact
+*     `METHOD path` set that family may consist of;
+*   - `forbiddenPaths` are spellings that must not be routed at all.
+* Verbs a package fixes belong in `exemptVerbs`; one that no longer exists fails as stale.
+*/
+async function checkNaming(opts) {
+	const app = await resolve(opts.app);
+	const pattern = opts.verbPattern ?? /^[a-z][a-zA-Z0-9]*$/;
+	const exempt = exceptionKeys(opts.exemptVerbs);
+	const problems = [];
+	const verbs = registryEntries(app).flatMap((entry) => (entry.actions ?? []).map((a) => ({
+		resource: entry.name,
+		verb: a.name
+	})));
+	const seen = /* @__PURE__ */ new Set();
+	for (const { resource, verb } of verbs) {
+		if (exempt.includes(verb)) {
+			seen.add(verb);
+			continue;
+		}
+		if (!pattern.test(verb)) problems.push(`action ${resource}.${verb} does not match ${pattern}`);
+	}
+	for (const verb of staleOf(exempt, seen)) problems.push(`stale exempt verb ${verb}`);
+	for (const verb of opts.requiredVerbs ?? []) if (!verbs.some((v) => v.verb === verb)) problems.push(`expected action verb ${verb} is not registered`);
+	const min = opts.minVerbs ?? 1;
+	if (verbs.length < min) problems.push(`only ${verbs.length} action verbs found, expected at least ${min}`);
+	const routes = routeTable(app);
+	const label = (r) => `${r.methods.filter((m) => !IMPLICIT_METHODS.has(m)).join("+")} ${r.path}`;
+	for (const rule of opts.pathRules ?? []) {
+		const found = routes.filter((r) => rule.match.test(r.path)).map(label).sort();
+		const want = [...rule.allowed].sort();
+		for (const route of found) if (!want.includes(route)) problems.push(`${rule.name}: unexpected route ${route}`);
+		for (const route of want) if (!found.includes(route)) problems.push(`${rule.name}: missing route ${route}`);
+	}
+	for (const re of opts.forbiddenPaths ?? []) for (const r of routes.filter((row) => re.test(row.path))) problems.push(`forbidden path ${label(r)} (${re})`);
+	return problems;
+}
+/** Registers the naming guard as vitest tests. */
+function registerNamingGuard(opts) {
+	it("action verbs and named route families follow the naming rules", async () => {
+		const problems = await checkNaming(opts);
+		expect(problems, report("route naming violations", problems)).toEqual([]);
+	});
+}
+// src/conformance/openapi.ts
+/**
+* The generated API reference (an OpenAPI 3 document): it names every route the server answers,
+* says which of them need a sign-in, and carries no configuration value. The document is supplied
+* by the host (`fetchOpenApi(caller)` reads it from the running app).
+*/
+const OPENAPI_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"patch"
+];
+/** Read the document from the running app (default `/openapi.json`). */
+async function fetchOpenApi(caller, path = "/openapi.json") {
+	const res = await caller.get(path);
+	if (res.status !== 200) throw new Error(`GET ${path} answered ${res.status}, expected the OpenAPI document`);
+	return res.body;
+}
+const DEFAULT_SECRET_PATTERNS = [/mongodb(\+srv)?:\/\//i, /redis:\/\//i];
+function matchesPublic(rule, path) {
+	if (typeof rule.path === "string") return rule.path === path;
+	if (rule.path instanceof RegExp) return rule.path.test(path);
+	return rule.path(path);
+}
+function operationsOf(spec) {
+	const out = [];
+	for (const [path, item] of Object.entries(spec.paths ?? {})) for (const method of OPENAPI_METHODS) {
+		const op = item[method];
+		if (op) out.push({
+			method,
+			path,
+			op
+		});
+	}
+	return out;
+}
+/** The document is OpenAPI 3, prefixed, and has no trailing-slash path. */
+async function checkOpenApiShape(opts) {
+	const spec = await resolve(opts.spec);
+	const problems = [];
+	if (!/^3\./.test(String(spec.openapi))) problems.push(`openapi is "${String(spec.openapi)}", expected 3.x`);
+	const ops = operationsOf(spec);
+	const min = opts.minOperations ?? 1;
+	if (ops.length < min) problems.push(`only ${ops.length} operations documented, expected at least ${min}`);
+	const rules = opts.publicOperations ?? [];
+	for (const path of Object.keys(spec.paths ?? {})) {
+		if (path.length > 1 && path.endsWith("/")) problems.push(`${path} ends with a slash`);
+		if (opts.prefix !== void 0 && !path.startsWith(opts.prefix) && !rules.some((r) => matchesPublic(r, path))) problems.push(`${path} is outside the ${opts.prefix} prefix`);
+	}
+	return problems;
+}
+/** Every route in the table is documented (once, in its bare form). */
+async function checkRoutesDocumented(opts) {
+	if (opts.app === void 0) return ["checkRoutesDocumented needs `app`"];
+	const spec = await resolve(opts.spec);
+	const app = await resolve(opts.app);
+	const listed = /* @__PURE__ */ new Set();
+	for (const { method, path } of operationsOf(spec)) listed.add(`${method.toUpperCase()} ${shapeOf(path)}`);
+	const problems = [];
+	for (const row of routeTable(app)) {
+		if (opts.undocumented?.test(row.path)) continue;
+		for (const method of row.methods) {
+			if (IMPLICIT_METHODS.has(method)) continue;
+			if (!listed.has(`${method} ${shapeOf(row.path)}`)) problems.push(`${method} ${row.path} is not in the document`);
+		}
+	}
+	return problems;
+}
+/**
+* Every operation requires a security scheme (its own `security`, else the document's), except the
+* public list; a public rule that matches no operation fails as stale.
+*/
+async function checkSecurity(opts) {
+	const spec = await resolve(opts.spec);
+	const rules = opts.publicOperations ?? [];
+	const used = /* @__PURE__ */ new Set();
+	const problems = [];
+	for (const { method, path, op } of operationsOf(spec)) {
+		const idx = rules.findIndex((r) => matchesPublic(r, path));
+		if (idx >= 0) {
+			used.add(idx);
+			continue;
+		}
+		const effective = op.security ?? spec.security;
+		if (!Array.isArray(effective) || effective.length === 0) problems.push(`${method.toUpperCase()} ${path} has no security requirement`);
+	}
+	rules.forEach((rule, i) => {
+		if (!used.has(i)) problems.push(`stale public operation (${rule.why}): ${String(rule.path)} matches nothing`);
+	});
+	return problems;
+}
+/** An anonymous GET of every documented, protected, parameterless path is refused with 401. */
+async function checkAnonymousRefused(opts, expected = 401) {
+	if (opts.anonymous === void 0) return ["checkAnonymousRefused needs `anonymous`"];
+	const spec = await resolve(opts.spec);
+	const anon = await resolve(opts.anonymous);
+	const skip = opts.skipAnonymous ?? /\{|\/stream$/;
+	const rules = opts.publicOperations ?? [];
+	const problems = [];
+	for (const { method, path, op } of operationsOf(spec)) {
+		if (method !== "get" || skip.test(path) || rules.some((r) => matchesPublic(r, path))) continue;
+		const effective = op.security ?? spec.security;
+		if (!Array.isArray(effective) || effective.length === 0) continue;
+		const res = await anon.get(path);
+		if (res.status !== expected) problems.push(`GET ${path} -> ${res.status}, expected ${expected}`);
+	}
+	return problems;
+}
+/** The serialised document carries no configuration value. */
+async function checkNoSecrets(opts) {
+	const text = JSON.stringify(await resolve(opts.spec));
+	const problems = [];
+	const values = opts.secretValues === void 0 ? [] : await resolve(opts.secretValues);
+	for (const value of values) if (typeof value === "string" && value.length >= 6 && text.includes(value)) problems.push("a configuration value is in the document");
+	for (const re of opts.secretPatterns ?? DEFAULT_SECRET_PATTERNS) if (re.test(text)) problems.push(`the document matches ${re}`);
+	return [...new Set(problems)];
+}
+/** Registers the OpenAPI guards as vitest tests (the optional ones only when their input is given). */
+function registerOpenApiGuard(opts) {
+	const run = (name, check) => it(name, async () => {
+		const problems = await check();
+		expect(problems, report(name, problems)).toEqual([]);
+	});
+	run("the document is OpenAPI 3, prefixed, with bare paths", () => checkOpenApiShape(opts));
+	if (opts.app !== void 0) run("the document names every route the server answers", () => checkRoutesDocumented(opts));
+	run("every operation requires a sign-in, except the public list", () => checkSecurity(opts));
+	if (opts.anonymous !== void 0) run("an anonymous request to a protected route is refused", () => checkAnonymousRefused(opts));
+	run("the document carries no configuration value", () => checkNoSecrets(opts));
+}
+// src/conformance/refusal.ts
+/**
+* A refused request does no work. Every mutating route is called as an anonymous and as an
+* unprivileged caller; each call must be refused (401/403) AND leave the host's state untouched.
+*
+* Why the state check and not the status alone: a gate that sends its 403 from an async hook
+* without returning the reply still answers 403 when two or more async `preSerialization` /
+* `onSend` hooks defer the write, yet Fastify goes on to run the handler. The status is right
+* and the side effect already happened, so only a before/after comparison catches it.
+*/
+const MUTATING = /* @__PURE__ */ new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+async function derive(opts) {
+	const keys = [];
+	if (opts.routes !== void 0) return {
+		routes: [...await resolve(opts.routes)],
+		keys
+	};
+	if (opts.app === void 0) throw new Error("checkRefusalDoesNoWork needs `app` or `routes`");
+	const table = routeTable(await resolve(opts.app));
+	const value = opts.paramValue ?? "000000000000000000000001";
+	const routes = [];
+	for (const row of table) {
+		if (opts.prefix !== void 0 && !row.path.startsWith(opts.prefix)) continue;
+		for (const method of row.methods) {
+			if (IMPLICIT_METHODS.has(method) || !MUTATING.has(method)) continue;
+			const key = `${method} ${row.path}`;
+			keys.push(key);
+			routes.push({
+				method,
+				path: row.path.replace(/\{[^}]+\}/g, value).replace(/:[A-Za-z0-9_]+(?:\|:[A-Za-z0-9_]+)*/g, value).replace(/\*/g, "x")
+			});
+		}
+	}
+	return {
+		routes,
+		keys
+	};
+}
+/** Problems found; empty when every refusal answered and left the snapshot unchanged. */
+async function checkRefusalDoesNoWork(opts) {
+	const problems = [];
+	const callers = [];
+	if (opts.anonymous !== void 0) callers.push(["anonymous", await resolve(opts.anonymous)]);
+	if (opts.unprivileged !== void 0) callers.push(["unprivileged", await resolve(opts.unprivileged)]);
+	if (callers.length === 0) return ["checkRefusalDoesNoWork needs `anonymous` and/or `unprivileged`"];
+	const refused = opts.refusedStatuses ?? [401, 403];
+	const settle = opts.settleMs ?? 25;
+	const excluded = exceptionKeys(opts.exclude);
+	const { routes, keys } = await derive(opts);
+	const used = /* @__PURE__ */ new Set();
+	let checked = 0;
+	for (const [index, route] of routes.entries()) {
+		const method = route.method.toUpperCase();
+		const key = keys[index] ?? `${method} ${route.path}`;
+		if (excluded.includes(key) || excluded.includes(`${method} ${route.path}`)) {
+			used.add(key);
+			used.add(`${method} ${route.path}`);
+			continue;
+		}
+		checked++;
+		for (const [who, caller] of callers) {
+			const before = await opts.snapshot();
+			const body = method === "DELETE" ? void 0 : route.body ?? {};
+			const reply = await caller.request(method, route.path, body);
+			await new Promise((done) => setTimeout(done, settle));
+			const after = await opts.snapshot();
+			const label = `${who} ${method} ${route.path}`;
+			if (!refused.includes(reply.status)) problems.push(`${label}: answered ${reply.status}, expected a refusal (${refused.join("/")})`);
+			if (!isDeepStrictEqual(before, after)) problems.push(`${label}: answered ${reply.status} but the snapshot changed: the handler ran after the refusal (a gate must \`return reply\` after \`reply.send\`, or throw)`);
+		}
+	}
+	if (checked < (opts.minRoutes ?? 1)) problems.push(`only ${checked} mutating route(s) checked, expected at least ${opts.minRoutes ?? 1}`);
+	for (const key of staleOf(excluded, used)) problems.push(`stale exclusion ${key}: no such mutating route is checked`);
+	return problems;
+}
+/** Registers the refusal guard as a vitest test. */
+function registerRefusalDoesNoWorkGuard(opts) {
+	it("a refused request does no work (state is unchanged after every 401/403)", async () => {
+		const problems = await checkRefusalDoesNoWork(opts);
+		expect(problems, report("refusal violations", problems)).toEqual([]);
+	});
+}
+// src/conformance/route-schemas.ts
+/**
+* Request validation lives at the route layer. Read from the app's resource registry so a new route
+* cannot slip past:
+*   - every entry of every `actions` map declares its schema (`actionSchemas`);
+*   - every POST / PUT / PATCH custom route declares a `body` schema, unless it takes no JSON body or
+*     a shared package mounts it, both listed with the reason.
+* The exception lists are the only way out, and an entry that no longer matches anything fails too.
+*/
+async function checkRouteSchemas(opts) {
+	const app = await resolve(opts.app);
+	const actionOk = exceptionKeys(opts.actionExceptions);
+	const routeOk = exceptionKeys(opts.routeExceptions);
+	const methods = (opts.bodyMethods ?? [
+		"POST",
+		"PUT",
+		"PATCH"
+	]).map((m) => m.toUpperCase());
+	const problems = [];
+	const seenActions = /* @__PURE__ */ new Set();
+	const seenRoutes = /* @__PURE__ */ new Set();
+	let actions = 0;
+	let routes = 0;
+	for (const entry of registryEntries(app)) {
+		for (const action of entry.actions ?? []) {
+			actions++;
+			const key = `${entry.name}.${action.name}`;
+			const allowed = actionOk.includes(key);
+			if (allowed) seenActions.add(key);
+			if (!action.schema && !allowed) problems.push(`action ${key} declares no schema (add it to actionSchemas)`);
+		}
+		for (const route of entry.customRoutes ?? []) {
+			if (!methods.includes(route.method.toUpperCase())) continue;
+			routes++;
+			const key = `${entry.name} ${route.method.toUpperCase()} ${route.path}`;
+			const allowed = routeOk.includes(key);
+			if (allowed) seenRoutes.add(key);
+			if (!route.schema?.body && !allowed) problems.push(`route ${key} declares no body schema`);
+		}
+	}
+	for (const key of staleOf(actionOk, seenActions)) problems.push(`stale action exception ${key}`);
+	for (const key of staleOf(routeOk, seenRoutes)) problems.push(`stale route exception ${key}`);
+	const min = opts.minActions ?? 1;
+	if (actions < min) problems.push(`only ${actions} actions found, expected at least ${min}`);
+	return {
+		problems,
+		actions,
+		routes
+	};
+}
+/** Registers the schema guard as vitest tests. */
+function registerRouteSchemaGuard(opts) {
+	it("every action declares a schema and every write route a body schema", async () => {
+		const { problems } = await checkRouteSchemas(opts);
+		expect(problems, report("route-layer validation gaps", problems)).toEqual([]);
+	});
+}
+export { ERROR_CLASSES, OPENAPI_METHODS, bodyFieldProblems, checkAnonymousRefused, checkClientDrift, checkCollectionRoutes, checkErrorContracts, checkFilterDeclarations, checkListEnvelopes, checkNaming, checkNoSecrets, checkOpenApiShape, checkRefusalDoesNoWork, checkRouteSchemas, checkRoutesDocumented, checkSecurity, dumpOpenApi, errorContractProblems, expectClean, expectErrorContract, fetchOpenApi, injectCaller, listEnvelopeProblems, loadOpenApiDump, missingClientRoutes, propertyNames, registerClientDriftGuard, registerCollectionRoutesGuard, registerErrorContractGuard, registerFilterDeclarationsGuard, registerListEnvelopeGuard, registerNamingGuard, registerOpenApiGuard, registerRefusalDoesNoWorkGuard, registerRouteSchemaGuard, resolveRef, routeTable, shapeOf, specMatcher };