[api-extractor] Add a docModel.releaseTagsToTrim property to api-extractor.json to specify which release tags should be trimmed when the doc model is produced. (#5113)

* Add a docModel.releaseTagsToTrim property to api-extractor.json to specify which release tags should be trimmed when the doc model is produced.

* Add a test for doc model trimming.

* fixup! Add a test for doc model trimming.

* fixup! Add a docModel.releaseTagsToTrim property to api-extractor.json to specify which release tags should be trimmed when the doc model is produced.

Author: iclanton

README.md

@@ -152,6 +152,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/build-tests/api-extractor-test-02](./build-tests/api-extractor-test-02/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-test-03](./build-tests/api-extractor-test-03/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-test-04](./build-tests/api-extractor-test-04/) | Building this project is a regression test for api-extractor |
+| [/build-tests/api-extractor-test-05](./build-tests/api-extractor-test-05/) | Building this project is a regression test for api-extractor |
 | [/build-tests/eslint-7-11-test](./build-tests/eslint-7-11-test/) | This project contains a build test to validate ESLint 7.11.0 compatibility with the latest version of @rushstack/eslint-config (and by extension, the ESLint plugin) |
 | [/build-tests/eslint-7-7-test](./build-tests/eslint-7-7-test/) | This project contains a build test to validate ESLint 7.7.0 compatibility with the latest version of @rushstack/eslint-config (and by extension, the ESLint plugin) |
 | [/build-tests/eslint-7-test](./build-tests/eslint-7-test/) | This project contains a build test to validate ESLint 7 compatibility with the latest version of @rushstack/eslint-config (and by extension, the ESLint plugin) |

apps/api-extractor/src/api/Extractor.ts

@@ -254,7 +254,7 @@ export class Extractor {
     const collector: Collector = new Collector({
       program: compilerState.program as ts.Program,
       messageRouter,
-      extractorConfig: extractorConfig,
+      extractorConfig,
       sourceMapper
     });
 
@@ -263,14 +263,14 @@ export class Extractor {
     DocCommentEnhancer.analyze(collector);
     ValidationEnhancer.analyze(collector);
 
-    const modelBuilder: ApiModelGenerator = new ApiModelGenerator(collector);
+    const modelBuilder: ApiModelGenerator = new ApiModelGenerator(collector, extractorConfig);
     const apiPackage: ApiPackage = modelBuilder.buildApiPackage();
 
     if (messageRouter.showDiagnostics) {
       messageRouter.logDiagnostic(''); // skip a line after any diagnostic messages
     }
 
-    if (extractorConfig.docModelEnabled) {
+    if (modelBuilder.docModelEnabled) {
       messageRouter.logVerbose(
         ConsoleMessageId.WritingDocModelFile,
         'Writing: ' + extractorConfig.apiJsonFilePath

apps/api-extractor/src/api/ExtractorConfig.ts

@@ -17,6 +17,9 @@ import {
   NewlineKind
 } from '@rushstack/node-core-library';
 import { type IRigConfig, RigConfig } from '@rushstack/rig-package';
+import { EnumMemberOrder, ReleaseTag } from '@microsoft/api-extractor-model';
+import { TSDocConfiguration } from '@microsoft/tsdoc';
+import { TSDocConfigFile } from '@microsoft/tsdoc-config';
 
 import type {
   ApiReportVariant,
@@ -26,9 +29,7 @@ import type {
 } from './IConfigFile';
 import { PackageMetadataManager } from '../analyzer/PackageMetadataManager';
 import { MessageRouter } from '../collector/MessageRouter';
-import { EnumMemberOrder } from '@microsoft/api-extractor-model';
-import { TSDocConfiguration } from '@microsoft/tsdoc';
-import { TSDocConfigFile } from '@microsoft/tsdoc-config';
+import type { IApiModelGenerationOptions } from '../generators/ApiModelGenerator';
 
 import apiExtractorSchema from '../schemas/api-extractor.schema.json';
 
@@ -186,7 +187,7 @@ interface IExtractorConfigParameters {
   reportFolder: string;
   reportTempFolder: string;
   apiReportIncludeForgottenExports: boolean;
-  docModelEnabled: boolean;
+  docModelGenerationOptions: IApiModelGenerationOptions | undefined;
   apiJsonFilePath: string;
   docModelIncludeForgottenExports: boolean;
   projectFolderUrl: string | undefined;
@@ -305,8 +306,11 @@ export class ExtractorConfig {
   /** {@inheritDoc IConfigApiReport.includeForgottenExports} */
   public readonly apiReportIncludeForgottenExports: boolean;
 
-  /** {@inheritDoc IConfigDocModel.enabled} */
-  public readonly docModelEnabled: boolean;
+  /**
+   * If specified, the doc model is enabled and the specified options will be used.
+   * @beta
+   */
+  public readonly docModelGenerationOptions: IApiModelGenerationOptions | undefined;
   /** {@inheritDoc IConfigDocModel.apiJsonFilePath} */
   public readonly apiJsonFilePath: string;
   /** {@inheritDoc IConfigDocModel.includeForgottenExports} */
@@ -357,38 +361,70 @@ export class ExtractorConfig {
   /** {@inheritDoc IConfigFile.enumMemberOrder} */
   public readonly enumMemberOrder: EnumMemberOrder;
 
-  private constructor(parameters: IExtractorConfigParameters) {
-    this.projectFolder = parameters.projectFolder;
-    this.packageJson = parameters.packageJson;
-    this.packageFolder = parameters.packageFolder;
-    this.mainEntryPointFilePath = parameters.mainEntryPointFilePath;
-    this.bundledPackages = parameters.bundledPackages;
-    this.tsconfigFilePath = parameters.tsconfigFilePath;
-    this.overrideTsconfig = parameters.overrideTsconfig;
-    this.skipLibCheck = parameters.skipLibCheck;
-    this.apiReportEnabled = parameters.apiReportEnabled;
-    this.apiReportIncludeForgottenExports = parameters.apiReportIncludeForgottenExports;
-    this.reportConfigs = parameters.reportConfigs;
-    this.reportFolder = parameters.reportFolder;
-    this.reportTempFolder = parameters.reportTempFolder;
-    this.docModelEnabled = parameters.docModelEnabled;
-    this.apiJsonFilePath = parameters.apiJsonFilePath;
-    this.docModelIncludeForgottenExports = parameters.docModelIncludeForgottenExports;
-    this.projectFolderUrl = parameters.projectFolderUrl;
-    this.rollupEnabled = parameters.rollupEnabled;
-    this.untrimmedFilePath = parameters.untrimmedFilePath;
-    this.alphaTrimmedFilePath = parameters.alphaTrimmedFilePath;
-    this.betaTrimmedFilePath = parameters.betaTrimmedFilePath;
-    this.publicTrimmedFilePath = parameters.publicTrimmedFilePath;
-    this.omitTrimmingComments = parameters.omitTrimmingComments;
-    this.tsdocMetadataEnabled = parameters.tsdocMetadataEnabled;
-    this.tsdocMetadataFilePath = parameters.tsdocMetadataFilePath;
-    this.tsdocConfigFile = parameters.tsdocConfigFile;
-    this.tsdocConfiguration = parameters.tsdocConfiguration;
-    this.newlineKind = parameters.newlineKind;
-    this.messages = parameters.messages;
-    this.testMode = parameters.testMode;
-    this.enumMemberOrder = parameters.enumMemberOrder;
+  private constructor({
+    projectFolder,
+    packageJson,
+    packageFolder,
+    mainEntryPointFilePath,
+    bundledPackages,
+    tsconfigFilePath,
+    overrideTsconfig,
+    skipLibCheck,
+    apiReportEnabled,
+    apiReportIncludeForgottenExports,
+    reportConfigs,
+    reportFolder,
+    reportTempFolder,
+    docModelGenerationOptions,
+    apiJsonFilePath,
+    docModelIncludeForgottenExports,
+    projectFolderUrl,
+    rollupEnabled,
+    untrimmedFilePath,
+    alphaTrimmedFilePath,
+    betaTrimmedFilePath,
+    publicTrimmedFilePath,
+    omitTrimmingComments,
+    tsdocMetadataEnabled,
+    tsdocMetadataFilePath,
+    tsdocConfigFile,
+    tsdocConfiguration,
+    newlineKind,
+    messages,
+    testMode,
+    enumMemberOrder
+  }: IExtractorConfigParameters) {
+    this.projectFolder = projectFolder;
+    this.packageJson = packageJson;
+    this.packageFolder = packageFolder;
+    this.mainEntryPointFilePath = mainEntryPointFilePath;
+    this.bundledPackages = bundledPackages;
+    this.tsconfigFilePath = tsconfigFilePath;
+    this.overrideTsconfig = overrideTsconfig;
+    this.skipLibCheck = skipLibCheck;
+    this.apiReportEnabled = apiReportEnabled;
+    this.apiReportIncludeForgottenExports = apiReportIncludeForgottenExports;
+    this.reportConfigs = reportConfigs;
+    this.reportFolder = reportFolder;
+    this.reportTempFolder = reportTempFolder;
+    this.docModelGenerationOptions = docModelGenerationOptions;
+    this.apiJsonFilePath = apiJsonFilePath;
+    this.docModelIncludeForgottenExports = docModelIncludeForgottenExports;
+    this.projectFolderUrl = projectFolderUrl;
+    this.rollupEnabled = rollupEnabled;
+    this.untrimmedFilePath = untrimmedFilePath;
+    this.alphaTrimmedFilePath = alphaTrimmedFilePath;
+    this.betaTrimmedFilePath = betaTrimmedFilePath;
+    this.publicTrimmedFilePath = publicTrimmedFilePath;
+    this.omitTrimmingComments = omitTrimmingComments;
+    this.tsdocMetadataEnabled = tsdocMetadataEnabled;
+    this.tsdocMetadataFilePath = tsdocMetadataFilePath;
+    this.tsdocConfigFile = tsdocConfigFile;
+    this.tsdocConfiguration = tsdocConfiguration;
+    this.newlineKind = newlineKind;
+    this.messages = messages;
+    this.testMode = testMode;
+    this.enumMemberOrder = enumMemberOrder;
   }
 
   /**
@@ -998,19 +1034,55 @@ export class ExtractorConfig {
         }
       }
 
-      let docModelEnabled: boolean = false;
+      let docModelGenerationOptions: IApiModelGenerationOptions | undefined = undefined;
       let apiJsonFilePath: string = '';
       let docModelIncludeForgottenExports: boolean = false;
       let projectFolderUrl: string | undefined;
-      if (configObject.docModel) {
-        docModelEnabled = !!configObject.docModel.enabled;
+      if (configObject.docModel?.enabled) {
         apiJsonFilePath = ExtractorConfig._resolvePathWithTokens(
           'apiJsonFilePath',
           configObject.docModel.apiJsonFilePath,
           tokenContext
         );
         docModelIncludeForgottenExports = !!configObject.docModel.includeForgottenExports;
         projectFolderUrl = configObject.docModel.projectFolderUrl;
+
+        const releaseTagsToTrim: Set<ReleaseTag> = new Set<ReleaseTag>();
+        const releaseTagsToTrimOption: string[] = configObject.docModel.releaseTagsToTrim || ['@internal'];
+        for (const releaseTagToTrim of releaseTagsToTrimOption) {
+          let releaseTag: ReleaseTag;
+          switch (releaseTagToTrim) {
+            case '@internal': {
+              releaseTag = ReleaseTag.Internal;
+              break;
+            }
+
+            case '@alpha': {
+              releaseTag = ReleaseTag.Alpha;
+              break;
+            }
+
+            case '@beta': {
+              releaseTag = ReleaseTag.Beta;
+              break;
+            }
+
+            case '@public': {
+              releaseTag = ReleaseTag.Public;
+              break;
+            }
+
+            default: {
+              throw new Error(`The release tag "${releaseTagToTrim}" is not supported`);
+            }
+          }
+
+          releaseTagsToTrim.add(releaseTag);
+        }
+
+        docModelGenerationOptions = {
+          releaseTagsToTrim
+        };
       }
 
       let tsdocMetadataEnabled: boolean = false;
@@ -1116,7 +1188,7 @@ export class ExtractorConfig {
         reportFolder,
         reportTempFolder,
         apiReportIncludeForgottenExports,
-        docModelEnabled,
+        docModelGenerationOptions,
         apiJsonFilePath,
         docModelIncludeForgottenExports,
         projectFolderUrl,

apps/api-extractor/src/api/IConfigFile.ts

@@ -141,6 +141,12 @@ export interface IConfigApiReport {
   includeForgottenExports?: boolean;
 }
 
+/**
+ * The allowed release tags that can be used to mark API items.
+ * @public
+ */
+export type ReleaseTagForTrim = '@internal' | '@alpha' | '@beta' | '@public';
+
 /**
  * Configures how the doc model file (*.api.json) will be generated.
  *
@@ -188,6 +194,13 @@ export interface IConfigDocModel {
    * Can be omitted if you don't need source code links in your API documentation reference.
    */
   projectFolderUrl?: string;
+
+  /**
+   * Specifies a list of release tags that will be trimmed from the doc model.
+   *
+   * @defaultValue `["@internal"]`
+   */
+  releaseTagsToTrim?: ReleaseTagForTrim[];
 }
 
 /**

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

@@ -48,22 +48,45 @@ import { AstNamespaceImport } from '../analyzer/AstNamespaceImport';
 import type { AstEntity } from '../analyzer/AstEntity';
 import type { AstModule } from '../analyzer/AstModule';
 import { TypeScriptInternals } from '../analyzer/TypeScriptInternals';
+import type { ExtractorConfig } from '../api/ExtractorConfig';
 
 interface IProcessAstEntityContext {
   name: string;
   isExported: boolean;
   parentApiItem: ApiItemContainerMixin;
 }
 
+/**
+ * @beta
+ */
+export interface IApiModelGenerationOptions {
+  /**
+   * The release tags to trim.
+   */
+  releaseTagsToTrim: Set<ReleaseTag>;
+}
+
 export class ApiModelGenerator {
   private readonly _collector: Collector;
   private readonly _apiModel: ApiModel;
   private readonly _referenceGenerator: DeclarationReferenceGenerator;
+  private readonly _releaseTagsToTrim: Set<ReleaseTag> | undefined;
+
+  public readonly docModelEnabled: boolean;
 
-  public constructor(collector: Collector) {
+  public constructor(collector: Collector, extractorConfig: ExtractorConfig) {
     this._collector = collector;
     this._apiModel = new ApiModel();
     this._referenceGenerator = new DeclarationReferenceGenerator(collector);
+
+    const apiModelGenerationOptions: IApiModelGenerationOptions | undefined =
+      extractorConfig.docModelGenerationOptions;
+    if (apiModelGenerationOptions) {
+      this._releaseTagsToTrim = apiModelGenerationOptions.releaseTagsToTrim;
+      this.docModelEnabled = true;
+    } else {
+      this.docModelEnabled = false;
+    }
   }
 
   public get apiModel(): ApiModel {
@@ -176,8 +199,8 @@ export class ApiModelGenerator {
 
     const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
     const releaseTag: ReleaseTag = apiItemMetadata.effectiveReleaseTag;
-    if (releaseTag === ReleaseTag.Internal) {
-      return; // trim out items marked as "@internal"
+    if (this._releaseTagsToTrim?.has(releaseTag)) {
+      return;
     }
 
     switch (astDeclaration.declaration.kind) {

apps/api-extractor/src/index.ts

@@ -22,6 +22,8 @@ export {
   ExtractorConfig
 } from './api/ExtractorConfig';
 
+export type { IApiModelGenerationOptions } from './generators/ApiModelGenerator';
+
 export { ExtractorLogLevel } from './api/ExtractorLogLevel';
 
 export {
@@ -42,5 +44,6 @@ export type {
   IConfigMessageReportingRule,
   IConfigMessageReportingTable,
   IExtractorMessagesConfig,
-  IConfigFile
+  IConfigFile,
+  ReleaseTagForTrim
 } from './api/IConfigFile';

apps/api-extractor/src/schemas/api-extractor.schema.json

@@ -131,6 +131,14 @@
         "projectFolderUrl": {
           "description": "The base URL where the project's source code can be viewed on a website such as GitHub or Azure DevOps. This URL path corresponds to the `<projectFolder>` path on disk. This URL is concatenated with the file paths serialized to the doc model to produce URL file paths to individual API items. For example, if the `projectFolderUrl` is \"https://github.com/microsoft/rushstack/tree/main/apps/api-extractor\" and an API item's file path is \"api/ExtractorConfig.ts\", the full URL file path would be \"https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js\". Can be omitted if you don't need source code links in your API documentation reference.",
           "type": "string"
+        },
+        "releaseTagsToTrim": {
+          "description": "Specifies a list of release tags that will be trimmed from the doc model. The default value is `[\"@internal\"]`.",
+          "type": "array",
+          "items": {
+            "enum": ["@internal", "@alpha", "@beta", "@public"]
+          },
+          "uniqueItems": true
         }
       },
       "required": ["enabled"],

build-tests/api-extractor-test-05/.gitignore

@@ -0,0 +1,5 @@
+# This project's outputs are tracked to surface changes to API Extractor rollups during PRs
+!dist
+dist/*
+!dist/*.d.ts
+!dist/*.json

build-tests/api-extractor-test-05/config/api-extractor.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+
+  "apiReport": {
+    "enabled": true
+  },
+
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/dist/api-extractor-test-05.api.json",
+    "releaseTagsToTrim": ["@internal", "@alpha"]
+  },
+
+  "dtsRollup": {
+    "enabled": true,
+
+    "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
+    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
+    "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
+  },
+
+  "testMode": true
+}