From 018094dbd6e5af8de75bf5566f6a134aaa7b52ec Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Sun, 2 Mar 2025 08:54:07 -0600 Subject: [PATCH] feat: allow multiple CLI reports for easier diff Signed-off-by: aramissennyeydd --- .../cli/cli-report.backstage-cli-alpha.md | 181 ++++++++++++++++++ ...-report.md => cli-report.backstage-cli.md} | 121 +++++++----- packages/cli/package.json | 3 +- packages/cli/src/alpha.ts | 3 +- packages/cli/src/modules/config/alpha.ts | 36 ++++ .../cli-reports/generateCliReport.ts | 35 ++-- .../cli-reports/runCliExtraction.ts | 69 ++++--- yarn.lock | 1 + 8 files changed, 356 insertions(+), 93 deletions(-) create mode 100644 packages/cli/cli-report.backstage-cli-alpha.md rename packages/cli/{cli-report.md => cli-report.backstage-cli.md} (86%) diff --git a/packages/cli/cli-report.backstage-cli-alpha.md b/packages/cli/cli-report.backstage-cli-alpha.md new file mode 100644 index 0000000000..a5f857c893 --- /dev/null +++ b/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] [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: + +Options: + --help + --package + --version +``` + +### `backstage-cli-alpha config schema` + +``` +Usage: + +Options: + --format + --help + --merge + --no-merge + --package + --version +``` + +### `backstage-cli-alpha config:check` + +``` +Usage: + +Options: + --config + --deprecated + --frontend + --help + --lax + --package + --strict + --version +``` + +### `backstage-cli-alpha config:docs` + +``` +Usage: program [options] + +Options: + --package + -h, --help +``` + +### `backstage-cli-alpha config:print` + +``` +Usage: + +Options: + --config + --format + --frontend + --help + --lax + --package + --version + --with-secrets +``` + +### `backstage-cli-alpha config:schema` + +``` +Usage: + +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 + --minify + --role + --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 + -h, --help +``` diff --git a/packages/cli/cli-report.md b/packages/cli/cli-report.backstage-cli.md similarity index 86% rename from packages/cli/cli-report.md rename to packages/cli/cli-report.backstage-cli.md index 699161966c..51f7b8c998 100644 --- a/packages/cli/cli-report.md +++ b/packages/cli/cli-report.backstage-cli.md @@ -12,10 +12,10 @@ Options: -h, --help Commands: - new [options] + build-workspace [options] [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 help [command] + create-github-app + 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 - --lax - --frontend - --deprecated - --strict --config + --deprecated + --frontend + --lax + --package + --strict -h, --help ``` @@ -69,12 +78,12 @@ Options: Usage: backstage-cli config:print [options] Options: - --package - --lax - --frontend - --with-secrets - --format --config + --format + --frontend + --lax + --package + --with-secrets -h, --help ``` @@ -84,10 +93,10 @@ Options: Usage: backstage-cli config:schema [options] Options: - --package --format --merge --no-merge + --package -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 - --option = - --skip-install - --scope - --npm-registry --baseVersion --license --no-private + --npm-registry + --option = + --scope + --select + --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 + --config --minify + --role --skip-build-dependencies --stats - --config -h, --help ``` @@ -236,10 +253,10 @@ Options: Usage: backstage-cli package lint [options] [directories...] Options: - --format - --output-file --fix + --format --max-warnings + --output-file -h, --help ``` @@ -267,13 +284,17 @@ Options: Usage: backstage-cli package start [options] Options: - --config - --role --check + --config --inspect [host] --inspect-brk [host] +<<<<<<< HEAD:packages/cli/cli-report.md --require +======= +>>>>>>> e27a77cb9a9d1 (feat: allow multiple CLI reports for easier diff):packages/cli/cli-report.backstage-cli.md --link + --require + --role -h, --help ``` @@ -283,11 +304,8 @@ Options: Usage: backstage-cli [--config=] [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 --minify + --since -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 --output-file --since --successCache --successCacheDir +<<<<<<< HEAD:packages/cli/cli-report.md --max-warnings --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 --successCache --successCacheDir - --jest-help -h, --help ``` diff --git a/packages/cli/package.json b/packages/cli/package.json index 8f3f1764c6..52566341ce 100644 --- a/packages/cli/package.json +++ b/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", diff --git a/packages/cli/src/alpha.ts b/packages/cli/src/alpha.ts index 49e739bbdc..f1ccb65a53 100644 --- a/packages/cli/src/alpha.ts +++ b/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', ), diff --git a/packages/cli/src/modules/config/alpha.ts b/packages/cli/src/modules/config/alpha.ts index 8e5ff8b783..a0f2624922 100644 --- a/packages/cli/src/modules/config/alpha.ts +++ b/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); + }, + }); }, }); diff --git a/packages/repo-tools/src/commands/api-reports/cli-reports/generateCliReport.ts b/packages/repo-tools/src/commands/api-reports/cli-reports/generateCliReport.ts index 7df5058723..9876be997b 100644 --- a/packages/repo-tools/src/commands/api-reports/cli-reports/generateCliReport.ts +++ b/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 ?? ''}`, - ); + for (const helpPage of model.helpPages) { + content.push( + `### \`${[model.name, ...helpPage.path].join(' ')}\``, + '', + '```', + `Usage: ${helpPage.usage ?? ''}`, + ); - 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'); diff --git a/packages/repo-tools/src/commands/api-reports/cli-reports/runCliExtraction.ts b/packages/repo-tools/src/commands/api-reports/cli-reports/runCliExtraction.ts index cb4256f2fc..6ab72024c8 100644 --- a/packages/repo-tools/src/commands/api-reports/cli-reports/runCliExtraction.ts +++ b/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}, `); } } } diff --git a/yarn.lock b/yarn.lock index 9b199ff03b..215e6ce4bf 100644 --- a/yarn.lock +++ b/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