[api-extractor] Improve symbol analyzer to support "export * from" constructs

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/analyzer/AstDeclaration.ts

@@ -29,7 +29,7 @@ export interface IAstDeclarationOptions {
  * of analyzing AEDoc and emitting *.d.ts files.
  *
  * The AstDeclarations correspond to items from the compiler's ts.Node hierarchy, but
- * omitting/skipping any nodes that don't match the SymbolAnalyzer.isAstDeclaration()
+ * omitting/skipping any nodes that don't match the AstDeclaration.isSupportedSyntaxKind()
  * criteria.  This simplification makes the other API Extractor stages easier to implement.
  */
 export class AstDeclaration {
@@ -121,7 +121,7 @@ export class AstDeclaration {
   public getDump(indent: string = ''): string {
     const declarationKind: string = ts.SyntaxKind[this.declaration.kind];
     let result: string = indent + `+ ${this.astSymbol.localName} (${declarationKind})`;
-    if (this.astSymbol.nominal) {
+    if (this.astSymbol.nominalAnalysis) {
       result += ' (nominal)';
     }
     result += '\n';
@@ -180,4 +180,40 @@ export class AstDeclaration {
       child.forEachDeclarationRecursive(action);
     }
   }
+
+  /**
+   * This function determines which ts.Node kinds will generate an AstDeclaration.
+   * These correspond to the definitions that we can add AEDoc to.
+   */
+  public static isSupportedSyntaxKind(kind: ts.SyntaxKind): boolean {
+    // (alphabetical order)
+    switch (kind) {
+      case ts.SyntaxKind.CallSignature:
+      case ts.SyntaxKind.ClassDeclaration:
+      case ts.SyntaxKind.ConstructSignature:    // Example: "new(x: number): IMyClass"
+      case ts.SyntaxKind.Constructor:           // Example: "constructor(x: number)"
+      case ts.SyntaxKind.EnumDeclaration:
+      case ts.SyntaxKind.EnumMember:
+      case ts.SyntaxKind.FunctionDeclaration:   // Example: "(x: number): number"
+      case ts.SyntaxKind.IndexSignature:        // Example: "[key: string]: string"
+      case ts.SyntaxKind.InterfaceDeclaration:
+      case ts.SyntaxKind.MethodDeclaration:
+      case ts.SyntaxKind.MethodSignature:
+      case ts.SyntaxKind.ModuleDeclaration:     // Used for both "module" and "namespace" declarations
+      case ts.SyntaxKind.PropertyDeclaration:
+      case ts.SyntaxKind.PropertySignature:
+      case ts.SyntaxKind.TypeAliasDeclaration:  // Example: "type Shape = Circle | Square"
+      case ts.SyntaxKind.VariableDeclaration:
+        return true;
+
+      // NOTE: In contexts where a source file is treated as a module, we do create "nominal analysis"
+      // AstSymbol objects corresponding to a ts.SyntaxKind.SourceFile node.  However, a source file
+      // is NOT considered a nesting structure, and it does NOT act as a root for the declarations
+      // appearing in the file.  This is because the *.d.ts generator is in the business of rolling up
+      // source files, and thus wants to ignore them in general.
+    }
+
+    return false;
+  }
+
 }

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

@@ -16,26 +16,24 @@ export interface IAstImportOptions {
 export class AstImport {
   /**
    * The name of the external package (and possibly module path) that this definition
-   * was imported from.  If it was defined in the referencing source file, or if it was
-   * imported from a local file, or if it is an ambient definition, then externalPackageName
-   * will be undefined.
+   * was imported from.
    *
-   * Example: "@microsoft/gulp-core-build/lib/IBuildConfig"
+   * Example: "@microsoft/node-core-library/lib/FileSystem"
    */
   public readonly modulePath: string;
 
   /**
-   * If importPackagePath is defined, then this specifies the export name for the definition.
+   * If modulePath is defined, then this specifies the export name for the definition.
    *
    * Example: "IBuildConfig"
    */
   public readonly exportName: string;
 
   /**
-   * If importPackagePath and importPackageExportName are defined, then this is a dictionary key
+   * If modulePath and exportName are defined, then this is a dictionary key
    * that combines them with a colon (":").
    *
-   * Example: "@microsoft/gulp-core-build/lib/IBuildConfig:IBuildConfig"
+   * Example: "@microsoft/node-core-library/lib/FileSystem:FileSystem"
    */
   public readonly key: string;
 

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

@@ -0,0 +1,33 @@
+// 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 './AstSymbol';
+
+/**
+ */
+export class AstModule {
+  public readonly sourceFile: ts.SourceFile;
+
+  public readonly exportedSymbols: Map<string, AstSymbol>;
+  public readonly starExportedExternalModules: Set<AstModule>;
+
+  /**
+   * Example:  "@microsoft/node-core-library/lib/FileSystem"
+   * but never: "./FileSystem"
+   */
+  public externalModulePath: string | undefined;
+
+  public constructor(sourceFile: ts.SourceFile) {
+    this.sourceFile = sourceFile;
+    this.exportedSymbols = new Map<string, AstSymbol>();
+    this.starExportedExternalModules = new Set<AstModule>();
+    this.externalModulePath = undefined;
+  }
+
+  public get isExternal(): boolean {
+    return this.externalModulePath !== undefined;
+  }
+
+}

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

@@ -13,7 +13,7 @@ export interface IAstSymbolOptions {
   readonly followedSymbol: ts.Symbol;
   readonly localName: string;
   readonly astImport: AstImport | undefined;
-  readonly nominal: boolean;
+  readonly nominalAnalysis: boolean;
   readonly parentAstSymbol: AstSymbol | undefined;
   readonly rootAstSymbol: AstSymbol | undefined;
 }
@@ -44,7 +44,9 @@ export class AstSymbol {
 
   /**
    * If this symbol was imported from another package, that information is tracked here.
-   * Otherwise, the value is undefined.
+   * Otherwise, the value is undefined.  For example, if this symbol was defined in the referencing source file,
+   * or if it was imported from a local file in the current project, or if it is an ambient definition,
+   * then astImport will be undefined.
    */
   public readonly astImport: AstImport | undefined;
 
@@ -55,7 +57,7 @@ export class AstSymbol {
    *
    * Nominal symbols are tracked because we still need to emit exports for them.
    */
-  public readonly nominal: boolean;
+  public readonly nominalAnalysis: boolean;
 
   /**
    * Returns the symbol of the parent of this AstSymbol, or undefined if there is no parent.
@@ -90,7 +92,7 @@ export class AstSymbol {
     this.followedSymbol = options.followedSymbol;
     this.localName = options.localName;
     this.astImport = options.astImport;
-    this.nominal = options.nominal;
+    this.nominalAnalysis = options.nominalAnalysis;
     this.parentAstSymbol = options.parentAstSymbol;
     this.rootAstSymbol = options.rootAstSymbol || this;
     this._astDeclarations = [];