@maizzle/framework 6.0.0-rc.0 → 6.0.0-rc.2

package/node_modules/{commander → maizzle/node_modules/commander}/lib/command.js

@@ -80,6 +80,12 @@ class Command extends EventEmitter {
     /** @type {Command} */
     this._helpCommand = undefined; // lazy initialised, inherited
     this._helpConfiguration = {};
+    /** @type {string | undefined} */
+    this._helpGroupHeading = undefined; // soft initialised when added to parent
+    /** @type {string | undefined} */
+    this._defaultCommandGroup = undefined;
+    /** @type {string | undefined} */
+    this._defaultOptionGroup = undefined;
   }
 
   /**
@@ -239,7 +245,10 @@ class Command extends EventEmitter {
   configureOutput(configuration) {
     if (configuration === undefined) return this._outputConfiguration;
 
-    Object.assign(this._outputConfiguration, configuration);
+    this._outputConfiguration = {
+      ...this._outputConfiguration,
+      ...configuration,
+    };
     return this;
   }
 
@@ -320,16 +329,16 @@ class Command extends EventEmitter {
    *
    * @param {string} name
    * @param {string} [description]
-   * @param {(Function|*)} [fn] - custom argument processing function
+   * @param {(Function|*)} [parseArg] - custom argument processing function or default value
    * @param {*} [defaultValue]
    * @return {Command} `this` command for chaining
    */
-  argument(name, description, fn, defaultValue) {
+  argument(name, description, parseArg, defaultValue) {
     const argument = this.createArgument(name, description);
-    if (typeof fn === 'function') {
-      argument.default(defaultValue).argParser(fn);
+    if (typeof parseArg === 'function') {
+      argument.default(defaultValue).argParser(parseArg);
     } else {
-      argument.default(fn);
+      argument.default(parseArg);
     }
     this.addArgument(argument);
     return this;
@@ -365,7 +374,7 @@ class Command extends EventEmitter {
    */
   addArgument(argument) {
     const previousArgument = this.registeredArguments.slice(-1)[0];
-    if (previousArgument && previousArgument.variadic) {
+    if (previousArgument?.variadic) {
       throw new Error(
         `only the last argument can be variadic '${previousArgument.name()}'`,
       );
@@ -400,11 +409,15 @@ class Command extends EventEmitter {
   helpCommand(enableOrNameAndArgs, description) {
     if (typeof enableOrNameAndArgs === 'boolean') {
       this._addImplicitHelpCommand = enableOrNameAndArgs;
+      if (enableOrNameAndArgs && this._defaultCommandGroup) {
+        // make the command to store the group
+        this._initCommandGroup(this._getHelpCommand());
+      }
       return this;
     }
 
-    enableOrNameAndArgs = enableOrNameAndArgs ?? 'help [command]';
-    const [, helpName, helpArgs] = enableOrNameAndArgs.match(/([^ ]+) *(.*)/);
+    const nameAndArgs = enableOrNameAndArgs ?? 'help [command]';
+    const [, helpName, helpArgs] = nameAndArgs.match(/([^ ]+) *(.*)/);
     const helpDescription = description ?? 'display help for command';
 
     const helpCommand = this.createCommand(helpName);
@@ -414,6 +427,8 @@ class Command extends EventEmitter {
 
     this._addImplicitHelpCommand = true;
     this._helpCommand = helpCommand;
+    // init group unless lazy create
+    if (enableOrNameAndArgs || description) this._initCommandGroup(helpCommand);
 
     return this;
   }
@@ -435,6 +450,7 @@ class Command extends EventEmitter {
 
     this._addImplicitHelpCommand = true;
     this._helpCommand = helpCommand;
+    this._initCommandGroup(helpCommand);
     return this;
   }
 
@@ -613,6 +629,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 -  already used by option '${matchingOption.flags}'`);
     }
 
+    this._initOptionGroup(option);
     this.options.push(option);
   }
 
@@ -640,6 +657,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       );
     }
 
+    this._initCommandGroup(command);
     this.commands.push(command);
   }
 
@@ -683,7 +701,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       if (val !== null && option.parseArg) {
         val = this._callParseArg(option, val, oldValue, invalidValueMessage);
       } else if (val !== null && option.variadic) {
-        val = option._concatValue(val, oldValue);
+        val = option._collectValue(val, oldValue);
       }
 
       // Fill-in appropriate missing values. Long winded but easy to follow.
@@ -1462,7 +1480,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   _chainOrCall(promise, fn) {
     // thenable
-    if (promise && promise.then && typeof promise.then === 'function') {
+    if (promise?.then && typeof promise.then === 'function') {
       // already have a promise, chain callback
       return promise.then(() => fn());
     }
@@ -1593,7 +1611,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       promiseChain = this._chainOrCallHooks(promiseChain, 'postAction');
       return promiseChain;
     }
-    if (this.parent && this.parent.listenerCount(commandEvent)) {
+    if (this.parent?.listenerCount(commandEvent)) {
       checkForUnknownOptions();
       this._processArguments();
       this.parent.emit(commandEvent, operands, unknown); // legacy
@@ -1723,33 +1741,49 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *     sub --unknown uuu op => [sub], [--unknown uuu op]
    *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    *
-   * @param {string[]} argv
+   * @param {string[]} args
    * @return {{operands: string[], unknown: string[]}}
    */
 
-  parseOptions(argv) {
+  parseOptions(args) {
     const operands = []; // operands, not options or values
     const unknown = []; // first unknown option and remaining unknown args
     let dest = operands;
-    const args = argv.slice();
 
     function maybeOption(arg) {
       return arg.length > 1 && arg[0] === '-';
     }
 
+    const negativeNumberArg = (arg) => {
+      // return false if not a negative number
+      if (!/^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/.test(arg)) return false;
+      // negative number is ok unless digit used as an option in command hierarchy
+      return !this._getCommandAndAncestors().some((cmd) =>
+        cmd.options
+          .map((opt) => opt.short)
+          .some((short) => /^-\d$/.test(short)),
+      );
+    };
+
     // parse options
     let activeVariadicOption = null;
-    while (args.length) {
-      const arg = args.shift();
+    let activeGroup = null; // working through group of short options, like -abc
+    let i = 0;
+    while (i < args.length || activeGroup) {
+      const arg = activeGroup ?? args[i++];
+      activeGroup = null;
 
       // literal
       if (arg === '--') {
         if (dest === unknown) dest.push(arg);
-        dest.push(...args);
+        dest.push(...args.slice(i));
         break;
       }
 
-      if (activeVariadicOption && !maybeOption(arg)) {
+      if (
+        activeVariadicOption &&
+        (!maybeOption(arg) || negativeNumberArg(arg))
+      ) {
         this.emit(`option:${activeVariadicOption.name()}`, arg);
         continue;
       }
@@ -1760,14 +1794,17 @@ Expecting one of '${allowedValues.join("', '")}'`);
         // recognised option, call listener to assign value with possible custom processing
         if (option) {
           if (option.required) {
-            const value = args.shift();
+            const value = args[i++];
             if (value === undefined) this.optionMissingArgument(option);
             this.emit(`option:${option.name()}`, value);
           } else if (option.optional) {
             let value = null;
             // historical behaviour is optional value is following arg unless an option
-            if (args.length > 0 && !maybeOption(args[0])) {
-              value = args.shift();
+            if (
+              i < args.length &&
+              (!maybeOption(args[i]) || negativeNumberArg(args[i]))
+            ) {
+              value = args[i++];
             }
             this.emit(`option:${option.name()}`, value);
           } else {
@@ -1790,9 +1827,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
             // option with value following in same argument
             this.emit(`option:${option.name()}`, arg.slice(2));
           } else {
-            // boolean option, emit and put back remainder of arg for further processing
+            // boolean option
             this.emit(`option:${option.name()}`);
-            args.unshift(`-${arg.slice(2)}`);
+            // remove the processed option and keep processing group
+            activeGroup = `-${arg.slice(2)}`;
           }
           continue;
         }
@@ -1812,7 +1850,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
       // Might be a command-argument, or subcommand option, or unknown option, or help command or option.
 
       // An unknown option means further arguments also classified as unknown so can be reprocessed by subcommands.
-      if (maybeOption(arg)) {
+      // A negative number in a leaf command is not an unknown option.
+      if (
+        dest === operands &&
+        maybeOption(arg) &&
+        !(this.commands.length === 0 && negativeNumberArg(arg))
+      ) {
         dest = unknown;
       }
 
@@ -1824,26 +1867,23 @@ Expecting one of '${allowedValues.join("', '")}'`);
       ) {
         if (this._findCommand(arg)) {
           operands.push(arg);
-          if (args.length > 0) unknown.push(...args);
+          unknown.push(...args.slice(i));
           break;
         } else if (
           this._getHelpCommand() &&
           arg === this._getHelpCommand().name()
         ) {
-          operands.push(arg);
-          if (args.length > 0) operands.push(...args);
+          operands.push(arg, ...args.slice(i));
           break;
         } else if (this._defaultCommandName) {
-          unknown.push(arg);
-          if (args.length > 0) unknown.push(...args);
+          unknown.push(arg, ...args.slice(i));
           break;
         }
       }
 
       // If using passThroughOptions, stop processing options at first command-argument.
       if (this._passThroughOptions) {
-        dest.push(arg);
-        if (args.length > 0) dest.push(...args);
+        dest.push(arg, ...args.slice(i));
         break;
       }
 
@@ -2294,6 +2334,75 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return this;
   }
 
+  /**
+   * Set/get the help group heading for this subcommand in parent command's help.
+   *
+   * @param {string} [heading]
+   * @return {Command | string}
+   */
+
+  helpGroup(heading) {
+    if (heading === undefined) return this._helpGroupHeading ?? '';
+    this._helpGroupHeading = heading;
+    return this;
+  }
+
+  /**
+   * Set/get the default help group heading for subcommands added to this command.
+   * (This does not override a group set directly on the subcommand using .helpGroup().)
+   *
+   * @example
+   * program.commandsGroup('Development Commands:);
+   * program.command('watch')...
+   * program.command('lint')...
+   * ...
+   *
+   * @param {string} [heading]
+   * @returns {Command | string}
+   */
+  commandsGroup(heading) {
+    if (heading === undefined) return this._defaultCommandGroup ?? '';
+    this._defaultCommandGroup = heading;
+    return this;
+  }
+
+  /**
+   * Set/get the default help group heading for options added to this command.
+   * (This does not override a group set directly on the option using .helpGroup().)
+   *
+   * @example
+   * program
+   *   .optionsGroup('Development Options:')
+   *   .option('-d, --debug', 'output extra debugging')
+   *   .option('-p, --profile', 'output profiling information')
+   *
+   * @param {string} [heading]
+   * @returns {Command | string}
+   */
+  optionsGroup(heading) {
+    if (heading === undefined) return this._defaultOptionGroup ?? '';
+    this._defaultOptionGroup = heading;
+    return this;
+  }
+
+  /**
+   * @param {Option} option
+   * @private
+   */
+  _initOptionGroup(option) {
+    if (this._defaultOptionGroup && !option.helpGroupHeading)
+      option.helpGroup(this._defaultOptionGroup);
+  }
+
+  /**
+   * @param {Command} cmd
+   * @private
+   */
+  _initCommandGroup(cmd) {
+    if (this._defaultCommandGroup && !cmd.helpGroup())
+      cmd.helpGroup(this._defaultCommandGroup);
+  }
+
   /**
    * Set the name of the command from script filename, such as process.argv[1],
    * or require.main.filename, or __filename.
@@ -2448,12 +2557,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   helpOption(flags, description) {
-    // Support disabling built-in help option.
+    // Support enabling/disabling built-in help option.
     if (typeof flags === 'boolean') {
-      // true is not an expected value. Do something sensible but no unit-test.
-      // istanbul ignore if
       if (flags) {
-        this._helpOption = this._helpOption ?? undefined; // preserve existing option
+        if (this._helpOption === null) this._helpOption = undefined; // reenable
+        if (this._defaultOptionGroup) {
+          // make the option to store the group
+          this._initOptionGroup(this._getHelpOption());
+        }
       } else {
         this._helpOption = null; // disable
       }
@@ -2461,9 +2572,12 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     // Customise flags and description.
-    flags = flags ?? '-h, --help';
-    description = description ?? 'display help for command';
-    this._helpOption = this.createOption(flags, description);
+    this._helpOption = this.createOption(
+      flags ?? '-h, --help',
+      description ?? 'display help for command',
+    );
+    // init group unless lazy create
+    if (flags || description) this._initOptionGroup(this._helpOption);
 
     return this;
   }
@@ -2492,6 +2606,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
   addHelpOption(option) {
     this._helpOption = option;
+    this._initOptionGroup(option);
     return this;
   }
 

package/node_modules/{commander → maizzle/node_modules/commander}/lib/help.js

@@ -352,7 +352,11 @@ class Help {
       extraInfo.push(`env: ${option.envVar}`);
     }
     if (extraInfo.length > 0) {
-      return `${option.description} (${extraInfo.join(', ')})`;
+      const extraDescription = `(${extraInfo.join(', ')})`;
+      if (option.description) {
+        return `${option.description} ${extraDescription}`;
+      }
+      return extraDescription;
     }
 
     return option.description;
@@ -388,6 +392,46 @@ class Help {
     return argument.description;
   }
 
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   *
+   * @param {string} heading
+   * @param {string[]} items
+   * @param {Help} helper
+   * @returns string[]
+   */
+  formatItemList(heading, items, helper) {
+    if (items.length === 0) return [];
+
+    return [helper.styleTitle(heading), ...items, ''];
+  }
+
+  /**
+   * Group items by their help group heading.
+   *
+   * @param {Command[] | Option[]} unsortedItems
+   * @param {Command[] | Option[]} visibleItems
+   * @param {Function} getGroup
+   * @returns {Map<string, Command[] | Option[]>}
+   */
+  groupItems(unsortedItems, visibleItems, getGroup) {
+    const result = new Map();
+    // Add groups in order of appearance in unsortedItems.
+    unsortedItems.forEach((item) => {
+      const group = getGroup(item);
+      if (!result.has(group)) result.set(group, []);
+    });
+    // Add items in order of appearance in visibleItems.
+    visibleItems.forEach((item) => {
+      const group = getGroup(item);
+      if (!result.has(group)) {
+        result.set(group, []);
+      }
+      result.get(group).push(item);
+    });
+    return result;
+  }
+
   /**
    * Generate the built-in help text.
    *
@@ -429,28 +473,25 @@ class Help {
         helper.styleArgumentDescription(helper.argumentDescription(argument)),
       );
     });
-    if (argumentList.length > 0) {
-      output = output.concat([
-        helper.styleTitle('Arguments:'),
-        ...argumentList,
-        '',
-      ]);
-    }
+    output = output.concat(
+      this.formatItemList('Arguments:', argumentList, helper),
+    );
 
     // Options
-    const optionList = helper.visibleOptions(cmd).map((option) => {
-      return callFormatItem(
-        helper.styleOptionTerm(helper.optionTerm(option)),
-        helper.styleOptionDescription(helper.optionDescription(option)),
-      );
+    const optionGroups = this.groupItems(
+      cmd.options,
+      helper.visibleOptions(cmd),
+      (option) => option.helpGroupHeading ?? 'Options:',
+    );
+    optionGroups.forEach((options, group) => {
+      const optionList = options.map((option) => {
+        return callFormatItem(
+          helper.styleOptionTerm(helper.optionTerm(option)),
+          helper.styleOptionDescription(helper.optionDescription(option)),
+        );
+      });
+      output = output.concat(this.formatItemList(group, optionList, helper));
     });
-    if (optionList.length > 0) {
-      output = output.concat([
-        helper.styleTitle('Options:'),
-        ...optionList,
-        '',
-      ]);
-    }
 
     if (helper.showGlobalOptions) {
       const globalOptionList = helper
@@ -461,29 +502,26 @@ class Help {
             helper.styleOptionDescription(helper.optionDescription(option)),
           );
         });
-      if (globalOptionList.length > 0) {
-        output = output.concat([
-          helper.styleTitle('Global Options:'),
-          ...globalOptionList,
-          '',
-        ]);
-      }
+      output = output.concat(
+        this.formatItemList('Global Options:', globalOptionList, helper),
+      );
     }
 
     // Commands
-    const commandList = helper.visibleCommands(cmd).map((cmd) => {
-      return callFormatItem(
-        helper.styleSubcommandTerm(helper.subcommandTerm(cmd)),
-        helper.styleSubcommandDescription(helper.subcommandDescription(cmd)),
-      );
+    const commandGroups = this.groupItems(
+      cmd.commands,
+      helper.visibleCommands(cmd),
+      (sub) => sub.helpGroup() || 'Commands:',
+    );
+    commandGroups.forEach((commands, group) => {
+      const commandList = commands.map((sub) => {
+        return callFormatItem(
+          helper.styleSubcommandTerm(helper.subcommandTerm(sub)),
+          helper.styleSubcommandDescription(helper.subcommandDescription(sub)),
+        );
+      });
+      output = output.concat(this.formatItemList(group, commandList, helper));
     });
-    if (commandList.length > 0) {
-      output = output.concat([
-        helper.styleTitle('Commands:'),
-        ...commandList,
-        '',
-      ]);
-    }
 
     return output.join('\n');
   }

package/node_modules/{commander → maizzle/node_modules/commander}/lib/option.js

@@ -33,6 +33,7 @@ class Option {
     this.argChoices = undefined;
     this.conflictsWith = [];
     this.implied = undefined;
+    this.helpGroupHeading = undefined; // soft initialised when option added to command
   }
 
   /**
@@ -161,12 +162,13 @@ class Option {
    * @package
    */
 
-  _concatValue(value, previous) {
+  _collectValue(value, previous) {
     if (previous === this.defaultValue || !Array.isArray(previous)) {
       return [value];
     }
 
-    return previous.concat(value);
+    previous.push(value);
+    return previous;
   }
 
   /**
@@ -185,7 +187,7 @@ class Option {
         );
       }
       if (this.variadic) {
-        return this._concatValue(arg, previous);
+        return this._collectValue(arg, previous);
       }
       return arg;
     };
@@ -219,6 +221,17 @@ class Option {
     return camelcase(this.name());
   }
 
+  /**
+   * Set the help group heading.
+   *
+   * @param {string} heading
+   * @return {Option}
+   */
+  helpGroup(heading) {
+    this.helpGroupHeading = heading;
+    return this;
+  }
+
   /**
    * Check if `arg` matches the short or long flag.
    *

package/node_modules/{commander → maizzle/node_modules/commander}/package-support.json

@@ -9,7 +9,10 @@
         "type": "time-permitting"
       },
       "backing": {
-        "npm-funding": true
+        "donations": [
+          "https://github.com/sponsors/abetomo",
+          "https://github.com/sponsors/shadowspawn"
+        ]
       }
     }
   ]

package/node_modules/{commander → maizzle/node_modules/commander}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "13.1.0",
+  "version": "14.0.3",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -61,22 +61,22 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.4.0",
-    "@types/jest": "^29.2.4",
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.7.4",
     "eslint": "^9.17.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-jest": "^28.3.0",
-    "globals": "^15.7.0",
-    "jest": "^29.3.1",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-jest": "^29.0.1",
+    "globals": "^16.0.0",
+    "jest": "^30.0.3",
     "prettier": "^3.2.5",
     "ts-jest": "^29.0.3",
-    "tsd": "^0.31.0",
+    "tsd": "^0.33.0",
     "typescript": "^5.0.4",
     "typescript-eslint": "^8.12.2"
   },
   "types": "typings/index.d.ts",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "support": true
 }