feat: add ESM support

.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

README.md

@@ -113,9 +113,13 @@ module.exports.fuzz = function (data /*: Buffer */) {
 };
 ```
 
+ES modules are supported on Node.js >= 20.6 — use `export function fuzz` in a
+`.js`/`.mjs` file with `"type": "module"` in your `package.json`. See
+[docs/fuzz-targets.md](docs/fuzz-targets.md#esm-support) for details.
+
 ## Documentation
 
-Further documentation is available at [docs/readme.md](docs/README.md).
+Further documentation is available at [docs/README.md](docs/README.md).
 
 ### Demo Video - Introduction to Jazzer.js
 

docs/architecture.md

@@ -25,14 +25,16 @@ The _fuzzing library_ is the main entry point and is used to start fuzzing. It
 is invoked with the name of a _fuzz target_ module and possible fuzzer options.
 As a first step it loads a
 [native plugin](https://nodejs.org/api/addons.html#wrapping-c-objects) Node.js
-addon, _fuzzer plugin_, to interact with libFuzzer and registers a `require`
-hook, _interceptor_, to instrument subsequently loaded code.
-
-The _interceptor_ transforms code using [Babel](https://babeljs.io/) to provide
-feedback to the fuzzer in multiple ways. It extends the loaded code to gather
-coverage statistics so that the fuzzer can detect when new code paths are
-reached. And it also intercepts comparison functions, like `==` or `!=`, to
-detect the parts of the provided input that should be mutated and in what way.
+addon, _fuzzer plugin_, to interact with libFuzzer and registers instrumentation
+hooks to transform subsequently loaded code.
+
+For CJS modules, a `require` hook (via `istanbul-lib-hook`) intercepts loading.
+For ES modules (Node >= 20.6), a loader hook registered via `module.register()`
+intercepts `import` statements in a dedicated loader thread.
+
+Both paths use [Babel](https://babeljs.io/) to transform source code, inserting
+coverage counters so the fuzzer can detect new code paths, and comparison hooks
+(for `==`, `!=`, etc.) so the fuzzer can mutate input toward specific values.
 Available feedback methods are defined in libFuzzer's
 [hook interface definitions](https://github.com/llvm/llvm-project/blob/main/compiler-rt/include/sanitizer/common_interface_defs.h).
 
@@ -70,14 +72,14 @@ information to detect progress and comparison hints to improve mutations. These
 feedback mechanisms have to be added to the application code without user
 intervention.
 
-**Decision**: Use the `istanbul-lib-hook` library to hook into dynamic code
-loading and `babel` plugins to extend the loaded code with the required feedback
-functionality. Instrumenting the code at such a high level leads to an
-independence of the underlying JavaScript engine. Furthermore, it is easily
-possible to decide if a loaded module should be instrumented or not.
+**Decision**: Use `istanbul-lib-hook` to hook into CJS loading and
+`module.register()` to hook into ESM loading, with Babel plugins to insert
+feedback instrumentation. Instrumenting at the source level decouples from the
+underlying JavaScript engine and allows fine-grained control over which modules
+are instrumented.
 
 **Consequences**: Independence of JavaScript engine, fine-grained
-instrumentation control
+instrumentation control, ESM support on Node >= 20.6.
 
 ## Visualization
 

docs/bug-detectors.md

@@ -91,7 +91,7 @@ prototype, it will be able also find a way to modify other properties of the
 prototype that are not functions. If you find a use case where this assumption
 does not hold, feel free to open an issue.
 
-_Disable with:_ `--disableBugDetectors=prototype-pollution`in CLI mode; or when
+_Disable with:_ `--disableBugDetectors=prototype-pollution` in CLI mode; or when
 using Jest in `.jazzerjsrc.json`:
 
 ```json
@@ -104,7 +104,7 @@ Hooks the `eval` and `Function` functions and reports a finding if the fuzzer
 was able to pass a special string to `eval` and to the function body of
 `Function`.
 
-_Disable with:_ `--disable_bug_detectors=remote-code-execution`in CLI mode; or
+_Disable with:_ `--disableBugDetectors=remote-code-execution` in CLI mode; or
 when using Jest in `.jazzerjsrc.json`:
 
 ```json
@@ -127,8 +127,8 @@ getBugDetectorConfiguration("ssrf")
 	.addPermittedUDPConnection("localhost", 9090);
 ```
 
-_Disable with:_ `--disable_bug_detectors=ssrf` in CLI mode; or when using Jest
-in `.jazzerjsrc.json`:
+_Disable with:_ `--disableBugDetectors=ssrf` in CLI mode; or when using Jest in
+`.jazzerjsrc.json`:
 
 ```json
 { "disableBugDetectors": ["ssrf"] }

docs/fuzz-settings.md

@@ -297,7 +297,7 @@ configured for Jest.
 add the following environment variable to the command:
 
 ```bash
-JAZZER_COVERAGE='["json","lcov"]' npx jazzer my-fuzz-file --coverage
+JAZZER_COVERAGE_REPORTERS='["json","lcov"]' npx jazzer my-fuzz-file --coverage
 ```
 
 _Note:_ Setting this environmental variable in Jest mode has no effect.
@@ -366,11 +366,11 @@ provide them as an array of strings, `Uint8Arrays`, or `Int8Arrays` to the
 `dictionaryEntries` option of the `it.fuzz` function:
 
 ```javascript
-const xmlDictionary = ["IDREF","<![IGNORE[","<![INCLUDE[",<!"];
+const xmlDictionary = ["IDREF", "<![IGNORE[", "<![INCLUDE[", "<!"];
 
 it.fuzz("XML parser",
 	(data) => {...},
-	{dictionaryEntries: xmlDictionary}
+	{dictionaryEntries: xmlDictionary});
 ```
 
 ### `disableBugDetectors` : [array\<RegExp\>]
@@ -814,8 +814,7 @@ In _regression_ mode on command line, Jazzer.js runs each input from the seed
 and regression corpus directories on the fuzz target once, and then stops. Under
 the hood, this option adds `-runs=0` to the option
 [`fuzzerOptions`](#fuzzeroptions--arraystring). Setting the fuzzer option to
-`-runs=0` (run each input only once) or `-runs=-1` (run each input indefinitely)
-can be used to achieve the same behavior.
+`-runs=0` (run each input only once) can be used to achieve the same behavior.
 
 **Jest:** Default: `"regression"`.
 
@@ -954,7 +953,7 @@ example how a timeout of 1 second can be set for the test "My test 1":
 ```javascript
 it.fuzz("My test 1",
 	(data) => {...},
-	1000
+	1000);
 ```
 
 _Two:_ by providing it as part of an object with options as the third argument

docs/fuzz-targets.md

@@ -107,42 +107,97 @@ supported! However, it is possible to use the
 [Jest integration](jest-integration.md) to execute Jest fuzz tests written in
 TypeScript.
 
-### ⚠️ Using Jazzer.js on pure ESM projects ⚠️
+### ESM support
 
-ESM brings a couple of challenges to the table, which are currently not fully
-solved. Jazzer.js does have general ESM support as in your project should be
-loaded properly. If your project internally still relies on calls to
-`require()`, all of these dependencies will be hooked. However, _pure_
-ECMAScript projects will currently not be instrumented!
+Jazzer.js instruments ES modules via a
+[Node.js loader hook](https://nodejs.org/api/module.html#customization-hooks)
+(`module.register`). Coverage counters, compare hooks, and function hooks all
+work on ESM code — the fuzzer sees the same feedback it gets from CJS modules.
 
-The Jest integration can improve on this and use Jest's ESM features to properly
-transform external code and dependencies. However,
-[ESM support](https://jestjs.io/docs/ecmascript-modules) in Jest is also only
-experimental.
+**Requirements:** Node.js >= 20.6. Function hooks (bug detectors) additionally
+require Node.js >= 20.11 (for `transferList` support in `module.register`). On
+older Node versions, ESM loading still works but modules are not instrumented.
 
-One such example that Jazzer.js can handle just fine can be found at
-[examples/protobufjs/fuzz.js](../examples/protobufjs/protobufjs.fuzz.js):
+#### Minimal ESM fuzz target
 
 ```js
-import proto from "protobufjs";
-import { temporaryWriteSync } from "tempy";
-
-describe("protobufjs", () => {
-	test.fuzz("loadSync", (data) => {
-		const file = temporaryWriteSync(data);
-		proto.loadSync(file);
-	});
-});
-```
+// fuzz.js  (or fuzz.mjs)
+import { parseInput } from "my-library";
 
-You also have to adapt your `package.json` accordingly, by adding:
+export function fuzz(data) {
+	parseInput(data.toString());
+}
+```
 
 ```json
 {
-	"type": "module"
+	"type": "module",
+	"main": "fuzz.js",
+	"scripts": {
+		"fuzz": "jazzer fuzz -i my-library corpus"
+	},
+	"devDependencies": {
+		"@jazzer.js/core": "^3.0.0"
+	}
 }
 ```
 
+```shell
+npm run fuzz
+```
+
+The `-i` flag tells Jazzer.js which packages to instrument. Without it,
+everything outside `node_modules` is instrumented by default.
+
+#### Direct ESM vs. Jest ESM — when to use which
+
+There are two ways to fuzz ESM code with Jazzer.js:
+
+|                               | Direct (`npx jazzer`)                                  | Jest (`@jazzer.js/jest-runner`)                                          |
+| ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------ |
+| **How ESM is instrumented**   | Loader hook (`module.register`) — native ESM stays ESM | Babel transform via `jest.config` — ESM is converted to CJS at test time |
+| **Node.js requirement**       | >= 20.6 (function hooks: >= 20.11)                     | Any supported Node.js                                                    |
+| **Fuzz target format**        | `export function fuzz(data)` in a `.js`/`.mjs` file    | `it.fuzz(name, fn)` inside a `.fuzz.cjs` test file                       |
+| **Async targets**             | Works out of the box (default mode)                    | Works out of the box                                                     |
+| **Regression testing**        | `--mode=regression` replays the corpus                 | Default Jest mode replays corpus seeds automatically                     |
+| **IDE integration**           | None (CLI only)                                        | VS Code / IntelliJ run individual inputs                                 |
+| **Multiple targets per file** | No — one exported `fuzz` function per file             | Yes — multiple `it.fuzz()` blocks in one file                            |
+| **Corpus management**         | Manual directory, passed as positional arg             | Automatic per-test directories                                           |
+
+**Rule of thumb:** use the Jest integration when you want multiple fuzz tests in
+one file, IDE debugging, or need to support Node < 20.6. Use direct ESM when you
+want a minimal setup with no Babel/Jest indirection — just your `.mjs` target
+and `npx jazzer`.
+
+#### Jest ESM setup (Babel transform approach)
+
+When fuzzing an ESM library through Jest, the fuzz tests themselves must be CJS
+(`.fuzz.cjs`), and Jest's Babel transform converts the library's ESM imports to
+`require()` calls so that Jazzer.js's CJS instrumentation hooks can intercept
+them:
+
+```js
+// jest.config.cjs
+module.exports = {
+	projects: [
+		{
+			testRunner: "@jazzer.js/jest-runner",
+			testMatch: ["<rootDir>/fuzz/**/*.fuzz.cjs"],
+			transform: {
+				"\\.js$": [
+					"babel-jest",
+					{ plugins: ["@babel/plugin-transform-modules-commonjs"] },
+				],
+			},
+			transformIgnorePatterns: ["/node_modules/"],
+		},
+	],
+};
+```
+
+This requires `@babel/core`, `babel-jest`, and
+`@babel/plugin-transform-modules-commonjs` as dev dependencies.
+
 ## Running the fuzz target
 
 After adding `@jazzer.js/core` as a `dev-dependency` to a project, the fuzzer
@@ -179,7 +234,7 @@ Here we list some of the most important parameters:
 | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `<fuzzTarget>`                          | Import path to the fuzz target module.                                                                                                                                                                                                                                                                                                                                                |
 | `[corpus...]`                           | Paths to the corpus directories. If not given, no initial seeds are used nor interesting inputs saved.                                                                                                                                                                                                                                                                                |
-| `-f`, `--fuzzFunction`                  | Name of the fuzz test entry point. It must be an exported function with a single [Buffer](https://nodejs.org/api/buffer.html) parameter. Default is `fuzz`.                                                                                                                                                                                                                           |
+| `-f`, `--fuzzEntryPoint`                | Name of the fuzz test entry point. It must be an exported function with a single [Buffer](https://nodejs.org/api/buffer.html) parameter. Default is `fuzz`.                                                                                                                                                                                                                           |
 | `-i`, `--includes` / `-e`, `--excludes` | Part of filepath names to include/exclude in the instrumentation. A tailing `/` should be used to include directories and prevent confusion with filenames. `*` can be used to include all files. Can be specified multiple times. Default will include everything outside the `node_modules` directory. If either of these flags are set the default value for the other is ignored. |
 | `--sync`                                | Enables synchronous fuzzing. **May only be used for entirely synchronous code**.                                                                                                                                                                                                                                                                                                      |
 | `-h`, `--customHooks`                   | Filenames with custom hooks. Several hooks per file are possible. See further details in [docs/fuzz-settings.md](fuzz-settings.md#customhooks--arraystring).                                                                                                                                                                                                                          |
@@ -194,14 +249,14 @@ In the following example, the `--coverage` flag is combined with the mode flag
 any fuzzing.
 
 ```shell
-npx jazzer --mode=regression <fuzzer parameters> --corpus <corpus directories> --coverage -- <libFuzzer parameters>
+npx jazzer <fuzzTarget> --mode=regression --coverage <corpus directories> -- <libFuzzer parameters>
 ```
 
 Alternatively, you can add a new script to your `package.json`:
 
 ```json
 "scripts": {
-    "coverage": "jazzer --mode=regression --includes=fileToInstrument --includes=anotherFileToInstrument <fuzzer parameters> --corpus <corpus directories> --coverage -- <libFuzzer parameters>"
+    "coverage": "jazzer <fuzzTarget> --mode=regression -i fileToInstrument -i anotherFileToInstrument --coverage <corpus directories>"
 }
 ```
 
@@ -219,6 +274,6 @@ This default directory can be changed by setting the flag
 ### Coverage reporters
 
 The desired report format can be set by the flag `--coverageReporters`, which by
-default is set to `--coverageReporters clover json lcov text`. See
+default is set to `--coverageReporters json text lcov clover`. See
 [here](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
 for a list of supported coverage reporters.

docs/jest-integration.md

@@ -53,8 +53,8 @@ runner.
 		"coverage": "jest --coverage"
 	},
 	"devDependencies": {
-		"@jazzer.js/jest-runner": "2.1.0",
-		"jest": "29.3.1"
+		"@jazzer.js/jest-runner": "^3.0.0",
+		"jest": "^29.0.0"
 	},
 	"jest": {
 		"projects": [
@@ -188,13 +188,15 @@ const target = require("./target");
 const { FuzzedDataProvider } = require("@jazzer.js/core");
 
 describe("My describe", () => {
-  it.fuzz("My fuzz test", (data) => {
-    const provider = new FuzzedDataProvider(data);
-    target.fuzzMeMore(
-      provider.consumeNumber(),
-      provider.consumeBoolean(),
-      provider.consumeRemainingAsString());
-  });
+	it.fuzz("My fuzz test", (data) => {
+		const provider = new FuzzedDataProvider(data);
+		target.fuzzMeMore(
+			provider.consumeNumber(),
+			provider.consumeBoolean(),
+			provider.consumeRemainingAsString(),
+		);
+	});
+});
 ```
 
 For more information on how to use the `FuzzedDataProvider` class, please refer
@@ -211,14 +213,14 @@ possible to use `async/await`, `Promise` and `done callback` based tests.
 
 ```javascript
 describe("My describe", () => {
-  it.fuzz("My callback fuzz test", (data, done) => {
-    target.callbackFuzzMe(data, done);
-  });
-
-  it.fuzz("My async fuzz test", async (data) => {
-    await target.asyncFuzzMe(data);
-  });
-)};
+	it.fuzz("My callback fuzz test", (data, done) => {
+		target.callbackFuzzMe(data, done);
+	});
+
+	it.fuzz("My async fuzz test", async (data) => {
+		await target.asyncFuzzMe(data);
+	});
+});
 ```
 
 ### TypeScript Jest fuzz tests
@@ -372,7 +374,7 @@ Additional options for coverage report generation are described in the
 [fuzz targets documentation](./fuzz-targets.md#coverage-report-generation).
 
 The desired report format can be set by the flag `--coverageReporters`, which by
-default is set to `--coverageReporters clover json lcov text`. See
+default is set to `--coverageReporters json text lcov clover`. See
 [here](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
 for a list of supported coverage reporters.
 

docs/release.md

@@ -21,7 +21,7 @@ To release a new version of Jazzer.js follow the described process:
    - An automatic changelog, based on the included merge requests, is added to
      the prerelease description
    - The prerelease is listed on the
-     [release page](https://github.com/CodeIntelligenceTesting/jazzer.js-commercial/releases)
+     [release page](https://github.com/CodeIntelligenceTesting/jazzer.js/releases)
 8. Release the prerelease in GitHub
    - Adjust the prerelease description to include the highlights of the release
    - If you find some problems with the prerelease and want to start over:

eslint.config.mjs

@@ -128,6 +128,7 @@ export default tseslint.config(
 	// Markdown files
 	{
 		files: ["**/*.md"],
+		ignores: ["AGENTS.md"],
 		plugins: {
 			markdownlint,
 		},