feat: allow multiple CLI reports for easier diff

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

packages/cli/cli-report.backstage-cli-alpha.md

@@ -0,0 +1,181 @@
+## CLI Report file for "@backstage/cli"
+
+> Do not edit this file. It is a report generated by `yarn build:api-reports`
+
+### `backstage-cli-alpha`
+
+```
+Usage: backstage-cli [options] [command]
+
+Options:
+  -V, --version
+  -h, --help
+
+Commands:
+  build-workspace
+  config [command]
+  config:check
+  config:docs
+  config:print
+  config:schema
+  help [command]
+  package [command]
+  repo [command]
+```
+
+### `backstage-cli-alpha build-workspace`
+
+```
+Usage: program [options] <workspace-dir> [packages...]
+
+Options:
+  --alwaysPack
+  -h, --help
+```
+
+### `backstage-cli-alpha config`
+
+```
+Usage: backstage-cli config [options] [command] [command]
+
+Options:
+  -h, --help
+
+Commands:
+  docs
+  help [command]
+  schema
+```
+
+### `backstage-cli-alpha config docs`
+
+```
+Usage: <none>
+
+Options:
+  --help
+  --package
+  --version
+```
+
+### `backstage-cli-alpha config schema`
+
+```
+Usage: <none>
+
+Options:
+  --format
+  --help
+  --merge
+  --no-merge
+  --package
+  --version
+```
+
+### `backstage-cli-alpha config:check`
+
+```
+Usage: <none>
+
+Options:
+  --config
+  --deprecated
+  --frontend
+  --help
+  --lax
+  --package
+  --strict
+  --version
+```
+
+### `backstage-cli-alpha config:docs`
+
+```
+Usage: program [options]
+
+Options:
+  --package <name>
+  -h, --help
+```
+
+### `backstage-cli-alpha config:print`
+
+```
+Usage: <none>
+
+Options:
+  --config
+  --format
+  --frontend
+  --help
+  --lax
+  --package
+  --version
+  --with-secrets
+```
+
+### `backstage-cli-alpha config:schema`
+
+```
+Usage: <none>
+
+Options:
+  --format
+  --help
+  --merge
+  --no-merge
+  --package
+  --version
+```
+
+### `backstage-cli-alpha package`
+
+```
+Usage: backstage-cli package [options] [command] [command]
+
+Options:
+  -h, --help
+
+Commands:
+  build
+  help [command]
+```
+
+### `backstage-cli-alpha package build`
+
+```
+Usage: program [options]
+
+Options:
+  --config <path>
+  --minify
+  --role <name>
+  --skip-build-dependencies
+  --stats
+  -h, --help
+```
+
+### `backstage-cli-alpha repo`
+
+```
+Usage: backstage-cli repo [options] [command] [command]
+
+Options:
+  -h, --help
+
+Commands:
+  build
+  help [command]
+```
+
+### `backstage-cli-alpha repo build`
+
+```
+Usage: program [options] [command]
+
+Options:
+  --all
+  --minify
+  --since <ref>
+  -h, --help
+```

packages/cli/cli-report.backstage-cli.md

@@ -12,10 +12,10 @@ Options:
   -h, --help
 
 Commands:
-  new [options]
+  build-workspace [options] <workspace-dir> [packages...]
+  config:check [options]
   config:docs [options]
   config:print [options]
-  config:check [options]
   config:schema [options]
   repo [command]
   package [command]
@@ -26,6 +26,15 @@ Commands:
   info
   create-github-app <github-org>
   help [command]
+  create-github-app <github-org>
+  help [command]
+  info
+  migrate [command]
+  new [options]
+  package [command]
+  repo [command]
+  versions:bump [options]
+  versions:migrate [options]
 ```
 
 ### `backstage-cli build-workspace`
@@ -44,12 +53,12 @@ Options:
 Usage: backstage-cli config:check [options]
 
 Options:
-  --package <name>
-  --lax
-  --frontend
-  --deprecated
-  --strict
   --config <path>
+  --deprecated
+  --frontend
+  --lax
+  --package <name>
+  --strict
   -h, --help
 ```
 
@@ -69,12 +78,12 @@ Options:
 Usage: backstage-cli config:print [options]
 
 Options:
-  --package <name>
-  --lax
-  --frontend
-  --with-secrets
-  --format <format>
   --config <path>
+  --format <format>
+  --frontend
+  --lax
+  --package <name>
+  --with-secrets
   -h, --help
 ```
 
@@ -84,10 +93,10 @@ Options:
 Usage: backstage-cli config:schema [options]
 
 Options:
-  --package <name>
   --format <format>
   --merge
   --no-merge
+  --package <name>
   -h, --help
 ```
 
@@ -118,12 +127,12 @@ Options:
   -h, --help
 
 Commands:
-  package-roles
-  package-scripts
+  help [command]
   package-exports
   package-lint-configs
+  package-roles
+  package-scripts
   react-router-deps
-  help [command]
 ```
 
 ### `backstage-cli migrate package-exports`
@@ -177,14 +186,14 @@ Options:
 Usage: backstage-cli new [options]
 
 Options:
-  --select <name>
-  --option <name>=<value>
-  --skip-install
-  --scope <scope>
-  --npm-registry <URL>
   --baseVersion <version>
   --license <license>
   --no-private
+  --npm-registry <URL>
+  --option <name>=<value>
+  --scope <scope>
+  --select <name>
+  --skip-install
   -h, --help
 ```
 
@@ -197,14 +206,22 @@ Options:
   -h, --help
 
 Commands:
-  start [options]
   build [options]
+<<<<<<< HEAD:packages/cli/cli-report.md
   test
   clean
   prepack
   postpack
   lint [options] [directories...]
+=======
+  clean
+>>>>>>> e27a77cb9a9d1 (feat: allow multiple CLI reports for easier diff):packages/cli/cli-report.backstage-cli.md
   help [command]
+  lint [options] [directories...]
+  postpack
+  prepack
+  start [options]
+  test
 ```
 
 ### `backstage-cli package build`
@@ -213,11 +230,11 @@ Commands:
 Usage: backstage-cli package build [options]
 
 Options:
-  --role <name>
+  --config <path>
   --minify
+  --role <name>
   --skip-build-dependencies
   --stats
-  --config <path>
   -h, --help
 ```
 
@@ -236,10 +253,10 @@ Options:
 Usage: backstage-cli package lint [options] [directories...]
 
 Options:
-  --format <format>
-  --output-file <path>
   --fix
+  --format <format>
   --max-warnings <number>
+  --output-file <path>
   -h, --help
 ```
 
@@ -267,13 +284,17 @@ Options:
 Usage: backstage-cli package start [options]
 
 Options:
-  --config <path>
-  --role <name>
   --check
+  --config <path>
   --inspect [host]
   --inspect-brk [host]
+<<<<<<< HEAD:packages/cli/cli-report.md
   --require <path...>
+=======
+>>>>>>> e27a77cb9a9d1 (feat: allow multiple CLI reports for easier diff):packages/cli/cli-report.backstage-cli.md
   --link <path>
+  --require <path>
+  --role <name>
   -h, --help
 ```
 
@@ -283,11 +304,8 @@ Options:
 Usage: backstage-cli [--config=<pathToConfigFile>] [TestPathPattern]
 
 Options:
-  -h, --help
-  --version
   --all
   --automock
-  -b, --bail
   --cache
   --cacheDirectory
   --changedFilesWithAncestor
@@ -299,7 +317,6 @@ Options:
   --collectCoverageFrom
   --color
   --colors
-  -c, --config
   --coverage
   --coverageDirectory
   --coveragePathIgnorePatterns
@@ -311,7 +328,6 @@ Options:
   --detectOpenHandles
   --env
   --errorOnDeprecated
-  -e, --expand
   --filter
   --findRelatedTests
   --forceExit
@@ -327,7 +343,6 @@ Options:
   --listTests
   --logHeapUsage
   --maxConcurrency
-  -w, --maxWorkers
   --moduleDirectories
   --moduleFileExtensions
   --moduleNameMapper
@@ -336,8 +351,6 @@ Options:
   --noStackTrace
   --notify
   --notifyMode
-  -o, --onlyChanged
-  -f, --onlyFailures
   --openHandlesTimeout
   --outputFile
   --passWithNoTests
@@ -352,7 +365,6 @@ Options:
   --restoreMocks
   --rootDir
   --roots
-  -i, --runInBand
   --runTestsByPath
   --runner
   --seed
@@ -370,7 +382,6 @@ Options:
   --testFailureExitCode
   --testLocationInResults
   --testMatch
-  -t, --testNamePattern
   --testPathIgnorePatterns
   --testPathPattern
   --testRegex
@@ -381,14 +392,24 @@ Options:
   --transform
   --transformIgnorePatterns
   --unmockedModulePathPatterns
-  -u, --updateSnapshot
   --useStderr
   --verbose
+  --version
   --watch
   --watchAll
   --watchPathIgnorePatterns
   --watchman
   --workerThreads
+  -b, --bail
+  -c, --config
+  -e, --expand
+  -f, --onlyFailures
+  -h, --help
+  -i, --runInBand
+  -o, --onlyChanged
+  -t, --testNamePattern
+  -u, --updateSnapshot
+  -w, --maxWorkers
 ```
 
 ### `backstage-cli repo`
@@ -401,12 +422,22 @@ Options:
 
 Commands:
   build [options]
+<<<<<<< HEAD:packages/cli/cli-report.md
   test [options]
   lint [options]
   fix [options]
+=======
+>>>>>>> e27a77cb9a9d1 (feat: allow multiple CLI reports for easier diff):packages/cli/cli-report.backstage-cli.md
   clean
-  list-deprecations [options]
+  fix [options]
   help [command]
+  lint [options]
+  list-deprecations [options]
+<<<<<<< HEAD:packages/cli/cli-report.md
+  help [command]
+=======
+  test [options]
+>>>>>>> e27a77cb9a9d1 (feat: allow multiple CLI reports for easier diff):packages/cli/cli-report.backstage-cli.md
 ```
 
 ### `backstage-cli repo build`
@@ -416,8 +447,8 @@ Usage: backstage-cli repo build [options]
 
 Options:
   --all
-  --since <ref>
   --minify
+  --since <ref>
   -h, --help
 ```
 
@@ -436,8 +467,8 @@ Options:
 Usage: backstage-cli repo fix [options]
 
 Options:
-  --publish
   --check
+  --publish
   -h, --help
 ```
 
@@ -447,13 +478,17 @@ Options:
 Usage: backstage-cli repo lint [options]
 
 Options:
+  --fix
   --format <format>
   --output-file <path>
   --since <ref>
   --successCache
   --successCacheDir <path>
+<<<<<<< HEAD:packages/cli/cli-report.md
   --max-warnings <number>
   --fix
+=======
+>>>>>>> e27a77cb9a9d1 (feat: allow multiple CLI reports for easier diff):packages/cli/cli-report.backstage-cli.md
   -h, --help
 ```
 
@@ -473,10 +508,10 @@ Options:
 Usage: backstage-cli repo test [options]
 
 Options:
+  --jest-help
   --since <ref>
   --successCache
   --successCacheDir <path>
-  --jest-help
   -h, --help
 ```
 

packages/cli/package.json

@@ -20,7 +20,8 @@
   "license": "Apache-2.0",
   "main": "dist/index.cjs.js",
   "bin": {
-    "backstage-cli": "bin/backstage-cli"
+    "backstage-cli": "bin/backstage-cli",
+    "backstage-cli-alpha": "bin/backstage-cli-alpha"
   },
   "files": [
     "asset-types",

packages/cli/src/alpha.ts

@@ -18,7 +18,8 @@ import { CliInitializer } from './wiring/CliInitializer';
 import chalk from 'chalk';
 
 (async () => {
-  console.warn(
+  // Logging as stdout to prevent failures from stderr during api-report generation.
+  console.log(
     chalk.yellow(
       'THIS ENTRYPOINT IS IN ALPHA AND MAY CHANGE IN THE FUTURE - DO NOT USE THIS FOR NORMAL DEVELOPMENT',
     ),

packages/cli/src/modules/config/alpha.ts

@@ -97,5 +97,41 @@ export default createCliPlugin({
         await m.default(argv);
       },
     });
+
+    reg.addCommand({
+      path: ['config:schema'],
+      description: 'Print the JSON schema for the given configuration',
+      execute: async ({ args }) => {
+        const argv = await yargs
+          .options({
+            package: { type: 'string' },
+            format: { type: 'string' },
+            merge: { type: 'boolean' },
+            'no-merge': { type: 'boolean' },
+          })
+          .help()
+          .parse(args);
+        const m = await import('./commands/schema');
+        await m.default(argv);
+      },
+    });
+
+    reg.addCommand({
+      path: ['config', 'schema'],
+      description: 'Print the JSON schema for the given configuration',
+      execute: async ({ args }) => {
+        const argv = await yargs
+          .options({
+            package: { type: 'string' },
+            format: { type: 'string' },
+            merge: { type: 'boolean' },
+            'no-merge': { type: 'boolean' },
+          })
+          .help()
+          .parse(args);
+        const m = await import('./commands/schema');
+        await m.default(argv);
+      },
+    });
   },
 });

packages/repo-tools/src/commands/api-reports/cli-reports/generateCliReport.ts

@@ -18,33 +18,32 @@ import { CliModel } from './types';
 
 export function generateCliReport(options: {
   packageName: string;
-  models: CliModel[];
+  model: CliModel;
 }): string {
+  const { model, packageName } = options;
   const content = [
-    `## CLI Report file for "${options.packageName}"`,
+    `## CLI Report file for "${packageName}"`,
     '',
     '> Do not edit this file. It is a report generated by `yarn build:api-reports`',
     '',
   ];
 
-  for (const model of options.models) {
-    for (const helpPage of model.helpPages) {
-      content.push(
-        `### \`${[model.name, ...helpPage.path].join(' ')}\``,
-        '',
-        '```',
-        `Usage: ${helpPage.usage ?? '<none>'}`,
-      );
+  for (const helpPage of model.helpPages) {
+    content.push(
+      `### \`${[model.name, ...helpPage.path].join(' ')}\``,
+      '',
+      '```',
+      `Usage: ${helpPage.usage ?? '<none>'}`,
+    );
 
-      if (helpPage.options.length > 0) {
-        content.push('', 'Options:', ...helpPage.options.map(l => `  ${l}`));
-      }
-
-      if (helpPage.commands.length > 0) {
-        content.push('', 'Commands:', ...helpPage.commands.map(l => `  ${l}`));
-      }
-      content.push('```', '');
+    if (helpPage.options.length > 0) {
+      content.push('', 'Options:', ...helpPage.options.map(l => `  ${l}`));
     }
+
+    if (helpPage.commands.length > 0) {
+      content.push('', 'Commands:', ...helpPage.commands.map(l => `  ${l}`));
+    }
+    content.push('```', '');
   }
 
   return content.join('\n');

packages/repo-tools/src/commands/api-reports/cli-reports/runCliExtraction.ts

@@ -65,6 +65,10 @@ function parseHelpPage(helpPageContent: string) {
     }
   }
 
+  options.sort();
+  commands.sort();
+  commandArguments.sort();
+
   return {
     usage,
     options,
@@ -131,40 +135,45 @@ export async function runCliExtraction({
       }
     }
 
-    const report = generateCliReport({ packageName: pkgJson.name, models });
+    for (const model of models) {
+      const report = generateCliReport({ packageName: pkgJson.name, model });
 
-    const reportPath = resolvePath(fullDir, 'cli-report.md');
-    const existingReport = await fs
-      .readFile(reportPath, 'utf8')
-      .catch(error => {
-        if (error.code === 'ENOENT') {
-          return undefined;
-        }
-        throw error;
-      });
-
-    if (existingReport !== report) {
-      if (isLocalBuild) {
-        console.warn(`CLI report changed for ${packageDir}`);
-        await fs.writeFile(reportPath, report);
-      } else {
-        logApiReportInstructions();
-
-        if (existingReport) {
-          console.log('');
-          console.log(
-            `The conflicting file is ${relativePath(
-              cliPaths.targetRoot,
-              reportPath,
-            )}, expecting the following content:`,
-          );
-          console.log('');
-
-          console.log(report);
+      const reportPath = resolvePath(
+        fullDir,
+        `cli-report.${models.length === 1 ? '' : `${model.name}.`}md`,
+      );
+      const existingReport = await fs
+        .readFile(reportPath, 'utf8')
+        .catch(error => {
+          if (error.code === 'ENOENT') {
+            return undefined;
+          }
+          throw error;
+        });
 
+      if (existingReport !== report) {
+        if (isLocalBuild) {
+          console.warn(`CLI report changed for ${packageDir}`);
+          await fs.writeFile(reportPath, report);
+        } else {
           logApiReportInstructions();
+
+          if (existingReport) {
+            console.log('');
+            console.log(
+              `The conflicting file is ${relativePath(
+                cliPaths.targetRoot,
+                reportPath,
+              )}, expecting the following content:`,
+            );
+            console.log('');
+
+            console.log(report);
+
+            logApiReportInstructions();
+          }
+          throw new Error(`CLI report changed for ${packageDir}, `);
         }
-        throw new Error(`CLI report changed for ${packageDir}, `);
       }
     }
   }

yarn.lock

@@ -4035,6 +4035,7 @@ __metadata:
       optional: true
   bin:
     backstage-cli: bin/backstage-cli
+    backstage-cli-alpha: bin/backstage-cli-alpha
   languageName: unknown
   linkType: soft