From f1925a7136408a328dbfcf3146f8eb1fbd8d04a9 Mon Sep 17 00:00:00 2001
From: Mike Donnalley <mdonnalley@salesforce.com>
Date: Wed, 11 Oct 2023 13:41:59 -0600
Subject: [PATCH] feat: add hideAliases help option

---
 src/flags.ts                   |  5 +--
 src/help/index.ts              | 11 +++---
 src/interfaces/help.ts         |  4 +++
 src/main.ts                    |  2 +-
 test/help/fixtures/fixtures.ts |  9 +++++
 test/help/show-help.test.ts    | 64 ++++++++++++++++++++++++++++++++++
 test/integration/util.ts       |  1 -
 7 files changed, 87 insertions(+), 9 deletions(-)

diff --git a/src/flags.ts b/src/flags.ts
index 15183df86..9a9481fdc 100644
--- a/src/flags.ts
+++ b/src/flags.ts
@@ -1,4 +1,3 @@
-/* eslint-disable valid-jsdoc */
 import {URL} from 'node:url'
 
 import {CLIError} from './errors'
@@ -140,7 +139,9 @@ export const help = (opts: Partial<BooleanFlag<boolean>> = {}): BooleanFlag<void
     ...opts,
     async parse(_, cmd) {
       const Help = await loadHelpClass(cmd.config)
-      await new Help(cmd.config, cmd.config.pjson.helpOptions).showHelp(cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv)
+      await new Help(cmd.config, cmd.config.pjson.helpOptions ?? cmd.config.pjson.oclif.helpOptions).showHelp(
+        cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv,
+      )
       cmd.exit(0)
     },
   })
diff --git a/src/help/index.ts b/src/help/index.ts
index 0e28f9398..c1f6ea7d0 100644
--- a/src/help/index.ts
+++ b/src/help/index.ts
@@ -98,12 +98,13 @@ export class Help extends HelpBase {
 
   protected formatCommands(commands: Array<Command.Loadable>): string {
     if (commands.length === 0) return ''
-
     const body = this.renderList(
-      commands.map((c) => {
-        if (this.config.topicSeparator !== ':') c.id = c.id.replaceAll(':', this.config.topicSeparator)
-        return [c.id, this.summary(c)]
-      }),
+      commands
+        .filter((c) => (this.opts.hideAliasesFromRoot ? !c.aliases?.includes(c.id) : true))
+        .map((c) => {
+          if (this.config.topicSeparator !== ':') c.id = c.id.replaceAll(':', this.config.topicSeparator)
+          return [c.id, this.summary(c)]
+        }),
       {
         indentation: 2,
         spacer: '\n',
diff --git a/src/interfaces/help.ts b/src/interfaces/help.ts
index 23023a65b..f0ca5c0e7 100644
--- a/src/interfaces/help.ts
+++ b/src/interfaces/help.ts
@@ -4,6 +4,10 @@ export interface HelpOptions {
    * Use docopts as the usage. Defaults to true.
    */
   docopts?: boolean
+  /**
+   * If true, hide command aliases from the root help output. Defaults to false.
+   */
+  hideAliasesFromRoot?: boolean
   /**
    * By default, the command summary is show at the top of the help and as the first line in
    * the command description. Repeating the summary in the command description improves readability
diff --git a/src/main.ts b/src/main.ts
index 4d9e155f9..842fb7e53 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -70,7 +70,7 @@ export async function run(argv?: string[], options?: Interfaces.LoadOptions): Pr
   // display help version if applicable
   if (helpAddition(argv, config)) {
     const Help = await loadHelpClass(config)
-    const help = new Help(config, config.pjson.helpOptions)
+    const help = new Help(config, config.pjson.helpOptions ?? config.pjson.oclif.helpOptions)
     await help.showHelp(argv)
     await collectPerf()
     return
diff --git a/test/help/fixtures/fixtures.ts b/test/help/fixtures/fixtures.ts
index 9ff601f9e..fe05e21ef 100644
--- a/test/help/fixtures/fixtures.ts
+++ b/test/help/fixtures/fixtures.ts
@@ -154,3 +154,12 @@ export class LongDescription extends Command {
     'run'
   }
 }
+
+export class CommandWithAliases extends Command {
+  static aliases = ['bar', 'baz', 'qux']
+  static description = 'This is a command with aliases'
+  static id = 'foo'
+  async run(): Promise<void> {
+    'run'
+  }
+}
diff --git a/test/help/show-help.test.ts b/test/help/show-help.test.ts
index 9e44775de..01db70f07 100644
--- a/test/help/show-help.test.ts
+++ b/test/help/show-help.test.ts
@@ -13,6 +13,7 @@ import {
   AppsDestroy,
   AppsIndex,
   AppsTopic,
+  CommandWithAliases,
   DbCreate,
   DbTopic,
   DeprecateAliases,
@@ -135,6 +136,69 @@ USAGE
 COMMANDS
   apps  List all apps (app index command)`)
     })
+
+  test
+    .loadConfig()
+    .stdout()
+    .do(async (ctx) => {
+      const {config} = ctx
+
+      monkeyPatchCommands(config, [
+        {
+          name: 'plugin-1',
+          commands: [CommandWithAliases],
+          topics: [],
+        },
+      ])
+
+      const help = new TestHelp(config as any, {hideAliasesFromRoot: true})
+      await help.showHelp([])
+    })
+    .it('shows root help without aliases if hideAliasesFromRoot=true', ({stdout, config}) => {
+      expect(stdout.trim()).to.equal(`base library for oclif CLIs
+
+VERSION
+  ${config.userAgent}
+
+USAGE
+  $ oclif [COMMAND]
+
+COMMANDS
+  foo  This is a command with aliases`)
+    })
+
+  test
+    .loadConfig()
+    .stdout()
+    .do(async (ctx) => {
+      const {config} = ctx
+
+      monkeyPatchCommands(config, [
+        {
+          name: 'plugin-1',
+          commands: [CommandWithAliases],
+          topics: [],
+        },
+      ])
+
+      const help = new TestHelp(config as any)
+      await help.showHelp([])
+    })
+    .it('shows root help with aliases commands by default', ({stdout, config}) => {
+      expect(stdout.trim()).to.equal(`base library for oclif CLIs
+
+VERSION
+  ${config.userAgent}
+
+USAGE
+  $ oclif [COMMAND]
+
+COMMANDS
+  bar  This is a command with aliases
+  baz  This is a command with aliases
+  foo  This is a command with aliases
+  qux  This is a command with aliases`)
+    })
 })
 
 describe('showHelp for a topic', () => {
diff --git a/test/integration/util.ts b/test/integration/util.ts
index 005f92cee..fc2c3066e 100644
--- a/test/integration/util.ts
+++ b/test/integration/util.ts
@@ -113,7 +113,6 @@ export class Executor {
   }
 }
 
-// eslint-disable-next-line valid-jsdoc
 /**
  * Setup for integration tests.
  *