Add typings for helpGroup support (#2367)

Author: shadowspawn

lib/help.js

@@ -393,6 +393,8 @@ class Help {
   }
 
   /**
+   * Format a list of items, given a heading and an array of formatted items.
+   *
    * @param {string} heading
    * @param {string[]} items
    * @param {Help} helper
@@ -405,6 +407,7 @@ class Help {
   }
 
   /**
+   * Group items by their help group heading.
    *
    * @param {Command[] | Option[]} unsortedItems
    * @param {Command[] | Option[]} visibleItems

typings/index.d.ts

@@ -110,6 +110,7 @@ export class Option {
   parseArg?: <T>(value: string, previous: T) => T;
   hidden: boolean;
   argChoices?: string[];
+  helpGroupHeading?: string;
 
   constructor(flags: string, description?: string);
 
@@ -193,6 +194,11 @@ export class Option {
    */
   attributeName(): string;
 
+  /**
+   * Set the help group heading.
+   */
+  helpGroup(heading: string): this;
+
   /**
    * Return whether a boolean option.
    *
@@ -314,6 +320,20 @@ export class Help {
     helper: Help,
   ): string;
 
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   */
+  formatItemList(heading: string, items: string[], helper: Help): string[];
+
+  /**
+   * Group items by their help group heading.
+   */
+  groupItems<T extends Command | Option>(
+    unsortedItems: T[],
+    visibleItems: T[],
+    getGroup: (item: T) => string,
+  ): Map<string, T[]>;
+
   /** Generate the built-in help text. */
   formatHelp(cmd: Command, helper: Help): string;
 }
@@ -969,6 +989,53 @@ export class Command {
    */
   executableDir(): string | null;
 
+  /**
+   * Set the help group heading for this subcommand in parent command's help.
+   *
+   * @returns `this` command for chaining
+   */
+  helpGroup(heading: string): this;
+  /**
+   * Get the help group heading for this subcommand in parent command's help.
+   */
+  helpGroup(): string;
+
+  /**
+   * Set 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')...
+   * ...
+   *
+   * @returns `this` command for chaining
+   */
+  commandsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for subcommands added to this command.
+   */
+  commandsGroup(): string;
+
+  /**
+   * Set 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')
+   *
+   * @returns `this` command for chaining
+   */
+  optionsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for options added to this command.
+   */
+  optionsGroup(): string;
+
   /**
    * Output help information for this command.
    *

typings/index.test-d.ts

@@ -433,6 +433,16 @@ expectType<string>(program.usage());
 expectType<commander.Command>(program.name('my-name'));
 expectType<string>(program.name());
 
+// helpGroup related
+expectType<commander.Command>(program.helpGroup('My Group'));
+expectType<string>(program.helpGroup());
+
+expectType<commander.Command>(program.commandsGroup('My Group'));
+expectType<string>(program.commandsGroup());
+
+expectType<commander.Command>(program.optionsGroup('My Group'));
+expectType<string>(program.optionsGroup());
+
 // nameFromFilename
 expectType<commander.Command>(program.nameFromFilename(__filename));
 
@@ -599,6 +609,40 @@ expectType<string>(
 );
 expectType<boolean>(helper.preformatted('a\nb c'));
 
+{
+  const formattedItems = [
+    '--example  example description',
+    '--example2 example2 description',
+  ];
+  expectType<string[]>(
+    helper.formatItemList('Options', formattedItems, helper),
+  );
+}
+
+{
+  const unsortedOptions = [new commander.Option('-a, --all')];
+  const sortedOptions = unsortedOptions;
+  const groupsItemsOptionHeading = (option: commander.Option) =>
+    option.helpGroupHeading ?? 'Options:';
+  expectType<Map<string, commander.Option[]>>(
+    helper.groupItems(unsortedOptions, sortedOptions, groupsItemsOptionHeading),
+  );
+}
+
+{
+  const unsortedCommands = [new commander.Command('foo')];
+  const sortedCommands = unsortedCommands;
+  const groupsItemsCommandHeading = (cmd: commander.Command) =>
+    cmd.helpGroup() ?? 'Commands:';
+  expectType<Map<string, commander.Command[]>>(
+    helper.groupItems(
+      unsortedCommands,
+      sortedCommands,
+      groupsItemsCommandHeading,
+    ),
+  );
+}
+
 expectType<string>(helper.styleTitle('Usage:'));
 
 expectType<string>(helper.styleUsage('foo [options] <file>'));
@@ -638,6 +682,7 @@ expectType<unknown>(baseOption.presetArg);
 expectType<string | undefined>(baseOption.envVar);
 expectType<boolean>(baseOption.hidden);
 expectType<string[] | undefined>(baseOption.argChoices);
+expectType<string | undefined>(baseOption.helpGroupHeading);
 
 // Option methods
 
@@ -690,6 +735,11 @@ expectType<string>(baseOption.name());
 // attributeName
 expectType<string>(baseOption.attributeName());
 
+// helpGroup
+expectType<commander.Option>(baseOption.helpGroup('My Group'));
+// @ts-expect-error: Option helpGroup() can not be used as a getter.
+baseOption.helpGroup();
+
 // isBoolean
 expectType<boolean>(baseOption.isBoolean());