feat: add flagSortOrder to help options

src/help/command.ts

@@ -15,6 +15,17 @@ import {HelpFormatter, HelpSection, HelpSectionRenderer} from './formatter'
 // split on any platform, not just the os specific EOL at runtime.
 const POSSIBLE_LINE_FEED = /\r\n|\n/
 
+/**
+ * Determines the sort order of flags. Will default to alphabetical if not set or set to an invalid value.
+ */
+function determineSortOrder(
+  flagSortOrder: HelpFormatter['opts']['flagSortOrder'],
+): NonNullable<HelpFormatter['opts']['flagSortOrder']> {
+  if (flagSortOrder === 'alphabetical') return 'alphabetical'
+  if (flagSortOrder === 'none') return 'none'
+  return 'alphabetical'
+}
+
 export class CommandHelp extends HelpFormatter {
   constructor(
     public command: Command.Loadable,
@@ -218,15 +229,17 @@ export class CommandHelp extends HelpFormatter {
 
   generate(): string {
     const cmd = this.command
-    const flags = sortBy(
-      Object.entries(cmd.flags || {})
-        .filter(([, v]) => !v.hidden)
-        .map(([k, v]) => {
-          v.name = k
-          return v
-        }),
-      (f) => [!f.char, f.char, f.name],
-    )
+    const unsortedFlags = Object.entries(cmd.flags || {})
+      .filter(([, v]) => !v.hidden)
+      .map(([k, v]) => {
+        v.name = k
+        return v
+      })
+
+    const flags =
+      determineSortOrder(this.opts.flagSortOrder) === 'alphabetical'
+        ? sortBy(unsortedFlags, (f) => [!f.char, f.char, f.name])
+        : unsortedFlags
 
     const args = Object.values(ensureArgObject(cmd.args)).filter((a) => !a.hidden)
     const output = compact(

src/interfaces/help.ts

@@ -4,6 +4,13 @@ export interface HelpOptions {
    * Use docopts as the usage. Defaults to true.
    */
   docopts?: boolean
+  /**
+   * Order in which to sort flags in help output. Defaults to `alphabetical`.
+   *
+   * `alphabetical`: Sort flags alphabetically. All flags with short characters will come first.
+   * `none`: Do not sort flags. They will appear in the order in which they were defined on the command.
+   */
+  flagSortOrder?: 'alphabetical' | 'none'
   /**
    * If true, hide command aliases from the root help output. Defaults to false.
    */

test/help/format-command.test.ts

@@ -732,3 +732,81 @@ EXAMPLES
     })
   })
 })
+
+describe('formatCommand with flagSortOrder', () => {
+  let config: Config
+
+  before(async () => {
+    config = await Config.load(process.cwd())
+  })
+
+  it('should not sort flags when set to "none"', async () => {
+    const help = new TestHelp(config, {flagSortOrder: 'none'})
+    const cmd = await makeLoadable(
+      makeCommandClass({
+        id: 'apps:create',
+        flags: {
+          cFlag: flags.string({char: 'c'}),
+          aFlag: flags.string({char: 'a'}),
+          bFlag: flags.string({char: 'b'}),
+        },
+      }),
+    )
+
+    const output = help.formatCommand(cmd)
+    expect(output).to.equal(`USAGE
+  $ oclif apps:create [-c <value>] [-a <value>] [-b <value>]
+
+FLAGS
+  -c, --cFlag=<value>
+  -a, --aFlag=<value>
+  -b, --bFlag=<value>`)
+  })
+
+  it('should sort flags alphabetically when flagSortOrder is not set', async () => {
+    const help = new TestHelp(config)
+    const cmd = await makeLoadable(
+      makeCommandClass({
+        id: 'apps:create',
+        flags: {
+          cFlag: flags.string({char: 'c'}),
+          aFlag: flags.string({char: 'a'}),
+          bFlag: flags.string({char: 'b'}),
+        },
+      }),
+    )
+
+    const output = help.formatCommand(cmd)
+    expect(output).to.equal(`USAGE
+  $ oclif apps:create [-c <value>] [-a <value>] [-b <value>]
+
+FLAGS
+  -a, --aFlag=<value>
+  -b, --bFlag=<value>
+  -c, --cFlag=<value>`)
+  })
+
+  it('should sort flags alphabetically when flagSortOrder is invalid', async () => {
+    // @ts-expect-error because we're testing an invalid flagSortOrder
+    const help = new TestHelp(config, {flagSortOrder: 'INVALID'})
+    const cmd = await makeLoadable(
+      makeCommandClass({
+        id: 'apps:create',
+        flags: {
+          cFlag: flags.string({char: 'c'}),
+          aFlag: flags.string({char: 'a'}),
+          bFlag: flags.string({char: 'b'}),
+        },
+      }),
+    )
+
+    const output = help.formatCommand(cmd)
+    expect(output).to.equal(`USAGE
+  $ oclif apps:create [-c <value>] [-a <value>] [-b <value>]
+
+FLAGS
+  -a, --aFlag=<value>
+  -b, --bFlag=<value>
+  -c, --cFlag=<value>`)
+  })
+})