refactor(cli): streamline CLI arguments for a more intuitive Jazzer.js usage (#429)

BREAKING CHANGE: A new release will break in the wild fuzz tests.

However, a uniform format for CLI flags should be aimed for to improve
UX.

Author: 0xricksanchez

docs/fuzz-settings.md

@@ -20,7 +20,7 @@ directories are executed during startup.
 **Example invocation:**
 
 ```shell
-npx jazzer fuzzTarget corpusDir otherCorupsDir
+npx jazzer target corpus_dir other_corpus
 ```
 
 ## Reproducing errors
@@ -32,7 +32,7 @@ This input can then be used to reproduce the issue by specifying it as last
 parameter in the CLI call:
 
 ```shell
-npx jazzer fuzzTarget crash-abcdef0123456789
+npx jazzer target crash-abcdef0123456789
 ```
 
 ## Value profile
@@ -49,7 +49,7 @@ An example of using value profiling can be found at
 **Example invocation:**
 
 ```shell
-npx jazzer fuzzTarget -- -use_value_profile=1
+npx jazzer target -- -use_value_profile=1
 ```
 
 ## Timeout
@@ -64,7 +64,7 @@ Timeouts work in the sync- and asynchronous fuzzing mode.
 **Example invocation:**
 
 ```shell
-npx jazzer fuzzTarget --timeout=10000
+npx jazzer target --timeout=10000
 ```
 
 **Example output:**
@@ -113,7 +113,7 @@ definitions.
 ### Defining Custom Hooks
 
 Import the functions `registerBeforeHook`, `registerReplaceHook`,
-`registerAfterHook` from jazzer.js:
+`registerAfterHook` from Jazzer.js:
 
 ```javascript
 const {

docs/fuzz-targets.md

@@ -176,19 +176,19 @@ flag, so that only the most important parameters are discussed here.
 
 ## Coverage report generation
 
-To generate a coverage report, add the `--coverage` flag to the Jazzer.js CLI.
-In this example, the `--coverage` flag is combined with the dry run flag `-d`
-that disables internal instrumentation used by the fuzzer.
+To generate a coverage report, add the `--cov`/`--coverage` flag to the
+Jazzer.js CLI. In the following example, the `--cov` flag is combined with the
+dry run flag `-d` that disables internal instrumentation used by the fuzzer.
 
 ```shell
-npx jazzer -d <fuzzer parameters> --corpus <corpus directories> --coverage -- <libFuzzer parameters>
+npx jazzer -d <fuzzer parameters> --corpus <corpus directories> --cov -- <libFuzzer parameters>
 ```
 
-Alternatively, you can add a new script to your package.json:
+Alternatively, you can add a new script to your `package.json`:
 
 ```json
 "scripts": {
- "coverage": "jazzer -d -i target -i another_target <fuzzer parameters> --corpus <corpus directories> --coverage -- <libFuzzer parameters>"
+ "coverage": "jazzer -d -i target -i another_target <fuzzer parameters> --corpus <corpus directories> --cov -- <libFuzzer parameters>"
 }
 ```
 
@@ -201,11 +201,13 @@ fuzzing, because of the substantial overhead that it adds.
 
 By default, the coverage reports can be found in the `./coverage` directory.
 This default directory can be changed by setting the flag
-`--coverageDirectory=<another coverage directory>`.
+`--cov_dir=<another coverage directory>`. A longer flag of the form
+`--coverage_directory` also exists.
 
 ### Coverage reporters
 
-The desired report format can be set by the flag `--coverageReports`, which by
-default is set to `--coverageReports clover json lcov text`. See
+The desired report format can be set by the flags
+`--cov_reporters`/`--coverage_reporters`, which by default is set to
+`--coverage_reporters clover json lcov text`. See
 [here](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
 for a list of supported coverage reporters.

docs/jest-integration.md

@@ -299,11 +299,14 @@ To generate a coverage report, run jest with the `--coverage` flag:
 npx jest --coverage
 ```
 
+Note that unlike for the Jazzer.js CLI Jest only accepts the long flag of
+`--coverage`!
+
 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 `--coverageReports`, which by
-default is set to `--coverageReports clover json lcov text`. See
+The desired report format can be set by the flag `--coverage_reporters`, which
+by default is set to `--coverage_reporters clover json lcov text`. See
 [here](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
 for a list of supported coverage reporters.
 

examples/custom-hooks/package.json

@@ -9,7 +9,7 @@
 	"scripts": {
 		"fuzz": "jazzer fuzz -i jpeg-js -h custom-hooks --sync",
 		"dryRun": "jazzer fuzz -i jpeg-js --sync -h custom-hooks -- -runs=100 -seed=123456789",
-		"coverage": "jazzer fuzz -i jpeg-js -i fuzz.js -i custom-hooks.js -h custom-hooks --sync --coverage -- -max_total_time=10"
+		"coverage": "jazzer fuzz -i jpeg-js -i fuzz.js -i custom-hooks.js -h custom-hooks --sync --cov -- -max_total_time=10"
 	},
 	"devDependencies": {
 		"@jazzer.js/core": "file:../../packages/core"

examples/jpeg/package.json

@@ -11,7 +11,7 @@
 	"scripts": {
 		"fuzz": "jazzer fuzz -i jpeg-js --sync",
 		"dryRun": "jazzer fuzz -i jpeg-js --sync -- -runs=100 -seed=123456789",
-		"coverage": "jazzer fuzz -i jpeg-js/lib -i fuzz.js --sync --coverage -- -max_total_time=1 -seed=123456789"
+		"coverage": "jazzer fuzz -i jpeg-js/lib -i fuzz.js --sync --cov -- -max_total_time=1 -seed=123456789"
 	},
 	"devDependencies": {
 		"@jazzer.js/core": "file:../../packages/core"

packages/core/cli.ts

@@ -27,21 +27,21 @@ yargs(process.argv.slice(2))
 		"greedy-arrays": false,
 	})
 	.example(
-		"$0 package/fuzzTarget -i packages/foo -i packages/bar",
-		'Start a fuzzing run using the "fuzz" function exported by "fuzzTarget" ' +
+		"$0 package/target -i packages/foo -i packages/bar",
+		'Start a fuzzing run using the "fuzz" function exported by "target" ' +
 			'and only instrument code in the "packages/a" and "packages/b" modules.'
 	)
 	.example(
-		"$0 package/fuzzTarget corpus -- -max_total_time=60",
-		'Start a fuzzing run using the "fuzz" function exported by "fuzzTarget" ' +
+		"$0 package/target corpus -- -max_total_time=60",
+		'Start a fuzzing run using the "fuzz" function exported by "target" ' +
 			'and use the directory "corpus" to store newly generated inputs. ' +
 			'Also pass the "-max_total_time" flag to the internal fuzzing engine ' +
 			"(libFuzzer) to stop the fuzzing run after 60 seconds."
 	)
 	.command(
-		"$0 <fuzzTarget> [corpus..]",
+		"$0 <target> [corpus..]",
 		"Coverage-guided, in-process fuzzer for the Node.js platform. \n\n" +
-			'The "fuzzTarget" module has to export a function "fuzz" which accepts ' +
+			'The "target" module has to export a function "fuzz" which accepts ' +
 			"a byte array as first parameter and uses that to invoke the actual " +
 			"function to fuzz.\n\n" +
 			'The "corpus" directory is optional and can be used to provide initial ' +
@@ -52,11 +52,11 @@ yargs(process.argv.slice(2))
 			"An example is shown in the examples section of this help message.",
 		(yargs: Argv) => {
 			yargs
-				.positional("fuzzTarget", {
+				.positional("target", {
 					describe: "Name of the module that exports the fuzz target function.",
 					type: "string",
 				})
-				.demandOption("fuzzTarget")
+				.demandOption("target")
 
 				.array("corpus")
 				.positional("corpus", {
@@ -162,22 +162,25 @@ yargs(process.argv.slice(2))
 					group: "Fuzzer:",
 					default: false,
 				})
-				.boolean("coverage")
-				.option("coverage", {
+				.boolean("cov")
+				.option("cov", {
 					describe: "Enable code coverage.",
+					alias: "coverage",
 					type: "boolean",
 					group: "Fuzzer:",
 					default: false,
 				})
-				.option("coverageDirectory", {
+				.option("cov_dir", {
 					describe: "Directory for storing coverage reports.",
+					alias: "coverage_directory",
 					type: "string",
 					default: "coverage",
 					group: "Fuzzer:",
 				})
-				.array("coverageReporters")
-				.option("coverageReporters", {
+				.array("cov_reporters")
+				.option("cov_reporters", {
 					describe: "A list of reporter names for writing coverage reports.",
+					alias: "coverage_reporters",
 					type: "string",
 					group: "Fuzzer:",
 					default: ["json", "text", "lcov", "clover"],
@@ -196,7 +199,7 @@ yargs(process.argv.slice(2))
 			}
 			// noinspection JSIgnoredPromiseFromCall
 			startFuzzing({
-				fuzzTarget: ensureFilepath(args.fuzzTarget),
+				fuzzTarget: ensureFilepath(args.target),
 				fuzzEntryPoint: args.fuzz_function,
 				includes: args.instrumentation_includes,
 				excludes: args.instrumentation_excludes,
@@ -207,9 +210,9 @@ yargs(process.argv.slice(2))
 				customHooks: args.custom_hooks,
 				expectedErrors: args.expected_errors,
 				idSyncFile: args.id_sync_file,
-				coverage: args.coverage,
-				coverageDirectory: args.coverageDirectory,
-				coverageReporters: args.coverageReporters,
+				coverage: args.cov,
+				coverageDirectory: args.cov_dir,
+				coverageReporters: args.cov_reporters,
 			});
 		}
 	)

tests/code_coverage/coverage.test.js

@@ -190,18 +190,30 @@ describe("Source code coverage reports for our custom Jest runner", () => {
 	});
 });
 
+/**
+ * @param {string} coverageDirectory
+ */
 function readCoverageJson(coverageDirectory) {
 	return JSON.parse(
-		fs.readFileSync(path.join(coverageDirectory, "coverage-final.json"))
+		fs
+			.readFileSync(path.join(coverageDirectory, "coverage-final.json"))
+			.toString()
 	);
 }
 
+/**
+ * @param {string} name
+ */
 function readExpectedCoverage(name) {
 	return JSON.parse(
-		fs.readFileSync(path.join(expectedCoverageDirectory, name))
+		fs.readFileSync(path.join(expectedCoverageDirectory, name)).toString()
 	);
 }
 
+/**
+ * @param {{ statementMap: any; s: any; fnMap: any; f: any; branchMap: any; b: any; }} coverage
+ * @param {{ statementMap: any; s: any; fnMap: any; f: any; branchMap: any; b: any; }} expectedCoverage
+ */
 function expectEqualCoverage(coverage, expectedCoverage) {
 	expect(coverage.statementMap).toStrictEqual(expectedCoverage.statementMap);
 	expect(coverage.s).toStrictEqual(expectedCoverage.s);
@@ -211,11 +223,17 @@ function expectEqualCoverage(coverage, expectedCoverage) {
 	expect(coverage.b).toStrictEqual(expectedCoverage.b);
 }
 
+/**
+ * @param {boolean} includeLib
+ * @param {boolean} includeTarget
+ * @param {boolean} useCustomHooks
+ * @param {boolean} _coverage
+ */
 function executeJestRunner(
 	includeLib,
 	includeTarget,
 	useCustomHooks,
-	coverage,
+	_coverage,
 	coverageOutputDir = "coverage",
 	excludePattern = ["nothing"],
 	verbose = false
@@ -256,6 +274,13 @@ function executeJestRunner(
 	if (verbose) console.log(process.output.toString());
 }
 
+/**
+ * @param {boolean} dryRun
+ * @param {boolean} includeLib
+ * @param {boolean} includeTarget
+ * @param {boolean} useCustomHooks
+ * @param {boolean} coverage
+ */
 function executeFuzzTest(
 	dryRun,
 	includeLib,
@@ -296,10 +321,10 @@ function executeFuzzTest(
 		options.push("custom-hooks");
 	}
 	if (coverage) {
-		options.push("--coverage");
+		options.push("--cov");
 	}
 	if (coverageOutputDir) {
-		options.push("--coverageDirectory");
+		options.push("--cov_dir");
 		options.push(coverageOutputDir);
 	}
 	options.push("--");