Generalize CollectorEntity to support a given declaration being exported multiple times (fixes GitHub issue #950)

Author: pgonzal

apps/api-extractor/.vscode/launch.json

@@ -11,9 +11,9 @@
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-01",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local"
       ],
       "sourceMaps": true
     },
@@ -24,9 +24,9 @@
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-02",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local"
       ],
       "sourceMaps": true
     },
@@ -37,9 +37,9 @@
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-03",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local"
       ],
       "sourceMaps": true
     },
@@ -50,9 +50,9 @@
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-04",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local"
       ],
       "sourceMaps": true
     },
@@ -63,22 +63,24 @@
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-05",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local"
       ],
       "sourceMaps": true
     },
     {
       "type": "node",
       "request": "launch",
-      "name": "test-06",
+      "name": "scenario",
       "program": "${workspaceFolder}/lib/start.js",
-      "cwd": "${workspaceFolder}/../../build-tests/api-extractor-test-06",
+      "cwd": "${workspaceFolder}/../../build-tests/api-extractor-scenarios",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local",
+        "--config",
+        "./temp/configs/api-extractor-defaultExportOfEntryPoint1.json"
       ],
       "sourceMaps": true
     },
@@ -89,9 +91,9 @@
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "(your project path)",
       "args": [
-        "-d",
+        "--debug",
         "run",
-        "-l"
+        "--local"
       ],
       "sourceMaps": true
     }

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

@@ -248,27 +248,17 @@ export class Collector {
     let entity: CollectorEntity | undefined = this._entitiesByAstSymbol.get(astSymbol);
 
     if (!entity) {
-      entity = new CollectorEntity({
-        astSymbol: astSymbol,
-        originalName: exportedName || astSymbol.localName,
-        exported: !!exportedName
-      });
+      entity = new CollectorEntity(astSymbol);
 
       this._entitiesByAstSymbol.set(astSymbol, entity);
       this._entitiesBySymbol.set(astSymbol.followedSymbol, entity);
       this._entities.push(entity);
 
       this._collectReferenceDirectives(astSymbol);
-    } else {
-      if (exportedName) {
-        if (!entity.exported) {
-          throw new InternalError('CollectorEntity should have been marked as exported');
-        }
-        if (entity.originalName !== exportedName) {
-          throw new InternalError(`The symbol ${exportedName} was also exported as ${entity.originalName};`
-            + ` this is not supported yet`);
-        }
-      }
+    }
+
+    if (exportedName) {
+      entity.addExportName(exportedName);
     }
   }
 
@@ -294,31 +284,39 @@ export class Collector {
 
     // First collect the explicit package exports (named)
     for (const entity of this._entities) {
-      if (entity.exported && entity.originalName !== ts.InternalSymbolName.Default) {
-
-        if (usedNames.has(entity.originalName)) {
+      for (const exportName of entity.exportNames) {
+        if (usedNames.has(exportName)) {
           // This should be impossible
-          throw new InternalError(`A package cannot have two exports with the name ${entity.originalName}`);
+          throw new InternalError(`A package cannot have two exports with the name "${exportName}"`);
         }
 
-        entity.nameForEmit = entity.originalName;
-
-        usedNames.add(entity.nameForEmit);
+        usedNames.add(exportName);
       }
     }
 
     // Next generate unique names for the non-exports that will be emitted (and the default export)
     for (const entity of this._entities) {
-      if (!entity.exported || entity.originalName === ts.InternalSymbolName.Default) {
-        let suffix: number = 1;
-        entity.nameForEmit = entity.astSymbol.localName;
 
-        while (usedNames.has(entity.nameForEmit)) {
-          entity.nameForEmit = `${entity.astSymbol.localName}_${++suffix}`;
-        }
+      // If this entity is exported exactly once, then emit the exported name
+      if (entity.singleExportName !== undefined && entity.singleExportName !== ts.InternalSymbolName.Default) {
+        entity.nameForEmit = entity.singleExportName;
+        continue;
+      }
+
+      // If the localName happens to be the same as one of the exports, then emit that name
+      if (entity.exportNames.has(entity.astSymbol.localName)) {
+        entity.nameForEmit = entity.astSymbol.localName;
+        continue;
+      }
 
-        usedNames.add(entity.nameForEmit);
+      // In all other cases, generate a unique name based on the localName
+      let suffix: number = 1;
+      let nameForEmit: string = entity.astSymbol.localName;
+      while (usedNames.has(nameForEmit)) {
+        nameForEmit = `${entity.astSymbol.localName}_${++suffix}`;
       }
+      entity.nameForEmit = nameForEmit;
+      usedNames.add(nameForEmit);
     }
   }
 

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

@@ -1,21 +1,15 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import * as ts from 'typescript';
+
 import { AstSymbol } from '../analyzer/AstSymbol';
 import { Collector } from './Collector';
+import { Sort } from '@microsoft/node-core-library';
 
 /**
- * Constructor options for CollectorEntity
- */
-export interface ICollectorEntityOptions {
-  readonly astSymbol: AstSymbol;
-  readonly originalName: string;
-  readonly exported: boolean;
-}
-
-/**
- * This is a data structure used by DtsRollupGenerator to track an AstSymbol that may be
- * emitted in the *.d.ts file.
+ * This is a data structure used by the Collector to track an AstSymbol that may be emitted in the *.d.ts file.
+ *
  * @remarks
  * The additional contextual state beyond AstSymbol is:
  * - Whether it's an export of this entry point or not
@@ -27,28 +21,22 @@ export class CollectorEntity {
    */
   public readonly astSymbol: AstSymbol;
 
-  /**
-   * The original name, prior to any renaming by DtsRollupGenerator._makeUniqueNames()
-   */
-  public readonly originalName: string;
-
-  /**
-   * Whether this API item is exported by the *.t.s file
-   */
-  public readonly exported: boolean;
+  private _exportNames: Set<string> = new Set<string>();
+  private _exportNamesSorted: boolean = false;
+  private _singleExportName: string | undefined = undefined;
 
   private _nameForEmit: string | undefined = undefined;
 
   private _sortKey: string | undefined = undefined;
 
-  public constructor(options: ICollectorEntityOptions) {
-    this.astSymbol = options.astSymbol;
-    this.originalName = options.originalName;
-    this.exported = options.exported;
+  public constructor(astSymbol: AstSymbol) {
+    this.astSymbol = astSymbol;
   }
 
   /**
-   * The originalName, possibly renamed to ensure that all the top-level exports have unique names.
+   * The declaration name that will be emitted in a .d.ts rollup.  For non-exported declarations,
+   * Collector._makeUniqueNames() may need to rename the declaration to avoid conflicts with other declarations
+   * in that module.
    */
   public get nameForEmit(): string | undefined {
     return this._nameForEmit;
@@ -59,13 +47,72 @@ export class CollectorEntity {
     this._sortKey = undefined; // invalidate the cached value
   }
 
+  /**
+   * If this symbol is exported from the entry point, the list of export names.
+   *
+   * @remarks
+   * Note that a given symbol may be exported more than once:
+   * ```
+   * class X { }
+   * export { X }
+   * export { X as Y }
+   * ```
+   */
+  public get exportNames(): ReadonlySet<string> {
+    if (!this._exportNamesSorted) {
+      Sort.sortSet(this._exportNames);
+      this._exportNamesSorted = true;
+    }
+    return this._exportNames;
+  }
+
+  /**
+   * If exportNames contains only one string, then singleExportName is that string.
+   * In all other cases, it is undefined.
+   */
+  public get singleExportName(): string | undefined {
+   return this._singleExportName;
+  }
+
+  /**
+   * This is true if exportNames contains only one string, and the declaration can be exported using the inline syntax
+   * such as "export class X { }" instead of "export { X }".
+   */
+  public get emitWithExportKeyword(): boolean {
+    return this._singleExportName !== undefined
+      && this._singleExportName !== ts.InternalSymbolName.Default
+      && this.astSymbol.astImport === undefined;
+  }
+
+  /**
+   * Returns true if this symbol is an export for the entry point being analyzed.
+   */
+  public get exported(): boolean {
+    return this.exportNames.size > 0;
+  }
+
+  /**
+   * Adds a new exportName to the exportNames set.
+   */
+  public addExportName(exportName: string): void {
+    if (!this._exportNames.has(exportName)) {
+      this._exportNamesSorted = false;
+      this._exportNames.add(exportName);
+
+      if (this._exportNames.size === 1) {
+        this._singleExportName = exportName;
+      } else {
+        this._singleExportName = undefined;
+      }
+    }
+  }
+
   /**
    * A sorting key used by DtsRollupGenerator._makeUniqueNames()
    */
   public getSortKey(): string {
     if (!this._sortKey) {
-      const name: string = this.nameForEmit || this.originalName;
-      this._sortKey = Collector.getSortKeyIgnoringUnderscore(name);
+      this._sortKey = Collector.getSortKeyIgnoringUnderscore(this.nameForEmit || this.astSymbol.localName);
     }
     return this._sortKey;
   }