refactor(options): align extracted options with LibAFL

Finish the options split by moving engine and mode checks into the leaf package and sharing the LibAFL backend DTO with the fuzzer package. This leaves one generic extraction commit at the start of the branch and one LibAFL-specific follow-up later in the stack.

Author: oetr

package-lock.json

@@ -18,29 +18,10 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 
-import {
-	defaultCLIOptions,
-	defaultJestOptions,
-	Options,
-	OptionsManager,
-	OptionSource,
-	resolveEngine,
-} from "@jazzer.js/options";
+import { OptionsManager, OptionSource } from "@jazzer.js/options";
 
 import { buildLibAflOptions, spawnsSubprocess } from "./options";
 
-describe("options", () => {
-	describe("merge", () => {
-		it("keeps libFuzzer as default CLI engine", () => {
-			expect(defaultCLIOptions.engine).toBe("libfuzzer");
-		});
-
-		it("keeps libFuzzer as default Jest engine", () => {
-			expect(defaultJestOptions.engine).toBe("libfuzzer");
-		});
-	});
-});
-
 describe("buildLibFuzzerOptions", () => {
 	describe("spawnsSubprocess", () => {
 		it("checks if subprocess libFuzzer flags are present", () => {
@@ -57,22 +38,6 @@ describe("buildLibFuzzerOptions", () => {
 });
 
 describe("libafl options", () => {
-	it("normalizes engine aliases", () => {
-		expect(resolveEngine("libfuzzer")).toBe("libfuzzer");
-		expect(resolveEngine("afl")).toBe("libafl");
-		expect(resolveEngine("libafl")).toBe("libafl");
-		expect(() => resolveEngine("unknown")).toThrow("Unknown fuzzing engine");
-	});
-
-	it("canonicalizes engine aliases during option merge", () => {
-		const manager = new OptionsManager(OptionSource.DefaultJestOptions).merge(
-			{ engine: "afl" },
-			OptionSource.ConfigurationFile,
-		);
-
-		expect(manager.get("engine")).toBe("libafl");
-	});
-
 	it("builds structured LibAFL options from fuzzer options", () => {
 		const manager = new OptionsManager(OptionSource.DefaultCLIOptions).merge(
 			{

packages/core/options.test.ts

@@ -20,6 +20,7 @@ import * as util from "util";
 import * as tmp from "tmp";
 
 import {
+	type LibAflOptions,
 	type OptionsManager,
 	resolveEngine,
 	toOptionsWithPrintableSources,
@@ -29,31 +30,22 @@ import { useDictionaryByParams } from "./dictionary";
 
 export * from "@jazzer.js/options";
 
-export type LibAflOptions = {
-	mode: "fuzzing" | "regression";
-	runs: number;
-	seed: number;
-	maxLen: number;
-	timeoutMillis: number;
-	maxTotalTimeSeconds: number;
-	artifactPrefix: string;
-	corpusDirectories: string[];
-	dictionaryFiles: string[];
-};
-
 export function buildLibFuzzerOptions(options: OptionsManager) {
 	let params: string[] = [];
 	params = optionDependentParams(options, params);
 	params = forkedExecutionParams(params);
 	params = useDictionaryByParams(params, options.get("dictionaryEntries"));
 
+	// libFuzzer has to ignore SIGINT and SIGTERM, as it interferes
+	// with the Node.js signal handling.
 	params = params.concat("-handle_int=0", "-handle_term=0", "-handle_segv=0");
 
 	printOptions(options);
 	logInfoAboutFuzzerOptions(params);
 	return params;
 }
 
+// Backwards-compatible alias for existing call sites.
 export const buildFuzzerOption = buildLibFuzzerOptions;
 
 export function buildLibAflOptions(options: OptionsManager): LibAflOptions {
@@ -114,6 +106,8 @@ export function buildLibAflOptions(options: OptionsManager): LibAflOptions {
 	}
 
 	if (options.get("mode") === "regression") {
+		// Regression mode should replay every available corpus input unless the
+		// user asked to stop for some other reason, mirroring libFuzzer's behavior.
 		runs = 0;
 	}
 
@@ -216,6 +210,7 @@ function optionDependentParams(
 
 	let opts = options.get("fuzzerOptions");
 	if (options.get("mode") === "regression") {
+		// The last provided option takes precedence
 		opts = opts.concat("-runs=0");
 	}
 

packages/core/options.ts

@@ -17,6 +17,8 @@
 import * as fs from "fs";
 import * as path from "path";
 
+import type { LibAflOptions } from "@jazzer.js/options";
+
 export type FuzzTargetAsyncOrValue = (
 	data: Buffer,
 ) => unknown | Promise<unknown>;
@@ -26,18 +28,7 @@ export type FuzzTargetCallback = (
 ) => unknown;
 export type FuzzTarget = FuzzTargetAsyncOrValue | FuzzTargetCallback;
 export type FuzzOpts = string[];
-
-export type LibAflOptions = {
-	mode: "fuzzing" | "regression";
-	runs: number;
-	seed: number;
-	maxLen: number;
-	timeoutMillis: number;
-	maxTotalTimeSeconds: number;
-	artifactPrefix: string;
-	corpusDirectories: string[];
-	dictionaryFiles: string[];
-};
+export type { LibAflOptions } from "@jazzer.js/options";
 
 export type StartFuzzingSyncFn = (
 	fuzzFn: FuzzTarget,

packages/fuzzer/addon.ts

@@ -28,6 +28,7 @@
 		]
 	},
 	"dependencies": {
+		"@jazzer.js/options": "4.0.0",
 		"bindings": "^1.5.0",
 		"cmake-js": "^8.0.0",
 		"node-addon-api": "^8.7.0"

packages/fuzzer/package.json

@@ -4,5 +4,10 @@
 		"rootDir": ".",
 		"outDir": "dist"
 	},
-	"exclude": ["build", "dist", "runtime", "cmake-build-*"]
+	"exclude": ["build", "dist", "runtime", "cmake-build-*"],
+	"references": [
+		{
+			"path": "../options"
+		}
+	]
 }

packages/fuzzer/tsconfig.json

@@ -14,6 +14,18 @@
  * limitations under the License.
  */
 
+export type LibAflOptions = {
+	mode: "fuzzing" | "regression";
+	runs: number;
+	seed: number;
+	maxLen: number;
+	timeoutMillis: number;
+	maxTotalTimeSeconds: number;
+	artifactPrefix: string;
+	corpusDirectories: string[];
+	dictionaryFiles: string[];
+};
+
 /**
  * Jazzer.js options structure expected by the fuzzer.
  *
@@ -137,6 +149,7 @@ export const fromSnakeCase: KeyFormatSource = (key: string): string => {
 		group.toUpperCase().replace("_", ""),
 	);
 };
+
 export const fromSnakeCaseWithPrefix: (prefix: string) => KeyFormatSource = (
 	prefix: string,
 ): KeyFormatSource => {

packages/options/index.ts

@@ -273,30 +273,6 @@ describe("options", () => {
 	});
 });
 
-describe("engine and mode", () => {
-	it("normalizes engine aliases", () => {
-		expect(resolveEngine("libfuzzer")).toBe("libfuzzer");
-		expect(resolveEngine("afl")).toBe("libafl");
-		expect(resolveEngine("libafl")).toBe("libafl");
-		expect(() => resolveEngine("unknown")).toThrow("Unknown fuzzing engine");
-	});
-
-	it("normalizes fuzzing modes", () => {
-		expect(resolveMode("fuzzing")).toBe("fuzzing");
-		expect(resolveMode("regression")).toBe("regression");
-		expect(() => resolveMode("unknown")).toThrow("Unknown fuzzing mode");
-	});
-
-	it("canonicalizes engine aliases during option merge", () => {
-		const manager = new OptionsManager(OptionSource.DefaultJestOptions).merge(
-			{ engine: "afl" },
-			OptionSource.ConfigurationFile,
-		);
-
-		expect(manager.get("engine")).toBe("libafl");
-	});
-});
-
 describe("KeyFormatSource", () => {
 	describe("fromSnakeCase", () => {
 		it("converts to camelCase", () => {
@@ -334,6 +310,30 @@ describe("KeyFormatSource", () => {
 	});
 });
 
+describe("engine and mode", () => {
+	it("normalizes engine aliases", () => {
+		expect(resolveEngine("libfuzzer")).toBe("libfuzzer");
+		expect(resolveEngine("afl")).toBe("libafl");
+		expect(resolveEngine("libafl")).toBe("libafl");
+		expect(() => resolveEngine("unknown")).toThrow("Unknown fuzzing engine");
+	});
+
+	it("normalizes fuzzing modes", () => {
+		expect(resolveMode("fuzzing")).toBe("fuzzing");
+		expect(resolveMode("regression")).toBe("regression");
+		expect(() => resolveMode("unknown")).toThrow("Unknown fuzzing mode");
+	});
+
+	it("canonicalizes engine aliases during option merge", () => {
+		const manager = new OptionsManager(OptionSource.DefaultJestOptions).merge(
+			{ engine: "afl" },
+			OptionSource.ConfigurationFile,
+		);
+
+		expect(manager.get("engine")).toBe("libafl");
+	});
+});
+
 function expectDefaultsExceptKeys(
 	options: Options,
 	source: OptionSource,