[api-extractor] Upgrade compiler engine to TypeScript 3.9

apps/api-extractor/package.json

@@ -39,15 +39,17 @@
     "colors": "~1.2.1",
     "lodash": "~4.17.15",
     "resolve": "~1.17.0",
+    "semver": "~5.3.0",
     "source-map": "~0.6.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   },
   "devDependencies": {
     "@microsoft/node-library-build": "6.4.10",
     "@microsoft/rush-stack-compiler-3.5": "0.4.4",
     "@rushstack/eslint-config": "1.0.2",
     "@types/jest": "25.2.1",
     "@types/lodash": "4.14.116",
+    "@types/semver": "5.3.33",
     "@types/node": "10.17.13",
     "@types/resolve": "1.17.1",
     "gulp": "~4.0.2"

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

@@ -427,7 +427,10 @@ export class ExportAnalyzer {
         const exportSpecifier: ts.ExportSpecifier = declaration as ts.ExportSpecifier;
         exportName = (exportSpecifier.propertyName || exportSpecifier.name).getText().trim();
       } else {
-        throw new InternalError('Unimplemented export declaration kind: ' + declaration.getText());
+        throw new InternalError(
+          `Unimplemented export declaration kind: ${declaration.getText()}\n` +
+            SourceFileLocationFormatter.formatDeclaration(declaration)
+        );
       }
 
       // Ignore "export { A }" without a module specifier
@@ -485,9 +488,8 @@ export class ExportAnalyzer {
           // 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
+            '"import * as ___ from ___;" is not supported yet for local files.\n' +
+              SourceFileLocationFormatter.formatDeclaration(importDeclaration)
           );
         }
 
@@ -571,7 +573,10 @@ export class ExportAnalyzer {
           declarationSymbol
         );
       } else {
-        throw new InternalError('Unimplemented import declaration kind: ' + declaration.getText());
+        throw new InternalError(
+          `Unimplemented import declaration kind: ${declaration.getText()}\n` +
+            SourceFileLocationFormatter.formatDeclaration(declaration)
+        );
       }
     }
 
@@ -715,7 +720,10 @@ export class ExportAnalyzer {
       importOrExportDeclaration
     );
     if (!moduleSpecifier) {
-      throw new InternalError('Unable to parse module specifier');
+      throw new InternalError(
+        'Unable to parse module specifier\n' +
+          SourceFileLocationFormatter.formatDeclaration(importOrExportDeclaration)
+      );
     }
 
     // Match:       "@microsoft/sp-lodash-subset" or "lodash/has"
@@ -740,7 +748,10 @@ export class ExportAnalyzer {
       importOrExportDeclaration
     );
     if (!moduleSpecifier) {
-      throw new InternalError('Unable to parse module specifier');
+      throw new InternalError(
+        'Unable to parse module specifier\n' +
+          SourceFileLocationFormatter.formatDeclaration(importOrExportDeclaration)
+      );
     }
 
     const resolvedModule: ts.ResolvedModuleFull | undefined = TypeScriptInternals.getResolvedModule(
@@ -751,8 +762,11 @@ export class ExportAnalyzer {
     if (resolvedModule === undefined) {
       // This should not happen, since getResolvedModule() specifically looks up names that the compiler
       // found in export declarations for this source file
+      //
+      // Encountered in https://github.com/microsoft/rushstack/issues/1914
       throw new InternalError(
-        'getResolvedModule() could not resolve module name ' + JSON.stringify(moduleSpecifier)
+        `getResolvedModule() could not resolve module name ${JSON.stringify(moduleSpecifier)}\n` +
+          SourceFileLocationFormatter.formatDeclaration(importOrExportDeclaration)
       );
     }
 
@@ -765,7 +779,8 @@ export class ExportAnalyzer {
       // This should not happen, since getResolvedModule() specifically looks up names that the compiler
       // found in export declarations for this source file
       throw new InternalError(
-        'getSourceFile() failed to locate ' + JSON.stringify(resolvedModule.resolvedFileName)
+        `getSourceFile() failed to locate ${JSON.stringify(resolvedModule.resolvedFileName)}\n` +
+          SourceFileLocationFormatter.formatDeclaration(importOrExportDeclaration)
       );
     }
 

apps/api-extractor/src/api/ConsoleMessageId.ts

@@ -12,6 +12,17 @@
  * @public
  */
 export const enum ConsoleMessageId {
+  /**
+   * "Analysis will use the bundled TypeScript version ___"
+   */
+  Preamble = 'console-preamble',
+
+  /**
+   * "The target project appears to use TypeScript ___ which is newer than the bundled compiler engine;
+   * consider upgrading API Extractor."
+   */
+  CompilerVersionNotice = 'console-compiler-version-notice',
+
   /**
    * "Found metadata in ___"
    */

apps/api-extractor/src/api/Extractor.ts

@@ -2,8 +2,16 @@
 // See LICENSE in the project root for license information.
 
 import * as path from 'path';
+import * as semver from 'semver';
 import * as ts from 'typescript';
-import { FileSystem, NewlineKind, PackageJsonLookup, IPackageJson } from '@rushstack/node-core-library';
+import * as resolve from 'resolve';
+import {
+  FileSystem,
+  NewlineKind,
+  PackageJsonLookup,
+  IPackageJson,
+  INodePackageJson
+} from '@rushstack/node-core-library';
 
 import { ExtractorConfig } from './ExtractorConfig';
 import { Collector } from '../collector/Collector';
@@ -200,7 +208,10 @@ export class Extractor {
       showDiagnostics: !!options.showDiagnostics
     });
 
+    this._checkCompilerCompatibility(extractorConfig, messageRouter);
+
     if (messageRouter.showDiagnostics) {
+      messageRouter.logDiagnostic('');
       messageRouter.logDiagnosticHeader('Final prepared ExtractorConfig');
       messageRouter.logDiagnostic(extractorConfig.getDiagnosticDump());
       messageRouter.logDiagnosticFooter();
@@ -395,6 +406,45 @@ export class Extractor {
     });
   }
 
+  private static _checkCompilerCompatibility(
+    extractorConfig: ExtractorConfig,
+    messageRouter: MessageRouter
+  ): void {
+    messageRouter.logInfo(
+      ConsoleMessageId.Preamble,
+      `Analysis will use the bundled TypeScript version ${ts.version}`
+    );
+
+    try {
+      const typescriptPath: string = resolve.sync('typescript', {
+        basedir: extractorConfig.projectFolder,
+        preserveSymlinks: false
+      });
+      const packageJsonLookup: PackageJsonLookup = new PackageJsonLookup();
+      const packageJson: INodePackageJson | undefined = packageJsonLookup.tryLoadNodePackageJsonFor(
+        typescriptPath
+      );
+      if (packageJson && packageJson.version && semver.valid(packageJson.version)) {
+        // Consider a newer MINOR release to be incompatible
+        const ourMajor: number = semver.major(ts.version);
+        const ourMinor: number = semver.minor(ts.version);
+
+        const theirMajor: number = semver.major(packageJson.version);
+        const theirMinor: number = semver.minor(packageJson.version);
+
+        if (theirMajor > ourMajor || (theirMajor === ourMajor && theirMinor > ourMinor)) {
+          messageRouter.logInfo(
+            ConsoleMessageId.CompilerVersionNotice,
+            `*** The target project appears to use TypeScript ${packageJson.version} which is newer than the` +
+              ` bundled compiler engine; consider upgrading API Extractor.`
+          );
+        }
+      }
+    } catch (e) {
+      // The compiler detection heuristic is not expected to work in many configurations
+    }
+  }
+
   private static _generateRollupDtsFile(
     collector: Collector,
     outputPath: string,

apps/api-extractor/src/cli/RunAction.ts

@@ -138,7 +138,7 @@ export class RunAction extends CommandLineAction {
         }
       }
 
-      console.log(`Using configuration from ${configFilename}` + os.EOL);
+      console.log(`Using configuration from ${configFilename}`);
     }
 
     const configObjectFullPath: string = path.resolve(configFilename);

build-tests/api-documenter-test/package.json

@@ -14,6 +14,6 @@
     "@types/jest": "25.2.1",
     "@types/node": "10.17.13",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/api-extractor-lib2-test/package.json

@@ -13,6 +13,6 @@
     "@types/jest": "25.2.1",
     "@types/node": "10.17.13",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/api-extractor-lib3-test/package.json

@@ -16,6 +16,6 @@
     "@types/jest": "25.2.1",
     "@types/node": "10.17.13",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

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

@@ -19,6 +19,6 @@
     "api-extractor-lib3-test": "1.0.0",
     "colors": "~1.2.1",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/api-extractor-scenarios/src/runScenarios.ts

@@ -93,9 +93,15 @@ export function runScenarios(buildConfigPath: string): void {
       localBuild: true,
       showVerboseMessages: true,
       messageCallback: (message: ExtractorMessage) => {
-        if (message.messageId === ConsoleMessageId.ApiReportCreated) {
-          // This script deletes the outputs for a clean build, so don't issue a warning if the file gets created
-          message.logLevel = ExtractorLogLevel.None;
+        switch (message.messageId) {
+          case ConsoleMessageId.ApiReportCreated:
+            // This script deletes the outputs for a clean build, so don't issue a warning if the file gets created
+            message.logLevel = ExtractorLogLevel.None;
+            break;
+          case ConsoleMessageId.Preamble:
+            // Less verbose output
+            message.logLevel = ExtractorLogLevel.None;
+            break;
         }
       },
       compilerState

build-tests/api-extractor-test-01/package.json

@@ -17,6 +17,6 @@
     "@microsoft/api-extractor": "7.8.15",
     "@types/node": "10.17.13",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/api-extractor-test-02/package.json

@@ -17,6 +17,6 @@
     "@microsoft/api-extractor": "7.8.15",
     "@types/node": "10.17.13",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/api-extractor-test-03/package.json

@@ -11,6 +11,6 @@
     "@types/node": "10.17.13",
     "api-extractor-test-02": "1.0.0",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/api-extractor-test-04/package.json

@@ -12,6 +12,6 @@
     "@microsoft/api-extractor": "7.8.15",
     "api-extractor-lib1-test": "1.0.0",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

build-tests/ts-command-line-test/package.json

@@ -11,6 +11,6 @@
     "@rushstack/ts-command-line": "4.4.5",
     "@types/node": "10.17.13",
     "fs-extra": "~7.0.1",
-    "typescript": "~3.7.2"
+    "typescript": "~3.9.5"
   }
 }

common/changes/@microsoft/api-extractor/octogonz-upgrade-ae_2020-07-03-01-09.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Upgrade the bundled compiler engine to TypeScript 3.9",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "[email protected]"
+}

common/changes/@microsoft/api-extractor/octogonz-upgrade-ae_2020-07-03-01-11.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Log the TypeScript bundled compiler version, and warn if it is outdated",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "[email protected]"
+}

common/changes/@microsoft/rush-stack-compiler-2.4/octogonz-upgrade-ae_2020-07-03-03-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Disable the \"--typescript-compiler-folder\" setting for API Extractor, since it was causing errors with the latest TypeScript engine",
+      "type": "minor",
+      "packageName": "@microsoft/rush-stack-compiler-2.4"
+    }
+  ],
+  "packageName": "@microsoft/rush-stack-compiler-2.4",
+  "email": "[email protected]"
+}

common/changes/@microsoft/rush-stack-compiler-2.7/octogonz-upgrade-ae_2020-07-03-03-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Disable the \"--typescript-compiler-folder\" setting for API Extractor, since it was causing errors with the latest TypeScript engine",
+      "type": "minor",
+      "packageName": "@microsoft/rush-stack-compiler-2.7"
+    }
+  ],
+  "packageName": "@microsoft/rush-stack-compiler-2.7",
+  "email": "[email protected]"
+}

common/changes/@microsoft/rush-stack-compiler-2.8/octogonz-upgrade-ae_2020-07-03-03-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Disable the \"--typescript-compiler-folder\" setting for API Extractor, since it was causing errors with the latest TypeScript engine",
+      "type": "minor",
+      "packageName": "@microsoft/rush-stack-compiler-2.8"
+    }
+  ],
+  "packageName": "@microsoft/rush-stack-compiler-2.8",
+  "email": "[email protected]"
+}

common/changes/@microsoft/rush-stack-compiler-2.9/octogonz-upgrade-ae_2020-07-03-03-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Disable the \"--typescript-compiler-folder\" setting for API Extractor, since it was causing errors with the latest TypeScript engine",
+      "type": "minor",
+      "packageName": "@microsoft/rush-stack-compiler-2.9"
+    }
+  ],
+  "packageName": "@microsoft/rush-stack-compiler-2.9",
+  "email": "[email protected]"
+}

common/changes/@microsoft/rush-stack-compiler-3.0/octogonz-upgrade-ae_2020-07-03-03-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Disable the \"--typescript-compiler-folder\" setting for API Extractor, since it was causing errors with the latest TypeScript engine",
+      "type": "minor",
+      "packageName": "@microsoft/rush-stack-compiler-3.0"
+    }
+  ],
+  "packageName": "@microsoft/rush-stack-compiler-3.0",
+  "email": "[email protected]"
+}

common/changes/@microsoft/rush-stack-compiler-3.1/octogonz-upgrade-ae_2020-07-03-03-23.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Disable the \"--typescript-compiler-folder\" setting for API Extractor, since it was causing errors with the latest TypeScript engine",
+      "type": "minor",
+      "packageName": "@microsoft/rush-stack-compiler-3.1"
+    }
+  ],
+  "packageName": "@microsoft/rush-stack-compiler-3.1",
+  "email": "[email protected]"
+}