☕️ Classic, reliable, trusted test framework for Node.js and the browser
feat!: replace yargs-parser in CLI option loading (#6124)
Josh Goldberg ✨e846f8f54754
diff --git a/lib/cli/options.cjs b/lib/cli/options.cjsindex 11f79a52..f28c1450 100644--- a/lib/cli/options.cjs+++ b/lib/cli/options.cjs@@ -9,38 +9,25 @@const { readFileSync } = require("node:fs");const pc = require("picocolors");-const yargsParser = require("yargs-parser");-const {- types,- aliases,- isMochaFlag,- expectedTypeForFlag,-} = require("./run-option-metadata.cjs");+const { parseMochaArgs } = require("./parse-args.js");const { ONE_AND_DONE_ARGS } = require("./one-and-dones.js");const mocharc = require("../mocharc.json");-const { list } = require("./run-helpers.cjs");const { loadConfig, findConfig } = require("./config.cjs");const { sync } = require("find-up");const debugModule = require("debug");-const { isNodeFlag } = require("./node-flags.cjs");-const {- createUnparsableFileError,- createInvalidArgumentTypeError,- createUnsupportedError,-} = require("../errors.js");-const { isNumeric } = require("../utils.cjs");+const { createUnparsableFileError, isMochaError } = require("../errors.js");const debug = debugModule("mocha:cli:options");/**- * The `yargs-parser` namespace- * @external yargsParser- * @see {@link https://npm.im/yargs-parser}+ * The `parseArgs` function+ * @external parseArgs+ * @see {@link https://nodejs.org/api/util.html#utilparseargsconfig}*//**- * An object returned by a configured `yargs-parser` representing arguments- * @memberof external:yargsParser+ * An object representing arguments parsed from the CLI+ * @memberof external:parseArgs* @interface Arguments*/@@ -56,152 +43,23 @@ const YARGS_PARSER_CONFIG = {};/**- * This is the config pulled from the `yargs` property of Mocha's- * `package.json`, but it also disables camel case expansion as to- * avoid outputting non-canonical keynames, as we need to do some- * lookups.- * @private- * @ignore- */-const configuration = Object.assign({}, YARGS_PARSER_CONFIG, {- "camel-case-expansion": false,-});--/**- * This is a really fancy way to:- * - `array`-type options: ensure unique values and evtl. split comma-delimited lists- * - `boolean`/`number`/`string`- options: use last element when given multiple times- * This is passed as the `coerce` option to `yargs-parser`- * @private- * @ignore- */-const globOptions = ["spec", "ignore"];-const coerceOpts = Object.assign(- types.array.reduce(- (acc, arg) =>- Object.assign(acc, {- [arg]: (v) =>- Array.from(new Set(globOptions.includes(arg) ? v : list(v))),- }),- {},- ),- types.boolean- .concat(types.string, types.number)- .reduce(- (acc, arg) =>- Object.assign(acc, { [arg]: (v) => (Array.isArray(v) ? v.pop() : v) }),- {},- ),-);--/**- * We do not have a case when multiple arguments are ever allowed after a flag- * (e.g., `--foo bar baz quux`), so we fix the number of arguments to 1 across- * the board of non-boolean options.- * This is passed as the `narg` option to `yargs-parser`- * @private- * @ignore- */-const nargOpts = types.array- .concat(types.string, types.number)- .reduce((acc, arg) => Object.assign(acc, { [arg]: 1 }), {});--/**- * Throws either "UNSUPPORTED" error or "INVALID_ARG_TYPE" error for numeric positional arguments.- * @param {string[]} allArgs - Stringified args passed to mocha cli- * @param {number} numericArg - Numeric positional arg for which error must be thrown- * @param {Object} parsedResult - Result from `yargs-parser`- * @private- * @ignore- */-const createErrorForNumericPositionalArg = (- numericArg,- allArgs,- parsedResult,-) => {- // A flag for `numericArg` exists if:- // 1. A mocha flag immediately preceeded the numericArg in `allArgs` array and- // 2. `numericArg` value could not be assigned to this flag by `yargs-parser` because of incompatible datatype.- const flag = allArgs.find((arg, index) => {- const normalizedArg = arg.replace(/^--?/, "");- return (- isMochaFlag(arg) &&- allArgs[index + 1] === String(numericArg) &&- parsedResult[normalizedArg] !== String(numericArg)- );- });-- if (flag) {- throw createInvalidArgumentTypeError(- `Mocha flag '${flag}' given invalid option: '${numericArg}'`,- numericArg,- expectedTypeForFlag(flag),- );- } else {- throw createUnsupportedError(- `Option ${numericArg} is unsupported by the mocha cli`,- );- }-};--/**- * Wrapper around `yargs-parser` which applies our settings+ * Wrapper around `parseArgs` which applies our settings* @param {string|string[]} args - Arguments to parse* @param {Object} defaultValues - Default values of mocharc.json- * @param {...Object} configObjects - `configObjects` for yargs-parser+ * @param {...Object} configObjects - Objects to merge into parsed arguments* @private* @ignore*/const parse = (args = [], defaultValues = {}, ...configObjects) => {- // save node-specific args for special handling.- // 1. when these args have a "=" they should be considered to have values- // 2. if they don't, they are just boolean flags- // 3. to avoid explicitly defining the set of them, we tell yargs-parser they- // are ALL boolean flags.- // 4. we can then reapply the values after yargs-parser is done.- const allArgs = Array.isArray(args) ? args : args.split(" ");- const nodeArgs = allArgs.reduce((acc, arg) => {- const pair = arg.split("=");- let flag = pair[0];- if (isNodeFlag(flag, false)) {- flag = flag.replace(/^--?/, "");- return acc.concat([[flag, arg.includes("=") ? pair[1] : true]]);+ try {+ return parseMochaArgs(args, defaultValues, ...configObjects);+ } catch (err) {+ if (isMochaError(err)) {+ throw err;}- return acc;- }, []);-- const result = yargsParser.detailed(args, {- configuration,- configObjects,- default: defaultValues,- coerce: coerceOpts,- narg: nargOpts,- alias: aliases,- string: types.string,- array: types.array,- number: types.number,- boolean: types.boolean.concat(nodeArgs.map((pair) => pair[0])),- });- if (result.error) {- console.error(pc.red(`Error: ${result.error.message}`));+ console.error(pc.red(`Error: ${err.message}`));process.exit(1);}-- const numericPositionalArg = result.argv._.find((arg) => isNumeric(arg));- if (numericPositionalArg) {- createErrorForNumericPositionalArg(- numericPositionalArg,- allArgs,- result.argv,- );- }-- // reapply "=" arg values from above- nodeArgs.forEach(([key, value]) => {- result.argv[key] = value;- });-- return result.argv;};/**diff --git a/lib/cli/parse-args.js b/lib/cli/parse-args.jsnew file mode 100644index 00000000..f35c133f--- /dev/null+++ b/lib/cli/parse-args.js@@ -0,0 +1,306 @@+import { parseArgs } from "node:util";+import {+ createInvalidArgumentTypeError,+ createUnsupportedError,+} from "../errors.js";+import { isNumeric } from "../utils.cjs";+import { list } from "./run-helpers.cjs";+import {+ aliases,+ expectedTypeForFlag,+ isMochaFlag,+ types,+} from "./run-option-metadata.cjs";+import { isNodeFlag } from "./node-flags.cjs";++const globOptions = ["spec", "ignore"];+const aliasToCanonical = Object.entries(aliases).reduce(+ (acc, [canonical, optionAliases]) => {+ optionAliases.forEach((alias) => {+ acc[alias] = canonical;+ });+ return acc;+ },+ {},+);++const canonicalOptionName = (name) => aliasToCanonical[name] || name;++const optionTypeByName = Object.entries(types).reduce((acc, [type, names]) => {+ names.forEach((name) => {+ acc[name] = type;+ });+ return acc;+}, {});++const arrayOptions = new Set(types.array);+const booleanOptions = new Set(types.boolean);+const numberOptions = new Set(types.number);+const scalarOptions = new Set(types.boolean.concat(types.string, types.number));++/**+ * Directly-passed Node/V8 flags are not a fixed list known to this parser. When+ * we see them, define them as boolean options for parseArgs(), then reapply any+ * values from equals-form flags after parsing.+ */+const createParseArgsOptions = (nodeArgs) => {+ const options = {};++ Object.entries(optionTypeByName).forEach(([name, type]) => {+ const short = (aliases[name] || []).find((alias) => alias.length === 1);+ options[name] = {+ type: type === "boolean" ? "boolean" : "string",+ multiple: type !== "boolean",+ };+ if (short) {+ options[name].short = short;+ }+ });++ nodeArgs.forEach(([name]) => {+ options[name] = { type: "boolean" };+ });++ return options;+};++const toArray = (value) => {+ if (value === undefined) {+ return [];+ }+ return Array.isArray(value) ? value : [value];+};++// Array-type options should have unique values, with comma-delimited values+// split unless the option is a glob where commas can be part of the pattern.+const coerceArrayOption = (name, value) => {+ const values = toArray(value);+ return Array.from(+ new Set(globOptions.includes(name) ? values : list(values)),+ );+};++// Boolean/string/number options use the last value when given multiple times.+const coerceScalarOption = (name, value) => {+ const scalar = Array.isArray(value) ? value[value.length - 1] : value;++ if (booleanOptions.has(name)) {+ if (scalar === "false") {+ return false;+ }+ if (scalar === "true") {+ return true;+ }+ }++ return scalar;+};++const coerceNumberOption = (value) => {+ const scalar = Array.isArray(value) ? value[value.length - 1] : value;+ return scalar === undefined ? scalar : Number(scalar);+};++const mergeValue = (existing, next) => {+ if (existing === undefined) {+ return next;+ }+ return toArray(existing).concat(toArray(next));+};++const mergeConfigObjects = (defaultValues, configObjects) => {+ const defaultArrayOptions = new Set();++ return [defaultValues]+ .concat(configObjects.slice().reverse())+ .reduce((merged, config) => {+ if (!config) {+ return merged;+ }++ Object.entries(config).forEach(([rawName, value]) => {+ const name = canonicalOptionName(rawName);+ if (name === "_") {+ merged._ = mergeValue(value, merged._);+ } else if (arrayOptions.has(name)) {+ if (config === defaultValues) {+ defaultArrayOptions.add(name);+ merged[name] = value;+ } else if (defaultArrayOptions.has(name)) {+ defaultArrayOptions.delete(name);+ merged[name] = value;+ } else {+ merged[name] = mergeValue(value, merged[name]);+ }+ } else {+ merged[name] = value;+ }+ });++ return merged;+ }, {});+};++const preprocessArgs = (allArgs) => {+ return allArgs.map((arg) => {+ const noPrefix = arg.replace(/^--?/, "");+ const [name, ...rest] = noPrefix.split("=");+ const canonical = canonicalOptionName(name.replace(/^no-/, ""));+ const negated = name.startsWith("no-");+ const prefix = arg.startsWith("--") ? "--" : arg.startsWith("-") ? "-" : "";++ if (!prefix || name === canonical || name.length === 1) {+ return arg;+ }++ const normalizedName = negated ? `no-${canonical}` : canonical;+ return `${prefix}${normalizedName}${rest.length ? `=${rest.join("=")}` : ""}`;+ });+};++const requiresValue = (name) => {+ const canonical = canonicalOptionName(name);+ return (+ arrayOptions.has(canonical) ||+ types.string.includes(canonical) ||+ numberOptions.has(canonical)+ );+};++/**+ * Disallows multiple arguments after a single option, such as `--grep abc def`.+ */+const validateArgsBeforeParse = (allArgs) => {+ allArgs.forEach((arg, index) => {+ if (!arg.startsWith("-") || arg === "--" || arg.includes("=")) {+ return;+ }++ const name = canonicalOptionName(arg.replace(/^--?/, ""));+ const next = allArgs[index + 1];++ if (requiresValue(name) && (next === undefined || next.startsWith("-"))) {+ throw new Error(`Not enough arguments following: ${name}`);+ }+ });+};++const normalizeParsedValues = (values, positionals) => {+ const normalized = Object.assign({ _: positionals }, values);++ Object.keys(normalized).forEach((rawName) => {+ if (rawName === "_") {+ return;+ }++ const name = canonicalOptionName(rawName);+ if (name !== rawName) {+ normalized[name] = mergeValue(normalized[name], normalized[rawName]);+ delete normalized[rawName];+ }+ });++ arrayOptions.forEach((name) => {+ if (normalized[name] !== undefined) {+ normalized[name] = coerceArrayOption(name, normalized[name]);+ }+ });++ scalarOptions.forEach((name) => {+ if (normalized[name] !== undefined) {+ normalized[name] = coerceScalarOption(name, normalized[name]);+ }+ });++ numberOptions.forEach((name) => {+ if (normalized[name] !== undefined) {+ normalized[name] = coerceNumberOption(normalized[name]);+ }+ });++ return normalized;+};++const createErrorForNumericPositionalArg = (+ numericArg,+ allArgs,+ parsedResult,+) => {+ // A flag for `numericArg` exists if:+ // 1. A Mocha flag immediately preceded the numericArg in `allArgs`, and+ // 2. parseArgs() could not assign the numericArg to that flag because the+ // option has an incompatible datatype.+ const flag = allArgs.find((arg, index) => {+ const normalizedArg = arg.replace(/^--?/, "");+ return (+ isMochaFlag(arg) &&+ allArgs[index + 1] === String(numericArg) &&+ parsedResult[normalizedArg] !== String(numericArg)+ );+ });++ if (flag) {+ throw createInvalidArgumentTypeError(+ `Mocha flag '${flag}' given invalid option: '${numericArg}'`,+ numericArg,+ expectedTypeForFlag(flag),+ );+ }++ throw createUnsupportedError(+ `Option ${numericArg} is unsupported by the mocha cli`,+ );+};++export const parseMochaArgs = (+ args = [],+ defaultValues = {},+ ...configObjects+) => {+ const allArgs = Array.isArray(args) ? args : args ? args.split(" ") : [];++ // Save Node-specific args for special handling. Equals-form args have values;+ // the rest are boolean flags.+ const nodeArgs = allArgs.reduce((acc, arg) => {+ const pair = arg.split("=");+ let flag = pair[0];+ if (isNodeFlag(flag, false)) {+ flag = flag.replace(/^--?/, "");+ return acc.concat([[flag, arg.includes("=") ? pair[1] : true]]);+ }+ return acc;+ }, []);++ validateArgsBeforeParse(allArgs);+ const parsed = parseArgs({+ args: preprocessArgs(allArgs),+ options: createParseArgsOptions(nodeArgs),+ allowNegative: true,+ allowPositionals: true,+ strict: false,+ });++ const result = normalizeParsedValues(+ Object.assign(+ mergeConfigObjects(defaultValues, configObjects),+ parsed.values,+ ),+ parsed.positionals,+ );++ const numericPositionalArg = result._.find((arg) => isNumeric(arg));+ if (numericPositionalArg) {+ createErrorForNumericPositionalArg(+ Number(numericPositionalArg),+ allArgs,+ result,+ );+ }++ // Reapply equals-form Node/V8 flag values saved above.+ nodeArgs.forEach(([key, value]) => {+ result[key] = value;+ });++ return result;+};diff --git a/package-lock.json b/package-lock.jsonindex 9297f25e..cd77d144 100644--- a/package-lock.json+++ b/package-lock.json@@ -26,7 +26,6 @@"supports-color": "^8.1.1","workerpool": "^10.0.0","yargs": "^17.7.2",- "yargs-parser": "^21.1.1","yargs-unparser": "^2.0.0"},"bin": {diff --git a/package.json b/package.jsonindex f5e230cd..15551803 100644--- a/package.json+++ b/package.json@@ -104,7 +104,6 @@"supports-color": "^8.1.1","workerpool": "^10.0.0","yargs": "^17.7.2",- "yargs-parser": "^21.1.1","yargs-unparser": "^2.0.0"},"devDependencies": {diff --git a/test/node-unit/cli/parse-args.spec.js b/test/node-unit/cli/parse-args.spec.jsnew file mode 100644index 00000000..5b8c2d5c--- /dev/null+++ b/test/node-unit/cli/parse-args.spec.js@@ -0,0 +1,292 @@+import { constants } from "../../../lib/error-constants.js";+import { parseMochaArgs } from "../../../lib/cli/parse-args.js";++const defaults = {+ timeout: 1000,+ extension: ["js"],+};++describe("parse-args", function () {+ it("canonicalizes aliases and strips alias keys", function () {+ const result = parseMochaArgs(+ [+ "-R",+ "json",+ "-t",+ "123",+ "-A",+ "-b",+ "-g",+ "foo",+ "-r",+ "./x.js",+ "-O",+ "a=b",+ "test/a.js",+ ],+ defaults,+ );++ expect(result, "to satisfy", {+ _: ["test/a.js"],+ reporter: "json",+ timeout: "123",+ "async-only": true,+ bail: true,+ grep: "foo",+ require: ["./x.js"],+ "reporter-option": ["a=b"],+ });+ ["R", "t", "A", "b", "g", "r", "O"].forEach((alias) => {+ expect(result, "not to have property", alias);+ });+ });++ it("uses the last value for repeated scalar options across aliases", function () {+ expect(+ parseMochaArgs(["--timeout", "100", "-t", "10"], defaults),+ "to satisfy",+ {+ timeout: "10",+ },+ );+ });++ it("canonicalizes long aliases in equals form", function () {+ const result = parseMochaArgs(+ ["--reporter-options=a=b", "--timeouts=200"],+ defaults,+ );++ expect(result, "to satisfy", {+ "reporter-option": ["a=b"],+ timeout: "200",+ });+ expect(result, "not to have property", "reporter-options");+ expect(result, "not to have property", "timeouts");+ });++ it("splits, deduplicates, and preserves order for repeated array options", function () {+ expect(+ parseMochaArgs(+ [+ "--require",+ "a",+ "--require",+ "a,b",+ "--extension",+ "js,ts",+ "--extension",+ "ts",+ ],+ defaults,+ ),+ "to satisfy",+ {+ require: ["a", "b"],+ extension: ["js", "ts"],+ },+ );+ });++ it("does not split glob array options on commas", function () {+ expect(+ parseMochaArgs(+ [+ "--spec",+ "{dirA,dirB}/**/*.spec.js",+ "--ignore",+ "fixtures/{one,two}.js",+ ],+ defaults,+ ),+ "to satisfy",+ {+ spec: ["{dirA,dirB}/**/*.spec.js"],+ ignore: ["fixtures/{one,two}.js"],+ },+ );+ });++ it("replaces default array options before merging user config arrays", function () {+ expect(+ parseMochaArgs(+ [],+ defaults,+ { extension: ["ts"] },+ { extension: ["tsx"] },+ ),+ "to satisfy",+ {+ extension: ["ts", "tsx"],+ },+ );+ });++ it("canonicalizes aliases from config objects", function () {+ const result = parseMochaArgs([], defaults, {+ R: "json",+ r: ["./setup.js"],+ timeouts: "200",+ });++ expect(result, "to satisfy", {+ reporter: "json",+ require: ["./setup.js"],+ timeout: "200",+ });+ expect(result, "not to have property", "R");+ expect(result, "not to have property", "r");+ expect(result, "not to have property", "timeouts");+ });++ it("gives parsed args precedence over config objects", function () {+ expect(+ parseMochaArgs(["--require", "./cli.js", "--timeout", "100"], defaults, {+ require: ["./config.js"],+ timeout: "200",+ }),+ "to satisfy",+ {+ require: ["./cli.js"],+ timeout: "100",+ },+ );+ });++ it("preserves boolean negation including long alias negation", function () {+ expect(+ parseMochaArgs(+ [+ "--color",+ "--no-color",+ "--no-colors",+ "--parallel",+ "--no-parallel",+ "--no-timeouts",+ ],+ defaults,+ ),+ "to satisfy",+ {+ color: false,+ parallel: false,+ timeout: false,+ },+ );+ });++ it("coerces known boolean options in equals form", function () {+ expect(+ parseMochaArgs(["--color=false", "--parallel=true"], defaults),+ "to satisfy",+ {+ color: false,+ parallel: true,+ },+ );+ });++ it("coerces repeated number options to the last numeric value", function () {+ expect(+ parseMochaArgs(["--jobs", "2", "-j", "4", "--retries=3"], defaults),+ "to satisfy",+ {+ jobs: 4,+ retries: 3,+ },+ );+ });++ it("preserves unknown option negation", function () {+ expect(parseMochaArgs(["--no-foo"], defaults), "to satisfy", {+ foo: false,+ });+ });++ it("keeps unknown options accepted in equals form", function () {+ expect(parseMochaArgs(["--foo=bar"], defaults), "to satisfy", {+ _: [],+ foo: "bar",+ });+ });++ it("treats separated unknown option values as positionals", function () {+ expect(+ parseMochaArgs(["--foo", "bar", "-x", "baz"], defaults),+ "to satisfy",+ {+ _: ["bar", "baz"],+ foo: true,+ x: true,+ },+ );+ });++ it("treats the option terminator as the start of positionals", function () {+ expect(+ parseMochaArgs(["--", "--not-an-option", "test.js"], defaults),+ "to satisfy",+ {+ _: ["--not-an-option", "test.js"],+ },+ );+ });++ it("accepts dash-prefixed option values in equals form", function () {+ expect(parseMochaArgs(["--grep=-foo"], defaults), "to satisfy", {+ grep: "-foo",+ });+ });++ it("rejects dash-prefixed option values in separated form", function () {+ expect(+ () => parseMochaArgs(["--grep", "-foo"], defaults),+ "to throw",+ /Not enough arguments following: grep/,+ );+ });++ it("preserves directly-passed Node and V8 flags", function () {+ expect(+ parseMochaArgs(+ ["--trace-warnings", "--max-old-space-size=4096", "--conditions=dev"],+ defaults,+ ),+ "to satisfy",+ {+ "trace-warnings": true,+ "max-old-space-size": "4096",+ conditions: "dev",+ },+ );+ });++ it("uses the last value for repeated directly-passed Node and V8 flags", function () {+ expect(+ parseMochaArgs(["--conditions=dev", "--conditions=test"], defaults),+ "to satisfy",+ {+ conditions: "test",+ },+ );+ });++ it("uses native short option grouping behavior", function () {+ expect(parseMochaArgs(["-bc"], defaults), "to satisfy", {+ _: [],+ bail: true,+ color: true,+ });+ });++ it("preserves numeric positional argument errors", function () {+ expect(() => parseMochaArgs(["--delay", "123"], defaults), "to throw", {+ message: "Mocha flag '--delay' given invalid option: '123'",+ code: constants.INVALID_ARG_TYPE,+ argument: 123,+ actual: "number",+ expected: "boolean",+ });+ });+});