Add support for an alphaTrimmedFilePath.

Author: iclanton

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

@@ -384,6 +384,12 @@ export class Extractor {
         DtsRollupKind.PublicRelease,
         extractorConfig.newlineKind
       );
+      Extractor._generateRollupDtsFile(
+        collector,
+        extractorConfig.alphaTrimmedFilePath,
+        DtsRollupKind.AlphaRelease,
+        extractorConfig.newlineKind
+      );
       Extractor._generateRollupDtsFile(
         collector,
         extractorConfig.betaTrimmedFilePath,

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

@@ -153,6 +153,7 @@ interface IExtractorConfigParameters {
   apiJsonFilePath: string;
   rollupEnabled: boolean;
   untrimmedFilePath: string;
+  alphaTrimmedFilePath: string;
   betaTrimmedFilePath: string;
   publicTrimmedFilePath: string;
   omitTrimmingComments: boolean;
@@ -245,6 +246,8 @@ export class ExtractorConfig {
   public readonly rollupEnabled: boolean;
   /** {@inheritDoc IConfigDtsRollup.untrimmedFilePath} */
   public readonly untrimmedFilePath: string;
+  /** {@inheritDoc IConfigDtsRollup.alphaTrimmedFilePath} */
+  public readonly alphaTrimmedFilePath: string;
   /** {@inheritDoc IConfigDtsRollup.betaTrimmedFilePath} */
   public readonly betaTrimmedFilePath: string;
   /** {@inheritDoc IConfigDtsRollup.publicTrimmedFilePath} */
@@ -295,6 +298,7 @@ export class ExtractorConfig {
     this.apiJsonFilePath = parameters.apiJsonFilePath;
     this.rollupEnabled = parameters.rollupEnabled;
     this.untrimmedFilePath = parameters.untrimmedFilePath;
+    this.alphaTrimmedFilePath = parameters.alphaTrimmedFilePath;
     this.betaTrimmedFilePath = parameters.betaTrimmedFilePath;
     this.publicTrimmedFilePath = parameters.publicTrimmedFilePath;
     this.omitTrimmingComments = parameters.omitTrimmingComments;
@@ -611,6 +615,13 @@ export class ExtractorConfig {
           currentConfigFolderPath
         );
       }
+      if (configFile.dtsRollup.alphaTrimmedFilePath) {
+        configFile.dtsRollup.alphaTrimmedFilePath = ExtractorConfig._resolveConfigFileRelativePath(
+          'alphaTrimmedFilePath',
+          configFile.dtsRollup.alphaTrimmedFilePath,
+          currentConfigFolderPath
+        );
+      }
       if (configFile.dtsRollup.betaTrimmedFilePath) {
         configFile.dtsRollup.betaTrimmedFilePath = ExtractorConfig._resolveConfigFileRelativePath(
           'betaTrimmedFilePath',
@@ -912,6 +923,7 @@ export class ExtractorConfig {
       let rollupEnabled: boolean = false;
       let untrimmedFilePath: string = '';
       let betaTrimmedFilePath: string = '';
+      let alphaTrimmedFilePath: string = '';
       let publicTrimmedFilePath: string = '';
       let omitTrimmingComments: boolean = false;
 
@@ -922,6 +934,11 @@ export class ExtractorConfig {
           configObject.dtsRollup.untrimmedFilePath,
           tokenContext
         );
+        alphaTrimmedFilePath = ExtractorConfig._resolvePathWithTokens(
+          'alphaTrimmedFilePath',
+          configObject.dtsRollup.alphaTrimmedFilePath,
+          tokenContext
+        );
         betaTrimmedFilePath = ExtractorConfig._resolvePathWithTokens(
           'betaTrimmedFilePath',
           configObject.dtsRollup.betaTrimmedFilePath,
@@ -963,6 +980,7 @@ export class ExtractorConfig {
         apiJsonFilePath,
         rollupEnabled,
         untrimmedFilePath,
+        alphaTrimmedFilePath,
         betaTrimmedFilePath,
         publicTrimmedFilePath,
         omitTrimmingComments,

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

@@ -148,6 +148,17 @@ export interface IConfigDtsRollup {
    */
   untrimmedFilePath?: string;
 
+  /**
+   * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
+   *
+   * @remarks
+   * This file will include only declarations that are marked as `@public`, `@beta`, or `@alpha`.
+   *
+   * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+   * prepend a folder token such as `<projectFolder>`.
+   */
+  alphaTrimmedFilePath?: string;
+
   /**
    * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
    *

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

@@ -34,6 +34,13 @@ export enum DtsRollupKind {
    */
   InternalRelease,
 
+  /**
+   * Generate a *.d.ts file for a preview release.
+   * This output file will contain all definitions that are reachable from the entry point,
+   * except definitions marked as \@internal.
+   */
+  AlphaRelease,
+
   /**
    * Generate a *.d.ts file for a preview release.
    * This output file will contain all definitions that are reachable from the entry point,
@@ -445,10 +452,20 @@ export class DtsRollupGenerator {
     switch (dtsKind) {
       case DtsRollupKind.InternalRelease:
         return true;
+      case DtsRollupKind.AlphaRelease:
+        return (
+          releaseTag === ReleaseTag.Alpha ||
+          releaseTag === ReleaseTag.Beta ||
+          releaseTag === ReleaseTag.Public ||
+          // NOTE: If the release tag is "None", then we don't have enough information to trim it
+          releaseTag === ReleaseTag.None
+        );
       case DtsRollupKind.BetaRelease:
-        // NOTE: If the release tag is "None", then we don't have enough information to trim it
         return (
-          releaseTag === ReleaseTag.Beta || releaseTag === ReleaseTag.Public || releaseTag === ReleaseTag.None
+          releaseTag === ReleaseTag.Beta ||
+          releaseTag === ReleaseTag.Public ||
+          // NOTE: If the release tag is "None", then we don't have enough information to trim it
+          releaseTag === ReleaseTag.None
         );
       case DtsRollupKind.PublicRelease:
         return releaseTag === ReleaseTag.Public || releaseTag === ReleaseTag.None;

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

@@ -28,6 +28,7 @@
     // ("enabled" is required)
 
     "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
+    "alphaTrimmedFilePath": "",
     "betaTrimmedFilePath": "",
     "publicTrimmedFilePath": "",
     "omitTrimmingComments": false

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

@@ -197,6 +197,18 @@
      */
     // "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
 
+    /**
+     * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
+     * This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
+     *
+     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+     * prepend a folder token such as "<projectFolder>".
+     *
+     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+     * DEFAULT VALUE: ""
+     */
+    // "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
+
     /**
      * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
      * This file will include only declarations that are marked as "@public" or "@beta".

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

@@ -108,6 +108,10 @@
           "description": "Specifies the output path for a .d.ts rollup file to be generated without any trimming. This file will include all declarations that are exported by the main entry point. If the path is an empty string, then this file will not be written. The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as \"<projectFolder>\".",
           "type": "string"
         },
+        "alphaTrimmedFilePath": {
+          "description": "Specifies the output path for a .d.ts rollup file to be generated with trimming for an \"alpha\" release. This file will include only declarations that are marked as \"@public\", \"@beta\", or \"@alpha\". The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as \"<projectFolder>\".",
+          "type": "string"
+        },
         "betaTrimmedFilePath": {
           "description": "Specifies the output path for a .d.ts rollup file to be generated with trimming for a \"beta\" release. This file will include only declarations that are marked as \"@public\" or \"@beta\". The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as \"<projectFolder>\".",
           "type": "string"

build-tests/api-extractor-scenarios/src/functionOverload/config/api-extractor-overrides.json

@@ -2,6 +2,7 @@
   "dtsRollup": {
     "enabled": true,
     "untrimmedFilePath": "<projectFolder>/etc/test-outputs/functionOverload/rollup.d.ts",
+    "alphaTrimmedFilePath": "<projectFolder>/etc/test-outputs/functionOverload/alpha-rollup.d.ts",
     "betaTrimmedFilePath": "<projectFolder>/etc/test-outputs/functionOverload/beta-rollup.d.ts",
     "publicTrimmedFilePath": "<projectFolder>/etc/test-outputs/functionOverload/public-rollup.d.ts"
   }

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

@@ -14,6 +14,7 @@
   "dtsRollup": {
     "enabled": true,
 
+    "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
     "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
     "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
   },

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

@@ -14,6 +14,7 @@
   "dtsRollup": {
     "enabled": true,
 
+    "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
     "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
     "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
   },

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

@@ -14,6 +14,7 @@
   "dtsRollup": {
     "enabled": true,
 
+    "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
     "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
     "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts"
   },

build-tests/heft-node-everything-test/config/api-extractor.json

@@ -11,6 +11,7 @@
   },
   "dtsRollup": {
     "enabled": true,
+    "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
     "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts"
   }
 }

common/reviews/api/api-extractor.api.md

@@ -45,6 +45,7 @@ export class Extractor {
 
 // @public
 export class ExtractorConfig {
+    readonly alphaTrimmedFilePath: string;
     readonly apiJsonFilePath: string;
     readonly apiReportEnabled: boolean;
     readonly betaTrimmedFilePath: string;
@@ -184,6 +185,7 @@ export interface IConfigDocModel {
 
 // @public
 export interface IConfigDtsRollup {
+    alphaTrimmedFilePath?: string;
     betaTrimmedFilePath?: string;
     enabled: boolean;
     omitTrimmingComments?: boolean;
@@ -265,5 +267,4 @@ export interface IExtractorMessagesConfig {
     tsdocMessageReporting?: IConfigMessageReportingTable;
 }
 
-
 ```