fix: don't overwrite commands with equivalent topics in other plugins

* chore: better progress

* chore: wip

* refactor: narrower types and stronger type checking

@W-13138789@

* chore: fix tests after merge

* chore: reapply stash

* chore: wireit updates

* test: e2e tests generate test files first

* refactor: typeguard in place of assertion

* fix: binary is on commandMeta, not command

* fix: merge subtopics, use maps

* fix: config replacements in descriptions

* fix: use the correct ensureArray

* docs: readme

* refactor: reduce ts workarounds

* chore: remove unused code

* fix: missing commands where there was a topic collision

* chore: gitignore for my output files

* refactor: remove unused

---------

Co-authored-by: Peter Hale <peter.hale@salesforce.com>

Author: mshanemc

.eslintrc.js

@@ -5,7 +5,7 @@
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 module.exports = {
-  extends: ['eslint-config-salesforce-typescript', 'eslint-config-salesforce-license'],
+  extends: ['eslint-config-salesforce-typescript', 'eslint-config-salesforce-license', 'plugin:sf-plugin/recommended'],
   rules: {
     '@typescript-eslint/restrict-template-expressions': 'off',
     '@typescript-eslint/explicit-function-return-type': 'off',

.gitignore

@@ -24,8 +24,11 @@ coverage
 
 # generated docs
 docs
+output*
 
 # -- CLEAN ALL
+.eslintcache
+.wireit
 node_modules
 
 # --

.sfdevrc.json

@@ -2,5 +2,24 @@
   "test": {
     "testsPath": "test/**/*.test.ts"
   },
+  "wireit": {
+    "test:command-reference": {
+      "command": "\"./bin/dev\" commandreference:generate --plugins auth --outputdir test/tmp",
+      "files": ["src/**/*.ts", "messages/**", "package.json"],
+      "output": ["test/tmp"]
+    },
+    "test": {
+      "dependencies": ["test:compile", "test:only", "lint"]
+    },
+    "test:only": {
+      "command": "nyc mocha \"test/**/*.test.ts\"",
+      "env": {
+        "FORCE_COLOR": "2"
+      },
+      "files": ["test/**/*.ts", "src/**/*.ts", "**/tsconfig.json", ".mocha*", "!*.nut.ts", ".nycrc"],
+      "output": [],
+      "dependencies": ["test:command-reference"]
+    }
+  },
   "exclude-scripts": ["pretest"]
 }

CHANGELOG.md

@@ -9,20 +9,21 @@ Generate the [Salesforce CLI command reference guide](https://developer.salesfor
 
 First install the plugin.
 
-```sh-session
-$ sfdx plugins:install @salesforce/plugin-command-reference
+```bash
+$ sf plugins install @salesforce/plugin-command-reference
 ```
 
 Ensure any plugins are installed that you with to generate documentation for.
 
-```sh-session
-$ sfdx plugins:install salesforcedx@latest-rc
+```bash
+$ sf plugins:install salesforce@plugin-auth
 ```
 
 Now we can generate the documentation for the `latest-rc` tag.
 
-```sh-session
-$ sfdx commandreference --plugins salesforcedx
+```bash
+# notice we can use the oclif shorthand for the plugin name.  @salesforce/plugin-foo => foo
+$ sf commandreference --plugins auth
 ```
 
 **Note:** Warnings will occur for missing properties in plugins. Those have to be fixed in the plugin itself.
@@ -50,23 +51,37 @@ Then you can run this in your plugin's CI.
 If you need to make changes to this repository, the easiest thing to do is to link it to your Salesforce CLI. After you cloned this plugin, run the following from this plugin directory:
 
 ```sh-session
-sfdx plugins:link .
+sf plugins link .
 ```
 
-Now, you can install any plugins you want and run the command reference generation on them.
+## Testing
 
-```sh-session
-sfdx plugins:install salesforcedx
-sfdx plugins:install config
-sfdx plugins:install alias
-sfdx plugins:install auth
-sfdx commandreference --plugins salesforcedx,alias,config,auth
+How do you know if the output is correct, given your change?
+
+```bash
+# Install the current version of the plugin (use `@sf` until the plugin is publishing the sf version as main)
+sf plugins install @salesforce/plugin-command-reference@sf
+# installs all JIT plugins (if you intend to produce ditamaps for them)
+sf jit install
+# run using a relatively current version of plugins, saving the output as a "gold file"
+sf commandreference generate --plugins login env deploy-retrieve settings functions info sobject limits schema custom-metadata data community signups user org packaging templates apex auth dev @salesforce/sfdx-plugin-lwc-test -d outputGold
 ```
 
+While working on your branch
+
+```bash
+sf plugins link .
+# run the same command from above, but with your new version of the plugin, writing to a new output file
+sf commandreference generate --plugins login env deploy-retrieve settings functions info sobject limits schema custom-metadata data community signups user org packaging templates apex auth dev @salesforce/sfdx-plugin-lwc-test -d outputNew
+```
+
+Now diff the output. Changes should be intentional!
+
 ## Commands
 
 <!-- commands -->
-* [`sf commandreference generate`](#sf-commandreference-generate)
+
+- [`sf commandreference generate`](#sf-commandreference-generate)
 
 ## `sf commandreference generate`
 
@@ -91,4 +106,5 @@ GLOBAL FLAGS
 DESCRIPTION
   generate the command reference guide located
 ```
+
 <!-- commandsstop -->

README.md

@@ -0,0 +1,53 @@
+# commandSummary
+
+generate the command reference guide located
+
+# commandDescription
+
+generate the command reference guide located
+
+# pluginFlagSummary
+
+comma separated list of plugin names to be part of the generation. Defaults to the oclif plugin in the current working directory
+
+# allFlagSummary
+
+include all relevant plugins in the generation
+
+# hiddenFlagSummary
+
+show hidden commands
+
+# outputdirFlagSummary
+
+output directory to put generated files
+
+# erroronwarningFlagSummary
+
+fail the command if there are any warnings
+
+# ditamapSuffixFlagSummary
+
+unique suffix to append to generated ditamap
+
+# configPathFlagSummary
+
+A path to the directory containing a plugin or cli
+
+# examples
+
+- Generate the command reference guide
+
+  <%= config.bin %> <%= command.id %>
+
+- Generate the command reference for a set of plugins
+
+  <%= config.bin %> <%= command.id %> --plugins pluginA,pluginB
+
+- Generate the command reference for all plugins
+
+  <%= config.bin %> <%= command.id %> --all --output-dir ./docs
+
+- Generate the command reference for all plugins in a directory
+
+  <%= config.bin %> <%= command.id %> --all --config-path /path/to/plugin --output-dir ./docs