ccqa-tools 1.37.0

package/dist/coverage/middleware.js

@@ -0,0 +1,158 @@
+//#region src/coverage/core.ts
+const RUNTIME_KEY = Symbol.for("ccqa.coverage.runtime");
+function globals() {
+	return globalThis;
+}
+/**
+* Memoized so the hot path skips the `globalThis` read. `installRuntime`
+* primes it and never replaces an installed runtime, so once set it never
+* goes stale — but it must stay undefined (and keep re-reading `globalThis`)
+* until then, or a module that finished loading before `register` installs
+* the runtime would be stuck uninstrumented for the rest of the process.
+*/
+let cachedRuntime;
+function runtime() {
+	if (cachedRuntime === void 0) cachedRuntime = globals()[RUNTIME_KEY];
+	return cachedRuntime;
+}
+/** The spec the current async context belongs to, if any. */
+function currentSpecId() {
+	return runtime()?.als.getStore()?.specId;
+}
+/**
+* Opens `specId`'s bucket and runs `fn` inside its context. Every entry point —
+* HTTP, Temporal activity, manual — funnels through here.
+*
+* The bucket outlives `fn`: work a request schedules and does not await still
+* belongs to the spec that caused it.
+*/
+function runInSpec(specId, fn) {
+	const rt = runtime();
+	if (rt === void 0) return fn();
+	return rt.als.run({
+		specId,
+		files: openBucket(rt, specId)
+	}, fn);
+}
+/** Returns `specId`'s file set, creating it — and arming the gate — if new. */
+function openBucket(runtime, specId) {
+	let files = runtime.buckets.get(specId);
+	if (files === void 0) {
+		files = /* @__PURE__ */ new Set();
+		runtime.buckets.set(specId, files);
+		armGate(runtime);
+	}
+	return files;
+}
+function armGate(runtime) {
+	runtime.active = runtime.buckets.size + runtime.actors.size;
+}
+//#endregion
+//#region src/coverage/wire.ts
+/**
+* The names a spec id travels under. Every carrier holds the same value,
+* `<runId>.<specId>`, so a hop between them is a copy and never a translation.
+*
+* Like `core.ts` this file imports nothing: the Temporal workflow sandbox reads
+* it too.
+*/
+/** Set on the browser by ccqa at spec start, scoped to the target origin. */
+const COOKIE_NAME = "__ccqa_coverage";
+/** OTel baggage key, for the hop from the first service to downstream ones. */
+const BAGGAGE_KEY = "ccqa.coverage";
+const SPEC_ID = /^[A-Za-z0-9._\-/]{1,200}$/;
+/**
+* Accepts a carrier value only if it looks like an id we wrote.
+*
+* The cookie is client-controlled, so this is the first of two gates: the
+* second is the hub refusing runs it never started.
+*/
+function parseSpecId(raw) {
+	if (!raw) return void 0;
+	const value = raw.trim();
+	if (!SPEC_ID.test(value)) return void 0;
+	if (value === "1" || value === "true") return void 0;
+	return value;
+}
+function readCookie(header) {
+	return readKeyed(header, COOKIE_NAME, ";");
+}
+/** Pulls our key out of a `baggage` header (W3C: `k=v;props,k2=v2`). */
+function readBaggage(header) {
+	return readKeyed(header, BAGGAGE_KEY, ",", ";");
+}
+/**
+* Both carriers are `key=value` lists; they differ only in what separates the
+* entries, and baggage allowing properties after each value.
+*
+* One function because the decode-and-validate step is the part that matters,
+* and two copies of it would be free to drift into accepting different things.
+*/
+function readKeyed(header, key, between, propertiesAfter) {
+	if (!header) return void 0;
+	if (header.indexOf(key) < 0) return void 0;
+	for (const raw of header.split(between)) {
+		const entry = propertiesAfter === void 0 ? raw : raw.split(propertiesAfter)[0] ?? "";
+		const eq = entry.indexOf("=");
+		if (eq < 0) continue;
+		if (entry.slice(0, eq).trim() !== key) continue;
+		try {
+			return parseSpecId(decodeURIComponent(entry.slice(eq + 1).trim()));
+		} catch {
+			return;
+		}
+	}
+}
+/** Adds our key to an existing `baggage` header value, replacing any old one. */
+function writeBaggage(existing, specId) {
+	const kept = (existing ?? "").split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0 && !entry.startsWith(`ccqa.coverage=`));
+	kept.push(`${BAGGAGE_KEY}=${encodeURIComponent(specId)}`);
+	return kept.join(",");
+}
+//#endregion
+//#region src/coverage/middleware.ts
+/**
+* Entry points for servers `ccqa-tools/coverage/register` cannot wrap on its own:
+* anything that does not receive its requests from `node:http`.
+*
+* A framework running on plain Node needs none of this — the register hook
+* already opened the context before the framework saw the request.
+*/
+/** connect / express / fastify-compat middleware. */
+function coverageMiddleware() {
+	return function coverage(request, _response, next) {
+		const specId = specIdFromNodeHeaders(request.headers);
+		if (specId === void 0) {
+			next();
+			return;
+		}
+		runInSpec(specId, next);
+	};
+}
+/** Wraps a `Request` -> `Response` handler (Hono, Next.js route handlers, workerd). */
+function withCoverage(handler) {
+	return function covered(request, ...rest) {
+		const specId = readCookie(request.headers.get("cookie")) ?? readBaggage(request.headers.get("baggage"));
+		if (specId === void 0) return handler(request, ...rest);
+		return runInSpec(specId, () => handler(request, ...rest));
+	};
+}
+/**
+* Converts the cookie into a `baggage` header so downstream services — which
+* never see the browser's cookie jar — inherit the attribution. Call it where
+* the first service fans out, or in an edge middleware that forwards to one.
+*/
+function forwardHeaders(incoming, outgoing) {
+	const headers = outgoing ?? new Headers();
+	const specId = currentSpecId() ?? readCookie(incoming.get("cookie")) ?? readBaggage(incoming.get("baggage"));
+	if (specId !== void 0) headers.set("baggage", writeBaggage(headers.get("baggage") ?? incoming.get("baggage"), specId));
+	return headers;
+}
+function specIdFromNodeHeaders(headers) {
+	return readCookie(single(headers.cookie)) ?? readBaggage(single(headers.baggage));
+}
+function single(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+//#endregion
+export { coverageMiddleware, forwardHeaders, withCoverage };

package/dist/coverage/next-loader.cjs

@@ -0,0 +1,158 @@
+let node_path = require("node:path");
+let acorn = require("acorn");
+//#region src/coverage/instrument/select.ts
+/** Path relative to the project root, in posix form so ids match across hosts. */
+function fileIdFor(filename, root) {
+	const rel = (0, node_path.relative)((0, node_path.resolve)(root), filename);
+	if (rel.startsWith("..") || rel === "") return void 0;
+	return rel.split(node_path.sep).join("/");
+}
+//#endregion
+//#region src/coverage/instrument/transform.ts
+/**
+* Rewrites a module so that entering it, or entering one of its functions,
+* calls `globalThis.__ccqaCoverage`.
+*
+* Two properties drive the whole shape:
+*
+* - **Insertions only, never a newline.** Line numbers survive untouched, so
+*   the source map the application already ships keeps pointing at the right
+*   lines and stack traces stay readable. A codegen round-trip would have
+*   forced us to produce and merge maps of our own.
+* - **File granularity.** The record is "this file ran", so there is no need to
+*   track statements or branches, and the whole class of line/branch
+*   normalisation bugs that follow V8-to-istanbul conversion never appears.
+*/
+const DEFAULT_MAX_DEPTH = 2;
+function transform(code, options) {
+	const program = parseProgram(code);
+	if (program === void 0) return void 0;
+	const local = `__ccqa_${hash(options.fileId)}`;
+	const literal = JSON.stringify(options.fileId);
+	const enter = `${local}&&${local}(${literal});`;
+	const points = [];
+	collect(program, options.maxDepth ?? DEFAULT_MAX_DEPTH, points);
+	if (code.length === 0) return void 0;
+	const prologueAt = afterDirectives(code, program);
+	const edits = points.filter((offset) => offset > prologueAt).map((offset) => ({
+		offset,
+		text: enter
+	}));
+	edits.push({
+		offset: prologueAt,
+		text: `var ${local}=globalThis.__ccqaCoverage;${local}&&${local}(${literal},true);`
+	});
+	edits.sort((a, b) => a.offset - b.offset);
+	const parts = [];
+	let last = 0;
+	for (const edit of edits) {
+		parts.push(code.slice(last, edit.offset), edit.text);
+		last = edit.offset;
+	}
+	parts.push(code.slice(last));
+	return parts.join("");
+}
+function parseProgram(code) {
+	for (const sourceType of ["module", "script"]) try {
+		return (0, acorn.parse)(code, {
+			ecmaVersion: "latest",
+			sourceType,
+			allowHashBang: true,
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: sourceType === "script"
+		});
+	} catch {}
+}
+/**
+* A directive prologue only counts while it is still the first thing in its
+* scope. Inserting ahead of `"use strict"` demotes it to an ordinary string
+* expression, and the code it governed silently starts running sloppy — the
+* instrumentation would be changing the behaviour it is supposed to observe.
+* Applies to a function body as much as to the module.
+*/
+function afterDirectives(code, program) {
+	let offset = program.start;
+	if (code.startsWith("#!")) {
+		const newline = code.indexOf("\n");
+		offset = newline < 0 ? code.length : newline + 1;
+	}
+	return skipDirectives(program.body, offset);
+}
+function skipDirectives(statements, from) {
+	let offset = from;
+	for (const statement of statements) {
+		if (statement.type !== "ExpressionStatement") break;
+		const expression = statement.expression;
+		if (expression.type !== "Literal" || typeof expression.value !== "string") break;
+		offset = statement.end;
+	}
+	return offset;
+}
+const FUNCTION_TYPES = new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression"
+]);
+function collect(root, maxDepth, points) {
+	walk(root, 0, false);
+	function walk(node, depth, inClass) {
+		const isFunction = FUNCTION_TYPES.has(node.type);
+		const nextDepth = isFunction ? depth + 1 : depth;
+		if (isFunction) {
+			const wanted = inClass || nextDepth <= maxDepth;
+			const body = node.body;
+			if (wanted && body && body.type === "BlockStatement") {
+				const statements = body.body;
+				points.push(skipDirectives(statements, body.start + 1));
+			}
+		}
+		for (const key in node) {
+			if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+			const value = node[key];
+			if (Array.isArray(value)) {
+				for (const item of value) if (isNode(item)) walk(item, nextDepth, childInClass(node, key, inClass));
+			} else if (isNode(value)) walk(value, nextDepth, childInClass(node, key, inClass));
+		}
+	}
+}
+/** True while walking the value of a class member, false again inside its body. */
+function childInClass(parent, key, inherited) {
+	if (parent.type === "MethodDefinition" || parent.type === "PropertyDefinition") return key === "value";
+	if (FUNCTION_TYPES.has(parent.type)) return false;
+	return inherited;
+}
+function isNode(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+/** Short, collision-resistant suffix so bundlers can hoist several modules into one scope. */
+function hash(value) {
+	let h = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		h ^= value.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(36);
+}
+//#endregion
+//#region src/coverage/next/loader.ts
+/**
+* webpack loader form of the instrumenter, for code that reaches the runtime as
+* part of a bundle and so is invisible to the load hooks.
+*
+* It is registered with `enforce: "post"` so it sees JavaScript: webpack runs
+* post loaders last, after the framework's own TypeScript/JSX transform, which
+* keeps this file free of a TypeScript parser.
+*/
+function ccqaCoverageLoader(source) {
+	const root = this.getOptions?.().root ?? process.cwd();
+	const fileId = fileIdFor(this.resourcePath, root);
+	if (fileId === void 0) return source;
+	const instrumented = transform(source, { fileId });
+	if (instrumented === void 0) {
+		this.emitWarning?.(/* @__PURE__ */ new Error(`ccqa-tools could not parse ${fileId}; left uninstrumented`));
+		return source;
+	}
+	return instrumented;
+}
+//#endregion
+module.exports = ccqaCoverageLoader;

package/dist/coverage/next-loader.d.cts

@@ -0,0 +1,18 @@
+//#region src/coverage/next/loader.d.ts
+/**
+ * webpack loader form of the instrumenter, for code that reaches the runtime as
+ * part of a bundle and so is invisible to the load hooks.
+ *
+ * It is registered with `enforce: "post"` so it sees JavaScript: webpack runs
+ * post loaders last, after the framework's own TypeScript/JSX transform, which
+ * keeps this file free of a TypeScript parser.
+ */
+interface LoaderContext {
+  resourcePath: string;
+  getOptions?: () => {
+    root?: string;
+  };
+  emitWarning?: (warning: Error) => void;
+}
+declare function ccqaCoverageLoader(this: LoaderContext, source: string): string;
+export = ccqaCoverageLoader;

package/dist/coverage/next-loader.d.ts

@@ -0,0 +1,19 @@
+//#region src/coverage/next/loader.d.ts
+/**
+ * webpack loader form of the instrumenter, for code that reaches the runtime as
+ * part of a bundle and so is invisible to the load hooks.
+ *
+ * It is registered with `enforce: "post"` so it sees JavaScript: webpack runs
+ * post loaders last, after the framework's own TypeScript/JSX transform, which
+ * keeps this file free of a TypeScript parser.
+ */
+interface LoaderContext {
+  resourcePath: string;
+  getOptions?: () => {
+    root?: string;
+  };
+  emitWarning?: (warning: Error) => void;
+}
+declare function ccqaCoverageLoader(this: LoaderContext, source: string): string;
+//#endregion
+export { ccqaCoverageLoader as default };

package/dist/coverage/next-loader.js

@@ -0,0 +1,158 @@
+import { relative, resolve, sep } from "node:path";
+import { parse } from "acorn";
+//#region src/coverage/instrument/select.ts
+/** Path relative to the project root, in posix form so ids match across hosts. */
+function fileIdFor(filename, root) {
+	const rel = relative(resolve(root), filename);
+	if (rel.startsWith("..") || rel === "") return void 0;
+	return rel.split(sep).join("/");
+}
+//#endregion
+//#region src/coverage/instrument/transform.ts
+/**
+* Rewrites a module so that entering it, or entering one of its functions,
+* calls `globalThis.__ccqaCoverage`.
+*
+* Two properties drive the whole shape:
+*
+* - **Insertions only, never a newline.** Line numbers survive untouched, so
+*   the source map the application already ships keeps pointing at the right
+*   lines and stack traces stay readable. A codegen round-trip would have
+*   forced us to produce and merge maps of our own.
+* - **File granularity.** The record is "this file ran", so there is no need to
+*   track statements or branches, and the whole class of line/branch
+*   normalisation bugs that follow V8-to-istanbul conversion never appears.
+*/
+const DEFAULT_MAX_DEPTH = 2;
+function transform(code, options) {
+	const program = parseProgram(code);
+	if (program === void 0) return void 0;
+	const local = `__ccqa_${hash(options.fileId)}`;
+	const literal = JSON.stringify(options.fileId);
+	const enter = `${local}&&${local}(${literal});`;
+	const points = [];
+	collect(program, options.maxDepth ?? DEFAULT_MAX_DEPTH, points);
+	if (code.length === 0) return void 0;
+	const prologueAt = afterDirectives(code, program);
+	const edits = points.filter((offset) => offset > prologueAt).map((offset) => ({
+		offset,
+		text: enter
+	}));
+	edits.push({
+		offset: prologueAt,
+		text: `var ${local}=globalThis.__ccqaCoverage;${local}&&${local}(${literal},true);`
+	});
+	edits.sort((a, b) => a.offset - b.offset);
+	const parts = [];
+	let last = 0;
+	for (const edit of edits) {
+		parts.push(code.slice(last, edit.offset), edit.text);
+		last = edit.offset;
+	}
+	parts.push(code.slice(last));
+	return parts.join("");
+}
+function parseProgram(code) {
+	for (const sourceType of ["module", "script"]) try {
+		return parse(code, {
+			ecmaVersion: "latest",
+			sourceType,
+			allowHashBang: true,
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: sourceType === "script"
+		});
+	} catch {}
+}
+/**
+* A directive prologue only counts while it is still the first thing in its
+* scope. Inserting ahead of `"use strict"` demotes it to an ordinary string
+* expression, and the code it governed silently starts running sloppy — the
+* instrumentation would be changing the behaviour it is supposed to observe.
+* Applies to a function body as much as to the module.
+*/
+function afterDirectives(code, program) {
+	let offset = program.start;
+	if (code.startsWith("#!")) {
+		const newline = code.indexOf("\n");
+		offset = newline < 0 ? code.length : newline + 1;
+	}
+	return skipDirectives(program.body, offset);
+}
+function skipDirectives(statements, from) {
+	let offset = from;
+	for (const statement of statements) {
+		if (statement.type !== "ExpressionStatement") break;
+		const expression = statement.expression;
+		if (expression.type !== "Literal" || typeof expression.value !== "string") break;
+		offset = statement.end;
+	}
+	return offset;
+}
+const FUNCTION_TYPES = new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression"
+]);
+function collect(root, maxDepth, points) {
+	walk(root, 0, false);
+	function walk(node, depth, inClass) {
+		const isFunction = FUNCTION_TYPES.has(node.type);
+		const nextDepth = isFunction ? depth + 1 : depth;
+		if (isFunction) {
+			const wanted = inClass || nextDepth <= maxDepth;
+			const body = node.body;
+			if (wanted && body && body.type === "BlockStatement") {
+				const statements = body.body;
+				points.push(skipDirectives(statements, body.start + 1));
+			}
+		}
+		for (const key in node) {
+			if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+			const value = node[key];
+			if (Array.isArray(value)) {
+				for (const item of value) if (isNode(item)) walk(item, nextDepth, childInClass(node, key, inClass));
+			} else if (isNode(value)) walk(value, nextDepth, childInClass(node, key, inClass));
+		}
+	}
+}
+/** True while walking the value of a class member, false again inside its body. */
+function childInClass(parent, key, inherited) {
+	if (parent.type === "MethodDefinition" || parent.type === "PropertyDefinition") return key === "value";
+	if (FUNCTION_TYPES.has(parent.type)) return false;
+	return inherited;
+}
+function isNode(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+/** Short, collision-resistant suffix so bundlers can hoist several modules into one scope. */
+function hash(value) {
+	let h = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		h ^= value.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(36);
+}
+//#endregion
+//#region src/coverage/next/loader.ts
+/**
+* webpack loader form of the instrumenter, for code that reaches the runtime as
+* part of a bundle and so is invisible to the load hooks.
+*
+* It is registered with `enforce: "post"` so it sees JavaScript: webpack runs
+* post loaders last, after the framework's own TypeScript/JSX transform, which
+* keeps this file free of a TypeScript parser.
+*/
+function ccqaCoverageLoader(source) {
+	const root = this.getOptions?.().root ?? process.cwd();
+	const fileId = fileIdFor(this.resourcePath, root);
+	if (fileId === void 0) return source;
+	const instrumented = transform(source, { fileId });
+	if (instrumented === void 0) {
+		this.emitWarning?.(/* @__PURE__ */ new Error(`ccqa-tools could not parse ${fileId}; left uninstrumented`));
+		return source;
+	}
+	return instrumented;
+}
+//#endregion
+export { ccqaCoverageLoader as default };

package/dist/coverage/next.cjs

@@ -0,0 +1,101 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_module = require("node:module");
+let node_path = require("node:path");
+//#region src/coverage/wire.ts
+/**
+* Enables the instrumentation. Unset means the register hook is never loaded
+* and the application pays nothing at all.
+*
+* `1` / `true` turns it on and leaves attribution to the incoming carrier.
+* Any other value is itself a `<runId>.<specId>` and becomes the ambient spec
+* for the process — the only way to attribute an entry point that has no
+* inbound request to read, such as a worker started per spec.
+*/
+const ENV_NAME = "CCQA_COVERAGE";
+const SPEC_ID = /^[A-Za-z0-9._\-/]{1,200}$/;
+/**
+* Accepts a carrier value only if it looks like an id we wrote.
+*
+* The cookie is client-controlled, so this is the first of two gates: the
+* second is the hub refusing runs it never started.
+*/
+function parseSpecId(raw) {
+	if (!raw) return void 0;
+	const value = raw.trim();
+	if (!SPEC_ID.test(value)) return void 0;
+	if (value === "1" || value === "true") return void 0;
+	return value;
+}
+//#endregion
+//#region src/coverage/runtime-env.ts
+function readConfig(env = process.env) {
+	const raw = env[ENV_NAME];
+	const include = (env["CCQA_COVERAGE_INCLUDE"] ?? "src").split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	return {
+		enabled: raw !== void 0 && raw !== "" && raw !== "0" && raw !== "false",
+		ambientSpecId: parseSpecId(raw),
+		root: env["CCQA_COVERAGE_ROOT"] ?? process.cwd(),
+		include,
+		debug: env["CCQA_COVERAGE_DEBUG"] === "1" || env["CCQA_COVERAGE_DEBUG"] === "true"
+	};
+}
+/**
+* Diagnostics go to stderr and nowhere else. A `--import` preload is inherited
+* by every child node process, and writing to stdout corrupts whatever the host
+* was parsing there — enough to make a framework's own toolchain fail to start.
+*/
+function debugLog(config, message) {
+	if (!config.debug) return;
+	process.stderr.write(`[ccqa-tools] ${message}\n`);
+}
+//#endregion
+//#region src/coverage/next/index.ts
+/**
+* Next.js integration.
+*
+* Next bundles its server code, so the load hooks in
+* `ccqa-tools/coverage/register` never see the application's own modules — only the
+* bundle. The instrumentation therefore has to happen at build time, while the
+* context that attributes it still comes from the register hook wrapping
+* `node:http`. Both halves are required:
+*
+*   // next.config.ts
+*   export default withCoverage({ ...yourConfig })
+*
+*   NODE_OPTIONS='--import ccqa-tools/coverage/register' CCQA_COVERAGE=1 next start
+*
+* Only server bundles are instrumented. Instrumenting the client would ship
+* `__ccqaCoverage` calls to browsers, where the front-end side of ccqa's
+* coverage already reads V8's own counters and needs nothing injected.
+*/
+const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
+/** Wraps a Next config, preserving any `webpack` hook it already has. */
+function withCoverage(config, options = {}) {
+	if (!(options.enabled ?? process.env["CCQA_COVERAGE"] !== void 0)) return config;
+	const root = (0, node_path.resolve)(options.root ?? readConfig().root);
+	const include = (options.include ?? ["src"]).map((dir) => (0, node_path.resolve)(root, dir));
+	const previous = config.webpack;
+	return {
+		...config,
+		webpack(webpackConfig, context) {
+			const next = previous ? previous(webpackConfig, context) : webpackConfig;
+			if (!context.isServer) return next;
+			next.module ??= {};
+			next.module.rules ??= [];
+			next.module.rules.push({
+				enforce: "post",
+				test: /\.(?:[cm]?js|jsx|tsx?)$/,
+				include,
+				exclude: /[\\/]node_modules[\\/]/,
+				use: [{
+					loader: require$1.resolve("./next-loader.cjs"),
+					options: { root }
+				}]
+			});
+			debugLog(readConfig(), `instrumenting server bundles under ${include.join(", ")}`);
+			return next;
+		}
+	};
+}
+//#endregion
+exports.withCoverage = withCoverage;

package/dist/coverage/next.d.cts

@@ -0,0 +1,33 @@
+//#region src/coverage/next/index.d.ts
+/**
+ * Next.js integration.
+ *
+ * Next bundles its server code, so the load hooks in
+ * `ccqa-tools/coverage/register` never see the application's own modules — only the
+ * bundle. The instrumentation therefore has to happen at build time, while the
+ * context that attributes it still comes from the register hook wrapping
+ * `node:http`. Both halves are required:
+ *
+ *   // next.config.ts
+ *   export default withCoverage({ ...yourConfig })
+ *
+ *   NODE_OPTIONS='--import ccqa-tools/coverage/register' CCQA_COVERAGE=1 next start
+ *
+ * Only server bundles are instrumented. Instrumenting the client would ship
+ * `__ccqaCoverage` calls to browsers, where the front-end side of ccqa's
+ * coverage already reads V8's own counters and needs nothing injected.
+ */
+interface CoverageNextOptions {
+  /** Project root that file ids are relative to. Defaults to `process.cwd()`. */
+  root?: string;
+  /** Directories, relative to the root, to instrument. Defaults to `["src"]`. */
+  include?: string[];
+  /** Set false to build without instrumentation while keeping the config in place. */
+  enabled?: boolean;
+}
+/** Wraps a Next config, preserving any `webpack` hook it already has. */
+declare function withCoverage<T extends {
+  webpack?: unknown;
+}>(config: T, options?: CoverageNextOptions): T;
+//#endregion
+export { CoverageNextOptions, withCoverage };

package/dist/coverage/next.d.ts

@@ -0,0 +1,33 @@
+//#region src/coverage/next/index.d.ts
+/**
+ * Next.js integration.
+ *
+ * Next bundles its server code, so the load hooks in
+ * `ccqa-tools/coverage/register` never see the application's own modules — only the
+ * bundle. The instrumentation therefore has to happen at build time, while the
+ * context that attributes it still comes from the register hook wrapping
+ * `node:http`. Both halves are required:
+ *
+ *   // next.config.ts
+ *   export default withCoverage({ ...yourConfig })
+ *
+ *   NODE_OPTIONS='--import ccqa-tools/coverage/register' CCQA_COVERAGE=1 next start
+ *
+ * Only server bundles are instrumented. Instrumenting the client would ship
+ * `__ccqaCoverage` calls to browsers, where the front-end side of ccqa's
+ * coverage already reads V8's own counters and needs nothing injected.
+ */
+interface CoverageNextOptions {
+  /** Project root that file ids are relative to. Defaults to `process.cwd()`. */
+  root?: string;
+  /** Directories, relative to the root, to instrument. Defaults to `["src"]`. */
+  include?: string[];
+  /** Set false to build without instrumentation while keeping the config in place. */
+  enabled?: boolean;
+}
+/** Wraps a Next config, preserving any `webpack` hook it already has. */
+declare function withCoverage<T extends {
+  webpack?: unknown;
+}>(config: T, options?: CoverageNextOptions): T;
+//#endregion
+export { CoverageNextOptions, withCoverage };