[api-extractor] Fix #3593 Incorrect canonical reference to aliased class in .api.json

.gitignore

@@ -80,3 +80,7 @@ dist
 
 # Heft
 .heft
+
+# IntelliJ IDEA
+.idea
+*.iml

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

@@ -82,6 +82,7 @@ export class Collector {
     AstEntity,
     CollectorEntity
   >();
+  private readonly _entitiesBySymbol: Map<ts.Symbol, CollectorEntity> = new Map<ts.Symbol, CollectorEntity>();
 
   private readonly _starExportedExternalModulePaths: string[] = [];
 
@@ -301,6 +302,37 @@ export class Collector {
     return this._entitiesByAstEntity.get(astEntity);
   }
 
+  /**
+   * Returns the name to emit for the given `symbol`.
+   * This is usually the `name` of that `symbol`.
+   * Only if this `symbol` has a `CollectorEntity`, the `nameForEmit` of that entity is used.
+   * @param symbol the symbol to compute the name to emit for
+   * @returns the name to emit for the given `symbol`
+   */
+  public getEmitName(symbol: ts.Symbol): string {
+    const collectorEntity: CollectorEntity | undefined = this._entitiesBySymbol.get(symbol);
+    return collectorEntity?.nameForEmit ?? symbol.name;
+  }
+
+  /**
+   * Returns (the symbol of) the namespace that exports the given `symbol`, if applicable.
+   * @param symbol the symbol representing the namespace that exports the given `symbol`,
+   *   or undefined if there is no such namespace
+   */
+  public getExportingNamespace(symbol: ts.Symbol): ts.Symbol | undefined {
+    const collectorEntity: CollectorEntity | undefined = this._entitiesBySymbol.get(symbol);
+    if (collectorEntity) {
+      const exportingNamespace: AstNamespaceImport | undefined = collectorEntity.getExportingNamespace();
+      if (exportingNamespace) {
+        return TypeScriptInternals.tryGetSymbolForDeclaration(
+          exportingNamespace.declaration,
+          this.typeChecker
+        );
+      }
+    }
+    return undefined;
+  }
+
   public fetchSymbolMetadata(astSymbol: AstSymbol): SymbolMetadata {
     if (astSymbol.symbolMetadata === undefined) {
       this._fetchSymbolMetadata(astSymbol);
@@ -420,6 +452,11 @@ export class Collector {
       entity = new CollectorEntity(astEntity);
 
       this._entitiesByAstEntity.set(astEntity, entity);
+      if (astEntity instanceof AstSymbol) {
+        this._entitiesBySymbol.set(astEntity.followedSymbol, entity);
+      } else if (astEntity instanceof AstNamespaceImport) {
+        this._entitiesBySymbol.set((astEntity.declaration as unknown as ts.Type).symbol, entity);
+      }
       this._entities.push(entity);
       this._collectReferenceDirectives(astEntity);
     }

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

@@ -7,6 +7,7 @@ import { AstSymbol } from '../analyzer/AstSymbol';
 import { Collector } from './Collector';
 import { Sort } from '@rushstack/node-core-library';
 import { AstEntity } from '../analyzer/AstEntity';
+import { AstNamespaceImport } from '../analyzer/AstNamespaceImport';
 
 /**
  * This is a data structure used by the Collector to track an AstEntity that may be emitted in the *.d.ts file.
@@ -189,6 +190,18 @@ export class CollectorEntity {
     return this._localExportNamesByParent.size > 0;
   }
 
+  /**
+   * Return the first namespace that exports this entity.
+   */
+  public getExportingNamespace(): AstNamespaceImport | undefined {
+    for (const [parent, localExportNames] of this._localExportNamesByParent) {
+      if (parent.consumable && localExportNames.size > 0 && parent.astEntity instanceof AstNamespaceImport) {
+        return parent.astEntity;
+      }
+    }
+    return undefined;
+  }
+
   /**
    * Adds a new export name to the entity.
    */

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

@@ -88,9 +88,18 @@ export class DeclarationReferenceGenerator {
   }
 
   private _getNavigationToSymbol(symbol: ts.Symbol): Navigation {
+    // resolve alias first:
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+      symbol = this._collector.typeChecker.getAliasedSymbol(symbol);
+    }
+    // namespace always uses ".":
+    if (symbol.flags & ts.SymbolFlags.Namespace) {
+      return Navigation.Exports;
+    }
     const declaration: ts.Declaration | undefined = TypeScriptHelpers.tryGetADeclaration(symbol);
     const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile();
-    const parent: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol);
+    const parent: ts.Symbol | undefined =
+      TypeScriptInternals.getSymbolParent(symbol) ?? this._collector.getExportingNamespace(symbol);
 
     // If it's global or from an external library, then use either Members or Exports. It's not possible for
     // global symbols or external library symbols to be Locals.
@@ -208,7 +217,11 @@ export class DeclarationReferenceGenerator {
       followedSymbol = this._collector.typeChecker.getExportSymbolOfSymbol(followedSymbol);
     }
     if (followedSymbol.flags & ts.SymbolFlags.Alias) {
-      followedSymbol = this._collector.typeChecker.getAliasedSymbol(followedSymbol);
+      const nextFollowedSymbol: ts.Symbol = this._collector.typeChecker.getAliasedSymbol(followedSymbol);
+      // do not follow alias to namespace, as it results in a source file that no longer knows its short name:
+      if (!(nextFollowedSymbol.flags & ts.SymbolFlags.Namespace)) {
+        followedSymbol = nextFollowedSymbol;
+      }
     }
 
     if (DeclarationReferenceGenerator._isExternalModuleSymbol(followedSymbol)) {
@@ -228,7 +241,7 @@ export class DeclarationReferenceGenerator {
       return undefined;
     }
 
-    let localName: string = followedSymbol.name;
+    let localName: string = this._collector.getEmitName(followedSymbol);
     if (followedSymbol.escapedName === ts.InternalSymbolName.Constructor) {
       localName = 'constructor';
     } else {
@@ -266,9 +279,13 @@ export class DeclarationReferenceGenerator {
   }
 
   private _getParentReference(symbol: ts.Symbol): DeclarationReference | undefined {
-    const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol);
+    // First case: the symbol is exported via a namespace
+    const exportingNamespace: ts.Symbol | undefined = this._collector.getExportingNamespace(symbol);
+    if (exportingNamespace) {
+      return this._symbolToDeclarationReference(exportingNamespace, exportingNamespace.flags, true);
+    }
 
-    // First, try to find a parent symbol via the symbol tree.
+    // Next, try to find a parent symbol via the symbol tree.
     const parentSymbol: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol);
     if (parentSymbol) {
       return this._symbolToDeclarationReference(
@@ -290,6 +307,7 @@ export class DeclarationReferenceGenerator {
     //
     // In the example above, `SomeType` doesn't have a parent symbol per the TS internal API above,
     // but its reference still needs to be qualified with the parent reference for `n`.
+    const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol);
     const grandParent: ts.Node | undefined = declaration?.parent?.parent;
     if (grandParent && ts.isModuleDeclaration(grandParent)) {
       const grandParentSymbol: ts.Symbol | undefined = TypeScriptInternals.tryGetSymbolForDeclaration(

build-tests/api-extractor-scenarios/config/build-config.json

@@ -14,6 +14,8 @@
     "docReferences",
     "docReferences2",
     "docReferences3",
+    "docReferencesAlias",
+    "docReferencesNamespaceAlias",
     "dynamicImportType",
     "dynamicImportType2",
     "dynamicImportType3",

build-tests/api-extractor-scenarios/etc/ambientNameConflict/api-extractor-scenarios.api.json

@@ -197,7 +197,7 @@
             {
               "kind": "Reference",
               "text": "MyPromise",
-              "canonicalReference": "api-extractor-scenarios!~Promise:class"
+              "canonicalReference": "api-extractor-scenarios!~Promise_2:class"
             },
             {
               "kind": "Content",