feat(instrumentor): instrument ESM modules via loader hooks

Add an ESM loader that intercepts import() and static imports on
Node >= 20.6, applying Babel coverage and compare-hook transforms.
Each module gets its own counter buffer via a preamble that runs on
the main thread.

The shared coverage visitor is extracted from codeCoverage.ts so
both the CJS path (global IDs via incrementCounter) and the new ESM
path (module-local IDs via direct array writes) reuse the same
branch/loop/ternary instrumentation logic.

The ESM counter uses % 255 + 1 for NeverZero instead of || 1 to
avoid infinite Babel visitor recursion on the generated expression.

Istanbul source coverage is included from the start so that ESM
modules appear in --coverage reports alongside CJS ones.

On older Node versions the loader is silently skipped.

Author: oetr

.npmignore

@@ -26,8 +26,11 @@ example
 
 # Exclude all TypeScript source files
 *.ts
+*.mts
 !*.d.ts
+!*.d.mts
 *test*.d.ts
+*test*.d.mts
 
 
 # Exclude native fuzzer sources

packages/instrumentor/esm-loader.mts

@@ -0,0 +1,160 @@
+/*
+ * 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 type { PluginItem } from "@babel/core";
+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");
+const { sourceCodeCoverage } =
+	require("./plugins/sourceCodeCoverage.js") as typeof import("./plugins/sourceCodeCoverage.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[];
+	coverage: boolean;
+}
+
+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 fuzzerCoverage = esmCodeCoverage();
+
+	const plugins: PluginItem[] = [fuzzerCoverage.plugin, compareHooks];
+
+	// When --coverage is active, also apply Istanbul instrumentation so
+	// that ESM modules appear in the human-readable coverage report.
+	// The plugin writes to globalThis.__coverage__ at runtime (on the
+	// main thread), just like the CJS path does.
+	if (config.coverage) {
+		plugins.push(sourceCodeCoverage(filename));
+	}
+
+	let transformed: ReturnType<typeof transformSync>;
+	try {
+		transformed = transformSync(code, {
+			filename,
+			sourceFileName: filename,
+			sourceMaps: "inline",
+			plugins,
+			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 = fuzzerCoverage.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,22 @@ export class Instrumentor {
 		);
 	}
 
+	get dryRun(): boolean {
+		return this.isDryRun;
+	}
+
+	get includePatterns(): string[] {
+		return this.includes;
+	}
+
+	get excludePatterns(): string[] {
+		return this.excludes;
+	}
+
+	get coverageEnabled(): boolean {
+		return this.shouldCollectSourceCodeCoverage;
+	}
+
 	private shouldCollectCodeCoverage(filepath: string): boolean {
 		return (
 			this.shouldCollectSourceCodeCoverage &&
@@ -223,4 +242,47 @@ 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,
+				coverage: instrumentor.coverageEnabled,
+			},
+		});
+	} catch {
+		// Silently fall back to CJS-only instrumentation.
+	}
 }

packages/instrumentor/plugins/codeCoverage.ts

@@ -14,111 +14,19 @@
  * limitations under the License.
  */
 
-import { NodePath, PluginTarget, types } from "@babel/core";
-import {
-	BlockStatement,
-	ConditionalExpression,
-	Expression,
-	ExpressionStatement,
-	Function,
-	IfStatement,
-	isBlockStatement,
-	isLogicalExpression,
-	LogicalExpression,
-	Loop,
-	Statement,
-	SwitchStatement,
-	TryStatement,
-} from "@babel/types";
+import { PluginTarget, types } from "@babel/core";
 
 import { EdgeIdStrategy } from "../edgeIdStrategy";
 
-export function codeCoverage(idStrategy: EdgeIdStrategy): () => PluginTarget {
-	function addCounterToStmt(stmt: Statement): BlockStatement {
-		const counterStmt = makeCounterIncStmt();
-		if (isBlockStatement(stmt)) {
-			const br = stmt as BlockStatement;
-			br.body.unshift(counterStmt);
-			return br;
-		} else {
-			return types.blockStatement([counterStmt, stmt]);
-		}
-	}
-
-	function makeCounterIncStmt(): ExpressionStatement {
-		return types.expressionStatement(makeCounterIncExpr());
-	}
+import { makeCoverageVisitor } from "./coverageVisitor";
 
-	function makeCounterIncExpr(): Expression {
-		return types.callExpression(
-			types.identifier("Fuzzer.coverageTracker.incrementCounter"),
-			[types.numericLiteral(idStrategy.nextEdgeId())],
-		);
-	}
-
-	return () => {
-		return {
-			visitor: {
-				Function(path: NodePath<Function>) {
-					if (isBlockStatement(path.node.body)) {
-						const bodyStmt = path.node.body as BlockStatement;
-						if (bodyStmt) {
-							bodyStmt.body.unshift(makeCounterIncStmt());
-						}
-					}
-				},
-				IfStatement(path: NodePath<IfStatement>) {
-					path.node.consequent = addCounterToStmt(path.node.consequent);
-					if (path.node.alternate) {
-						path.node.alternate = addCounterToStmt(path.node.alternate);
-					}
-					path.insertAfter(makeCounterIncStmt());
-				},
-				SwitchStatement(path: NodePath<SwitchStatement>) {
-					path.node.cases.forEach((caseStmt) =>
-						caseStmt.consequent.unshift(makeCounterIncStmt()),
-					);
-					path.insertAfter(makeCounterIncStmt());
-				},
-				Loop(path: NodePath<Loop>) {
-					path.node.body = addCounterToStmt(path.node.body);
-					path.insertAfter(makeCounterIncStmt());
-				},
-				TryStatement(path: NodePath<TryStatement>) {
-					const catchStmt = path.node.handler;
-					if (catchStmt) {
-						catchStmt.body.body.unshift(makeCounterIncStmt());
-					}
-					path.insertAfter(makeCounterIncStmt());
-				},
-				LogicalExpression(path: NodePath<LogicalExpression>) {
-					if (!isLogicalExpression(path.node.left)) {
-						path.node.left = types.sequenceExpression([
-							makeCounterIncExpr(),
-							path.node.left,
-						]);
-					}
-					if (!isLogicalExpression(path.node.right)) {
-						path.node.right = types.sequenceExpression([
-							makeCounterIncExpr(),
-							path.node.right,
-						]);
-					}
-				},
-				ConditionalExpression(path: NodePath<ConditionalExpression>) {
-					path.node.consequent = types.sequenceExpression([
-						makeCounterIncExpr(),
-						path.node.consequent,
-					]);
-					path.node.alternate = types.sequenceExpression([
-						makeCounterIncExpr(),
-						path.node.alternate,
-					]);
-					if (isBlockStatement(path.parent)) {
-						path.insertAfter(makeCounterIncStmt());
-					}
-				},
-			},
-		};
-	};
+export function codeCoverage(idStrategy: EdgeIdStrategy): () => PluginTarget {
+	return () => ({
+		visitor: makeCoverageVisitor(() =>
+			types.callExpression(
+				types.identifier("Fuzzer.coverageTracker.incrementCounter"),
+				[types.numericLiteral(idStrategy.nextEdgeId())],
+			),
+		),
+	});
 }