feat(instrumentor): ESM loader hook via module.register

Add an ESM loader that intercepts import() and static imports on
Node >= 20.6.  It runs in a dedicated loader thread, applies Babel
coverage + compare-hooks transforms, and hands the rewritten
source back to the main thread for evaluation.

Each module gets a preamble that allocates its own counter buffer
through the Fuzzer global (which lives on the main thread where
the transformed code actually executes).

On older Node versions the loader is silently skipped and the CJS
hookRequire path continues to work as before.

Author: oetr

packages/instrumentor/esm-loader.mts

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2026 Code Intelligence GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Node.js module-loader hook for ESM instrumentation.
+ *
+ * Registered via module.register() from registerInstrumentor().
+ * Runs in a dedicated loader thread — it has no access to the
+ * native fuzzer addon or to globalThis.Fuzzer.  All it does is
+ * transform source code and hand it back.  The transformed code
+ * executes in the main thread, where the Fuzzer global exists.
+ */
+
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+// Load CJS-compiled Babel plugins via createRequire so we don't
+// depend on Node.js CJS-named-export detection (varies by version).
+const require = createRequire(import.meta.url);
+const { transformSync } =
+	require("@babel/core") as typeof import("@babel/core");
+const { esmCodeCoverage } =
+	require("./plugins/esmCodeCoverage.js") as typeof import("./plugins/esmCodeCoverage.js");
+const { compareHooks } =
+	require("./plugins/compareHooks.js") as typeof import("./plugins/compareHooks.js");
+
+// Already-instrumented code contains this marker.
+const INSTRUMENTATION_MARKER = "Fuzzer.coverageTracker.incrementCounter";
+
+// Counter buffer variable injected into each instrumented module.
+const COUNTER_ARRAY = "__jazzer_cov";
+
+interface LoaderConfig {
+	includes: string[];
+	excludes: string[];
+}
+
+let config: LoaderConfig;
+
+export function initialize(data: LoaderConfig): void {
+	config = data;
+}
+
+interface LoadResult {
+	format?: string;
+	source?: string | ArrayBuffer | SharedArrayBuffer | Uint8Array;
+	shortCircuit?: boolean;
+}
+
+type LoadFn = (
+	url: string,
+	context: { format?: string | null },
+	nextLoad: (
+		url: string,
+		context: { format?: string | null },
+	) => Promise<LoadResult>,
+) => Promise<LoadResult>;
+
+export const load: LoadFn = async function load(url, context, nextLoad) {
+	const result = await nextLoad(url, context);
+
+	if (result.format !== "module" || !result.source) {
+		return result;
+	}
+
+	// Only instrument file:// URLs (skip builtins, data:, https:, etc.)
+	if (!url.startsWith("file://")) {
+		return result;
+	}
+
+	const filename = fileURLToPath(url);
+	if (!shouldInstrument(filename)) {
+		return result;
+	}
+
+	const code = result.source.toString();
+
+	// Avoid double-instrumenting code already processed by the CJS path
+	// or by the Jest transformer.
+	if (code.includes(INSTRUMENTATION_MARKER)) {
+		return result;
+	}
+
+	const instrumented = instrumentModule(code, filename);
+	if (!instrumented) {
+		return result;
+	}
+
+	return { ...result, source: instrumented };
+};
+
+// ── Instrumentation ──────────────────────────────────────────────
+
+function instrumentModule(code: string, filename: string): string | null {
+	const coverage = esmCodeCoverage();
+
+	let transformed: ReturnType<typeof transformSync>;
+	try {
+		transformed = transformSync(code, {
+			filename,
+			sourceFileName: filename,
+			sourceMaps: "inline",
+			plugins: [coverage.plugin, compareHooks],
+			sourceType: "module",
+		});
+	} catch {
+		// Babel parse failures on non-JS assets should not crash the
+		// loader — fall through and return the original source.
+		return null;
+	}
+
+	const edges = coverage.edgeCount();
+	if (edges === 0 || !transformed?.code) {
+		return null;
+	}
+
+	// Prepend a one-liner that allocates this module's counter buffer
+	// and registers it with libFuzzer via the main-thread Fuzzer global.
+	const preamble =
+		`const ${COUNTER_ARRAY} = ` +
+		`Fuzzer.coverageTracker.createModuleCounters(${edges});\n`;
+
+	return preamble + transformed.code;
+}
+
+// ── Include / exclude filtering ──────────────────────────────────
+
+function shouldInstrument(filepath: string): boolean {
+	const { includes, excludes } = config;
+	const included = includes.some((p) => filepath.includes(p));
+	const excluded = excludes.some((p) => filepath.includes(p));
+	return included && !excluded;
+}

packages/instrumentor/instrument.ts

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+import * as path from "path";
+import { pathToFileURL } from "url";
+
 import {
 	BabelFileResult,
 	PluginItem,
@@ -183,6 +186,18 @@ export class Instrumentor {
 		);
 	}
 
+	get dryRun(): boolean {
+		return this.isDryRun;
+	}
+
+	get includePatterns(): string[] {
+		return this.includes;
+	}
+
+	get excludePatterns(): string[] {
+		return this.excludes;
+	}
+
 	private shouldCollectCodeCoverage(filepath: string): boolean {
 		return (
 			this.shouldCollectSourceCodeCoverage &&
@@ -223,4 +238,46 @@ export function registerInstrumentor(instrumentor: Instrumentor) {
 		// instrumentor but the filename will still have a .ts extension
 		{ extensions: [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"] },
 	);
+
+	registerEsmHooks(instrumentor);
+}
+
+/**
+ * On Node.js >= 20.6 register an ESM loader hook so that
+ * import() and static imports are instrumented too.
+ */
+function registerEsmHooks(instrumentor: Instrumentor): void {
+	if (instrumentor.dryRun) {
+		return;
+	}
+
+	const [major, minor] = process.versions.node.split(".").map(Number);
+	if (major < 20 || (major === 20 && minor < 6)) {
+		return;
+	}
+
+	try {
+		// Dynamic require — the node:module API may not expose
+		// `register` on older versions even if the check above
+		// passed (e.g. unusual builds).
+		const { register } = require("node:module") as {
+			register: (
+				specifier: string,
+				options: { parentURL: string; data: unknown },
+			) => void;
+		};
+
+		const loaderUrl = pathToFileURL(
+			path.join(__dirname, "esm-loader.mjs"),
+		).href;
+		register(loaderUrl, {
+			parentURL: pathToFileURL(__filename).href,
+			data: {
+				includes: instrumentor.includePatterns,
+				excludes: instrumentor.excludePatterns,
+			},
+		});
+	} catch {
+		// Silently fall back to CJS-only instrumentation.
+	}
 }