feat: add --aliases flag for readme command (#925) (#952)

* feat: add `--aliases` flag for readme command

* fix: create test fixture to test --no-aliases flag

* fix: eslint issues

Co-authored-by: Shazron Abdullah <36107+shazron@users.noreply.github.com>

src/commands/readme.ts

@@ -30,6 +30,7 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
   static flags = {
     dir: Flags.string({description: 'output directory for multi docs', default: 'docs', required: true}),
     multi: Flags.boolean({description: 'create a different markdown page for each topic'}),
+    aliases: Flags.boolean({description: 'include aliases in the command list', allowNo: true, default: true}),
   }
 
   private HelpClass!: HelpBaseDerived
@@ -55,6 +56,7 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
 
     let commands = config.commands
     .filter(c => !c.hidden && c.pluginType === 'core')
+    .filter(c => flags.aliases ? true : !c.aliases.includes(c.id))
     .map(c => c.id === '.' ? {...c, id: ''} : c)
 
     this.debug('commands:', commands.map(c => c.id).length)

test/fixtures/cli-command-with-alias/README.md

@@ -0,0 +1,17 @@
+# cli-command-with-alias
+
+This file is a test for running `oclif-dev readme` with aliases. If the --no-aliases flag
+is passed as a flag, no aliases should be in the README.
+
+<!-- toc -->
+<!-- tocstop -->
+
+# Usage
+
+<!-- usage -->
+<!-- usagestop -->
+
+# Commands
+
+<!-- commands -->
+<!-- commandsstop -->

test/fixtures/cli-command-with-alias/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "cli-command-with-alias",
+  "files": [
+    "/lib"
+  ],
+  "oclif": {
+    "commands": "./lib/commands",
+    "bin": "oclif",
+    "helpClass": "./lib/help"
+  }
+}

test/fixtures/cli-command-with-alias/src/commands/hello.ts

@@ -0,0 +1,13 @@
+import {Command} from '@oclif/core'
+
+export default class Hello extends Command {
+  static description = 'a simple command'
+
+  static flags = {}
+
+  static aliases = ['hi']
+
+  async run(): Promise<void> {
+    this.log('hello world')
+  }
+}

test/fixtures/cli-command-with-alias/src/help.ts

@@ -0,0 +1,7 @@
+import {Interfaces, Help} from '@oclif/core'
+
+export default class CustomHelp extends Help {
+  formatCommand(command: Interfaces.Command): string {
+    return `Custom help for ${command.id}`
+  }
+}

test/fixtures/cli-command-with-alias/src/index.ts

@@ -0,0 +1 @@
+export {run} from '@oclif/core'

test/fixtures/cli-command-with-alias/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "importHelpers": true,
+    "module": "commonjs",
+    "outDir": "lib",
+    "rootDir": "src",
+    "strict": true,
+    "target": "es2017"
+  },
+  "include": [
+    "src/**/*"
+  ]
+}

test/unit/readme.test.ts

@@ -26,6 +26,33 @@ describe('readme', () => {
     expect(fs.readFileSync('README.md', 'utf8')).to.contain('multi')
   })
 
+  describe('with command that has an alias', () => {
+    const rootPath = path.join(__dirname, '../fixtures/cli-command-with-alias')
+    const readmePath = path.join(rootPath, 'README.md')
+    const originalReadme = fs.readFileSync(readmePath, 'utf8')
+    const aliasOutput = '`oclif hi`'
+
+    test
+    .stdout()
+    .finally(() => fs.writeFileSync(readmePath, originalReadme))
+    .stub(process, 'cwd', () => rootPath)
+    .command(['readme'])
+    .it('--aliases flag (default)', () => {
+      const newReadme = fs.readFileSync(readmePath, 'utf8')
+      expect(newReadme).to.contain(aliasOutput)
+    })
+
+    test
+    .stdout()
+    .finally(() => fs.writeFileSync(readmePath, originalReadme))
+    .stub(process, 'cwd', () => rootPath)
+    .command(['readme', '--no-aliases'])
+    .it('--no-aliases flag', () => {
+      const newReadme = fs.readFileSync(readmePath, 'utf8')
+      expect(newReadme).not.to.contain(aliasOutput)
+    })
+  })
+
   describe('with custom help that implements formatCommand', () => {
     const rootPath = path.join(__dirname, '../fixtures/cli-with-custom-help')
     const readmePath = path.join(rootPath, 'README.md')