refactor: Update ApiReportGenerator to support a minimum release level

Author: Josmithr

apps/api-extractor/src/generators/ApiReportGenerator.ts

@@ -22,6 +22,19 @@ import type { AstModuleExportInfo } from '../analyzer/AstModule';
 import { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';
 import { ExtractorMessageId } from '../api/ExtractorMessageId';
 
+/**
+ * Options for {@link ApiReportGenerator.generateReviewFileContent}.
+ */
+export interface IApiReportOptions {
+  /**
+   * The release level with which the report is associated.
+   * Can also be viewed as the minimal release level of items that should be included in the report.
+   *
+   * @defaultValue Include everything. I.e. {@link ReleaseTag.Internal}.
+   */
+  readonly releaseLevel?: Omit<ReleaseTag, ReleaseTag.None>;
+}
+
 export class ApiReportGenerator {
   private static _trimSpacesRegExp: RegExp = / +$/gm;
 
@@ -42,10 +55,12 @@ export class ApiReportGenerator {
     return normalizedActual === normalizedExpected;
   }
 
-  public static generateReviewFileContent(collector: Collector): string {
+  public static generateReviewFileContent(collector: Collector, options?: IApiReportOptions): string {
     const writer: IndentedWriter = new IndentedWriter();
     writer.trimLeadingSpaces = true;
 
+    const releaseLevel: ReleaseTag = (options?.releaseLevel as ReleaseTag) ?? ReleaseTag.Internal;
+
     writer.writeLine(
       [
         `## API Report File for "${collector.workingPackage.name}"`,
@@ -128,7 +143,7 @@ export class ApiReportGenerator {
             if (apiItemMetadata.isPreapproved) {
               ApiReportGenerator._modifySpanForPreapproved(span);
             } else {
-              ApiReportGenerator._modifySpan(collector, span, entity, astDeclaration, false);
+              ApiReportGenerator._modifySpan(collector, span, entity, astDeclaration, false, releaseLevel);
             }
 
             span.writeModifiedText(writer);
@@ -255,11 +270,12 @@ export class ApiReportGenerator {
     span: Span,
     entity: CollectorEntity,
     astDeclaration: AstDeclaration,
-    insideTypeLiteral: boolean
+    insideTypeLiteral: boolean,
+    releaseLevel: ReleaseTag
   ): void {
     // Should we process this declaration at all?
     // eslint-disable-next-line no-bitwise
-    if (!ApiReportGenerator._shouldIncludeInReport(astDeclaration)) {
+    if (!ApiReportGenerator._shouldIncludeInReport(collector, astDeclaration, releaseLevel)) {
       span.modification.skipAll();
       return;
     }
@@ -385,7 +401,8 @@ export class ApiReportGenerator {
               childSpan,
               entity,
               childAstDeclaration,
-              insideTypeLiteral
+              insideTypeLiteral,
+              releaseLevel
             );
           }
         );
@@ -402,7 +419,7 @@ export class ApiReportGenerator {
             astDeclaration
           );
 
-          if (ApiReportGenerator._shouldIncludeInReport(childAstDeclaration)) {
+          if (ApiReportGenerator._shouldIncludeInReport(collector, childAstDeclaration, releaseLevel)) {
             if (sortChildren) {
               span.modification.sortChildren = true;
               child.modification.sortKey = Collector.getSortKeyIgnoringUnderscore(
@@ -426,15 +443,35 @@ export class ApiReportGenerator {
           }
         }
 
-        ApiReportGenerator._modifySpan(collector, child, entity, childAstDeclaration, insideTypeLiteral);
+        ApiReportGenerator._modifySpan(
+          collector,
+          child,
+          entity,
+          childAstDeclaration,
+          insideTypeLiteral,
+          releaseLevel
+        );
       }
     }
   }
 
-  private static _shouldIncludeInReport(astDeclaration: AstDeclaration): boolean {
+  private static _shouldIncludeInReport(
+    collector: Collector,
+    astDeclaration: AstDeclaration,
+    releaseLevel: ReleaseTag
+  ): boolean {
     // Private declarations are not included in the API report
     // eslint-disable-next-line no-bitwise
-    return (astDeclaration.modifierFlags & ts.ModifierFlags.Private) === 0;
+    if ((astDeclaration.modifierFlags & ts.ModifierFlags.Private) !== 0) {
+      return false;
+    }
+
+    const apiItemMetadata: ApiItemMetadata = collector.fetchApiItemMetadata(astDeclaration);
+    const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
+
+    // If the declaration has a release tag that is not in scope, omit it from the report.
+    // No release tag is considered the same as `@public`.
+    return releaseTag === ReleaseTag.Public || releaseTag >= releaseLevel;
   }
 
   /**

build-tests/api-extractor-test-02/etc/api-extractor-test-02.api.md

@@ -38,5 +38,4 @@ export class SubclassWithImport extends RenamedReexportedClass3 implements ISimp
     test(): void;
 }
 
-
 ```

build-tests/api-extractor-test-04/etc/api-extractor-test-04.api.md

@@ -61,14 +61,14 @@ export namespace EntangledNamespace {
 export type ExportedAlias = AlphaClass;
 
 // Warning: (ae-internal-missing-underscore) The name "InternalClass" should be prefixed with an underscore because the declaration is marked as @internal
-// 
+//
 // @internal
 export class InternalClass {
     undecoratedMember(): void;
 }
 
 // Warning: (ae-internal-missing-underscore) The name "IPublicClassInternalParameters" should be prefixed with an underscore because the declaration is marked as @internal
-// 
+//
 // @internal
 export interface IPublicClassInternalParameters {
 }
@@ -110,5 +110,4 @@ export enum RegularEnum {
 // @beta
 export const variableDeclaration: string;
 
-
 ```

build-tests/heft-node-everything-test/etc/heft-node-everything-test.api.md

@@ -8,7 +8,6 @@
 export class TestClass {
 }
 
-
 // (No @packageDocumentation comment for this package)
 
 ```