@classytic/arc-testkit 0.6.0 → 0.7.0

package/dist/conformance.mjs

@@ -8,7 +8,7 @@ import { isDeepStrictEqual } from "node:util";
 * 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) {
+async function resolve$1(source) {
 	return typeof source === "function" ? await source() : source;
 }
 function registryEntries(app) {
@@ -145,17 +145,37 @@ function propertyNames(spec, schema, depth = 0) {
 	]) for (const name of propertyNames(spec, branch, depth + 1)) out.add(name);
 	return out;
 }
+/**
+* Every literal value a schema accepts: `enum` and `const` at its root, through refs and unions,
+* and on its top-level properties (an action router's `action` discriminator).
+*/
+function schemaValues(spec, schema, depth = 0) {
+	const out = /* @__PURE__ */ new Set();
+	const resolved = resolveRef(spec, schema);
+	if (!resolved || depth > 6) return out;
+	for (const value of resolved.enum ?? []) out.add(value);
+	if (resolved.const !== void 0) out.add(resolved.const);
+	for (const branch of [
+		...resolved.oneOf ?? [],
+		...resolved.allOf ?? [],
+		...resolved.anyOf ?? []
+	]) for (const value of schemaValues(spec, branch, depth + 1)) out.add(value);
+	if (depth === 0) for (const prop of Object.values(resolved.properties ?? {})) for (const value of schemaValues(spec, prop, depth + 1)) out.add(value);
+	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);
+	const schema = check.in === "response" ? op.responses?.[check.status ?? "200"]?.content?.["application/json"]?.schema : op.requestBody?.content?.["application/json"]?.schema;
+	const names = propertyNames(spec, 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`);
+	const accepted = check.values?.length ? schemaValues(spec, schema) : /* @__PURE__ */ new Set();
+	return [...check.fields.filter((f) => !names.has(f)).map((f) => `${label}: field "${f}" is not in the schema`), ...(check.values ?? []).filter((v) => !accepted.has(v)).map((v) => `${label}: value ${JSON.stringify(v)} is not one the schema accepts`)];
 }
 async function checkClientDrift(opts) {
-	const spec = await resolve(opts.spec);
-	const routes = await resolve(opts.routes);
+	const spec = await resolve$1(opts.spec);
+	const routes = await resolve$1(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}`);
@@ -166,14 +186,14 @@ async function checkClientDrift(opts) {
 /** 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 spec = await resolve$1(opts.spec);
+		const routes = await resolve$1(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 spec = await resolve$1(opts.spec);
 		const problems = (opts.bodyFields ?? []).flatMap((c) => bodyFieldProblems(spec, c));
 		expect(problems, report("body field drift", problems)).toEqual([]);
 	});
@@ -223,7 +243,7 @@ function loadOpenApiDump(file, opts = {}) {
 * form with the verbs the client sends, and serve it.
 */
 async function checkCollectionRoutes(opts) {
-	const table = routeTable(await resolve(opts.app));
+	const table = routeTable(await resolve$1(opts.app));
 	const problems = [];
 	for (const { path, methods } of opts.collections) {
 		if (path.length > 1 && path.endsWith("/")) {
@@ -238,7 +258,7 @@ async function checkCollectionRoutes(opts) {
 		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);
+		const caller = await resolve$1(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}`);
@@ -333,7 +353,7 @@ 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);
+		const caller = await resolve$1(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`);
@@ -375,10 +395,10 @@ function wireOps(op) {
 	return op === "between" ? ["gte", "lte"] : [op];
 }
 async function checkFilterDeclarations(opts) {
-	const spec = await resolve(opts.spec);
+	const spec = await resolve$1(opts.spec);
 	const find = specMatcher(spec);
 	const problems = [];
-	for (const decl of await resolve(opts.declarations)) {
+	for (const decl of await resolve$1(opts.declarations)) {
 		const path = find("GET", decl.route);
 		const op = path ? spec.paths?.[path]?.get : void 0;
 		if (!op) {
@@ -454,8 +474,8 @@ function listEnvelopeProblems(body, methods = ["offset", "keyset"], forbidden =
 	return problems;
 }
 async function checkListEnvelopes(opts) {
-	const app = await resolve(opts.app);
-	const caller = await resolve(opts.caller);
+	const app = await resolve$1(opts.app);
+	const caller = await resolve$1(opts.caller);
 	const skip = opts.skip ?? DEFAULT_SKIP;
 	const notLists = exceptionKeys(opts.notLists);
 	const custom = exceptionKeys(opts.customShapes);
@@ -516,7 +536,7 @@ function registerListEnvelopeGuard(opts) {
 * 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 app = await resolve$1(opts.app);
 	const pattern = opts.verbPattern ?? /^[a-z][a-zA-Z0-9]*$/;
 	const exempt = exceptionKeys(opts.exemptVerbs);
 	const problems = [];
@@ -593,7 +613,7 @@ function operationsOf(spec) {
 }
 /** The document is OpenAPI 3, prefixed, and has no trailing-slash path. */
 async function checkOpenApiShape(opts) {
-	const spec = await resolve(opts.spec);
+	const spec = await resolve$1(opts.spec);
 	const problems = [];
 	if (!/^3\./.test(String(spec.openapi))) problems.push(`openapi is "${String(spec.openapi)}", expected 3.x`);
 	const ops = operationsOf(spec);
@@ -609,8 +629,8 @@ async function checkOpenApiShape(opts) {
 /** 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 spec = await resolve$1(opts.spec);
+	const app = await resolve$1(opts.app);
 	const listed = /* @__PURE__ */ new Set();
 	for (const { method, path } of operationsOf(spec)) listed.add(`${method.toUpperCase()} ${shapeOf(path)}`);
 	const problems = [];
@@ -628,7 +648,7 @@ async function checkRoutesDocumented(opts) {
 * public list; a public rule that matches no operation fails as stale.
 */
 async function checkSecurity(opts) {
-	const spec = await resolve(opts.spec);
+	const spec = await resolve$1(opts.spec);
 	const rules = opts.publicOperations ?? [];
 	const used = /* @__PURE__ */ new Set();
 	const problems = [];
@@ -649,8 +669,8 @@ async function checkSecurity(opts) {
 /** 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 spec = await resolve$1(opts.spec);
+	const anon = await resolve$1(opts.anonymous);
 	const skip = opts.skipAnonymous ?? /\{|\/stream$/;
 	const rules = opts.publicOperations ?? [];
 	const problems = [];
@@ -665,9 +685,9 @@ async function checkAnonymousRefused(opts, expected = 401) {
 }
 /** The serialised document carries no configuration value. */
 async function checkNoSecrets(opts) {
-	const text = JSON.stringify(await resolve(opts.spec));
+	const text = JSON.stringify(await resolve$1(opts.spec));
 	const problems = [];
-	const values = opts.secretValues === void 0 ? [] : await resolve(opts.secretValues);
+	const values = opts.secretValues === void 0 ? [] : await resolve$1(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)];
@@ -693,6 +713,11 @@ function registerOpenApiGuard(opts) {
 * 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.
+*
+* Action routes: arc validates `POST …/:id/action` against the discriminated body (`{ action, …}`)
+* before the verb's permission runs, so a bare `{}` answers 400 and never reaches the gate. With
+* `actionBodies`, each derived action route becomes one call per registered verb, with that verb's
+* body.
 */
 const MUTATING = /* @__PURE__ */ new Set([
 	"POST",
@@ -700,73 +725,194 @@ const MUTATING = /* @__PURE__ */ new Set([
 	"PATCH",
 	"DELETE"
 ]);
-async function derive(opts) {
-	const keys = [];
-	if (opts.routes !== void 0) return {
-		routes: [...await resolve(opts.routes)],
-		keys
+const CALLERS = ["anonymous", "unprivileged"];
+const DEFAULT_NAME = "a refused request does no work (state is unchanged after every 401/403)";
+function isCallerExceptions(value) {
+	if (typeof value[Symbol.iterator] === "function") return false;
+	const entries = Object.entries(value);
+	return entries.length > 0 && entries.every(([key, list]) => (key === "anonymous" || key === "unprivileged") && typeof list !== "string");
+}
+function concrete(path, value) {
+	return path.replace(/\{[^}]+\}/g, value).replace(/:[A-Za-z0-9_]+(?:\|:[A-Za-z0-9_]+)*/g, value).replace(/\*/g, "x");
+}
+/** The resource whose prefix the path shape carries at a segment boundary; the longest prefix wins. */
+function resourceOf(shape, entries) {
+	let best;
+	for (const entry of entries) {
+		const prefix = entry.prefix === void 0 ? "" : shapeOf(entry.prefix);
+		if (prefix === "" || prefix === "/") continue;
+		for (let at = shape.indexOf(prefix); at !== -1; at = shape.indexOf(prefix, at + 1)) {
+			const rest = shape.slice(at + prefix.length);
+			if (rest !== "" && !rest.startsWith("/")) continue;
+			if (best === void 0 || prefix.length > best.length) best = {
+				entry,
+				rest,
+				length: prefix.length
+			};
+		}
+	}
+	return best && {
+		entry: best.entry,
+		rest: best.rest
 	};
+}
+async function derive(opts) {
+	if (opts.routes !== void 0) return (await resolve$1(opts.routes)).map((route) => {
+		const method = route.method.toUpperCase();
+		return {
+			method,
+			path: route.path,
+			keys: [`${method} ${route.path}`],
+			body: route.body
+		};
+	});
 	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 = [];
+	const app = await resolve$1(opts.app);
+	const table = routeTable(app);
+	const withActions = opts.actionBodies !== void 0;
+	const needsRegistry = withActions || typeof opts.paramValue === "function";
+	let entries = [];
+	if (withActions) entries = registryEntries(app);
+	else if (needsRegistry) try {
+		entries = registryEntries(app);
+	} catch {}
+	const param = async (method, path, resource) => typeof opts.paramValue === "function" ? await opts.paramValue({
+		method,
+		path,
+		resource
+	}) : opts.paramValue ?? "000000000000000000000001";
+	const planned = [];
 	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")
-			});
+			const owner = needsRegistry ? resourceOf(shapeOf(row.path), entries) : void 0;
+			const path = concrete(row.path, await param(method, row.path, owner?.entry.name));
+			const keys = key === `${method} ${path}` ? [key] : [key, `${method} ${path}`];
+			const mount = owner?.rest === "/:x/action" ? "id" : owner?.rest === "/action" ? "root" : void 0;
+			if (!withActions || method !== "POST" || owner === void 0 || mount === void 0) {
+				planned.push({
+					method,
+					path,
+					keys
+				});
+				continue;
+			}
+			const verbs = (owner.entry.actions ?? []).filter((a) => a.id !== false === (mount === "id"));
+			if (verbs.length === 0) {
+				planned.push({
+					method,
+					path,
+					keys
+				});
+				continue;
+			}
+			for (const action of verbs) {
+				const verbKey = `${owner.entry.name}.${action.name}`;
+				const source = opts.actionBodies?.[verbKey];
+				planned.push({
+					method,
+					path,
+					keys: [...keys, verbKey],
+					verb: {
+						resource: owner.entry.name,
+						action: action.name,
+						key: verbKey,
+						...source === void 0 ? {} : { source }
+					}
+				});
+			}
 		}
 	}
-	return {
-		routes,
-		keys
-	};
+	return planned;
 }
 /** 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 (opts.anonymous !== void 0) callers.push(["anonymous", await resolve$1(opts.anonymous)]);
+	if (opts.unprivileged !== void 0) callers.push(["unprivileged", await resolve$1(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();
+	const perCaller = opts.exclude !== void 0 && isCallerExceptions(opts.exclude);
+	const shared = perCaller ? [] : exceptionKeys(opts.exclude);
+	const own = {
+		anonymous: [],
+		unprivileged: []
+	};
+	if (perCaller) {
+		const lists = opts.exclude;
+		for (const who of CALLERS) own[who] = exceptionKeys(lists[who]);
+	}
+	const planned = await derive(opts);
+	const usedShared = /* @__PURE__ */ new Set();
+	const usedOwn = {
+		anonymous: /* @__PURE__ */ new Set(),
+		unprivileged: /* @__PURE__ */ new Set()
+	};
+	const usedBodies = /* @__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}`);
+	for (const call of planned) {
+		if (call.keys.some((k) => shared.includes(k))) {
+			for (const k of call.keys) usedShared.add(k);
 			continue;
 		}
-		checked++;
+		let ran = false;
+		let reportedMissing = false;
 		for (const [who, caller] of callers) {
+			if (call.keys.some((k) => own[who].includes(k))) {
+				for (const k of call.keys) usedOwn[who].add(k);
+				continue;
+			}
+			const label = `${who} ${call.method} ${call.path}${call.verb ? ` (${call.verb.key})` : ""}`;
+			let body = call.method === "DELETE" ? void 0 : call.body ?? {};
+			if (call.verb !== void 0) {
+				const source = call.verb.source;
+				if (source === void 0) {
+					if (!reportedMissing) problems.push(`no body for action ${call.verb.key} (${call.method} ${call.path}): add it to \`actionBodies\` or exclude it`);
+					reportedMissing = true;
+					continue;
+				}
+				usedBodies.add(call.verb.key);
+				body = {
+					...typeof source === "function" ? await source({
+						resource: call.verb.resource,
+						action: call.verb.action,
+						caller: who,
+						path: call.path
+					}) : source,
+					action: call.verb.action
+				};
+			}
+			ran = true;
 			const before = await opts.snapshot();
-			const body = method === "DELETE" ? void 0 : route.body ?? {};
-			const reply = await caller.request(method, route.path, body);
+			const reply = await caller.request(call.method, call.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 (ran) checked++;
 	}
 	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`);
+	for (const key of staleOf(shared, usedShared)) problems.push(`stale exclusion ${key}: no such mutating route is checked`);
+	const given = new Set(callers.map(([who]) => who));
+	for (const who of CALLERS) {
+		if (own[who].length === 0) continue;
+		if (!given.has(who)) {
+			problems.push(`exclude.${who} is given but no ${who} caller is`);
+			continue;
+		}
+		for (const key of staleOf(own[who], usedOwn[who])) problems.push(`stale exclusion (${who}) ${key}: no such mutating route is checked`);
+	}
+	for (const key of Object.keys(opts.actionBodies ?? {})) if (!usedBodies.has(key)) problems.push(`stale action body ${key}: no such action verb is checked`);
 	return problems;
 }
-/** Registers the refusal guard as a vitest test. */
+/** Registers the refusal guard as a vitest test (title: `name`, or the default). */
 function registerRefusalDoesNoWorkGuard(opts) {
-	it("a refused request does no work (state is unchanged after every 401/403)", async () => {
+	it(opts.name ?? DEFAULT_NAME, async () => {
 		const problems = await checkRefusalDoesNoWork(opts);
 		expect(problems, report("refusal violations", problems)).toEqual([]);
 	});
@@ -781,7 +927,7 @@ function registerRefusalDoesNoWorkGuard(opts) {
 * 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 app = await resolve$1(opts.app);
 	const actionOk = exceptionKeys(opts.actionExceptions);
 	const routeOk = exceptionKeys(opts.routeExceptions);
 	const methods = (opts.bodyMethods ?? [
@@ -828,4 +974,4 @@ function registerRouteSchemaGuard(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 };
+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, schemaValues, shapeOf, specMatcher };

package/dist/index.d.mts

@@ -1,8 +1,7 @@
 import { BootModuleAppOptions as BootModuleAppOptions$1, BootModulesInput, ModuleTestApp as ModuleTestApp$1, TestkitContext as TestkitContext$1 } from "@classytic/arc/testing";
 import { Connection } from "mongoose";
-type TestkitContext = TestkitContext$1<Connection>;
-type ModulesInput = BootModulesInput<Connection>;
-type BootModuleAppOptions = BootModuleAppOptions$1<Connection>;
-type ModuleTestApp = ModuleTestApp$1<Connection>;
-declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;
-export { BootModuleAppOptions, ModuleTestApp, ModulesInput, TestkitContext, bootModuleApp };
+export type TestkitContext = TestkitContext$1<Connection>;
+export type ModulesInput = BootModulesInput<Connection>;
+export type BootModuleAppOptions = BootModuleAppOptions$1<Connection>;
+export type ModuleTestApp = ModuleTestApp$1<Connection>;
+export declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;

package/dist/mongo-commands.d.mts

@@ -1,6 +1,6 @@
 import { Connection } from "mongoose";
 type MongoClientLike = ReturnType<Connection["getClient"]>;
-interface CountCommandsOptions {
+export interface CountCommandsOptions {
   /** Count only commands against these collections. */
   readonly collections?: readonly string[];
   /** Count only these command names (`find`, `aggregate`, `insert`, …). */
@@ -8,12 +8,12 @@ interface CountCommandsOptions {
   /** Never count these command names — e.g. `createIndexes` a model may run lazily. */
   readonly ignore?: readonly string[];
 }
-interface WireCommand {
+export interface WireCommand {
   readonly command: string;
   /** The collection the command targets; `undefined` for session, transaction and admin commands. */
   readonly collection: string | undefined;
 }
-interface CommandCount<T> {
+export interface CommandCount<T> {
   readonly result: T;
   readonly total: number;
   /** Counted commands, in the order the driver sent them. */
@@ -22,6 +22,6 @@ interface CommandCount<T> {
   readonly byCollection: Readonly<Record<string, number>>;
   readonly byCommand: Readonly<Record<string, number>>;
 }
-declare function countCommands<T>(source: Connection | MongoClientLike, fn: () => Promise<T>, options?: CountCommandsOptions): Promise<CommandCount<T>>;
-declare function assertConstantCommands<T>(source: Connection | MongoClientLike, run: (size: number) => Promise<T>, sizes: readonly number[], options?: CountCommandsOptions): Promise<readonly CommandCount<T>[]>;
-export { CommandCount, CountCommandsOptions, WireCommand, assertConstantCommands, countCommands };
+export declare function countCommands<T>(source: Connection | MongoClientLike, fn: () => Promise<T>, options?: CountCommandsOptions): Promise<CommandCount<T>>;
+export declare function assertConstantCommands<T>(source: Connection | MongoClientLike, run: (size: number) => Promise<T>, sizes: readonly number[], options?: CountCommandsOptions): Promise<readonly CommandCount<T>[]>;
+export {};

package/dist/mongo-explain.d.mts

@@ -8,8 +8,17 @@
  * const explain = await Model.find({ organizationId, state: "posted" }).explain("executionStats");
  * assertIndexServed(explain, { index: "org_state_date", maxDocsExamined: 40 });
  * ```
+ *
+ * `explainCaptured` explains the query a piece of code ACTUALLY sends (a repository method, a
+ * plugin-built filter) instead of a copy of it: it runs the code with command monitoring, captures
+ * the matching command and explains exactly that.
+ *
+ * ```ts
+ * const { explain } = await explainCaptured(conn, () => timers.claim(now), { collection: "timers", commands: ["findAndModify"] });
+ * assertIndexServed(explain, { index: "state_due", maxDocsExamined: 6 });
+ * ```
  */
-interface ExplainSummary {
+export interface ExplainSummary {
   /** Stage names of the winning plan(s), outermost first. */
   readonly stages: readonly string[];
   /** Index names the winning plan scans (`_id_` for an id lookup). */
@@ -19,7 +28,7 @@ interface ExplainSummary {
   readonly keysExamined: number | undefined;
   readonly returned: number | undefined;
 }
-interface IndexServedOptions {
+export interface IndexServedOptions {
   /** Every one of these must be scanned. */
   readonly index?: string | readonly string[];
   /** Every one of these stages must appear — e.g. `OR` for a `$or` served arm by arm. */
@@ -27,6 +36,49 @@ interface IndexServedOptions {
   /** Ceiling on `totalDocsExamined`; requires `executionStats` verbosity. */
   readonly maxDocsExamined?: number;
 }
-declare function summarizeExplain(explain: unknown): ExplainSummary;
-declare function assertIndexServed(explain: unknown, options?: IndexServedOptions): ExplainSummary;
-export { ExplainSummary, IndexServedOptions, assertIndexServed, summarizeExplain };
+export declare function summarizeExplain(explain: unknown): ExplainSummary;
+export declare function assertIndexServed(explain: unknown, options?: IndexServedOptions): ExplainSummary;
+/** A `commandStarted` event, as far as `explainCaptured` reads it. */
+export interface CommandStartedLike {
+  readonly commandName: string;
+  readonly databaseName: string;
+  readonly command: Readonly<Record<string, unknown>>;
+}
+/** A MongoDB driver client (`connection.getClient()` of mongoose, or a `MongoClient`). */
+export interface MonitoredClientLike {
+  readonly options: {
+    readonly monitorCommands?: boolean;
+  };
+  on(event: "commandStarted", listener: (event: CommandStartedLike) => void): unknown;
+  off(event: "commandStarted", listener: (event: CommandStartedLike) => void): unknown;
+  db(name: string): {
+    command(command: Record<string, unknown>): Promise<unknown>;
+  };
+}
+export interface ExplainCapturedOptions {
+  /** The collection the command targets. */
+  readonly collection: string;
+  /** Command names to capture. Default: `find`, `aggregate`, `findAndModify`, `count`, `distinct`, `update`, `delete`. */
+  readonly commands?: readonly string[];
+  /** Which captured command to explain (0-based). Required when more than one matches. */
+  readonly index?: number;
+  /** Default: `executionStats` (what `maxDocsExamined` needs). */
+  readonly verbosity?: "queryPlanner" | "executionStats" | "allPlansExecution";
+}
+export interface ExplainCaptured<T> {
+  readonly result: T;
+  /** The explain of the chosen command, ready for `assertIndexServed`. */
+  readonly explain: unknown;
+  /** The chosen command as the driver sent it, minus session and transport fields. */
+  readonly command: Readonly<Record<string, unknown>>;
+  /** Every matching command, in the order sent (same fields removed). */
+  readonly captured: readonly Readonly<Record<string, unknown>>[];
+}
+/**
+ * Runs `run` with command monitoring, captures the commands it sends to `collection` and explains
+ * the chosen one (the explain never applies a write). Refuses a client without
+ * `monitorCommands: true`, a run that sent no matching command, and an ambiguous capture.
+ */
+export declare function explainCaptured<T>(source: {
+  getClient(): MonitoredClientLike;
+} | MonitoredClientLike, run: () => Promise<T>, options: ExplainCapturedOptions): Promise<ExplainCaptured<T>>;

package/dist/mongo-explain.mjs

@@ -57,10 +57,80 @@ function assertIndexServed(explain, options = {}) {
 	}
 	return plan;
 }
+const EXPLAINABLE = [
+	"find",
+	"aggregate",
+	"findAndModify",
+	"count",
+	"distinct",
+	"update",
+	"delete"
+];
+/** Fields the driver adds to a command that an `explain` wrapper must not carry. */
+const TRANSPORT = /* @__PURE__ */ new Set([
+	"lsid",
+	"$db",
+	"$clusterTime",
+	"$readPreference",
+	"txnNumber",
+	"autocommit",
+	"startTransaction",
+	"readConcern",
+	"writeConcern",
+	"apiVersion",
+	"apiStrict",
+	"apiDeprecationErrors"
+]);
+/**
+* Runs `run` with command monitoring, captures the commands it sends to `collection` and explains
+* the chosen one (the explain never applies a write). Refuses a client without
+* `monitorCommands: true`, a run that sent no matching command, and an ambiguous capture.
+*/
+async function explainCaptured(source, run, options) {
+	const client = "getClient" in source ? source.getClient() : source;
+	const fail = (msg) => {
+		throw new Error(`[arc-testkit] explainCaptured: ${msg}`);
+	};
+	if (client.options.monitorCommands !== true) fail("the client was created without `monitorCommands: true` — the driver emits no command events, so nothing can be captured");
+	const names = options.commands ?? EXPLAINABLE;
+	const seen = [];
+	const onStarted = (e) => {
+		if (!names.includes(e.commandName) || e.command[e.commandName] !== options.collection) return;
+		const command = {};
+		for (const [key, value] of Object.entries(e.command)) if (!TRANSPORT.has(key)) command[key] = value;
+		seen.push({
+			db: e.databaseName,
+			command
+		});
+	};
+	client.on("commandStarted", onStarted);
+	let result;
+	try {
+		result = await run();
+	} finally {
+		client.off("commandStarted", onStarted);
+	}
+	const what = `${names.join("/")} on "${options.collection}"`;
+	if (seen.length === 0) fail(`run sent no ${what}`);
+	if (options.index === void 0 && seen.length > 1) fail(`run sent ${seen.length} ${what} (${seen.map((s) => Object.keys(s.command)[0]).join(", ")}): pass \`index\` to pick one`);
+	const chosen = seen[options.index ?? 0];
+	if (chosen === void 0) fail(`no captured command at index ${options.index} (${seen.length} captured)`);
+	const { db, command } = chosen;
+	const explain = await client.db(db).command({
+		explain: command,
+		verbosity: options.verbosity ?? "executionStats"
+	});
+	return {
+		result,
+		explain,
+		command,
+		captured: seen.map((s) => s.command)
+	};
+}
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
 function numberOr(value) {
 	return typeof value === "number" ? value : void 0;
 }
-export { assertIndexServed, summarizeExplain };
+export { assertIndexServed, explainCaptured, summarizeExplain };