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

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

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { AstModule } from './AstModule';
+
+export interface IAstImportAsModuleOptions {
+  readonly astModule: AstModule;
+  readonly exportName: string;
+}
+
+// TODO [MA]: add documentation
+export class AstImportAsModule {
+  // TODO [MA]: add documentation
+  public analyzed: boolean = false;
+
+  // TODO [MA]: add documentation
+  public readonly astModule: AstModule;
+
+  /**
+   * The name of the symbol being imported.
+   *
+   * @remarks
+   *
+   * The name depends on the type of import:
+   *
+   * ```ts
+   * // For AstImportKind.DefaultImport style, exportName would be "X" in this example:
+   * import X from "y";
+   *
+   * // For AstImportKind.NamedImport style, exportName would be "X" in this example:
+   * import { X } from "y";
+   *
+   * // For AstImportKind.StarImport style, exportName would be "x" in this example:
+   * import * as x from "y";
+   *
+   * // For AstImportKind.EqualsImport style, exportName would be "x" in this example:
+   * import x = require("y");
+   * ```
+   */
+  public readonly exportName: string;
+
+  public constructor(options: IAstImportAsModuleOptions) {
+    this.astModule = options.astModule;
+    this.exportName = options.exportName;
+  }
+
+  public get localName(): string {
+    return this.exportName;
+  }
+}

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

@@ -11,6 +11,7 @@ import { AstModule } from './AstModule';
 import { AstImport } from './AstImport';
 import { Collector } from '../collector/Collector';
 import { DeclarationMetadata } from '../collector/DeclarationMetadata';
+import { AstImportAsModule } from './AstImportAsModule';
 
 /**
  * Used by `AstReferenceResolver` to report a failed resolution.
@@ -87,6 +88,10 @@ export class AstReferenceResolver {
       return new ResolverFailure('Reexported declarations are not supported');
     }
 
+    if (rootAstEntity instanceof AstImportAsModule) {
+      return new ResolverFailure('Source file export declarations are not supported');
+    }
+
     let currentDeclaration: AstDeclaration | ResolverFailure = this._selectDeclaration(rootAstEntity.astDeclarations,
       rootMemberReference, rootAstEntity.localName);
 

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

@@ -11,11 +11,12 @@ import { AstModule, AstModuleExportInfo } from './AstModule';
 import { PackageMetadataManager } from './PackageMetadataManager';
 import { ExportAnalyzer } from './ExportAnalyzer';
 import { AstImport } from './AstImport';
+import { AstImportAsModule } from './AstImportAsModule';
 import { MessageRouter } from '../collector/MessageRouter';
 import { TypeScriptInternals } from './TypeScriptInternals';
 import { StringChecks } from './StringChecks';
 
-export type AstEntity = AstSymbol | AstImport;
+export type AstEntity = AstSymbol | AstImport | AstImportAsModule;
 
 /**
  * Options for `AstSymbolTable._fetchAstSymbol()`
@@ -137,43 +138,13 @@ export class AstSymbolTable {
    * or members.  (We do always construct its parents however, since AstDefinition.parent
    * is immutable, and needed e.g. to calculate release tag inheritance.)
    */
-  public analyze(astSymbol: AstSymbol): void {
-    if (astSymbol.analyzed) {
-      return;
+  public analyze(astEntity: AstEntity): void {
+    if (astEntity instanceof AstSymbol) {
+      return this._analyzeAstSymbol(astEntity);
     }
 
-    if (astSymbol.nominalAnalysis) {
-      // We don't analyze nominal symbols
-      astSymbol._notifyAnalyzed();
-      return;
-    }
-
-    // Start at the root of the tree
-    const rootAstSymbol: AstSymbol = astSymbol.rootAstSymbol;
-
-    // Calculate the full child tree for each definition
-    for (const astDeclaration of rootAstSymbol.astDeclarations) {
-      this._analyzeChildTree(astDeclaration.declaration, astDeclaration);
-    }
-
-    rootAstSymbol._notifyAnalyzed();
-
-    if (!astSymbol.isExternal) {
-      // If this symbol is non-external (i.e. it belongs to the working package), then we also analyze any
-      // referencedAstSymbols that are non-external.  For example, this ensures that forgotten exports
-      // get analyzed.
-      rootAstSymbol.forEachDeclarationRecursive((astDeclaration: AstDeclaration) => {
-        for (const referencedAstEntity of astDeclaration.referencedAstEntities) {
-
-          // Walk up to the root of the tree, looking for any imports along the way
-          if (referencedAstEntity instanceof AstSymbol) {
-            if (!referencedAstEntity.isExternal) {
-              this.analyze(referencedAstEntity);
-            }
-          }
-
-        }
-      });
+    if (astEntity instanceof AstImportAsModule) {
+      return this._analyzeAstImportAsModule(astEntity);
     }
   }
 
@@ -292,6 +263,71 @@ export class AstSymbolTable {
     return unquotedName;
   }
 
+
+  private _analyzeAstImportAsModule(astImportAsModule: AstImportAsModule): void {
+    if (astImportAsModule.analyzed) {
+      return;
+    }
+
+    // mark before actual analyzing, to handle module cyclic reexport
+    astImportAsModule.analyzed = true;
+
+    this.fetchAstModuleExportInfo(astImportAsModule.astModule).exportedLocalEntities.forEach(exportedEntity => {
+      if (exportedEntity instanceof AstImportAsModule) {
+        this._analyzeAstImportAsModule(exportedEntity);
+      }
+
+      if (exportedEntity instanceof AstSymbol) {
+        this._analyzeAstSymbol(exportedEntity);
+      }
+    });
+  }
+
+  private _analyzeAstSymbol(astSymbol: AstSymbol): void {
+    if (astSymbol.analyzed) {
+      return;
+    }
+
+    if (astSymbol.nominalAnalysis) {
+      // We don't analyze nominal symbols
+      astSymbol._notifyAnalyzed();
+      return;
+    }
+
+    // Start at the root of the tree
+    const rootAstSymbol: AstSymbol = astSymbol.rootAstSymbol;
+
+    // Calculate the full child tree for each definition
+    for (const astDeclaration of rootAstSymbol.astDeclarations) {
+      this._analyzeChildTree(astDeclaration.declaration, astDeclaration);
+    }
+
+    rootAstSymbol._notifyAnalyzed();
+
+    if (!astSymbol.isExternal) {
+      // If this symbol is non-external (i.e. it belongs to the working package), then we also analyze any
+      // referencedAstSymbols that are non-external.  For example, this ensures that forgotten exports
+      // get analyzed.
+      rootAstSymbol.forEachDeclarationRecursive((astDeclaration: AstDeclaration) => {
+        for (const referencedAstEntity of astDeclaration.referencedAstEntities) {
+
+          // Walk up to the root of the tree, looking for any imports along the way
+          if (referencedAstEntity instanceof AstSymbol) {
+            if (!referencedAstEntity.isExternal) {
+              this._analyzeAstSymbol(referencedAstEntity);
+            }
+          }
+
+          if (referencedAstEntity instanceof AstImportAsModule) {
+            if (!referencedAstEntity.astModule.isExternal) {
+              this._analyzeAstImportAsModule(referencedAstEntity)
+            }
+          }
+        }
+      });
+    }
+  }
+
   /**
    * Used by analyze to recursively analyze the entire child tree.
    */

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

@@ -11,6 +11,7 @@ import { AstModule, AstModuleExportInfo } from './AstModule';
 import { TypeScriptInternals } from './TypeScriptInternals';
 import { TypeScriptMessageFormatter } from './TypeScriptMessageFormatter';
 import { IFetchAstSymbolOptions, AstEntity } from './AstSymbolTable';
+import { AstImportAsModule } from './AstImportAsModule';
 
 /**
  * Exposes the minimal APIs from AstSymbolTable that are needed by ExportAnalyzer.
@@ -21,7 +22,7 @@ import { IFetchAstSymbolOptions, AstEntity } from './AstSymbolTable';
 export interface IAstSymbolTable {
   fetchAstSymbol(options: IFetchAstSymbolOptions): AstSymbol | undefined;
 
-  analyze(astSymbol: AstSymbol): void;
+  analyze(astEntity: AstEntity): void;
 }
 
 /**
@@ -73,6 +74,7 @@ export class ExportAnalyzer {
   private readonly _importableAmbientSourceFiles: Set<ts.SourceFile> = new Set<ts.SourceFile>();
 
   private readonly _astImportsByKey: Map<string, AstImport> = new Map<string, AstImport>();
+  private readonly _astImportAsModuleByModule: Map<AstModule, AstImportAsModule> = new Map<AstModule, AstImportAsModule>();
 
   public constructor(program: ts.Program, typeChecker: ts.TypeChecker, bundledPackageNames: Set<string>,
     astSymbolTable: IAstSymbolTable) {
@@ -308,6 +310,10 @@ export class ExportAnalyzer {
                     this._astSymbolTable.analyze(astEntity);
                   }
 
+                  if (astEntity instanceof AstImportAsModule && !astEntity.astModule.isExternal) {
+                    this._astSymbolTable.analyze(astEntity);
+                  }
+
                   astModuleExportInfo.exportedLocalEntities.set(exportSymbol.name, astEntity);
                 }
               }
@@ -447,10 +453,16 @@ export class ExportAnalyzer {
         //   SemicolonToken:  pre=[;]
 
         if (externalModulePath === undefined) {
-          // The implementation here only works when importing from an external module.
-          // The full solution is tracked by: https://github.com/microsoft/rushstack/issues/1029
-          throw new Error('"import * as ___ from ___;" is not supported yet for local files.'
-            + '\nFailure in: ' + importDeclaration.getSourceFile().fileName);
+          const astModule: AstModule = this._fetchSpecifierAstModule(importDeclaration, declarationSymbol);
+          let importAsModule: AstImportAsModule | undefined = this._astImportAsModuleByModule.get(astModule);
+          if (!importAsModule) {
+            importAsModule = new AstImportAsModule({
+              exportName: declarationSymbol.name,
+              astModule: astModule
+            });
+            this._astImportAsModuleByModule.set(astModule, importAsModule);
+          }
+          return importAsModule;
         }
 
         // Here importSymbol=undefined because {@inheritDoc} and such are not going to work correctly for

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

@@ -30,6 +30,7 @@ import { TypeScriptInternals } from '../analyzer/TypeScriptInternals';
 import { MessageRouter } from './MessageRouter';
 import { AstReferenceResolver } from '../analyzer/AstReferenceResolver';
 import { ExtractorConfig } from '../api/ExtractorConfig';
+import { AstImportAsModule } from '../analyzer/AstImportAsModule';
 
 /**
  * Options for Collector constructor.
@@ -294,6 +295,9 @@ export class Collector {
   }
 
   public tryFetchMetadataForAstEntity(astEntity: AstEntity): SymbolMetadata | undefined {
+    if (astEntity instanceof AstImportAsModule) {
+      return undefined;
+    }
     if (astEntity instanceof AstSymbol) {
       return this.fetchSymbolMetadata(astEntity);
     }
@@ -382,10 +386,7 @@ export class Collector {
 
       this._entitiesByAstEntity.set(astEntity, entity);
       this._entities.push(entity);
-
-      if (astEntity instanceof AstSymbol) {
-        this._collectReferenceDirectives(astEntity);
-      }
+      this._collectReferenceDirectives(astEntity);
     }
 
     if (exportedName) {
@@ -417,6 +418,14 @@ export class Collector {
         }
       });
     }
+
+    if (astEntity instanceof AstImportAsModule) {
+      this.astSymbolTable.fetchAstModuleExportInfo(astEntity.astModule).exportedLocalEntities.forEach((exportedEntity: AstEntity) => {
+        // Create a CollectorEntity for each top-level export of AstImportInternal entity
+        this._createCollectorEntity(exportedEntity, undefined);
+        this._createEntityForIndirectReferences(exportedEntity, alreadySeenAstEntities); // TODO- create entity for module export
+      });
+    }
   }
 
   /**
@@ -883,11 +892,23 @@ export class Collector {
     return parserContext;
   }
 
-  private _collectReferenceDirectives(astSymbol: AstSymbol): void {
+  private _collectReferenceDirectives(astEntity: AstEntity): void {
+    if (astEntity instanceof AstSymbol) {
+      const sourceFiles: ts.SourceFile[] = astEntity.astDeclarations.map(astDeclaration =>
+        astDeclaration.declaration.getSourceFile());
+      return this._collectReferenceDirectivesFromSourceFiles(sourceFiles);
+    }
+
+    if (astEntity instanceof AstImportAsModule) {
+      const sourceFiles: ts.SourceFile[] = [astEntity.astModule.sourceFile];
+      return this._collectReferenceDirectivesFromSourceFiles(sourceFiles);
+    }
+  }
+
+  private _collectReferenceDirectivesFromSourceFiles(sourceFiles: ts.SourceFile[]): void {
     const seenFilenames: Set<string> = new Set<string>();
 
-    for (const astDeclaration of astSymbol.astDeclarations) {
-      const sourceFile: ts.SourceFile = astDeclaration.declaration.getSourceFile();
+    for (const sourceFile of sourceFiles) {
       if (sourceFile && sourceFile.fileName) {
         if (!seenFilenames.has(sourceFile.fileName)) {
           seenFilenames.add(sourceFile.fileName);

apps/api-extractor/src/enhancers/ValidationEnhancer.ts

@@ -12,6 +12,7 @@ import { SymbolMetadata } from '../collector/SymbolMetadata';
 import { CollectorEntity } from '../collector/CollectorEntity';
 import { ExtractorMessageId } from '../api/ExtractorMessageId';
 import { ReleaseTag } from '@microsoft/api-extractor-model';
+import { AstImportAsModule } from '../analyzer/AstImportAsModule';
 
 export class ValidationEnhancer {
 
@@ -30,6 +31,10 @@ export class ValidationEnhancer {
           ValidationEnhancer._checkForInconsistentReleaseTags(collector, entity.astEntity, symbolMetadata);
         }
       }
+
+      if (entity.astEntity instanceof AstImportAsModule) {
+        // TODO [MA]: validation for local module import
+      }
     }
   }
 
@@ -175,6 +180,7 @@ export class ValidationEnhancer {
         const rootSymbol: AstSymbol = referencedEntity.rootAstSymbol;
 
         if (!rootSymbol.isExternal) {
+          // TODO: consider exported by local module import
           const collectorEntity: CollectorEntity | undefined = collector.tryGetCollectorEntity(rootSymbol);
 
           if (collectorEntity && collectorEntity.exported) {
@@ -210,6 +216,10 @@ export class ValidationEnhancer {
           }
         }
       }
+
+      if (referencedEntity instanceof AstImportAsModule) {
+        // TODO [MA]: add validation for local import
+      }
     }
   }