Add api extractor config overrides, fix child method trimming

Author: D4N14L

apps/api-extractor/src/collector/Collector.ts

@@ -526,7 +526,7 @@ export class Collector {
               astDeclaration.declaration.kind === ts.SyntaxKind.FunctionDeclaration ||
               astDeclaration.declaration.kind === ts.SyntaxKind.MethodDeclaration
             ) {
-              // For functions overrides, take the highest accessability from multiple declarations
+              // For function and method overloads, take the highest release from multiple declarations
               if (effectiveReleaseTag < declaredReleaseTag) {
                 effectiveReleaseTag = declaredReleaseTag;
               }

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

@@ -433,7 +433,7 @@ export class ApiModelGenerator {
       if (declaredReleaseTag === ReleaseTag.Internal || declaredReleaseTag === ReleaseTag.Alpha) {
         return; // trim out items marked as "@internal" or "@alpha"
       }
-      // If we have less accessible function overloads, include that information
+      // If we have lower-release function overloads, include that information
       const symbolMetadata: SymbolMetadata = this._collector.fetchMetadata(astDeclaration.astSymbol);
       const releaseTag: ReleaseTag = (
         declaredReleaseTag !== ReleaseTag.None &&
@@ -573,7 +573,7 @@ export class ApiModelGenerator {
       if (declaredReleaseTag === ReleaseTag.Internal || declaredReleaseTag === ReleaseTag.Alpha) {
         return; // trim out items marked as "@internal" or "@alpha"
       }
-      // If we have less accessible function overloads, include that information
+      // If we have lower-release function overloads, include that information
       const symbolMetadata: SymbolMetadata = this._collector.fetchMetadata(astDeclaration.astSymbol);
       const releaseTag: ReleaseTag = (
         declaredReleaseTag !== ReleaseTag.None &&

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

@@ -374,7 +374,7 @@ export class ApiReportGenerator {
 
     const declarationMetadata: DeclarationMetadata = collector.fetchMetadata(astDeclaration);
     const symbolMetadata: SymbolMetadata = collector.fetchMetadata(astDeclaration.astSymbol);
-    // If we have less accessible function overloads, include that information
+    // If we have lower-release function overloads, include that information
     const useDeclarationReleaseTag: boolean = (
         astDeclaration.declaration.kind === ts.SyntaxKind.FunctionDeclaration ||
         astDeclaration.declaration.kind === ts.SyntaxKind.MethodDeclaration

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

@@ -113,13 +113,10 @@ export class DtsRollupGenerator {
         // Emit all the declarations for this entry
         for (const astDeclaration of entity.astEntity.astDeclarations || []) {
           const declarationMetadata: DeclarationMetadata = collector.fetchMetadata(astDeclaration);
-          const checkDeclarationReleaseTag: boolean = (
-            astDeclaration.declaration.kind === ts.SyntaxKind.FunctionDeclaration ||
-            astDeclaration.declaration.kind === ts.SyntaxKind.MethodDeclaration
-          ) && !!declarationMetadata;
 
           if (
-            checkDeclarationReleaseTag &&
+            astDeclaration.declaration.kind === ts.SyntaxKind.FunctionDeclaration &&
+            !!declarationMetadata &&
             !this._shouldIncludeReleaseTag(declarationMetadata.declaredReleaseTag, dtsKind)
           ) {
               if (!collector.extractorConfig.omitTrimmingComments) {
@@ -279,8 +276,17 @@ export class DtsRollupGenerator {
         let trimmed: boolean = false;
         if (AstDeclaration.isSupportedSyntaxKind(child.kind)) {
           childAstDeclaration = collector.astSymbolTable.getChildAstDeclarationByNode(child.node, astDeclaration);
+          const childDeclarationMetadata: DeclarationMetadata = collector.fetchMetadata(childAstDeclaration);
+          const symbolMetadata: SymbolMetadata = collector.fetchMetadata(childAstDeclaration.astSymbol);
+          // If we have lower-release method overloads, include that information
+          const useDeclarationReleaseTag: boolean = (
+            childAstDeclaration.declaration.kind === ts.SyntaxKind.MethodDeclaration &&
+            !!childDeclarationMetadata
+          );
+          const releaseTag: ReleaseTag = useDeclarationReleaseTag
+            ? childDeclarationMetadata.declaredReleaseTag
+            : symbolMetadata.releaseTag;
 
-          const releaseTag: ReleaseTag = collector.fetchMetadata(childAstDeclaration.astSymbol).releaseTag;
           if (!this._shouldIncludeReleaseTag(releaseTag, dtsKind)) {
             let nodeToTrim: Span = child;
 
@@ -301,7 +307,9 @@ export class DtsRollupGenerator {
             modification.omitChildren = true;
 
             if (!collector.extractorConfig.omitTrimmingComments) {
-              modification.prefix = `/* Excluded from this release type: ${name} */`;
+              modification.prefix = useDeclarationReleaseTag
+                ? `/* Excluded from this release type: ${name} overload */`
+                : `/* Excluded from this release type: ${name} */`;
             } else {
               modification.prefix = '';
             }

build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/beta-rollup.d.ts

@@ -0,0 +1,29 @@
+
+/* Excluded from this release type: combine overload */
+
+/**
+ * @beta
+ */
+export declare function combine(x: string, y: string): string;
+
+/**
+ * @public
+ */
+export declare function combine(x: number, y: number): number;
+
+/**
+ * @public
+ */
+export declare class Combiner {
+    /* Excluded from this release type: combine overload */
+    /**
+     * @beta
+     */
+    combine(x: string, y: string): string;
+    /**
+     * @public
+     */
+    combine(x: number, y: number): number;
+}
+
+export { }

build-tests/api-extractor-scenarios/etc/test-outputs/functionOverload/public-rollup.d.ts

@@ -0,0 +1,23 @@
+
+/* Excluded from this release type: combine overload */
+
+/* Excluded from this release type: combine overload */
+
+/**
+ * @public
+ */
+export declare function combine(x: number, y: number): number;
+
+/**
+ * @public
+ */
+export declare class Combiner {
+    /* Excluded from this release type: combine overload */
+    /* Excluded from this release type: combine overload */
+    /**
+     * @public
+     */
+    combine(x: number, y: number): number;
+}
+
+export { }

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

@@ -0,0 +1,8 @@
+{
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/etc/test-outputs/functionOverload/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-scenarios/src/runScenarios.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import * as fs from 'fs';
 import * as path from 'path';
 import { JsonFile } from '@microsoft/node-core-library';
 import {
@@ -24,6 +25,8 @@ export function runScenarios(buildConfigPath: string): void {
     const entryPoint: string = path.resolve(`./lib/${scenarioFolderName}/index.d.ts`);
     entryPoints.push(entryPoint);
 
+    const overridesPath = path.resolve(`./src/${scenarioFolderName}/config/api-extractor-overrides.json`);
+    const apiExtractorJsonOverrides = fs.existsSync(overridesPath) ? JsonFile.load(overridesPath) : {};
     const apiExtractorJson = {
       '$schema': 'https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json',
 
@@ -59,7 +62,8 @@ export function runScenarios(buildConfigPath: string): void {
         }
       },
 
-      'testMode': true
+      'testMode': true,
+      ...apiExtractorJsonOverrides
     };
 
     const apiExtractorJsonPath: string = `./temp/configs/api-extractor-${scenarioFolderName}.json`;