From 547e41da5ac497e5a606c08c8fb57b429687d5f7 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 29 Dec 2024 12:22:27 +0100 Subject: [PATCH] repo-tools: refactor root api report generation Signed-off-by: Patrik Oldsberg --- .../generateTypeDeclarations.ts | 2 +- .../commands/api-reports/api-reports/index.ts | 1 + .../api-reports/patchApiReportGeneration.ts | 14 ++------ .../api-reports/runApiExtraction.ts | 2 +- ...eports.test.ts => buildApiReports.test.ts} | 24 ++++++++----- .../{api-reports.ts => buildApiReports.ts} | 8 ++--- ...-extractor.ts => categorizePackageDirs.ts} | 17 --------- .../cli-reports/runCliExtraction.ts | 2 +- .../src/commands/api-reports/common/index.ts | 18 ++++++++++ .../common/logApiReportInstructions.ts | 32 +++++++++++++++++ .../api-reports/common/tryRunPrettier.ts | 35 +++++++++++++++++++ .../src/commands/api-reports/index.ts | 17 +++++++++ .../sql-reports/runSqlExtraction.ts | 18 ++-------- packages/repo-tools/src/commands/index.ts | 2 +- 14 files changed, 131 insertions(+), 61 deletions(-) rename packages/repo-tools/src/commands/api-reports/{ => api-reports}/generateTypeDeclarations.ts (96%) rename packages/repo-tools/src/commands/api-reports/{api-reports.test.ts => buildApiReports.test.ts} (97%) rename packages/repo-tools/src/commands/api-reports/{api-reports.ts => buildApiReports.ts} (95%) rename packages/repo-tools/src/commands/api-reports/{api-extractor.ts => categorizePackageDirs.ts} (81%) create mode 100644 packages/repo-tools/src/commands/api-reports/common/index.ts create mode 100644 packages/repo-tools/src/commands/api-reports/common/logApiReportInstructions.ts create mode 100644 packages/repo-tools/src/commands/api-reports/common/tryRunPrettier.ts create mode 100644 packages/repo-tools/src/commands/api-reports/index.ts diff --git a/packages/repo-tools/src/commands/api-reports/generateTypeDeclarations.ts b/packages/repo-tools/src/commands/api-reports/api-reports/generateTypeDeclarations.ts similarity index 96% rename from packages/repo-tools/src/commands/api-reports/generateTypeDeclarations.ts rename to packages/repo-tools/src/commands/api-reports/api-reports/generateTypeDeclarations.ts index 43ee2aa85f..d7304553c0 100644 --- a/packages/repo-tools/src/commands/api-reports/generateTypeDeclarations.ts +++ b/packages/repo-tools/src/commands/api-reports/api-reports/generateTypeDeclarations.ts @@ -16,7 +16,7 @@ import fs from 'fs-extra'; import { spawnSync } from 'child_process'; -import { paths as cliPaths } from '../../lib/paths'; +import { paths as cliPaths } from '../../../lib/paths'; /** * Generates the TypeScript declaration files for the specified project, using the provided `tsconfig.json` file. diff --git a/packages/repo-tools/src/commands/api-reports/api-reports/index.ts b/packages/repo-tools/src/commands/api-reports/api-reports/index.ts index 92945dc8f7..f5c8d1fcda 100644 --- a/packages/repo-tools/src/commands/api-reports/api-reports/index.ts +++ b/packages/repo-tools/src/commands/api-reports/api-reports/index.ts @@ -17,3 +17,4 @@ export { runApiExtraction } from './runApiExtraction'; export { buildDocs } from './buildDocs'; export { createTemporaryTsConfig } from './createTemporaryTsConfig'; +export { generateTypeDeclarations } from './generateTypeDeclarations'; diff --git a/packages/repo-tools/src/commands/api-reports/api-reports/patchApiReportGeneration.ts b/packages/repo-tools/src/commands/api-reports/api-reports/patchApiReportGeneration.ts index 4f25b9fd98..982707e815 100644 --- a/packages/repo-tools/src/commands/api-reports/api-reports/patchApiReportGeneration.ts +++ b/packages/repo-tools/src/commands/api-reports/api-reports/patchApiReportGeneration.ts @@ -17,7 +17,7 @@ import { ExtractorMessage } from '@microsoft/api-extractor'; import { AstDeclaration } from '@microsoft/api-extractor/lib/analyzer/AstDeclaration'; import { Program } from 'typescript'; -import { paths as cliPaths } from '../../../lib/paths'; +import { tryRunPrettier } from '../common'; let applied = false; @@ -158,16 +158,6 @@ export function patchApiReportGeneration() { ...moreArgs, ); - try { - const prettier = require('prettier') as typeof import('prettier'); - - const config = prettier.resolveConfig.sync(cliPaths.targetRoot) ?? {}; - return prettier.format(content, { - ...config, - parser: 'markdown', - }); - } catch (e) { - return content; - } + return tryRunPrettier(content); }; } diff --git a/packages/repo-tools/src/commands/api-reports/api-reports/runApiExtraction.ts b/packages/repo-tools/src/commands/api-reports/api-reports/runApiExtraction.ts index 1e4133def2..1ba8852ed4 100644 --- a/packages/repo-tools/src/commands/api-reports/api-reports/runApiExtraction.ts +++ b/packages/repo-tools/src/commands/api-reports/api-reports/runApiExtraction.ts @@ -28,7 +28,7 @@ import { minimatch } from 'minimatch'; import { join, relative as relativePath, resolve as resolvePath } from 'path'; import { getPackageExportDetails } from '../../../lib/getPackageExportDetails'; import { paths as cliPaths } from '../../../lib/paths'; -import { logApiReportInstructions } from '../api-extractor'; +import { logApiReportInstructions } from '../common'; import { patchApiReportGeneration } from './patchApiReportGeneration'; const tmpDir = cliPaths.resolveTargetRoot( diff --git a/packages/repo-tools/src/commands/api-reports/api-reports.test.ts b/packages/repo-tools/src/commands/api-reports/buildApiReports.test.ts similarity index 97% rename from packages/repo-tools/src/commands/api-reports/api-reports.test.ts rename to packages/repo-tools/src/commands/api-reports/buildApiReports.test.ts index 796b733d97..cbe6fedad6 100644 --- a/packages/repo-tools/src/commands/api-reports/api-reports.test.ts +++ b/packages/repo-tools/src/commands/api-reports/buildApiReports.test.ts @@ -18,18 +18,29 @@ import { createMockDirectory } from '@backstage/backend-test-utils'; import { normalize } from 'path'; import * as pathsLib from '../../lib/paths'; -import { categorizePackageDirs } from './api-extractor'; +import { categorizePackageDirs } from './categorizePackageDirs'; -import { buildApiReports } from './api-reports'; -import { generateTypeDeclarations } from './generateTypeDeclarations'; +import { buildApiReports } from './buildApiReports'; +import { generateTypeDeclarations } from './api-reports'; import { PackageGraph } from '@backstage/cli-node'; import { runCliExtraction } from './cli-reports'; import { runApiExtraction, buildDocs } from './api-reports/index'; -jest.mock('./generateTypeDeclarations'); // create mocks for the dependencies of the `buildApiReports` function -jest.mock('./api-extractor', () => ({ +jest.mock('./api-reports', () => ({ + generateTypeDeclarations: jest.fn(), createTemporaryTsConfig: jest.fn(), + runApiExtraction: jest.fn(), + runCliExtraction: jest.fn(), + buildDocs: jest.fn(), +})); +jest.mock('./cli-reports', () => ({ + runCliExtraction: jest.fn(), +})); +jest.mock('./sql-reports', () => ({ + runSqlExtraction: jest.fn(), +})); +jest.mock('./categorizePackageDirs', () => ({ categorizePackageDirs: jest.fn().mockImplementation(async (p: string[]) => { console.log('categorizePackageDirs', p); return { @@ -38,9 +49,6 @@ jest.mock('./api-extractor', () => ({ sqlPackageDirs: [], }; }), - runApiExtraction: jest.fn(), - runCliExtraction: jest.fn(), - buildDocs: jest.fn(), })); const projectPaths = pathsLib.paths; diff --git a/packages/repo-tools/src/commands/api-reports/api-reports.ts b/packages/repo-tools/src/commands/api-reports/buildApiReports.ts similarity index 95% rename from packages/repo-tools/src/commands/api-reports/api-reports.ts rename to packages/repo-tools/src/commands/api-reports/buildApiReports.ts index d02a668af6..74b110236f 100644 --- a/packages/repo-tools/src/commands/api-reports/api-reports.ts +++ b/packages/repo-tools/src/commands/api-reports/buildApiReports.ts @@ -15,15 +15,15 @@ */ import { OptionValues } from 'commander'; -import { categorizePackageDirs } from './api-extractor'; +import { categorizePackageDirs } from './categorizePackageDirs'; import { paths as cliPaths, resolvePackagePaths } from '../../lib/paths'; -import { generateTypeDeclarations } from './generateTypeDeclarations'; import { runSqlExtraction } from './sql-reports'; import { runCliExtraction } from './cli-reports'; import { runApiExtraction, buildDocs, createTemporaryTsConfig, + generateTypeDeclarations, } from './api-reports/index'; type Options = { @@ -36,7 +36,7 @@ type Options = { validateReleaseTags?: boolean; } & OptionValues; -export const buildApiReports = async (paths: string[] = [], opts: Options) => { +export async function buildApiReports(paths: string[] = [], opts: Options) { const tmpDir = cliPaths.resolveTargetRoot( './node_modules/.cache/api-extractor', ); @@ -119,7 +119,7 @@ export const buildApiReports = async (paths: string[] = [], opts: Options) => { outputDir: cliPaths.resolveTargetRoot('docs/reference'), }); } -}; +} /** * Splits the input string on comma, and returns an array of the resulting substrings. diff --git a/packages/repo-tools/src/commands/api-reports/api-extractor.ts b/packages/repo-tools/src/commands/api-reports/categorizePackageDirs.ts similarity index 81% rename from packages/repo-tools/src/commands/api-reports/api-extractor.ts rename to packages/repo-tools/src/commands/api-reports/categorizePackageDirs.ts index c5d812e4a4..86694c3d68 100644 --- a/packages/repo-tools/src/commands/api-reports/api-extractor.ts +++ b/packages/repo-tools/src/commands/api-reports/categorizePackageDirs.ts @@ -17,23 +17,6 @@ import fs from 'fs-extra'; import { paths as cliPaths } from '../../lib/paths'; -export function logApiReportInstructions() { - console.log(''); - console.log( - '*************************************************************************************', - ); - console.log( - '* You have uncommitted changes to the public API or reports of a package. *', - ); - console.log( - '* To solve this, run `yarn build:api-reports` and commit all md file changes. *', - ); - console.log( - '*************************************************************************************', - ); - console.log(''); -} - export async function categorizePackageDirs(packageDirs: string[]) { const dirs = packageDirs.slice(); const tsPackageDirs = new Array(); 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 cd630afec3..cb4256f2fc 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 @@ -24,7 +24,7 @@ import { createBinRunner } from '../../util'; import { CliHelpPage, CliModel } from './types'; import { paths as cliPaths } from '../../../lib/paths'; import { generateCliReport } from './generateCliReport'; -import { logApiReportInstructions } from '../api-extractor'; +import { logApiReportInstructions } from '../common'; function parseHelpPage(helpPageContent: string) { const [, usage] = helpPageContent.match(/^\s*Usage: (.*)$/im) ?? []; diff --git a/packages/repo-tools/src/commands/api-reports/common/index.ts b/packages/repo-tools/src/commands/api-reports/common/index.ts new file mode 100644 index 0000000000..34bd95bfbe --- /dev/null +++ b/packages/repo-tools/src/commands/api-reports/common/index.ts @@ -0,0 +1,18 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +export { tryRunPrettier } from './tryRunPrettier'; +export { logApiReportInstructions } from './logApiReportInstructions'; diff --git a/packages/repo-tools/src/commands/api-reports/common/logApiReportInstructions.ts b/packages/repo-tools/src/commands/api-reports/common/logApiReportInstructions.ts new file mode 100644 index 0000000000..d4ab63f4db --- /dev/null +++ b/packages/repo-tools/src/commands/api-reports/common/logApiReportInstructions.ts @@ -0,0 +1,32 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +export function logApiReportInstructions() { + console.log(''); + console.log( + '*************************************************************************************', + ); + console.log( + '* You have uncommitted changes to the public API or reports of a package. *', + ); + console.log( + '* To solve this, run `yarn build:api-reports` and commit all md file changes. *', + ); + console.log( + '*************************************************************************************', + ); + console.log(''); +} diff --git a/packages/repo-tools/src/commands/api-reports/common/tryRunPrettier.ts b/packages/repo-tools/src/commands/api-reports/common/tryRunPrettier.ts new file mode 100644 index 0000000000..020853d726 --- /dev/null +++ b/packages/repo-tools/src/commands/api-reports/common/tryRunPrettier.ts @@ -0,0 +1,35 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { paths as cliPaths } from '../../../lib/paths'; +import type { Config } from 'prettier'; + +export function tryRunPrettier( + content: string, + extraConfig: Config = { parser: 'markdown' }, +): string { + try { + const prettier = require('prettier') as typeof import('prettier'); + + const config = prettier.resolveConfig.sync(cliPaths.targetRoot) ?? {}; + return prettier.format(content, { + ...config, + ...extraConfig, + }); + } catch (e) { + return content; + } +} diff --git a/packages/repo-tools/src/commands/api-reports/index.ts b/packages/repo-tools/src/commands/api-reports/index.ts new file mode 100644 index 0000000000..9c09590d86 --- /dev/null +++ b/packages/repo-tools/src/commands/api-reports/index.ts @@ -0,0 +1,17 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +export { buildApiReports } from './buildApiReports'; diff --git a/packages/repo-tools/src/commands/api-reports/sql-reports/runSqlExtraction.ts b/packages/repo-tools/src/commands/api-reports/sql-reports/runSqlExtraction.ts index 001c4c6c45..9462412436 100644 --- a/packages/repo-tools/src/commands/api-reports/sql-reports/runSqlExtraction.ts +++ b/packages/repo-tools/src/commands/api-reports/sql-reports/runSqlExtraction.ts @@ -22,7 +22,7 @@ import { SchemaInfo } from './types'; import { getPgSchemaInfo } from './getPgSchemaInfo'; import { generateSqlReport } from './generateSqlReport'; import type { Knex } from 'knex'; -import { logApiReportInstructions } from '../api-extractor'; +import { logApiReportInstructions, tryRunPrettier } from '../common'; interface SqlExtractionOptions { packageDirs: string[]; @@ -153,7 +153,7 @@ async function runSingleSqlExtraction( } } - const report = prettyReport( + const report = tryRunPrettier( generateSqlReport({ reportName, failedDownMigration, @@ -196,17 +196,3 @@ async function runSingleSqlExtraction( } } } - -function prettyReport(content: string): string { - try { - const prettier = require('prettier') as typeof import('prettier'); - - const config = prettier.resolveConfig.sync(cliPaths.targetRoot) ?? {}; - return prettier.format(content, { - ...config, - parser: 'markdown', - }); - } catch (e) { - return content; - } -} diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts index 65ab43d376..c298384375 100644 --- a/packages/repo-tools/src/commands/index.ts +++ b/packages/repo-tools/src/commands/index.ts @@ -194,7 +194,7 @@ export function registerCommands(program: Command) { 'Turn on release tag validation for the public, beta, and alpha APIs', ) .description('Generate an API report for selected packages') - .action(lazy(() => import('./api-reports/api-reports'), 'buildApiReports')); + .action(lazy(() => import('./api-reports'), 'buildApiReports')); program .command('type-deps')