[api-extractor] add basic support for import * as module from './local-module'

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

@@ -74,7 +74,13 @@
       "name": "scenario",
       "program": "${workspaceFolder}/lib/start.js",
       "cwd": "${workspaceFolder}/../../build-tests/api-extractor-scenarios",
-      "args": ["--debug", "run", "--local", "--config", "./temp/configs/api-extractor-typeof.json"],
+      "args": [
+        "--debug",
+        "run",
+        "--local",
+        "--config",
+        "./temp/configs/api-extractor-exportImportStarAs2.json"
+      ],
       "sourceMaps": true
     }
   ]

apps/api-extractor/src/analyzer/AstDeclaration.ts

@@ -5,7 +5,7 @@ import * as ts from 'typescript';
 import { AstSymbol } from './AstSymbol';
 import { Span } from './Span';
 import { InternalError } from '@rushstack/node-core-library';
-import { AstEntity } from './AstSymbolTable';
+import { AstEntity } from './AstEntity';
 
 /**
  * Constructor options for AstDeclaration

apps/api-extractor/src/analyzer/AstEntity.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * `AstEntity` is the abstract base class for analyzer objects that can become a `CollectorEntity`.
+ *
+ * @remarks
+ *
+ * The subclasses are:
+ * ```
+ * - AstEntity
+ *   - AstSymbol
+ *   - AstSyntheticEntity
+ *     - AstImport
+ *     - AstNamespaceImport
+ * ```
+ */
+export abstract class AstEntity {
+  /**
+   * The original name of the symbol, as exported from the module (i.e. source file)
+   * containing the original TypeScript definition.  Constructs such as
+   * `import { X as Y } from` may introduce other names that differ from the local name.
+   *
+   * @remarks
+   * For the most part, `localName` corresponds to `followedSymbol.name`, but there
+   * are some edge cases.  For example, the ts.Symbol.name for `export default class X { }`
+   * is actually `"default"`, not `"X"`.
+   */
+  public abstract readonly localName: string;
+}
+
+/**
+ * `AstSyntheticEntity` is the abstract base class for analyzer objects whose emitted declarations
+ * are not text transformations performed by the `Span` helper.
+ *
+ * @remarks
+ * Most of API Extractor's output is produced by using the using the `Span` utility to regurgitate strings from
+ * the input .d.ts files.  If we need to rename an identifier, the `Span` visitor can pick out an interesting
+ * node and rewrite its string, but otherwise the transformation operates on dumb text and not compiler concepts.
+ * (Historically we did this because the compiler's emitter was an internal API, but it still has some advantages,
+ * for example preserving syntaxes generated by an older compiler to avoid incompatibilities.)
+ *
+ * This strategy does not work for cases where the output looks very different from the input.  Today these
+ * cases are always kinds of `import` statements, but that may change in the future.
+ */
+export abstract class AstSyntheticEntity extends AstEntity {}

apps/api-extractor/src/analyzer/AstImport.ts

@@ -3,6 +3,7 @@
 
 import { AstSymbol } from './AstSymbol';
 import { InternalError } from '@rushstack/node-core-library';
+import { AstSyntheticEntity } from './AstEntity';
 
 /**
  * Indicates the import kind for an `AstImport`.
@@ -49,7 +50,7 @@ export interface IAstImportOptions {
  * For a symbol that was imported from an external package, this tracks the import
  * statement that was used to reach it.
  */
-export class AstImport {
+export class AstImport extends AstSyntheticEntity {
   public readonly importKind: AstImportKind;
 
   /**
@@ -110,6 +111,8 @@ export class AstImport {
   public readonly key: string;
 
   public constructor(options: IAstImportOptions) {
+    super();
+
     this.importKind = options.importKind;
     this.modulePath = options.modulePath;
     this.exportName = options.exportName;
@@ -120,11 +123,9 @@ export class AstImport {
     this.key = AstImport.getKey(options);
   }
 
-  /**
-   * Allows `AstEntity.localName` to be used as a convenient generalization of `AstSymbol.localName` and
-   * `AstImport.exportName`.
-   */
+  /** {@inheritdoc} */
   public get localName(): string {
+    // abstract
     return this.exportName;
   }
 

apps/api-extractor/src/analyzer/AstModule.ts

@@ -4,7 +4,7 @@
 import * as ts from 'typescript';
 
 import { AstSymbol } from './AstSymbol';
-import { AstEntity } from './AstSymbolTable';
+import { AstEntity } from './AstEntity';
 
 /**
  * Represents information collected by {@link AstSymbolTable.fetchAstModuleExportInfo}
@@ -16,6 +16,12 @@ export class AstModuleExportInfo {
 
 /**
  * Constructor parameters for AstModule
+ *
+ * @privateRemarks
+ * Our naming convention is to use I____Parameters for constructor options and
+ * I____Options for general function options.  However the word "parameters" is
+ * confusingly similar to the terminology for function parameters modeled by API Extractor,
+ * so we use I____Options for both cases in this code base.
  */
 export interface IAstModuleOptions {
   sourceFile: ts.SourceFile;
@@ -25,12 +31,6 @@ export interface IAstModuleOptions {
 
 /**
  * An internal data structure that represents a source file that is analyzed by AstSymbolTable.
- *
- * @privateRemarks
- * Our naming convention is to use I____Parameters for constructor options and
- * I____Options for general function options.  However the word "parameters" is
- * confusingly similar to the terminology for function parameters modeled by API Extractor,
- * so we use I____Options for both cases in this code base.
  */
 export class AstModule {
   /**

apps/api-extractor/src/analyzer/AstNamespaceImport.ts

@@ -0,0 +1,89 @@
+// 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 { AstModule, AstModuleExportInfo } from './AstModule';
+import { AstSyntheticEntity } from './AstEntity';
+import { Collector } from '../collector/Collector';
+
+export interface IAstNamespaceImportOptions {
+  readonly astModule: AstModule;
+  readonly namespaceName: string;
+  readonly declaration: ts.Declaration;
+}
+
+/**
+ * `AstNamespaceImport` represents a namespace that is created implicitly by a statement
+ * such as `import * as example from "./file";`
+ *
+ * @remarks
+ *
+ * A typical input looks like this:
+ * ```ts
+ * // Suppose that example.ts exports two functions f1() and f2().
+ * import * as example from "./file";
+ * export { example };
+ * ```
+ *
+ * API Extractor's .d.ts rollup will transform it into an explicit namespace, like this:
+ * ```ts
+ * declare f1(): void;
+ * declare f2(): void;
+ *
+ * declare namespace example {
+ *   export {
+ *     f1,
+ *     f2
+ *   }
+ * }
+ * ```
+ *
+ * The current implementation does not attempt to relocate f1()/f2() to be inside the `namespace`
+ * because other type signatures may reference them directly (without using the namespace qualifier).
+ * The `declare namespace example` is a synthetic construct represented by `AstNamespaceImport`.
+ */
+export class AstNamespaceImport extends AstSyntheticEntity {
+  /**
+   * Returns true if the AstSymbolTable.analyze() was called for this object.
+   * See that function for details.
+   */
+  public analyzed: boolean = false;
+
+  /**
+   * For example, if the original statement was `import * as example from "./file";`
+   * then `astModule` refers to the `./file.d.ts` file.
+   */
+  public readonly astModule: AstModule;
+
+  /**
+   * For example, if the original statement was `import * as example from "./file";`
+   * then `namespaceName` would be `example`.
+   */
+  public readonly namespaceName: string;
+
+  /**
+   * The original `ts.SyntaxKind.NamespaceImport` which can be used as a location for error messages.
+   */
+  public readonly declaration: ts.Declaration;
+
+  public constructor(options: IAstNamespaceImportOptions) {
+    super();
+    this.astModule = options.astModule;
+    this.namespaceName = options.namespaceName;
+    this.declaration = options.declaration;
+  }
+
+  /** {@inheritdoc} */
+  public get localName(): string {
+    // abstract
+    return this.namespaceName;
+  }
+
+  public fetchAstModuleExportInfo(collector: Collector): AstModuleExportInfo {
+    const astModuleExportInfo: AstModuleExportInfo = collector.astSymbolTable.fetchAstModuleExportInfo(
+      this.astModule
+    );
+    return astModuleExportInfo;
+  }
+}

apps/api-extractor/src/analyzer/AstReferenceResolver.ts

@@ -4,13 +4,14 @@
 import * as ts from 'typescript';
 import * as tsdoc from '@microsoft/tsdoc';
 
-import { AstSymbolTable, AstEntity } from './AstSymbolTable';
+import { AstSymbolTable } from './AstSymbolTable';
+import { AstEntity } from './AstEntity';
 import { AstDeclaration } from './AstDeclaration';
 import { WorkingPackage } from '../collector/WorkingPackage';
 import { AstModule } from './AstModule';
-import { AstImport } from './AstImport';
 import { Collector } from '../collector/Collector';
 import { DeclarationMetadata } from '../collector/DeclarationMetadata';
+import { AstSymbol } from './AstSymbol';
 
 /**
  * Used by `AstReferenceResolver` to report a failed resolution.
@@ -90,8 +91,8 @@ export class AstReferenceResolver {
       );
     }
 
-    if (rootAstEntity instanceof AstImport) {
-      return new ResolverFailure('Reexported declarations are not supported');
+    if (!(rootAstEntity instanceof AstSymbol)) {
+      return new ResolverFailure('This type of declaration is not supported yet by the resolver');
     }
 
     let currentDeclaration: AstDeclaration | ResolverFailure = this._selectDeclaration(

apps/api-extractor/src/analyzer/AstSymbol.ts

@@ -4,6 +4,7 @@
 import * as ts from 'typescript';
 import { AstDeclaration } from './AstDeclaration';
 import { InternalError } from '@rushstack/node-core-library';
+import { AstEntity } from './AstEntity';
 
 /**
  * Constructor options for AstSymbol
@@ -50,18 +51,9 @@ export interface IAstSymbolOptions {
  *                              - g
  * ```
  */
-export class AstSymbol {
-  /**
-   * The original name of the symbol, as exported from the module (i.e. source file)
-   * containing the original TypeScript definition.  Constructs such as
-   * `import { X as Y } from` may introduce other names that differ from the local name.
-   *
-   * @remarks
-   * For the most part, `localName` corresponds to `followedSymbol.name`, but there
-   * are some edge cases.  For example, the symbol name for `export default class X { }`
-   * is actually `"default"`, not `"X"`.
-   */
-  public readonly localName: string;
+export class AstSymbol extends AstEntity {
+  /** {@inheritdoc} */
+  public readonly localName: string; // abstract
 
   /**
    * If true, then the `followedSymbol` (i.e. original declaration) of this symbol
@@ -121,6 +113,8 @@ export class AstSymbol {
   private _analyzed: boolean = false;
 
   public constructor(options: IAstSymbolOptions) {
+    super();
+
     this.followedSymbol = options.followedSymbol;
     this.localName = options.localName;
     this.isExternal = options.isExternal;