diff --git a/.changeset/fluffy-pears-cry.md b/.changeset/fluffy-pears-cry.md new file mode 100644 index 0000000000..ad7eed680c --- /dev/null +++ b/.changeset/fluffy-pears-cry.md @@ -0,0 +1,5 @@ +--- +'@backstage/repo-tools': patch +--- + +Update @microsoft/api-extractor and use their api report resolution diff --git a/.prettierignore b/.prettierignore index 3a16bd1388..2212e834c0 100644 --- a/.prettierignore +++ b/.prettierignore @@ -4,8 +4,13 @@ microsite coverage *.hbs templates +# old reports api-report.md api-report-*.md +# new reports +api-report.api.md +api-report-*.api.md + knip-report.md cli-report.md plugins/scaffolder-backend/sample-templates diff --git a/REVIEWING.md b/REVIEWING.md index c443c15d77..880577da40 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -68,7 +68,7 @@ In general our changeset feedback bot will take care of informing whether a chan Changes that do NOT need a new changeset: -- Changes to any test, storybook, or other local development files, for example, `MyComponent.test.tsx`, `MyComponent.stories.tsx`, `**mocks**/MyMock.ts`, `.eslintrc.js`, `setupTests.ts`, or `api-report.md`. Explained differently, it is only files that affect the published package that need changesets, such as source files and additional resources like `package.json`, `README.md`, `config.d.ts`, etc. +- Changes to any test, storybook, or other local development files, for example, `MyComponent.test.tsx`, `MyComponent.stories.tsx`, `**mocks**/MyMock.ts`, `.eslintrc.js`, `setupTests.ts`, or `api-report.api.md`. Explained differently, it is only files that affect the published package that need changesets, such as source files and additional resources like `package.json`, `README.md`, `config.d.ts`, etc. - When tweaking a change that has not yet been released, you can rely on and potentially modify the existing changeset instead. - Changes that do not belong to a published packages, either because it's not a package at all, such as `docs/`, or because the package is private, such as `packages/app`. - Changes that do not end up having an effect on the published package, such as whitespace fixes or code formatting changes. Although it's also fine to have a short changeset for these kind of changes too. @@ -168,7 +168,7 @@ In this section we will be talking about changed "types", but by that we mean an #### API Reports -We generate API Reports using the [API Extractor](https://api-extractor.com/) tool. These reports are generated for most packages in the Backstage repository, and are stored in the `api-report.md` file of each package. For CLI package we use custom tooling, and instead store the result in `cli-report.md`. Whenever the public API of a package changes, the API Report needs to be updated to reflect the new state of the API. Our CI checks will fail if the API reports are not up to date in a pull request. +We generate API Reports using the [API Extractor](https://api-extractor.com/) tool. These reports are generated for most packages in the Backstage repository, and are stored in the `api-report.api.md` file of each package. For CLI package we use custom tooling, and instead store the result in `cli-report.md`. Whenever the public API of a package changes, the API Report needs to be updated to reflect the new state of the API. Our CI checks will fail if the API reports are not up to date in a pull request. Each API report contains a list of all the exported types of each package. As long as the API report does not have any warnings it will contain the full publicly facing API of the package, meaning you do not need to consider any other changes to the package from the point of view of TypeScript API stability. diff --git a/packages/repo-tools/package.json b/packages/repo-tools/package.json index 8fcd5079a3..76fb74cc42 100644 --- a/packages/repo-tools/package.json +++ b/packages/repo-tools/package.json @@ -50,8 +50,8 @@ "@backstage/config-loader": "workspace:^", "@backstage/errors": "workspace:^", "@manypkg/get-packages": "^1.1.3", - "@microsoft/api-documenter": "^7.22.33", - "@microsoft/api-extractor": "^7.36.4", + "@microsoft/api-documenter": "^7.25.7", + "@microsoft/api-extractor": "^7.47.2", "@openapitools/openapi-generator-cli": "^2.7.0", "@stoplight/spectral-core": "^1.18.0", "@stoplight/spectral-formatters": "^1.1.0", diff --git a/packages/repo-tools/src/commands/api-reports/api-extractor.ts b/packages/repo-tools/src/commands/api-reports/api-extractor.ts index 371f122713..fa8dea5f28 100644 --- a/packages/repo-tools/src/commands/api-reports/api-extractor.ts +++ b/packages/repo-tools/src/commands/api-reports/api-extractor.ts @@ -393,19 +393,16 @@ export async function runApiExtraction({ ); const remainingReportFiles = new Set( - fs - .readdirSync(projectFolder) - .filter( - filename => - filename.match(/^(.+)-api-report\.md$/) || - filename.match(/^api-report(-.+)?\.md$/), - ), + fs.readdirSync(projectFolder).filter(filename => + // https://regex101.com/r/QDZIV0/1 + filename.match(/^.*?api-report(-[^.-]+)?(\.md(\.api\.md)?)$/), + ), ); for (const packageEntryPoint of packageEntryPoints) { const suffix = packageEntryPoint.name === 'index' ? '' : `-${packageEntryPoint.name}`; - const reportFileName = `api-report${suffix}.md`; + const reportFileName = `api-report${suffix}`; const reportPath = resolvePath(projectFolder, reportFileName); remainingReportFiles.delete(reportFileName); @@ -522,7 +519,7 @@ export async function runApiExtraction({ ) { shouldLogInstructions = true; const match = message.text.match( - /Please copy the file "(.*)" to "api-report\.md"/, + /Please copy the file "(.*)" to "api-report\.api\.md"/, ); if (match) { conflictingFile = match[1];