@microsoft/api-extractor 7.56.2 → 7.57.0

package/lib-esm/analyzer/SyntaxHelpers.js

@@ -0,0 +1,72 @@
+// 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';
+/**
+ * Helpers for validating various text string formats.
+ */
+export class SyntaxHelpers {
+    /**
+     * Tests whether the input string is safe to use as an ECMAScript identifier without quotes.
+     *
+     * @remarks
+     * For example:
+     *
+     * ```ts
+     * class X {
+     *   public okay: number = 1;
+     *   public "not okay!": number = 2;
+     * }
+     * ```
+     *
+     * A precise check is extremely complicated and highly dependent on the ECMAScript standard version
+     * and how faithfully the interpreter implements it.  To keep things simple, `isSafeUnquotedMemberIdentifier()`
+     * conservatively accepts any identifier that would be valid with ECMAScript 5, and returns false otherwise.
+     */
+    static isSafeUnquotedMemberIdentifier(identifier) {
+        if (identifier.length === 0) {
+            return false; // cannot be empty
+        }
+        if (!ts.isIdentifierStart(identifier.charCodeAt(0), ts.ScriptTarget.ES5)) {
+            return false;
+        }
+        for (let i = 1; i < identifier.length; i++) {
+            if (!ts.isIdentifierPart(identifier.charCodeAt(i), ts.ScriptTarget.ES5)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Given an arbitrary input string, return a regular TypeScript identifier name.
+     *
+     * @remarks
+     * Example input:  "api-extractor-lib1-test"
+     * Example output: "apiExtractorLib1Test"
+     */
+    static makeCamelCaseIdentifier(input) {
+        const parts = input.split(/\W+/).filter((x) => x.length > 0);
+        if (parts.length === 0) {
+            return '_';
+        }
+        for (let i = 0; i < parts.length; ++i) {
+            let part = parts[i];
+            if (part.toUpperCase() === part) {
+                // Preserve existing case unless the part is all upper-case
+                part = part.toLowerCase();
+            }
+            if (i === 0) {
+                // If the first part starts with a number, prepend "_"
+                if (/[0-9]/.test(part.charAt(0))) {
+                    part = '_' + part;
+                }
+            }
+            else {
+                // Capitalize the first letter of each part, except for the first one
+                part = part.charAt(0).toUpperCase() + part.slice(1);
+            }
+            parts[i] = part;
+        }
+        return parts.join('');
+    }
+}
+//# sourceMappingURL=SyntaxHelpers.js.map

package/lib-esm/analyzer/SyntaxHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyntaxHelpers.js","sourceRoot":"","sources":["../../src/analyzer/SyntaxHelpers.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB;;;;;;;;;;;;;;;;OAgBG;IACI,MAAM,CAAC,8BAA8B,CAAC,UAAkB;QAC7D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC,CAAC,kBAAkB;QAClC,CAAC;QAED,IAAI,CAAC,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;QAED,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnD,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxE,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,uBAAuB,CAAC,KAAa;QACjD,MAAM,KAAK,GAAa,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,GAAG,CAAC;QACb,CAAC;QAED,KAAK,IAAI,CAAC,GAAW,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;YAC9C,IAAI,IAAI,GAAW,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC;gBAChC,2DAA2D;gBAC3D,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC5B,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,sDAAsD;gBACtD,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACjC,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;gBACpB,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,qEAAqE;gBACrE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACtD,CAAC;YACD,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;CACF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as ts from 'typescript';\n\n/**\n * Helpers for validating various text string formats.\n */\nexport class SyntaxHelpers {\n  /**\n   * Tests whether the input string is safe to use as an ECMAScript identifier without quotes.\n   *\n   * @remarks\n   * For example:\n   *\n   * ```ts\n   * class X {\n   *   public okay: number = 1;\n   *   public \"not okay!\": number = 2;\n   * }\n   * ```\n   *\n   * A precise check is extremely complicated and highly dependent on the ECMAScript standard version\n   * and how faithfully the interpreter implements it.  To keep things simple, `isSafeUnquotedMemberIdentifier()`\n   * conservatively accepts any identifier that would be valid with ECMAScript 5, and returns false otherwise.\n   */\n  public static isSafeUnquotedMemberIdentifier(identifier: string): boolean {\n    if (identifier.length === 0) {\n      return false; // cannot be empty\n    }\n\n    if (!ts.isIdentifierStart(identifier.charCodeAt(0), ts.ScriptTarget.ES5)) {\n      return false;\n    }\n\n    for (let i: number = 1; i < identifier.length; i++) {\n      if (!ts.isIdentifierPart(identifier.charCodeAt(i), ts.ScriptTarget.ES5)) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  /**\n   * Given an arbitrary input string, return a regular TypeScript identifier name.\n   *\n   * @remarks\n   * Example input:  \"api-extractor-lib1-test\"\n   * Example output: \"apiExtractorLib1Test\"\n   */\n  public static makeCamelCaseIdentifier(input: string): string {\n    const parts: string[] = input.split(/\\W+/).filter((x) => x.length > 0);\n    if (parts.length === 0) {\n      return '_';\n    }\n\n    for (let i: number = 0; i < parts.length; ++i) {\n      let part: string = parts[i];\n      if (part.toUpperCase() === part) {\n        // Preserve existing case unless the part is all upper-case\n        part = part.toLowerCase();\n      }\n      if (i === 0) {\n        // If the first part starts with a number, prepend \"_\"\n        if (/[0-9]/.test(part.charAt(0))) {\n          part = '_' + part;\n        }\n      } else {\n        // Capitalize the first letter of each part, except for the first one\n        part = part.charAt(0).toUpperCase() + part.slice(1);\n      }\n      parts[i] = part;\n    }\n    return parts.join('');\n  }\n}\n"]}

package/lib-esm/analyzer/TypeScriptHelpers.js

@@ -0,0 +1,242 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/* eslint-disable no-bitwise */
+import * as ts from 'typescript';
+import { InternalError } from '@rushstack/node-core-library';
+import { SourceFileLocationFormatter } from './SourceFileLocationFormatter';
+import { TypeScriptInternals } from './TypeScriptInternals';
+export class TypeScriptHelpers {
+    /**
+     * This traverses any symbol aliases to find the original place where an item was defined.
+     * For example, suppose a class is defined as "export default class MyClass { }"
+     * but exported from the package's index.ts like this:
+     *
+     *    export { default as _MyClass } from './MyClass';
+     *
+     * In this example, calling followAliases() on the _MyClass symbol will return the
+     * original definition of MyClass, traversing any intermediary places where the
+     * symbol was imported and re-exported.
+     */
+    static followAliases(symbol, typeChecker) {
+        let current = symbol;
+        for (;;) {
+            if (!(current.flags & ts.SymbolFlags.Alias)) {
+                break;
+            }
+            const currentAlias = typeChecker.getAliasedSymbol(current);
+            if (!currentAlias || currentAlias === current) {
+                break;
+            }
+            current = currentAlias;
+        }
+        return current;
+    }
+    /**
+     * Returns true if TypeScriptHelpers.followAliases() would return something different
+     * from the input `symbol`.
+     */
+    static isFollowableAlias(symbol, typeChecker) {
+        if (!(symbol.flags & ts.SymbolFlags.Alias)) {
+            return false;
+        }
+        const alias = typeChecker.getAliasedSymbol(symbol);
+        if (!alias || alias === symbol) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Certain virtual symbols do not have any declarations.  For example, `ts.TypeChecker.getExportsOfModule()` can
+     * sometimes return a "prototype" symbol for an object, even though there is no corresponding declaration in the
+     * source code.  API Extractor generally ignores such symbols.
+     */
+    static tryGetADeclaration(symbol) {
+        if (symbol.declarations && symbol.declarations.length > 0) {
+            return symbol.declarations[0];
+        }
+        return undefined;
+    }
+    /**
+     * Returns true if the specified symbol is an ambient declaration.
+     */
+    static isAmbient(symbol, typeChecker) {
+        const followedSymbol = TypeScriptHelpers.followAliases(symbol, typeChecker);
+        if (followedSymbol.declarations && followedSymbol.declarations.length > 0) {
+            const firstDeclaration = followedSymbol.declarations[0];
+            // Test 1: Are we inside the sinister "declare global {" construct?
+            const highestModuleDeclaration = TypeScriptHelpers.findHighestParent(firstDeclaration, ts.SyntaxKind.ModuleDeclaration);
+            if (highestModuleDeclaration) {
+                if (highestModuleDeclaration.name.getText().trim() === 'global') {
+                    return true;
+                }
+            }
+            // Test 2: Otherwise, the main heuristic for ambient declarations is by looking at the
+            // ts.SyntaxKind.SourceFile node to see whether it has a symbol or not (i.e. whether it
+            // is acting as a module or not).
+            const sourceFile = firstDeclaration.getSourceFile();
+            if (typeChecker.getSymbolAtLocation(sourceFile)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Same semantics as tryGetSymbolForDeclaration(), but throws an exception if the symbol
+     * cannot be found.
+     */
+    static getSymbolForDeclaration(declaration, checker) {
+        const symbol = TypeScriptInternals.tryGetSymbolForDeclaration(declaration, checker);
+        if (!symbol) {
+            throw new InternalError('Unable to determine semantic information for declaration:\n' +
+                SourceFileLocationFormatter.formatDeclaration(declaration));
+        }
+        return symbol;
+    }
+    // Return name of the module, which could be like "./SomeLocalFile' or like 'external-package/entry/point'
+    static getModuleSpecifier(nodeWithModuleSpecifier) {
+        if (nodeWithModuleSpecifier.kind === ts.SyntaxKind.ImportType) {
+            // As specified internally in typescript:/src/compiler/types.ts#ValidImportTypeNode
+            if (nodeWithModuleSpecifier.argument.kind !== ts.SyntaxKind.LiteralType ||
+                nodeWithModuleSpecifier.argument.literal.kind !== ts.SyntaxKind.StringLiteral) {
+                throw new InternalError(`Invalid ImportTypeNode: ${nodeWithModuleSpecifier.getText()}\n` +
+                    SourceFileLocationFormatter.formatDeclaration(nodeWithModuleSpecifier));
+            }
+            const literalTypeNode = nodeWithModuleSpecifier.argument;
+            const stringLiteral = literalTypeNode.literal;
+            return stringLiteral.text.trim();
+        }
+        // Node is a declaration
+        if (nodeWithModuleSpecifier.moduleSpecifier &&
+            ts.isStringLiteralLike(nodeWithModuleSpecifier.moduleSpecifier)) {
+            return TypeScriptInternals.getTextOfIdentifierOrLiteral(nodeWithModuleSpecifier.moduleSpecifier);
+        }
+        return undefined;
+    }
+    /**
+     * Returns an ancestor of "node", such that the ancestor, any intermediary nodes,
+     * and the starting node match a list of expected kinds.  Undefined is returned
+     * if there aren't enough ancestors, or if the kinds are incorrect.
+     *
+     * For example, suppose child "C" has parents A --> B --> C.
+     *
+     * Calling _matchAncestor(C, [ExportSpecifier, NamedExports, ExportDeclaration])
+     * would return A only if A is of kind ExportSpecifier, B is of kind NamedExports,
+     * and C is of kind ExportDeclaration.
+     *
+     * Calling _matchAncestor(C, [ExportDeclaration]) would return C.
+     */
+    static matchAncestor(node, kindsToMatch) {
+        // (slice(0) clones an array)
+        const reversedParentKinds = kindsToMatch.slice(0).reverse();
+        let current = undefined;
+        for (const parentKind of reversedParentKinds) {
+            if (!current) {
+                // The first time through, start with node
+                current = node;
+            }
+            else {
+                // Then walk the parents
+                current = current.parent;
+            }
+            // If we ran out of items, or if the kind doesn't match, then fail
+            if (!current || current.kind !== parentKind) {
+                return undefined;
+            }
+        }
+        // If we matched everything, then return the node that matched the last parentKinds item
+        return current;
+    }
+    /**
+     * Does a depth-first search of the children of the specified node.  Returns the first child
+     * with the specified kind, or undefined if there is no match.
+     */
+    static findFirstChildNode(node, kindToMatch) {
+        for (const child of node.getChildren()) {
+            if (child.kind === kindToMatch) {
+                return child;
+            }
+            const recursiveMatch = TypeScriptHelpers.findFirstChildNode(child, kindToMatch);
+            if (recursiveMatch) {
+                return recursiveMatch;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns the first parent node with the specified  SyntaxKind, or undefined if there is no match.
+     */
+    static findFirstParent(node, kindToMatch) {
+        let current = node.parent;
+        while (current) {
+            if (current.kind === kindToMatch) {
+                return current;
+            }
+            current = current.parent;
+        }
+        return undefined;
+    }
+    /**
+     * Returns the highest parent node with the specified SyntaxKind, or undefined if there is no match.
+     * @remarks
+     * Whereas findFirstParent() returns the first match, findHighestParent() returns the last match.
+     */
+    static findHighestParent(node, kindToMatch) {
+        let current = node;
+        let highest = undefined;
+        for (;;) {
+            current = TypeScriptHelpers.findFirstParent(current, kindToMatch);
+            if (!current) {
+                break;
+            }
+            highest = current;
+        }
+        return highest;
+    }
+    /**
+     * Decodes the names that the compiler generates for a built-in ECMAScript symbol.
+     *
+     * @remarks
+     * TypeScript binds well-known ECMAScript symbols like `[Symbol.iterator]` as `__@iterator`.
+     * If `name` is of this form, then `tryGetWellKnownSymbolName()` converts it back into e.g. `[Symbol.iterator]`.
+     * If the string does not start with `__@` then `undefined` is returned.
+     */
+    static tryDecodeWellKnownSymbolName(name) {
+        const match = TypeScriptHelpers._wellKnownSymbolNameRegExp.exec(name);
+        if (match) {
+            const identifier = match[1];
+            return `[Symbol.${identifier}]`;
+        }
+        return undefined;
+    }
+    /**
+     * Returns whether the provided name was generated for a TypeScript `unique symbol`.
+     */
+    static isUniqueSymbolName(name) {
+        return TypeScriptHelpers._uniqueSymbolNameRegExp.test(name);
+    }
+    /**
+     * Derives the string representation of a TypeScript late-bound symbol.
+     */
+    static tryGetLateBoundName(declarationName) {
+        // Create a node printer that ignores comments and indentation that we can use to convert
+        // declarationName to a string.
+        const printer = ts.createPrinter({ removeComments: true }, {
+            onEmitNode(hint, node, emitCallback) {
+                ts.setEmitFlags(declarationName, ts.EmitFlags.NoIndentation | ts.EmitFlags.SingleLine);
+                emitCallback(hint, node);
+            }
+        });
+        const sourceFile = declarationName.getSourceFile();
+        const text = printer.printNode(ts.EmitHint.Unspecified, declarationName, sourceFile);
+        // clean up any emit flags we've set on any nodes in the tree.
+        ts.disposeEmitNodes(sourceFile);
+        return text;
+    }
+}
+// Matches TypeScript's encoded names for well-known ECMAScript symbols like
+// "__@iterator" or "__@toStringTag".
+TypeScriptHelpers._wellKnownSymbolNameRegExp = /^__@(\w+)$/;
+// Matches TypeScript's encoded names for late-bound symbols derived from `unique symbol` declarations
+// which have the form of "__@<variableName>@<symbolId>", i.e. "__@someSymbol@12345".
+TypeScriptHelpers._uniqueSymbolNameRegExp = /^__@.*@\d+$/;
+//# sourceMappingURL=TypeScriptHelpers.js.map

package/lib-esm/analyzer/TypeScriptHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeScriptHelpers.js","sourceRoot":"","sources":["../../src/analyzer/TypeScriptHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/* eslint-disable no-bitwise */\n\nimport * as ts from 'typescript';\n\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport { SourceFileLocationFormatter } from './SourceFileLocationFormatter';\nimport { TypeScriptInternals } from './TypeScriptInternals';\n\nexport class TypeScriptHelpers {\n  // Matches TypeScript's encoded names for well-known ECMAScript symbols like\n  // \"__@iterator\" or \"__@toStringTag\".\n  private static readonly _wellKnownSymbolNameRegExp: RegExp = /^__@(\\w+)$/;\n\n  // Matches TypeScript's encoded names for late-bound symbols derived from `unique symbol` declarations\n  // which have the form of \"__@<variableName>@<symbolId>\", i.e. \"__@someSymbol@12345\".\n  private static readonly _uniqueSymbolNameRegExp: RegExp = /^__@.*@\\d+$/;\n\n  /**\n   * This traverses any symbol aliases to find the original place where an item was defined.\n   * For example, suppose a class is defined as \"export default class MyClass { }\"\n   * but exported from the package's index.ts like this:\n   *\n   *    export { default as _MyClass } from './MyClass';\n   *\n   * In this example, calling followAliases() on the _MyClass symbol will return the\n   * original definition of MyClass, traversing any intermediary places where the\n   * symbol was imported and re-exported.\n   */\n  public static followAliases(symbol: ts.Symbol, typeChecker: ts.TypeChecker): ts.Symbol {\n    let current: ts.Symbol = symbol;\n    for (;;) {\n      if (!(current.flags & ts.SymbolFlags.Alias)) {\n        break;\n      }\n      const currentAlias: ts.Symbol = typeChecker.getAliasedSymbol(current);\n      if (!currentAlias || currentAlias === current) {\n        break;\n      }\n      current = currentAlias;\n    }\n\n    return current;\n  }\n\n  /**\n   * Returns true if TypeScriptHelpers.followAliases() would return something different\n   * from the input `symbol`.\n   */\n  public static isFollowableAlias(symbol: ts.Symbol, typeChecker: ts.TypeChecker): boolean {\n    if (!(symbol.flags & ts.SymbolFlags.Alias)) {\n      return false;\n    }\n\n    const alias: ts.Symbol = typeChecker.getAliasedSymbol(symbol);\n    if (!alias || alias === symbol) {\n      return false;\n    }\n\n    return true;\n  }\n\n  /**\n   * Certain virtual symbols do not have any declarations.  For example, `ts.TypeChecker.getExportsOfModule()` can\n   * sometimes return a \"prototype\" symbol for an object, even though there is no corresponding declaration in the\n   * source code.  API Extractor generally ignores such symbols.\n   */\n  public static tryGetADeclaration(symbol: ts.Symbol): ts.Declaration | undefined {\n    if (symbol.declarations && symbol.declarations.length > 0) {\n      return symbol.declarations[0];\n    }\n    return undefined;\n  }\n\n  /**\n   * Returns true if the specified symbol is an ambient declaration.\n   */\n  public static isAmbient(symbol: ts.Symbol, typeChecker: ts.TypeChecker): boolean {\n    const followedSymbol: ts.Symbol = TypeScriptHelpers.followAliases(symbol, typeChecker);\n\n    if (followedSymbol.declarations && followedSymbol.declarations.length > 0) {\n      const firstDeclaration: ts.Declaration = followedSymbol.declarations[0];\n\n      // Test 1: Are we inside the sinister \"declare global {\" construct?\n      const highestModuleDeclaration: ts.ModuleDeclaration | undefined = TypeScriptHelpers.findHighestParent(\n        firstDeclaration,\n        ts.SyntaxKind.ModuleDeclaration\n      );\n      if (highestModuleDeclaration) {\n        if (highestModuleDeclaration.name.getText().trim() === 'global') {\n          return true;\n        }\n      }\n\n      // Test 2: Otherwise, the main heuristic for ambient declarations is by looking at the\n      // ts.SyntaxKind.SourceFile node to see whether it has a symbol or not (i.e. whether it\n      // is acting as a module or not).\n      const sourceFile: ts.SourceFile = firstDeclaration.getSourceFile();\n\n      if (typeChecker.getSymbolAtLocation(sourceFile)) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  /**\n   * Same semantics as tryGetSymbolForDeclaration(), but throws an exception if the symbol\n   * cannot be found.\n   */\n  public static getSymbolForDeclaration(declaration: ts.Declaration, checker: ts.TypeChecker): ts.Symbol {\n    const symbol: ts.Symbol | undefined = TypeScriptInternals.tryGetSymbolForDeclaration(\n      declaration,\n      checker\n    );\n    if (!symbol) {\n      throw new InternalError(\n        'Unable to determine semantic information for declaration:\\n' +\n          SourceFileLocationFormatter.formatDeclaration(declaration)\n      );\n    }\n    return symbol;\n  }\n\n  // Return name of the module, which could be like \"./SomeLocalFile' or like 'external-package/entry/point'\n  public static getModuleSpecifier(\n    nodeWithModuleSpecifier: ts.ImportDeclaration | ts.ExportDeclaration | ts.ImportTypeNode\n  ): string | undefined {\n    if (nodeWithModuleSpecifier.kind === ts.SyntaxKind.ImportType) {\n      // As specified internally in typescript:/src/compiler/types.ts#ValidImportTypeNode\n      if (\n        nodeWithModuleSpecifier.argument.kind !== ts.SyntaxKind.LiteralType ||\n        (nodeWithModuleSpecifier.argument as ts.LiteralTypeNode).literal.kind !== ts.SyntaxKind.StringLiteral\n      ) {\n        throw new InternalError(\n          `Invalid ImportTypeNode: ${nodeWithModuleSpecifier.getText()}\\n` +\n            SourceFileLocationFormatter.formatDeclaration(nodeWithModuleSpecifier)\n        );\n      }\n      const literalTypeNode: ts.LiteralTypeNode = nodeWithModuleSpecifier.argument as ts.LiteralTypeNode;\n      const stringLiteral: ts.StringLiteral = literalTypeNode.literal as ts.StringLiteral;\n      return stringLiteral.text.trim();\n    }\n\n    // Node is a declaration\n    if (\n      nodeWithModuleSpecifier.moduleSpecifier &&\n      ts.isStringLiteralLike(nodeWithModuleSpecifier.moduleSpecifier)\n    ) {\n      return TypeScriptInternals.getTextOfIdentifierOrLiteral(nodeWithModuleSpecifier.moduleSpecifier);\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Returns an ancestor of \"node\", such that the ancestor, any intermediary nodes,\n   * and the starting node match a list of expected kinds.  Undefined is returned\n   * if there aren't enough ancestors, or if the kinds are incorrect.\n   *\n   * For example, suppose child \"C\" has parents A --> B --> C.\n   *\n   * Calling _matchAncestor(C, [ExportSpecifier, NamedExports, ExportDeclaration])\n   * would return A only if A is of kind ExportSpecifier, B is of kind NamedExports,\n   * and C is of kind ExportDeclaration.\n   *\n   * Calling _matchAncestor(C, [ExportDeclaration]) would return C.\n   */\n  public static matchAncestor<T extends ts.Node>(\n    node: ts.Node,\n    kindsToMatch: ts.SyntaxKind[]\n  ): T | undefined {\n    // (slice(0) clones an array)\n    const reversedParentKinds: ts.SyntaxKind[] = kindsToMatch.slice(0).reverse();\n\n    let current: ts.Node | undefined = undefined;\n\n    for (const parentKind of reversedParentKinds) {\n      if (!current) {\n        // The first time through, start with node\n        current = node;\n      } else {\n        // Then walk the parents\n        current = current.parent;\n      }\n\n      // If we ran out of items, or if the kind doesn't match, then fail\n      if (!current || current.kind !== parentKind) {\n        return undefined;\n      }\n    }\n\n    // If we matched everything, then return the node that matched the last parentKinds item\n    return current as T;\n  }\n\n  /**\n   * Does a depth-first search of the children of the specified node.  Returns the first child\n   * with the specified kind, or undefined if there is no match.\n   */\n  public static findFirstChildNode<T extends ts.Node>(\n    node: ts.Node,\n    kindToMatch: ts.SyntaxKind\n  ): T | undefined {\n    for (const child of node.getChildren()) {\n      if (child.kind === kindToMatch) {\n        return child as T;\n      }\n\n      const recursiveMatch: T | undefined = TypeScriptHelpers.findFirstChildNode(child, kindToMatch);\n      if (recursiveMatch) {\n        return recursiveMatch;\n      }\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Returns the first parent node with the specified  SyntaxKind, or undefined if there is no match.\n   */\n  public static findFirstParent<T extends ts.Node>(node: ts.Node, kindToMatch: ts.SyntaxKind): T | undefined {\n    let current: ts.Node | undefined = node.parent;\n\n    while (current) {\n      if (current.kind === kindToMatch) {\n        return current as T;\n      }\n      current = current.parent;\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Returns the highest parent node with the specified SyntaxKind, or undefined if there is no match.\n   * @remarks\n   * Whereas findFirstParent() returns the first match, findHighestParent() returns the last match.\n   */\n  public static findHighestParent<T extends ts.Node>(\n    node: ts.Node,\n    kindToMatch: ts.SyntaxKind\n  ): T | undefined {\n    let current: ts.Node | undefined = node;\n    let highest: T | undefined = undefined;\n\n    for (;;) {\n      current = TypeScriptHelpers.findFirstParent<T>(current, kindToMatch);\n      if (!current) {\n        break;\n      }\n      highest = current as T;\n    }\n\n    return highest;\n  }\n\n  /**\n   * Decodes the names that the compiler generates for a built-in ECMAScript symbol.\n   *\n   * @remarks\n   * TypeScript binds well-known ECMAScript symbols like `[Symbol.iterator]` as `__@iterator`.\n   * If `name` is of this form, then `tryGetWellKnownSymbolName()` converts it back into e.g. `[Symbol.iterator]`.\n   * If the string does not start with `__@` then `undefined` is returned.\n   */\n  public static tryDecodeWellKnownSymbolName(name: ts.__String): string | undefined {\n    const match: RegExpExecArray | null = TypeScriptHelpers._wellKnownSymbolNameRegExp.exec(name as string);\n    if (match) {\n      const identifier: string = match[1];\n      return `[Symbol.${identifier}]`;\n    }\n    return undefined;\n  }\n\n  /**\n   * Returns whether the provided name was generated for a TypeScript `unique symbol`.\n   */\n  public static isUniqueSymbolName(name: ts.__String): boolean {\n    return TypeScriptHelpers._uniqueSymbolNameRegExp.test(name as string);\n  }\n\n  /**\n   * Derives the string representation of a TypeScript late-bound symbol.\n   */\n  public static tryGetLateBoundName(declarationName: ts.ComputedPropertyName): string | undefined {\n    // Create a node printer that ignores comments and indentation that we can use to convert\n    // declarationName to a string.\n    const printer: ts.Printer = ts.createPrinter(\n      { removeComments: true },\n      {\n        onEmitNode(\n          hint: ts.EmitHint,\n          node: ts.Node,\n          emitCallback: (hint: ts.EmitHint, node: ts.Node) => void\n        ): void {\n          ts.setEmitFlags(declarationName, ts.EmitFlags.NoIndentation | ts.EmitFlags.SingleLine);\n          emitCallback(hint, node);\n        }\n      }\n    );\n    const sourceFile: ts.SourceFile = declarationName.getSourceFile();\n    const text: string = printer.printNode(ts.EmitHint.Unspecified, declarationName, sourceFile);\n    // clean up any emit flags we've set on any nodes in the tree.\n    ts.disposeEmitNodes(sourceFile);\n    return text;\n  }\n}\n"]}

package/lib-esm/analyzer/TypeScriptInternals.js

@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as ts from 'typescript';
+import { InternalError } from '@rushstack/node-core-library';
+export class TypeScriptInternals {
+    static getImmediateAliasedSymbol(symbol, typeChecker) {
+        // Compiler internal:
+        // https://github.com/microsoft/TypeScript/blob/v3.2.2/src/compiler/checker.ts
+        return typeChecker.getImmediateAliasedSymbol(symbol);
+    }
+    /**
+     * Returns the Symbol for the provided Declaration.  This is a workaround for a missing
+     * feature of the TypeScript Compiler API.   It is the only apparent way to reach
+     * certain data structures, and seems to always work, but is not officially documented.
+     *
+     * @returns The associated Symbol.  If there is no semantic information (e.g. if the
+     * declaration is an extra semicolon somewhere), then "undefined" is returned.
+     */
+    static tryGetSymbolForDeclaration(declaration, checker) {
+        let symbol = declaration.symbol;
+        if (symbol && symbol.escapedName === ts.InternalSymbolName.Computed) {
+            const name = ts.getNameOfDeclaration(declaration);
+            symbol = (name && checker.getSymbolAtLocation(name)) || symbol;
+        }
+        return symbol;
+    }
+    /**
+     * Returns whether the provided Symbol is a TypeScript "late-bound" Symbol (i.e. was created by the Checker
+     * for a computed property based on its type, rather than by the Binder).
+     */
+    static isLateBoundSymbol(symbol) {
+        if (
+        // eslint-disable-next-line no-bitwise
+        symbol.flags & ts.SymbolFlags.Transient &&
+            ts.getCheckFlags(symbol) === ts.CheckFlags.Late) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Retrieves the comment ranges associated with the specified node.
+     */
+    static getJSDocCommentRanges(node, text) {
+        // Compiler internal:
+        // https://github.com/microsoft/TypeScript/blob/v2.4.2/src/compiler/utilities.ts#L616
+        return ts.getJSDocCommentRanges.apply(this, arguments);
+    }
+    /**
+     * Retrieves the (unescaped) value of an string literal, numeric literal, or identifier.
+     */
+    static getTextOfIdentifierOrLiteral(node) {
+        // Compiler internal:
+        // https://github.com/microsoft/TypeScript/blob/v3.2.2/src/compiler/utilities.ts#L2721
+        return ts.getTextOfIdentifierOrLiteral(node);
+    }
+    /**
+     * Retrieves the (cached) module resolution information for a module name that was exported from a SourceFile.
+     * The compiler populates this cache as part of analyzing the source file.
+     */
+    static getResolvedModule(program, sourceFile, moduleNameText, mode) {
+        // Compiler internal:
+        // https://github.com/microsoft/TypeScript/blob/v5.3.3/src/compiler/types.ts#L4698
+        const result = program.getResolvedModule(sourceFile, moduleNameText, mode);
+        return result === null || result === void 0 ? void 0 : result.resolvedModule;
+    }
+    /**
+     * Gets the mode required for module resolution required with the addition of Node16/nodenext
+     */
+    static getModeForUsageLocation(file, usage, compilerOptions) {
+        // Compiler internal:
+        // https://github.com/microsoft/TypeScript/blob/v5.8.2/src/compiler/program.ts#L931
+        var _a;
+        return (_a = ts.getModeForUsageLocation) === null || _a === void 0 ? void 0 : _a.call(ts, file, usage, compilerOptions);
+    }
+    /**
+     * Returns ts.Symbol.parent if it exists.
+     */
+    static getSymbolParent(symbol) {
+        return symbol.parent;
+    }
+    /**
+     * In an statement like `export default class X { }`, the `Symbol.name` will be `default`
+     * whereas the `localSymbol` is `X`.
+     */
+    static tryGetLocalSymbol(declaration) {
+        return declaration.localSymbol;
+    }
+    static getGlobalVariableAnalyzer(program) {
+        var _a;
+        const anyProgram = program;
+        const typeCheckerInstance = (_a = anyProgram.getDiagnosticsProducingTypeChecker) !== null && _a !== void 0 ? _a : anyProgram.getTypeChecker;
+        if (!typeCheckerInstance) {
+            throw new InternalError('Missing Program.getDiagnosticsProducingTypeChecker or Program.getTypeChecker');
+        }
+        const typeChecker = typeCheckerInstance();
+        if (!typeChecker.getEmitResolver) {
+            throw new InternalError('Missing TypeChecker.getEmitResolver');
+        }
+        const resolver = typeChecker.getEmitResolver();
+        if (!resolver.hasGlobalName) {
+            throw new InternalError('Missing EmitResolver.hasGlobalName');
+        }
+        return resolver;
+    }
+    /**
+     * Returns whether a variable is declared with the const keyword
+     */
+    static isVarConst(node) {
+        // Compiler internal: https://github.com/microsoft/TypeScript/blob/71286e3d49c10e0e99faac360a6bbd40f12db7b6/src/compiler/utilities.ts#L925
+        return ts.isVarConst(node);
+    }
+}
+//# sourceMappingURL=TypeScriptInternals.js.map

package/lib-esm/analyzer/TypeScriptInternals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeScriptInternals.js","sourceRoot":"","sources":["../../src/analyzer/TypeScriptInternals.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\nimport * as ts from 'typescript';\n\nimport { InternalError } from '@rushstack/node-core-library';\n\n/**\n * Exposes the TypeScript compiler internals for detecting global variable names.\n */\nexport interface IGlobalVariableAnalyzer {\n  hasGlobalName(name: string): boolean;\n}\n\nexport class TypeScriptInternals {\n  public static getImmediateAliasedSymbol(symbol: ts.Symbol, typeChecker: ts.TypeChecker): ts.Symbol {\n    // Compiler internal:\n    // https://github.com/microsoft/TypeScript/blob/v3.2.2/src/compiler/checker.ts\n    return (typeChecker as any).getImmediateAliasedSymbol(symbol);\n  }\n\n  /**\n   * Returns the Symbol for the provided Declaration.  This is a workaround for a missing\n   * feature of the TypeScript Compiler API.   It is the only apparent way to reach\n   * certain data structures, and seems to always work, but is not officially documented.\n   *\n   * @returns The associated Symbol.  If there is no semantic information (e.g. if the\n   * declaration is an extra semicolon somewhere), then \"undefined\" is returned.\n   */\n  public static tryGetSymbolForDeclaration(\n    declaration: ts.Declaration,\n    checker: ts.TypeChecker\n  ): ts.Symbol | undefined {\n    let symbol: ts.Symbol | undefined = (declaration as any).symbol;\n    if (symbol && symbol.escapedName === ts.InternalSymbolName.Computed) {\n      const name: ts.DeclarationName | undefined = ts.getNameOfDeclaration(declaration);\n      symbol = (name && checker.getSymbolAtLocation(name)) || symbol;\n    }\n    return symbol;\n  }\n\n  /**\n   * Returns whether the provided Symbol is a TypeScript \"late-bound\" Symbol (i.e. was created by the Checker\n   * for a computed property based on its type, rather than by the Binder).\n   */\n  public static isLateBoundSymbol(symbol: ts.Symbol): boolean {\n    if (\n      // eslint-disable-next-line no-bitwise\n      symbol.flags & ts.SymbolFlags.Transient &&\n      (ts as any).getCheckFlags(symbol) === (ts as any).CheckFlags.Late\n    ) {\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Retrieves the comment ranges associated with the specified node.\n   */\n  public static getJSDocCommentRanges(node: ts.Node, text: string): ts.CommentRange[] | undefined {\n    // Compiler internal:\n    // https://github.com/microsoft/TypeScript/blob/v2.4.2/src/compiler/utilities.ts#L616\n\n    return (ts as any).getJSDocCommentRanges.apply(this, arguments);\n  }\n\n  /**\n   * Retrieves the (unescaped) value of an string literal, numeric literal, or identifier.\n   */\n  public static getTextOfIdentifierOrLiteral(\n    node: ts.Identifier | ts.StringLiteralLike | ts.NumericLiteral\n  ): string {\n    // Compiler internal:\n    // https://github.com/microsoft/TypeScript/blob/v3.2.2/src/compiler/utilities.ts#L2721\n\n    return (ts as any).getTextOfIdentifierOrLiteral(node);\n  }\n\n  /**\n   * Retrieves the (cached) module resolution information for a module name that was exported from a SourceFile.\n   * The compiler populates this cache as part of analyzing the source file.\n   */\n  public static getResolvedModule(\n    program: ts.Program,\n    sourceFile: ts.SourceFile,\n    moduleNameText: string,\n    mode: ts.ModuleKind.CommonJS | ts.ModuleKind.ESNext | undefined\n  ): ts.ResolvedModuleFull | undefined {\n    // Compiler internal:\n    // https://github.com/microsoft/TypeScript/blob/v5.3.3/src/compiler/types.ts#L4698\n    const result: ts.ResolvedModuleWithFailedLookupLocations | undefined = (program as any).getResolvedModule(\n      sourceFile,\n      moduleNameText,\n      mode\n    );\n    return result?.resolvedModule;\n  }\n\n  /**\n   * Gets the mode required for module resolution required with the addition of Node16/nodenext\n   */\n  public static getModeForUsageLocation(\n    file: ts.SourceFile,\n    usage: ts.StringLiteralLike,\n    compilerOptions: ts.CompilerOptions\n  ): ts.ModuleKind.CommonJS | ts.ModuleKind.ESNext | undefined {\n    // Compiler internal:\n    // https://github.com/microsoft/TypeScript/blob/v5.8.2/src/compiler/program.ts#L931\n\n    return ts.getModeForUsageLocation?.(file, usage, compilerOptions);\n  }\n\n  /**\n   * Returns ts.Symbol.parent if it exists.\n   */\n  public static getSymbolParent(symbol: ts.Symbol): ts.Symbol | undefined {\n    return (symbol as any).parent;\n  }\n\n  /**\n   * In an statement like `export default class X { }`, the `Symbol.name` will be `default`\n   * whereas the `localSymbol` is `X`.\n   */\n  public static tryGetLocalSymbol(declaration: ts.Declaration): ts.Symbol | undefined {\n    return (declaration as any).localSymbol;\n  }\n\n  public static getGlobalVariableAnalyzer(program: ts.Program): IGlobalVariableAnalyzer {\n    const anyProgram: any = program;\n    const typeCheckerInstance: any =\n      anyProgram.getDiagnosticsProducingTypeChecker ?? anyProgram.getTypeChecker;\n\n    if (!typeCheckerInstance) {\n      throw new InternalError('Missing Program.getDiagnosticsProducingTypeChecker or Program.getTypeChecker');\n    }\n    const typeChecker: any = typeCheckerInstance();\n    if (!typeChecker.getEmitResolver) {\n      throw new InternalError('Missing TypeChecker.getEmitResolver');\n    }\n    const resolver: any = typeChecker.getEmitResolver();\n    if (!resolver.hasGlobalName) {\n      throw new InternalError('Missing EmitResolver.hasGlobalName');\n    }\n    return resolver;\n  }\n\n  /**\n   * Returns whether a variable is declared with the const keyword\n   */\n  public static isVarConst(node: ts.VariableDeclaration | ts.VariableDeclarationList): boolean {\n    // Compiler internal: https://github.com/microsoft/TypeScript/blob/71286e3d49c10e0e99faac360a6bbd40f12db7b6/src/compiler/utilities.ts#L925\n    return (ts as any).isVarConst(node);\n  }\n}\n"]}

package/lib-esm/api/CompilerState.js

@@ -0,0 +1,149 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as path from 'node:path';
+import * as ts from 'typescript';
+import { JsonFile } from '@rushstack/node-core-library';
+import { Colorize } from '@rushstack/terminal';
+import { ExtractorConfig } from './ExtractorConfig';
+/**
+ * This class represents the TypeScript compiler state.  This allows an optimization where multiple invocations
+ * of API Extractor can reuse the same TypeScript compiler analysis.
+ *
+ * @public
+ */
+export class CompilerState {
+    constructor(properties) {
+        this.program = properties.program;
+    }
+    /**
+     * Create a compiler state for use with the specified `IExtractorInvokeOptions`.
+     */
+    static create(extractorConfig, options) {
+        let tsconfig = extractorConfig.overrideTsconfig;
+        let configBasePath = extractorConfig.projectFolder;
+        if (!tsconfig) {
+            // If it wasn't overridden, then load it from disk
+            tsconfig = JsonFile.load(extractorConfig.tsconfigFilePath);
+            configBasePath = path.resolve(path.dirname(extractorConfig.tsconfigFilePath));
+        }
+        const commandLine = ts.parseJsonConfigFileContent(tsconfig, ts.sys, configBasePath);
+        if (!commandLine.options.skipLibCheck && extractorConfig.skipLibCheck) {
+            commandLine.options.skipLibCheck = true;
+            console.log(Colorize.cyan('API Extractor was invoked with skipLibCheck. This is not recommended and may cause ' +
+                'incorrect type analysis.'));
+        }
+        // Delete outDir and declarationDir to prevent TypeScript from redirecting self-package
+        // imports to source files. When these options are set, TypeScript's module resolution
+        // tries to map output .d.ts files back to their source .ts files to avoid analyzing
+        // build outputs during compilation. However, API Extractor specifically wants to analyze
+        // the .d.ts build artifacts, not the source files. Since API Extractor doesn't emit any
+        // files, these options are unnecessary and interfere with correct module resolution.
+        delete commandLine.options.outDir;
+        delete commandLine.options.declarationDir;
+        const inputFilePaths = commandLine.fileNames.concat(extractorConfig.mainEntryPointFilePath);
+        if (options && options.additionalEntryPoints) {
+            inputFilePaths.push(...options.additionalEntryPoints);
+        }
+        // Append the entry points and remove any non-declaration files from the list
+        const analysisFilePaths = CompilerState._generateFilePathsForAnalysis(inputFilePaths);
+        const compilerHost = CompilerState._createCompilerHost(commandLine, options);
+        const program = ts.createProgram(analysisFilePaths, commandLine.options, compilerHost);
+        if (commandLine.errors.length > 0) {
+            const errorText = ts.flattenDiagnosticMessageText(commandLine.errors[0].messageText, '\n');
+            throw new Error(`Error parsing tsconfig.json content: ${errorText}`);
+        }
+        return new CompilerState({
+            program
+        });
+    }
+    /**
+     * Given a list of absolute file paths, return a list containing only the declaration
+     * files.  Duplicates are also eliminated.
+     *
+     * @remarks
+     * The tsconfig.json settings specify the compiler's input (a set of *.ts source files,
+     * plus some *.d.ts declaration files used for legacy typings).  However API Extractor
+     * analyzes the compiler's output (a set of *.d.ts entry point files, plus any legacy
+     * typings).  This requires API Extractor to generate a special file list when it invokes
+     * the compiler.
+     *
+     * Duplicates are removed so that entry points can be appended without worrying whether they
+     * may already appear in the tsconfig.json file list.
+     */
+    static _generateFilePathsForAnalysis(inputFilePaths) {
+        const analysisFilePaths = [];
+        const seenFiles = new Set();
+        for (const inputFilePath of inputFilePaths) {
+            const inputFileToUpper = inputFilePath.toUpperCase();
+            if (!seenFiles.has(inputFileToUpper)) {
+                seenFiles.add(inputFileToUpper);
+                if (!path.isAbsolute(inputFilePath)) {
+                    throw new Error('Input file is not an absolute path: ' + inputFilePath);
+                }
+                if (ExtractorConfig.hasDtsFileExtension(inputFilePath)) {
+                    analysisFilePaths.push(inputFilePath);
+                }
+            }
+        }
+        return analysisFilePaths;
+    }
+    static _createCompilerHost(commandLine, options) {
+        // Create a default CompilerHost that we will override
+        const compilerHost = ts.createCompilerHost(commandLine.options);
+        // Save a copy of the original members.  Note that "compilerHost" cannot be the copy, because
+        // createCompilerHost() captures that instance in a closure that is used by the members.
+        const defaultCompilerHost = { ...compilerHost };
+        if (options && options.typescriptCompilerFolder) {
+            // Prevent a closure parameter
+            const typescriptCompilerLibFolder = path.join(options.typescriptCompilerFolder, 'lib');
+            compilerHost.getDefaultLibLocation = () => typescriptCompilerLibFolder;
+        }
+        // Used by compilerHost.fileExists()
+        // .d.ts file path --> whether the file exists
+        const dtsExistsCache = new Map();
+        // Used by compilerHost.fileExists()
+        // Example: "c:/folder/file.part.ts"
+        const fileExtensionRegExp = /^(.+)(\.[a-z0-9_]+)$/i;
+        compilerHost.fileExists = (fileName) => {
+            // In certain deprecated setups, the compiler may write its output files (.js and .d.ts)
+            // in the same folder as the corresponding input file (.ts or .tsx).  When following imports,
+            // API Extractor wants to analyze the .d.ts file; however recent versions of the compiler engine
+            // will instead choose the .ts file.  To work around this, we hook fileExists() to hide the
+            // existence of those files.
+            // Is "fileName" a .d.ts file?  The double extension ".d.ts" needs to be matched specially.
+            if (!ExtractorConfig.hasDtsFileExtension(fileName)) {
+                // It's not a .d.ts file.  Is the file extension a potential source file?
+                const match = fileExtensionRegExp.exec(fileName);
+                if (match) {
+                    // Example: "c:/folder/file.part"
+                    const pathWithoutExtension = match[1];
+                    // Example: ".ts"
+                    const fileExtension = match[2];
+                    switch (fileExtension.toLocaleLowerCase()) {
+                        case '.ts':
+                        case '.tsx':
+                        case '.js':
+                        case '.jsx':
+                            // Yes, this is a possible source file.  Is there a corresponding .d.ts file in the same folder?
+                            const dtsFileName = `${pathWithoutExtension}.d.ts`;
+                            let dtsFileExists = dtsExistsCache.get(dtsFileName);
+                            if (dtsFileExists === undefined) {
+                                dtsFileExists = defaultCompilerHost.fileExists(dtsFileName);
+                                dtsExistsCache.set(dtsFileName, dtsFileExists);
+                            }
+                            if (dtsFileExists) {
+                                // fileName is a potential source file and a corresponding .d.ts file exists.
+                                // Thus, API Extractor should ignore this file (so the .d.ts file will get analyzed instead).
+                                return false;
+                            }
+                            break;
+                    }
+                }
+            }
+            // Fall through to the default implementation
+            return defaultCompilerHost.fileExists(fileName);
+        };
+        return compilerHost;
+    }
+}
+//# sourceMappingURL=CompilerState.js.map