repo-tools: add release tag validation option

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

package.json

@@ -11,7 +11,7 @@
     "build:backend": "yarn workspace backend build",
     "build:all": "backstage-cli repo build --all",
     "build:api-reports": "yarn build:api-reports:only --tsc",
-    "build:api-reports:only": "backstage-repo-tools api-reports --allow-warnings 'packages/core-components,plugins/+(catalog|catalog-import|git-release-manager|jenkins|kubernetes)' -o ae-wrong-input-file-type",
+    "build:api-reports:only": "backstage-repo-tools api-reports --allow-warnings 'packages/core-components,plugins/+(catalog|catalog-import|git-release-manager|jenkins|kubernetes)' -o ae-wrong-input-file-type --validate-release-tags",
     "build:api-docs": "LANG=en_EN yarn build:api-reports --docs",
     "tsc": "tsc",
     "tsc:full": "backstage-cli repo clean && tsc --skipLibCheck false --incremental false",

packages/repo-tools/src/commands/api-reports/api-extractor.ts

@@ -334,6 +334,7 @@ interface ApiExtractionOptions {
   tsconfigFilePath: string;
   allowWarnings?: boolean | string[];
   omitMessages?: string[];
+  validateReleaseTags?: boolean;
 }
 
 export async function runApiExtraction({
@@ -343,6 +344,7 @@ export async function runApiExtraction({
   tsconfigFilePath,
   allowWarnings = false,
   omitMessages = [],
+  validateReleaseTags = false,
 }: ApiExtractionOptions) {
   await fs.remove(outputDir);
 
@@ -494,6 +496,30 @@ export async function runApiExtraction({
       compilerState,
     });
 
+    // This release tag validation makes sure that the release tag of known entry points match expectations.
+    // The root index entrypoint is only allowed @public exports, while /alpha and /beta only allow @alpha and @beta.
+    if (validateReleaseTags) {
+      if (['index', 'alpha', 'beta'].includes(name)) {
+        const report = await fs.readFile(
+          extractorConfig.reportFilePath,
+          'utf8',
+        );
+        const lines = report.split(/\r?\n/);
+        const expectedTag = name === 'index' ? 'public' : name;
+        for (let i = 0; i < lines.length; i += 1) {
+          const line = lines[i];
+          const match = line.match(/^\/\/ @(alpha|beta|public)/);
+          if (match && match[1] !== expectedTag) {
+            throw new Error(
+              `Unexpected release tag ${match[1]} in ${
+                extractorConfig.reportFilePath
+              } at line ${i + 1}`,
+            );
+          }
+        }
+      }
+    }
+
     if (!extractorResult.succeeded) {
       if (shouldLogInstructions) {
         logApiReportInstructions();

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

@@ -33,6 +33,7 @@ type Options = {
   allowWarnings?: string;
   allowAllWarnings?: boolean;
   omitMessages?: string;
+  validateReleaseTags?: boolean;
 } & OptionValues;
 
 export const buildApiReports = async (paths: string[] = [], opts: Options) => {
@@ -90,6 +91,7 @@ export const buildApiReports = async (paths: string[] = [], opts: Options) => {
       tsconfigFilePath,
       allowWarnings: allowAllWarnings || allowWarnings,
       omitMessages: Array.isArray(omitMessages) ? omitMessages : [],
+      validateReleaseTags: opts.validateReleaseTags,
     });
   }
   if (cliPackageDirs.length > 0) {

packages/repo-tools/src/commands/index.ts

@@ -37,6 +37,10 @@ export function registerCommands(program: Command) {
       '-o, --omit-messages <messageCodes>',
       'select some message code to be omited on the API Extractor (comma separated values i.e ae-cyclic-inherit-doc,ae-missing-getter )',
     )
+    .option(
+      '--validate-release-tags',
+      'Turn on release tag validation for the public, beta, and alpha APIs',
+    )
     .description('Generate an API report for selected packages')
     .action(
       lazy(() =>