ccqa-tools 1.37.0

package/dist/coverage/register.js

@@ -0,0 +1,716 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import http from "node:http";
+import https from "node:https";
+import * as nodeModule from "node:module";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { parse } from "acorn";
+//#region src/coverage/core.ts
+const RUNTIME_KEY = Symbol.for("ccqa.coverage.runtime");
+/** The name instrumented code calls through. Kept short; it appears per module. */
+const GLOBAL_RECORD = "__ccqaCoverage";
+function globals() {
+	return globalThis;
+}
+function getRuntime() {
+	return globals()[RUNTIME_KEY];
+}
+/**
+* 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;
+}
+/**
+* Installs the process-wide runtime, or returns the one already there.
+* Called by `ccqa-tools/coverage/register`; application code never calls it.
+*/
+function installRuntime(als) {
+	const g = globals();
+	const existing = g[RUNTIME_KEY];
+	if (existing) {
+		cachedRuntime = existing;
+		return existing;
+	}
+	const created = {
+		protocol: 1,
+		als,
+		buckets: /* @__PURE__ */ new Map(),
+		actors: /* @__PURE__ */ new Map(),
+		boot: /* @__PURE__ */ new Set(),
+		active: 0,
+		unattributed: 0,
+		uninstrumentedFiles: 0,
+		uninstrumentedProcess: false,
+		pid: typeof process === "undefined" ? -1 : process.pid,
+		startedAt: Date.now()
+	};
+	g[RUNTIME_KEY] = created;
+	g[GLOBAL_RECORD] = record;
+	cachedRuntime = created;
+	return created;
+}
+/**
+* Marks a file as reached. Instrumented code calls this through
+* `globalThis.__ccqaCoverage`, so the call sites cost one global read per
+* module and one truthiness check per invocation when coverage is off.
+*
+* @param topLevel set by the prologue a module runs on first import.
+*/
+function record(fileId, topLevel) {
+	const rt = runtime();
+	if (rt === void 0) return;
+	if (topLevel === true) {
+		rt.boot.add(fileId);
+		return;
+	}
+	if (rt.active === 0) return;
+	const store = rt.als.getStore();
+	if (store === void 0) {
+		rt.unattributed++;
+		return;
+	}
+	store.files.add(fileId);
+}
+/** 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;
+}
+/**
+* The key both halves of the collector agree on. A space separates them safely:
+* a spec id can never contain one, so identity keys and spec ids stay disjoint
+* where the collector tracks both in one map.
+*/
+function actorBucketKey(tag, at) {
+	return `${tag} ${at}`;
+}
+/** Drops a spec's bucket once it has been handed to the collector. */
+function closeBucket(runtime, specId) {
+	if (runtime.buckets.delete(specId)) armGate(runtime);
+}
+/** Drops an identity's bucket once it has been handed to the collector. */
+function closeActorBucket(runtime, key) {
+	if (runtime.actors.delete(key)) armGate(runtime);
+}
+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";
+/**
+* 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";
+/** Where the collector pushes to. Unset means collect in memory only. */
+const ENV_ENDPOINT = "CCQA_COVERAGE_ENDPOINT";
+/** The current ccqa sink does not check this. Carried for a relay in front of it, or a future endpoint that does. */
+const ENV_TOKEN = "CCQA_COVERAGE_TOKEN";
+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;
+		}
+	}
+}
+//#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/collector.ts
+/**
+* Ships what this process reached to a sink, on a timer.
+*
+* Push, not pull: behind a load balancer nothing can address one replica of N,
+* so an endpoint the runner scrapes would silently report a fraction of the
+* truth. Every replica pushes instead, and the sink unions — file sets make
+* that commutative, associative and idempotent, so the sink never has to know
+* how many replicas there were.
+*/
+const DEFAULT_INTERVAL_MS = 1e3;
+const DEFAULT_IDLE_TTL_MS = 12e4;
+/**
+* How many times the exit-time flush may run. More than one because a push the
+* timer started may still be in flight when the first one fires, and that one
+* returns without sending anything.
+*/
+const MAX_EXIT_FLUSHES = 3;
+/**
+* How often a process that instrumented nothing re-announces itself when it has
+* nothing else to send.
+*
+* It has no files and no attributions to report, so the delta it pushes is
+* empty forever after the first success — and the run that heard it is over.
+* Without this, every later run against the same process is told nothing
+* reported at all, rather than that one process is blind.
+*/
+const BLIND_HEARTBEAT_MS = 3e4;
+function createCollectorState() {
+	return {
+		sent: /* @__PURE__ */ new Map(),
+		sentBoot: /* @__PURE__ */ new Set(),
+		sentActors: /* @__PURE__ */ new Map(),
+		lastChange: /* @__PURE__ */ new Map(),
+		lastSentUnattributed: 0,
+		lastSentUninstrumentedFiles: 0,
+		lastSentUninstrumentedProcess: false,
+		lastSentAt: 0,
+		droppedPushes: 0
+	};
+}
+function startCollector(options, config) {
+	const runtime = getRuntime();
+	if (runtime === void 0) return () => {};
+	const idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+	const state = createCollectorState();
+	let inFlight = false;
+	let consecutiveFailures = 0;
+	const flush = () => {
+		if (inFlight) return Promise.resolve();
+		evict(runtime, state, idleTtlMs);
+		const payload = diff(runtime, state);
+		if (payload === void 0) return Promise.resolve();
+		inFlight = true;
+		return post(options, payload).then(() => {
+			for (const [specId, files] of Object.entries(payload.specs)) {
+				const acked = state.sent.get(specId) ?? /* @__PURE__ */ new Set();
+				for (const file of files) acked.add(file);
+				state.sent.set(specId, acked);
+			}
+			for (const file of payload.boot) state.sentBoot.add(file);
+			for (const bucket of payload.actors) {
+				const key = actorBucketKey(bucket.tag, bucket.at);
+				const acked = state.sentActors.get(key) ?? /* @__PURE__ */ new Set();
+				for (const file of bucket.files) acked.add(file);
+				state.sentActors.set(key, acked);
+			}
+			state.lastSentUnattributed = payload.unattributed;
+			state.lastSentUninstrumentedFiles = payload.uninstrumentedFiles;
+			state.lastSentUninstrumentedProcess = payload.uninstrumentedProcess;
+			consecutiveFailures = 0;
+		}).catch((error) => {
+			state.droppedPushes++;
+			consecutiveFailures++;
+			if (config) debugLog(config, `push failed: ${String(error)}`);
+			if (consecutiveFailures === 1 || consecutiveFailures % 10 === 0) process.stderr.write(`[ccqa-tools] push to ${options.endpoint} failed ${consecutiveFailures} times in a row: ${String(error)}\n`);
+		}).finally(() => {
+			inFlight = false;
+		});
+	};
+	const timer = setInterval(() => void flush(), options.intervalMs ?? DEFAULT_INTERVAL_MS);
+	timer.unref?.();
+	let exitFlushes = 0;
+	const onBeforeExit = async () => {
+		if (consecutiveFailures > 0 || exitFlushes >= MAX_EXIT_FLUSHES) return;
+		exitFlushes++;
+		await flush();
+	};
+	process.on("beforeExit", onBeforeExit);
+	return () => {
+		clearInterval(timer);
+		process.off("beforeExit", onBeforeExit);
+	};
+}
+/**
+* `acked` is always a subset of `reached`, and neither ever shrinks, so equal
+* sizes mean nothing new — skip the copy-then-filter and check that first.
+*/
+function freshOf(reached, acked) {
+	if (acked !== void 0 && acked.size === reached.size) return [];
+	const fresh = [];
+	for (const file of reached) if (acked === void 0 || !acked.has(file)) fresh.push(file);
+	return fresh;
+}
+/** Exported for tests: the sink's HTTP round trip is the only real-I/O part. */
+function diff(runtime, state) {
+	const specs = {};
+	let any = false;
+	const now = Date.now();
+	for (const [specId, files] of runtime.buckets) {
+		const fresh = freshOf(files, state.sent.get(specId));
+		if (fresh.length === 0) continue;
+		specs[specId] = fresh;
+		state.lastChange.set(specId, now);
+		any = true;
+	}
+	const actors = [];
+	for (const [key, bucket] of runtime.actors) {
+		const fresh = freshOf(bucket.files, state.sentActors.get(key));
+		if (fresh.length === 0) continue;
+		actors.push({
+			tag: bucket.tag,
+			at: bucket.at,
+			files: fresh
+		});
+		state.lastChange.set(key, now);
+	}
+	const boot = freshOf(runtime.boot, state.sentBoot);
+	const unattributedChanged = runtime.unattributed !== state.lastSentUnattributed;
+	const healthChanged = runtime.uninstrumentedFiles !== state.lastSentUninstrumentedFiles || runtime.uninstrumentedProcess !== state.lastSentUninstrumentedProcess;
+	const reannounce = runtime.uninstrumentedProcess && now - state.lastSentAt >= BLIND_HEARTBEAT_MS;
+	if (!any && boot.length === 0 && actors.length === 0 && !unattributedChanged && !healthChanged && !reannounce) return;
+	state.lastSentAt = now;
+	return {
+		protocol: 1,
+		pid: runtime.pid,
+		startedAt: runtime.startedAt,
+		unattributed: runtime.unattributed,
+		uninstrumentedFiles: runtime.uninstrumentedFiles,
+		uninstrumentedProcess: runtime.uninstrumentedProcess,
+		specs,
+		boot,
+		actors,
+		droppedPushes: state.droppedPushes
+	};
+}
+/**
+* Forgets specs that stopped changing and have nothing outstanding, so a long
+* lived server does not accumulate every spec it has ever served — and so the
+* hot-path gate falls back to zero between runs.
+*/
+function evict(runtime, state, idleTtlMs) {
+	const now = Date.now();
+	const cutoff = now - idleTtlMs;
+	const actors = [...runtime.actors].map(([key, bucket]) => [key, bucket.files]);
+	dropQuiet([...runtime.buckets], state.sent, state, cutoff, now, (key) => closeBucket(runtime, key));
+	dropQuiet(actors, state.sentActors, state, cutoff, now, (key) => closeActorBucket(runtime, key));
+}
+function dropQuiet(entries, sent, state, cutoff, now, close) {
+	for (const [key, files] of entries) {
+		const seen = state.lastChange.get(key);
+		if (seen === void 0) {
+			state.lastChange.set(key, now);
+			continue;
+		}
+		if (seen > cutoff) continue;
+		if (freshOf(files, sent.get(key)).length > 0) continue;
+		close(key);
+		sent.delete(key);
+		state.lastChange.delete(key);
+	}
+}
+async function post(options, payload) {
+	const headers = { "content-type": "application/json" };
+	if (options.token) headers.authorization = `Bearer ${options.token}`;
+	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+	const response = await fetch(options.endpoint, {
+		method: "POST",
+		headers,
+		body: JSON.stringify(payload),
+		signal: AbortSignal.timeout(intervalMs * 5)
+	});
+	if (!response.ok) throw new Error(`sink returned ${response.status}`);
+}
+//#endregion
+//#region src/coverage/instrument/select.ts
+const SOURCE_EXTENSIONS = [
+	".js",
+	".mjs",
+	".cjs",
+	".jsx",
+	".ts",
+	".mts",
+	".cts",
+	".tsx"
+];
+/**
+* Decides whether a file is part of the project under test, returning its id
+* if so. Returning the id here — rather than a plain boolean — spares the
+* caller a second `fileIdFor` pass over the same path.
+*
+* `node_modules` is excluded unconditionally: instrumenting dependencies costs
+* the most and answers the least — nobody adds a test because a library file
+* went unreached.
+*/
+function shouldInstrument(filename, config) {
+	if (filename.includes(`${sep}node_modules${sep}`)) return void 0;
+	if (!SOURCE_EXTENSIONS.some((extension) => filename.endsWith(extension))) return void 0;
+	const id = fileIdFor(filename, config.root);
+	if (id === void 0) return void 0;
+	return config.include.some((prefix) => id === prefix || id.startsWith(`${prefix}/`)) ? id : void 0;
+}
+/** 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/origin.ts
+/**
+* Reports a build output under the source it was compiled from.
+*
+* A server that runs from `dist/` would otherwise be measured in terms of its
+* own build artefacts, which nobody can act on: the answer has to name files
+* that exist in the repository. A 1:1 build — one output file per source file,
+* which is what an unbundled compile produces — says exactly which source that
+* is in its map's single `sources` entry.
+*
+* Only that single-source case is handled. A bundle's map lists every file
+* that went into it and cannot say which one the code at hand came from
+* without full mapping resolution, which is the build plugin's job, not the
+* loader's.
+*/
+function originalFileId(filename, code, root) {
+	const reference = readSourceMappingUrl(code);
+	if (reference === void 0) return void 0;
+	const map = loadMap(filename, reference);
+	if (map === void 0) return void 0;
+	const sources = map.sources;
+	if (!Array.isArray(sources) || sources.length !== 1) return void 0;
+	const source = sources[0];
+	if (typeof source !== "string" || source === "") return void 0;
+	return fileIdFor(resolve(dirname(filename), map.sourceRoot ?? "", source), root);
+}
+function loadMap(filename, reference) {
+	const json = reference.startsWith("data:") ? decodeDataUrl(reference) : readSibling(filename, reference);
+	if (json === void 0) return void 0;
+	try {
+		return JSON.parse(json);
+	} catch {
+		return;
+	}
+}
+function readSibling(filename, reference) {
+	if (/^[a-z]+:/i.test(reference)) return void 0;
+	try {
+		return readFileSync(resolve(dirname(filename), reference), "utf8");
+	} catch {
+		return;
+	}
+}
+function decodeDataUrl(url) {
+	const comma = url.indexOf(",");
+	if (comma < 0) return void 0;
+	const payload = url.slice(comma + 1);
+	try {
+		return url.slice(0, comma).includes(";base64") ? Buffer.from(payload, "base64").toString("utf8") : decodeURIComponent(payload);
+	} catch {
+		return;
+	}
+}
+const SOURCE_MAPPING_URL = /\/\/[#@][ \t]*sourceMappingURL=(\S+)/g;
+function readSourceMappingUrl(code) {
+	let found;
+	for (const match of code.matchAll(SOURCE_MAPPING_URL)) found = match[1];
+	return found;
+}
+//#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/instrument/hooks.ts
+/**
+* Instruments modules as Node loads them, so a deployment is instrumented by
+* adding one flag to its command line and rebuilding nothing. What runs is the
+* same artifact production runs, which is most of the reason this path is
+* preferred over a build plugin.
+*
+* Code a bundler already swallowed is out of reach here — the loader only ever
+* sees the bundle. Those runtimes use `ccqa-tools/coverage/next` instead.
+*/
+const textDecoder = new TextDecoder();
+function installLoadHooks(config, runtime) {
+	const registerHooks = nodeModule.registerHooks;
+	if (typeof registerHooks !== "function") {
+		runtime.uninstrumentedProcess = true;
+		process.stderr.write(`[ccqa-tools] load hooks unavailable on node ${process.version}; no file in this process will be instrumented\n`);
+		return;
+	}
+	registerHooks({ load(url, context, nextLoad) {
+		const result = nextLoad(url, context);
+		if (!url.startsWith("file:")) return result;
+		let filename;
+		try {
+			filename = fileURLToPath(url);
+		} catch {
+			return result;
+		}
+		const selectedId = shouldInstrument(filename, config);
+		if (selectedId === void 0) return result;
+		const source = toText(result.source);
+		if (source === void 0) {
+			runtime.uninstrumentedFiles++;
+			debugLog(config, `could not decode source for ${filename}; left as-is`);
+			return result;
+		}
+		const fileId = originalFileId(filename, source, config.root) ?? selectedId;
+		const instrumented = transform(source, { fileId });
+		if (instrumented === void 0) {
+			runtime.uninstrumentedFiles++;
+			debugLog(config, `could not parse ${fileId}; left as-is`);
+			return result;
+		}
+		return {
+			...result,
+			source: instrumented
+		};
+	} });
+	debugLog(config, `load hooks installed for ${config.include.join(", ")} under ${config.root}`);
+}
+function toText(source) {
+	if (typeof source === "string") return source;
+	if (source instanceof ArrayBuffer) return textDecoder.decode(source);
+	if (ArrayBuffer.isView(source)) return textDecoder.decode(new Uint8Array(source.buffer, source.byteOffset, source.byteLength));
+}
+//#endregion
+//#region src/coverage/register.ts
+/**
+* The Node-only half of the package, loaded with
+* `node --import ccqa-tools/coverage/register` (or via `NODE_OPTIONS`).
+*
+* Everything here would fail inside a bundler — `node:http`, `node:module`,
+* load-time source rewriting — which is exactly why it is not in `core.ts`.
+* When `CCQA_COVERAGE` is unset the process never loads this file at all.
+*/
+const config = readConfig();
+if (config.enabled) {
+	const runtime = installRuntime(new AsyncLocalStorage());
+	patchServers(runtime);
+	installLoadHooks(config, runtime);
+	if (config.ambientSpecId !== void 0) {
+		const files = openBucket(runtime, config.ambientSpecId);
+		runtime.als.enterWith({
+			specId: config.ambientSpecId,
+			files
+		});
+	}
+	const endpoint = process.env[ENV_ENDPOINT];
+	if (endpoint) startCollector({
+		endpoint,
+		token: process.env[ENV_TOKEN]
+	}, config);
+	else process.stderr.write(`[ccqa-tools] collection is enabled but ${ENV_ENDPOINT} is not set; results will be discarded\n`);
+	debugLog(config, `armed in pid ${process.pid}`);
+}
+/**
+* Wraps inbound requests in the spec's context.
+*
+* Patching `emit` rather than the handler covers servers created before this
+* ran and servers created by frameworks that never expose their handler.
+* `https.Server` does not inherit from `http.Server`, so both are patched.
+*/
+function patchServers(runtime) {
+	for (const server of [http.Server, https.Server]) {
+		const prototype = server.prototype;
+		const original = prototype.emit;
+		prototype.emit = function patched() {
+			if (arguments[0] !== "request") return original.apply(this, arguments);
+			const request = arguments[1];
+			const specId = readCookie(request.headers.cookie) ?? readBaggage(request.headers.baggage);
+			if (specId === void 0) return original.apply(this, arguments);
+			return runtime.als.run({
+				specId,
+				files: openBucket(runtime, specId)
+			}, () => original.apply(this, arguments));
+		};
+	}
+}
+//#endregion