@microsoft/api-extractor 7.56.2 → 7.57.0

package/lib-esm/generators/DeclarationReferenceGenerator.js

@@ -0,0 +1,292 @@
+// 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 { DeclarationReference, ModuleSource, GlobalSource, Navigation, Meaning } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
+import { InternalError } from '@rushstack/node-core-library';
+import { TypeScriptHelpers } from '../analyzer/TypeScriptHelpers';
+import { TypeScriptInternals } from '../analyzer/TypeScriptInternals';
+import { AstNamespaceImport } from '../analyzer/AstNamespaceImport';
+export class DeclarationReferenceGenerator {
+    constructor(collector) {
+        this._collector = collector;
+    }
+    /**
+     * Gets the UID for a TypeScript Identifier that references a type.
+     */
+    getDeclarationReferenceForIdentifier(node) {
+        const symbol = this._collector.typeChecker.getSymbolAtLocation(node);
+        if (symbol !== undefined) {
+            const isExpression = DeclarationReferenceGenerator._isInExpressionContext(node);
+            return (this.getDeclarationReferenceForSymbol(symbol, isExpression ? ts.SymbolFlags.Value : ts.SymbolFlags.Type) ||
+                this.getDeclarationReferenceForSymbol(symbol, isExpression ? ts.SymbolFlags.Type : ts.SymbolFlags.Value) ||
+                this.getDeclarationReferenceForSymbol(symbol, ts.SymbolFlags.Namespace));
+        }
+    }
+    /**
+     * Gets the DeclarationReference for a TypeScript Symbol for a given meaning.
+     */
+    getDeclarationReferenceForSymbol(symbol, meaning) {
+        return this._symbolToDeclarationReference(symbol, meaning, /*includeModuleSymbols*/ false);
+    }
+    static _isInExpressionContext(node) {
+        switch (node.parent.kind) {
+            case ts.SyntaxKind.TypeQuery:
+            case ts.SyntaxKind.ComputedPropertyName:
+                return true;
+            case ts.SyntaxKind.QualifiedName:
+                return DeclarationReferenceGenerator._isInExpressionContext(node.parent);
+            default:
+                return false;
+        }
+    }
+    static _isExternalModuleSymbol(symbol) {
+        return (!!(symbol.flags & ts.SymbolFlags.ValueModule) &&
+            symbol.valueDeclaration !== undefined &&
+            ts.isSourceFile(symbol.valueDeclaration));
+    }
+    static _isSameSymbol(left, right) {
+        return (left === right ||
+            !!(left &&
+                left.valueDeclaration &&
+                right.valueDeclaration &&
+                left.valueDeclaration === right.valueDeclaration));
+    }
+    _getNavigationToSymbol(symbol) {
+        const declaration = TypeScriptHelpers.tryGetADeclaration(symbol);
+        const sourceFile = declaration === null || declaration === void 0 ? void 0 : declaration.getSourceFile();
+        const parent = TypeScriptInternals.getSymbolParent(symbol);
+        // If it's global or from an external library, then use either Members or Exports. It's not possible for
+        // global symbols or external library symbols to be Locals.
+        const isGlobal = !!sourceFile && !ts.isExternalModule(sourceFile);
+        const isFromExternalLibrary = !!sourceFile && this._collector.program.isSourceFileFromExternalLibrary(sourceFile);
+        if (isGlobal || isFromExternalLibrary) {
+            if (parent &&
+                parent.members &&
+                DeclarationReferenceGenerator._isSameSymbol(parent.members.get(symbol.escapedName), symbol)) {
+                return Navigation.Members;
+            }
+            return Navigation.Exports;
+        }
+        // Otherwise, this symbol is from the current package. If we've found an associated consumable
+        // `CollectorEntity`, then use Exports. We use `consumable` here instead of `exported` because
+        // if the symbol is exported from a non-consumable `AstNamespaceImport`, we don't want to use
+        // Exports. We should use Locals instead.
+        const entity = this._collector.tryGetEntityForSymbol(symbol);
+        if (entity === null || entity === void 0 ? void 0 : entity.consumable) {
+            return Navigation.Exports;
+        }
+        // If its parent symbol is not a source file, then use either Exports or Members. If the parent symbol
+        // is a source file, but it wasn't exported from the package entry point (in the check above), then the
+        // symbol is a local, so fall through below.
+        if (parent && !DeclarationReferenceGenerator._isExternalModuleSymbol(parent)) {
+            if (parent.members &&
+                DeclarationReferenceGenerator._isSameSymbol(parent.members.get(symbol.escapedName), symbol)) {
+                return Navigation.Members;
+            }
+            return Navigation.Exports;
+        }
+        // Otherwise, we have a local symbol, so use a Locals navigation. These are either:
+        //
+        // 1. Symbols that are exported from a file module but not the package entry point.
+        // 2. Symbols that are not exported from their parent module.
+        return Navigation.Locals;
+    }
+    static _getMeaningOfSymbol(symbol, meaning) {
+        if (symbol.flags & meaning & ts.SymbolFlags.Class) {
+            return Meaning.Class;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Enum) {
+            return Meaning.Enum;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Interface) {
+            return Meaning.Interface;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.TypeAlias) {
+            return Meaning.TypeAlias;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Function) {
+            return Meaning.Function;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Variable) {
+            return Meaning.Variable;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Module) {
+            return Meaning.Namespace;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.ClassMember) {
+            return Meaning.Member;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Constructor) {
+            return Meaning.Constructor;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.EnumMember) {
+            return Meaning.Member;
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.Signature) {
+            if (symbol.escapedName === ts.InternalSymbolName.Call) {
+                return Meaning.CallSignature;
+            }
+            if (symbol.escapedName === ts.InternalSymbolName.New) {
+                return Meaning.ConstructSignature;
+            }
+            if (symbol.escapedName === ts.InternalSymbolName.Index) {
+                return Meaning.IndexSignature;
+            }
+        }
+        if (symbol.flags & meaning & ts.SymbolFlags.TypeParameter) {
+            // This should have already been handled in `getDeclarationReferenceOfSymbol`.
+            throw new InternalError('Not supported.');
+        }
+        return undefined;
+    }
+    _symbolToDeclarationReference(symbol, meaning, includeModuleSymbols) {
+        const declaration = TypeScriptHelpers.tryGetADeclaration(symbol);
+        const sourceFile = declaration === null || declaration === void 0 ? void 0 : declaration.getSourceFile();
+        let followedSymbol = symbol;
+        if (followedSymbol.flags & ts.SymbolFlags.ExportValue) {
+            followedSymbol = this._collector.typeChecker.getExportSymbolOfSymbol(followedSymbol);
+        }
+        if (followedSymbol.flags & ts.SymbolFlags.Alias) {
+            followedSymbol = this._collector.typeChecker.getAliasedSymbol(followedSymbol);
+            // Without this logic, we end up following the symbol `ns` in `import * as ns from './file'` to
+            // the actual file `file.ts`. We don't want to do this, so revert to the original symbol.
+            if (followedSymbol.flags & ts.SymbolFlags.ValueModule) {
+                followedSymbol = symbol;
+            }
+        }
+        if (DeclarationReferenceGenerator._isExternalModuleSymbol(followedSymbol)) {
+            if (!includeModuleSymbols) {
+                return undefined;
+            }
+            return new DeclarationReference(this._sourceFileToModuleSource(sourceFile));
+        }
+        // Do not generate a declaration reference for a type parameter.
+        if (followedSymbol.flags & ts.SymbolFlags.TypeParameter) {
+            return undefined;
+        }
+        let parentRef = this._getParentReference(followedSymbol);
+        if (!parentRef) {
+            return undefined;
+        }
+        let localName = followedSymbol.name;
+        const entity = this._collector.tryGetEntityForSymbol(followedSymbol);
+        if (entity === null || entity === void 0 ? void 0 : entity.nameForEmit) {
+            localName = entity.nameForEmit;
+        }
+        if (followedSymbol.escapedName === ts.InternalSymbolName.Constructor) {
+            localName = 'constructor';
+        }
+        else {
+            const wellKnownName = TypeScriptHelpers.tryDecodeWellKnownSymbolName(followedSymbol.escapedName);
+            if (wellKnownName) {
+                // TypeScript binds well-known ECMAScript symbols like 'Symbol.iterator' as '__@iterator'.
+                // This converts a string like '__@iterator' into the property name '[Symbol.iterator]'.
+                localName = wellKnownName;
+            }
+            else if (TypeScriptHelpers.isUniqueSymbolName(followedSymbol.escapedName)) {
+                for (const decl of followedSymbol.declarations || []) {
+                    const declName = ts.getNameOfDeclaration(decl);
+                    if (declName && ts.isComputedPropertyName(declName)) {
+                        const lateName = TypeScriptHelpers.tryGetLateBoundName(declName);
+                        if (lateName !== undefined) {
+                            localName = lateName;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        const navigation = this._getNavigationToSymbol(followedSymbol);
+        // If the symbol is a global, ensure the source is global.
+        if (sourceFile && !ts.isExternalModule(sourceFile) && parentRef.source !== GlobalSource.instance) {
+            parentRef = new DeclarationReference(GlobalSource.instance);
+        }
+        return parentRef
+            .addNavigationStep(navigation, localName)
+            .withMeaning(DeclarationReferenceGenerator._getMeaningOfSymbol(followedSymbol, meaning));
+    }
+    _getParentReference(symbol) {
+        var _a;
+        const declaration = TypeScriptHelpers.tryGetADeclaration(symbol);
+        const sourceFile = declaration === null || declaration === void 0 ? void 0 : declaration.getSourceFile();
+        // Note that it's possible for a symbol to be exported from an entry point as well as one or more
+        // namespaces. In that case, it's not clear what to choose as its parent. Today's logic is neither
+        // perfect nor particularly stable to API items being renamed and shuffled around.
+        const entity = this._collector.tryGetEntityForSymbol(symbol);
+        if (entity) {
+            if (entity.exportedFromEntryPoint) {
+                return new DeclarationReference(this._sourceFileToModuleSource(sourceFile));
+            }
+            const firstExportingConsumableParent = entity.getFirstExportingConsumableParent();
+            if (firstExportingConsumableParent &&
+                firstExportingConsumableParent.astEntity instanceof AstNamespaceImport) {
+                const parentSymbol = TypeScriptInternals.tryGetSymbolForDeclaration(firstExportingConsumableParent.astEntity.declaration, this._collector.typeChecker);
+                if (parentSymbol) {
+                    return this._symbolToDeclarationReference(parentSymbol, parentSymbol.flags, 
+                    /*includeModuleSymbols*/ true);
+                }
+            }
+        }
+        // Next, try to find a parent symbol via the symbol tree.
+        const parentSymbol = TypeScriptInternals.getSymbolParent(symbol);
+        if (parentSymbol) {
+            return this._symbolToDeclarationReference(parentSymbol, parentSymbol.flags, 
+            /*includeModuleSymbols*/ true);
+        }
+        // If that doesn't work, try to find a parent symbol via the node tree. As far as we can tell,
+        // this logic is only needed for local symbols within namespaces. For example:
+        //
+        // ```
+        // export namespace n {
+        //   type SomeType = number;
+        //   export function someFunction(): SomeType { return 5; }
+        // }
+        // ```
+        //
+        // In the example above, `SomeType` doesn't have a parent symbol per the TS internal API above,
+        // but its reference still needs to be qualified with the parent reference for `n`.
+        const grandParent = (_a = declaration === null || declaration === void 0 ? void 0 : declaration.parent) === null || _a === void 0 ? void 0 : _a.parent;
+        if (grandParent && ts.isModuleDeclaration(grandParent)) {
+            const grandParentSymbol = TypeScriptInternals.tryGetSymbolForDeclaration(grandParent, this._collector.typeChecker);
+            if (grandParentSymbol) {
+                return this._symbolToDeclarationReference(grandParentSymbol, grandParentSymbol.flags, 
+                /*includeModuleSymbols*/ true);
+            }
+        }
+        // At this point, we have a local symbol in a module.
+        if (sourceFile && ts.isExternalModule(sourceFile)) {
+            return new DeclarationReference(this._sourceFileToModuleSource(sourceFile));
+        }
+        else {
+            return new DeclarationReference(GlobalSource.instance);
+        }
+    }
+    _getPackageName(sourceFile) {
+        if (this._collector.program.isSourceFileFromExternalLibrary(sourceFile)) {
+            const packageJson = this._collector.packageJsonLookup.tryLoadNodePackageJsonFor(sourceFile.fileName);
+            if (packageJson && packageJson.name) {
+                return packageJson.name;
+            }
+            return DeclarationReferenceGenerator.unknownReference;
+        }
+        return this._collector.workingPackage.name;
+    }
+    _sourceFileToModuleSource(sourceFile) {
+        if (sourceFile && ts.isExternalModule(sourceFile)) {
+            const packageName = this._getPackageName(sourceFile);
+            if (this._collector.bundledPackageNames.has(packageName)) {
+                // The api-extractor.json config file has a "bundledPackages" setting, which causes imports from
+                // certain NPM packages to be treated as part of the working project.  In this case, we need to
+                // substitute the working package name.
+                return new ModuleSource(this._collector.workingPackage.name);
+            }
+            else {
+                return new ModuleSource(packageName);
+            }
+        }
+        return GlobalSource.instance;
+    }
+}
+DeclarationReferenceGenerator.unknownReference = '?';
+//# sourceMappingURL=DeclarationReferenceGenerator.js.map

package/lib-esm/generators/DeclarationReferenceGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclarationReferenceGenerator.js","sourceRoot":"","sources":["../../src/generators/DeclarationReferenceGenerator.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,+BAA+B;AAC/B,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,OAAO,EACR,MAAM,yDAAyD,CAAC;AACjE,OAAO,EAAyB,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAEpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEpE,MAAM,OAAO,6BAA6B;IAKxC,YAAmB,SAAoB;QACrC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,oCAAoC,CAAC,IAAmB;QAC7D,MAAM,MAAM,GAA0B,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAC5F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,YAAY,GAAY,6BAA6B,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;YACzF,OAAO,CACL,IAAI,CAAC,gCAAgC,CACnC,MAAM,EACN,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAC1D;gBACD,IAAI,CAAC,gCAAgC,CACnC,MAAM,EACN,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,CAC1D;gBACD,IAAI,CAAC,gCAAgC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACI,gCAAgC,CACrC,MAAiB,EACjB,OAAuB;QAEvB,OAAO,IAAI,CAAC,6BAA6B,CAAC,MAAM,EAAE,OAAO,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC7F,CAAC;IAEO,MAAM,CAAC,sBAAsB,CAAC,IAAa;QACjD,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACzB,KAAK,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAC7B,KAAK,EAAE,CAAC,UAAU,CAAC,oBAAoB;gBACrC,OAAO,IAAI,CAAC;YACd,KAAK,EAAE,CAAC,UAAU,CAAC,aAAa;gBAC9B,OAAO,6BAA6B,CAAC,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3E;gBACE,OAAO,KAAK,CAAC;QACjB,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,uBAAuB,CAAC,MAAiB;QACtD,OAAO,CACL,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC;YAC7C,MAAM,CAAC,gBAAgB,KAAK,SAAS;YACrC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,gBAAgB,CAAC,CACzC,CAAC;IACJ,CAAC;IAEO,MAAM,CAAC,aAAa,CAAC,IAA2B,EAAE,KAAgB;QACxE,OAAO,CACL,IAAI,KAAK,KAAK;YACd,CAAC,CAAC,CACA,IAAI;gBACJ,IAAI,CAAC,gBAAgB;gBACrB,KAAK,CAAC,gBAAgB;gBACtB,IAAI,CAAC,gBAAgB,KAAK,KAAK,CAAC,gBAAgB,CACjD,CACF,CAAC;IACJ,CAAC;IAEO,sBAAsB,CAAC,MAAiB;QAC9C,MAAM,WAAW,GAA+B,iBAAiB,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC7F,MAAM,UAAU,GAA8B,WAAW,aAAX,WAAW,uBAAX,WAAW,CAAE,aAAa,EAAE,CAAC;QAC3E,MAAM,MAAM,GAA0B,mBAAmB,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAElF,wGAAwG;QACxG,2DAA2D;QAC3D,MAAM,QAAQ,GAAY,CAAC,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAC3E,MAAM,qBAAqB,GACzB,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,+BAA+B,CAAC,UAAU,CAAC,CAAC;QACtF,IAAI,QAAQ,IAAI,qBAAqB,EAAE,CAAC;YACtC,IACE,MAAM;gBACN,MAAM,CAAC,OAAO;gBACd,6BAA6B,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,EAC3F,CAAC;gBACD,OAAO,UAAU,CAAC,OAAO,CAAC;YAC5B,CAAC;YAED,OAAO,UAAU,CAAC,OAAO,CAAC;QAC5B,CAAC;QAED,8FAA8F;QAC9F,8FAA8F;QAC9F,6FAA6F;QAC7F,yCAAyC;QACzC,MAAM,MAAM,GAAgC,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC1F,IAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,UAAU,EAAE,CAAC;YACvB,OAAO,UAAU,CAAC,OAAO,CAAC;QAC5B,CAAC;QAED,sGAAsG;QACtG,uGAAuG;QACvG,4CAA4C;QAC5C,IAAI,MAAM,IAAI,CAAC,6BAA6B,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7E,IACE,MAAM,CAAC,OAAO;gBACd,6BAA6B,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,EAC3F,CAAC;gBACD,OAAO,UAAU,CAAC,OAAO,CAAC;YAC5B,CAAC;YAED,OAAO,UAAU,CAAC,OAAO,CAAC;QAC5B,CAAC;QAED,mFAAmF;QACnF,EAAE;QACF,mFAAmF;QACnF,6DAA6D;QAC7D,OAAO,UAAU,CAAC,MAAM,CAAC;IAC3B,CAAC;IAEO,MAAM,CAAC,mBAAmB,CAAC,MAAiB,EAAE,OAAuB;QAC3E,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAClD,OAAO,OAAO,CAAC,KAAK,CAAC;QACvB,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;YACjD,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;YACtD,OAAO,OAAO,CAAC,SAAS,CAAC;QAC3B,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;YACtD,OAAO,OAAO,CAAC,SAAS,CAAC;QAC3B,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;YACrD,OAAO,OAAO,CAAC,QAAQ,CAAC;QAC1B,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;YACrD,OAAO,OAAO,CAAC,QAAQ,CAAC;QAC1B,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;YACnD,OAAO,OAAO,CAAC,SAAS,CAAC;QAC3B,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;YACxD,OAAO,OAAO,CAAC,MAAM,CAAC;QACxB,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;YACxD,OAAO,OAAO,CAAC,WAAW,CAAC;QAC7B,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;YACvD,OAAO,OAAO,CAAC,MAAM,CAAC;QACxB,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;YACtD,IAAI,MAAM,CAAC,WAAW,KAAK,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;gBACtD,OAAO,OAAO,CAAC,aAAa,CAAC;YAC/B,CAAC;YACD,IAAI,MAAM,CAAC,WAAW,KAAK,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC;gBACrD,OAAO,OAAO,CAAC,kBAAkB,CAAC;YACpC,CAAC;YACD,IAAI,MAAM,CAAC,WAAW,KAAK,EAAE,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;gBACvD,OAAO,OAAO,CAAC,cAAc,CAAC;YAChC,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC;YAC1D,8EAA8E;YAC9E,MAAM,IAAI,aAAa,CAAC,gBAAgB,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,6BAA6B,CACnC,MAAiB,EACjB,OAAuB,EACvB,oBAA6B;QAE7B,MAAM,WAAW,GAAwB,iBAAiB,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtF,MAAM,UAAU,GAA8B,WAAW,aAAX,WAAW,uBAAX,WAAW,CAAE,aAAa,EAAE,CAAC;QAE3E,IAAI,cAAc,GAAc,MAAM,CAAC;QACvC,IAAI,cAAc,CAAC,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;YACtD,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,uBAAuB,CAAC,cAAc,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,cAAc,CAAC,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAChD,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC;YAE9E,+FAA+F;YAC/F,yFAAyF;YACzF,IAAI,cAAc,CAAC,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;gBACtD,cAAc,GAAG,MAAM,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,6BAA6B,CAAC,uBAAuB,CAAC,cAAc,CAAC,EAAE,CAAC;YAC1E,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBAC1B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,IAAI,oBAAoB,CAAC,IAAI,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC,CAAC;QAC9E,CAAC;QAED,gEAAgE;QAChE,IAAI,cAAc,CAAC,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC;YACxD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,SAAS,GAAqC,IAAI,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;QAC3F,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,SAAS,GAAW,cAAc,CAAC,IAAI,CAAC;QAC5C,MAAM,MAAM,GAAgC,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,cAAc,CAAC,CAAC;QAClG,IAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,EAAE,CAAC;YACxB,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC;QACjC,CAAC;QAED,IAAI,cAAc,CAAC,WAAW,KAAK,EAAE,CAAC,kBAAkB,CAAC,WAAW,EAAE,CAAC;YACrE,SAAS,GAAG,aAAa,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,MAAM,aAAa,GAAuB,iBAAiB,CAAC,4BAA4B,CACtF,cAAc,CAAC,WAAW,CAC3B,CAAC;YACF,IAAI,aAAa,EAAE,CAAC;gBAClB,0FAA0F;gBAC1F,wFAAwF;gBACxF,SAAS,GAAG,aAAa,CAAC;YAC5B,CAAC;iBAAM,IAAI,iBAAiB,CAAC,kBAAkB,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC5E,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC;oBACrD,MAAM,QAAQ,GAAmC,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC;oBAC/E,IAAI,QAAQ,IAAI,EAAE,CAAC,sBAAsB,CAAC,QAAQ,CAAC,EAAE,CAAC;wBACpD,MAAM,QAAQ,GAAuB,iBAAiB,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;wBACrF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;4BAC3B,SAAS,GAAG,QAAQ,CAAC;4BACrB,MAAM;wBACR,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAe,IAAI,CAAC,sBAAsB,CAAC,cAAc,CAAC,CAAC;QAE3E,0DAA0D;QAC1D,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,YAAY,CAAC,QAAQ,EAAE,CAAC;YACjG,SAAS,GAAG,IAAI,oBAAoB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,SAAS;aACb,iBAAiB,CAAC,UAAU,EAAE,SAAS,CAAC;aACxC,WAAW,CAAC,6BAA6B,CAAC,mBAAmB,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7F,CAAC;IAEO,mBAAmB,CAAC,MAAiB;;QAC3C,MAAM,WAAW,GAAwB,iBAAiB,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtF,MAAM,UAAU,GAA8B,WAAW,aAAX,WAAW,uBAAX,WAAW,CAAE,aAAa,EAAE,CAAC;QAE3E,iGAAiG;QACjG,kGAAkG;QAClG,kFAAkF;QAClF,MAAM,MAAM,GAAgC,IAAI,CAAC,UAAU,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC1F,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;gBAClC,OAAO,IAAI,oBAAoB,CAAC,IAAI,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC,CAAC;YAC9E,CAAC;YAED,MAAM,8BAA8B,GAClC,MAAM,CAAC,iCAAiC,EAAE,CAAC;YAC7C,IACE,8BAA8B;gBAC9B,8BAA8B,CAAC,SAAS,YAAY,kBAAkB,EACtE,CAAC;gBACD,MAAM,YAAY,GAA0B,mBAAmB,CAAC,0BAA0B,CACxF,8BAA8B,CAAC,SAAS,CAAC,WAAW,EACpD,IAAI,CAAC,UAAU,CAAC,WAAW,CAC5B,CAAC;gBACF,IAAI,YAAY,EAAE,CAAC;oBACjB,OAAO,IAAI,CAAC,6BAA6B,CACvC,YAAY,EACZ,YAAY,CAAC,KAAK;oBAClB,wBAAwB,CAAC,IAAI,CAC9B,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,MAAM,YAAY,GAA0B,mBAAmB,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QACxF,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,6BAA6B,CACvC,YAAY,EACZ,YAAY,CAAC,KAAK;YAClB,wBAAwB,CAAC,IAAI,CAC9B,CAAC;QACJ,CAAC;QAED,8FAA8F;QAC9F,8EAA8E;QAC9E,EAAE;QACF,MAAM;QACN,uBAAuB;QACvB,4BAA4B;QAC5B,2DAA2D;QAC3D,IAAI;QACJ,MAAM;QACN,EAAE;QACF,+FAA+F;QAC/F,mFAAmF;QACnF,MAAM,WAAW,GAAwB,MAAA,WAAW,aAAX,WAAW,uBAAX,WAAW,CAAE,MAAM,0CAAE,MAAM,CAAC;QACrE,IAAI,WAAW,IAAI,EAAE,CAAC,mBAAmB,CAAC,WAAW,CAAC,EAAE,CAAC;YACvD,MAAM,iBAAiB,GAA0B,mBAAmB,CAAC,0BAA0B,CAC7F,WAAW,EACX,IAAI,CAAC,UAAU,CAAC,WAAW,CAC5B,CAAC;YACF,IAAI,iBAAiB,EAAE,CAAC;gBACtB,OAAO,IAAI,CAAC,6BAA6B,CACvC,iBAAiB,EACjB,iBAAiB,CAAC,KAAK;gBACvB,wBAAwB,CAAC,IAAI,CAC9B,CAAC;YACJ,CAAC;QACH,CAAC;QAED,qDAAqD;QACrD,IAAI,UAAU,IAAI,EAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;YAClD,OAAO,IAAI,oBAAoB,CAAC,IAAI,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC,CAAC;QAC9E,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,oBAAoB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,UAAyB;QAC/C,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,+BAA+B,CAAC,UAAU,CAAC,EAAE,CAAC;YACxE,MAAM,WAAW,GACf,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,yBAAyB,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAEnF,IAAI,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC;gBACpC,OAAO,WAAW,CAAC,IAAI,CAAC;YAC1B,CAAC;YACD,OAAO,6BAA6B,CAAC,gBAAgB,CAAC;QACxD,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC;IAC7C,CAAC;IAEO,yBAAyB,CAAC,UAAqC;QACrE,IAAI,UAAU,IAAI,EAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;YAClD,MAAM,WAAW,GAAW,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;YAE7D,IAAI,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;gBACzD,gGAAgG;gBAChG,+FAA+F;gBAC/F,uCAAuC;gBACvC,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAC/D,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QACD,OAAO,YAAY,CAAC,QAAQ,CAAC;IAC/B,CAAC;;AAtWsB,8CAAgB,GAAW,GAAG,CAAC","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 */\nimport * as ts from 'typescript';\n\nimport {\n  DeclarationReference,\n  ModuleSource,\n  GlobalSource,\n  Navigation,\n  Meaning\n} from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\nimport { type INodePackageJson, InternalError } from '@rushstack/node-core-library';\n\nimport { TypeScriptHelpers } from '../analyzer/TypeScriptHelpers';\nimport { TypeScriptInternals } from '../analyzer/TypeScriptInternals';\nimport type { Collector } from '../collector/Collector';\nimport type { CollectorEntity } from '../collector/CollectorEntity';\nimport { AstNamespaceImport } from '../analyzer/AstNamespaceImport';\n\nexport class DeclarationReferenceGenerator {\n  public static readonly unknownReference: string = '?';\n\n  private _collector: Collector;\n\n  public constructor(collector: Collector) {\n    this._collector = collector;\n  }\n\n  /**\n   * Gets the UID for a TypeScript Identifier that references a type.\n   */\n  public getDeclarationReferenceForIdentifier(node: ts.Identifier): DeclarationReference | undefined {\n    const symbol: ts.Symbol | undefined = this._collector.typeChecker.getSymbolAtLocation(node);\n    if (symbol !== undefined) {\n      const isExpression: boolean = DeclarationReferenceGenerator._isInExpressionContext(node);\n      return (\n        this.getDeclarationReferenceForSymbol(\n          symbol,\n          isExpression ? ts.SymbolFlags.Value : ts.SymbolFlags.Type\n        ) ||\n        this.getDeclarationReferenceForSymbol(\n          symbol,\n          isExpression ? ts.SymbolFlags.Type : ts.SymbolFlags.Value\n        ) ||\n        this.getDeclarationReferenceForSymbol(symbol, ts.SymbolFlags.Namespace)\n      );\n    }\n  }\n\n  /**\n   * Gets the DeclarationReference for a TypeScript Symbol for a given meaning.\n   */\n  public getDeclarationReferenceForSymbol(\n    symbol: ts.Symbol,\n    meaning: ts.SymbolFlags\n  ): DeclarationReference | undefined {\n    return this._symbolToDeclarationReference(symbol, meaning, /*includeModuleSymbols*/ false);\n  }\n\n  private static _isInExpressionContext(node: ts.Node): boolean {\n    switch (node.parent.kind) {\n      case ts.SyntaxKind.TypeQuery:\n      case ts.SyntaxKind.ComputedPropertyName:\n        return true;\n      case ts.SyntaxKind.QualifiedName:\n        return DeclarationReferenceGenerator._isInExpressionContext(node.parent);\n      default:\n        return false;\n    }\n  }\n\n  private static _isExternalModuleSymbol(symbol: ts.Symbol): boolean {\n    return (\n      !!(symbol.flags & ts.SymbolFlags.ValueModule) &&\n      symbol.valueDeclaration !== undefined &&\n      ts.isSourceFile(symbol.valueDeclaration)\n    );\n  }\n\n  private static _isSameSymbol(left: ts.Symbol | undefined, right: ts.Symbol): boolean {\n    return (\n      left === right ||\n      !!(\n        left &&\n        left.valueDeclaration &&\n        right.valueDeclaration &&\n        left.valueDeclaration === right.valueDeclaration\n      )\n    );\n  }\n\n  private _getNavigationToSymbol(symbol: ts.Symbol): Navigation {\n    const declaration: ts.Declaration | undefined = TypeScriptHelpers.tryGetADeclaration(symbol);\n    const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile();\n    const parent: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol);\n\n    // If it's global or from an external library, then use either Members or Exports. It's not possible for\n    // global symbols or external library symbols to be Locals.\n    const isGlobal: boolean = !!sourceFile && !ts.isExternalModule(sourceFile);\n    const isFromExternalLibrary: boolean =\n      !!sourceFile && this._collector.program.isSourceFileFromExternalLibrary(sourceFile);\n    if (isGlobal || isFromExternalLibrary) {\n      if (\n        parent &&\n        parent.members &&\n        DeclarationReferenceGenerator._isSameSymbol(parent.members.get(symbol.escapedName), symbol)\n      ) {\n        return Navigation.Members;\n      }\n\n      return Navigation.Exports;\n    }\n\n    // Otherwise, this symbol is from the current package. If we've found an associated consumable\n    // `CollectorEntity`, then use Exports. We use `consumable` here instead of `exported` because\n    // if the symbol is exported from a non-consumable `AstNamespaceImport`, we don't want to use\n    // Exports. We should use Locals instead.\n    const entity: CollectorEntity | undefined = this._collector.tryGetEntityForSymbol(symbol);\n    if (entity?.consumable) {\n      return Navigation.Exports;\n    }\n\n    // If its parent symbol is not a source file, then use either Exports or Members. If the parent symbol\n    // is a source file, but it wasn't exported from the package entry point (in the check above), then the\n    // symbol is a local, so fall through below.\n    if (parent && !DeclarationReferenceGenerator._isExternalModuleSymbol(parent)) {\n      if (\n        parent.members &&\n        DeclarationReferenceGenerator._isSameSymbol(parent.members.get(symbol.escapedName), symbol)\n      ) {\n        return Navigation.Members;\n      }\n\n      return Navigation.Exports;\n    }\n\n    // Otherwise, we have a local symbol, so use a Locals navigation. These are either:\n    //\n    // 1. Symbols that are exported from a file module but not the package entry point.\n    // 2. Symbols that are not exported from their parent module.\n    return Navigation.Locals;\n  }\n\n  private static _getMeaningOfSymbol(symbol: ts.Symbol, meaning: ts.SymbolFlags): Meaning | undefined {\n    if (symbol.flags & meaning & ts.SymbolFlags.Class) {\n      return Meaning.Class;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Enum) {\n      return Meaning.Enum;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Interface) {\n      return Meaning.Interface;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.TypeAlias) {\n      return Meaning.TypeAlias;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Function) {\n      return Meaning.Function;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Variable) {\n      return Meaning.Variable;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Module) {\n      return Meaning.Namespace;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.ClassMember) {\n      return Meaning.Member;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Constructor) {\n      return Meaning.Constructor;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.EnumMember) {\n      return Meaning.Member;\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.Signature) {\n      if (symbol.escapedName === ts.InternalSymbolName.Call) {\n        return Meaning.CallSignature;\n      }\n      if (symbol.escapedName === ts.InternalSymbolName.New) {\n        return Meaning.ConstructSignature;\n      }\n      if (symbol.escapedName === ts.InternalSymbolName.Index) {\n        return Meaning.IndexSignature;\n      }\n    }\n    if (symbol.flags & meaning & ts.SymbolFlags.TypeParameter) {\n      // This should have already been handled in `getDeclarationReferenceOfSymbol`.\n      throw new InternalError('Not supported.');\n    }\n    return undefined;\n  }\n\n  private _symbolToDeclarationReference(\n    symbol: ts.Symbol,\n    meaning: ts.SymbolFlags,\n    includeModuleSymbols: boolean\n  ): DeclarationReference | undefined {\n    const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol);\n    const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile();\n\n    let followedSymbol: ts.Symbol = symbol;\n    if (followedSymbol.flags & ts.SymbolFlags.ExportValue) {\n      followedSymbol = this._collector.typeChecker.getExportSymbolOfSymbol(followedSymbol);\n    }\n    if (followedSymbol.flags & ts.SymbolFlags.Alias) {\n      followedSymbol = this._collector.typeChecker.getAliasedSymbol(followedSymbol);\n\n      // Without this logic, we end up following the symbol `ns` in `import * as ns from './file'` to\n      // the actual file `file.ts`. We don't want to do this, so revert to the original symbol.\n      if (followedSymbol.flags & ts.SymbolFlags.ValueModule) {\n        followedSymbol = symbol;\n      }\n    }\n\n    if (DeclarationReferenceGenerator._isExternalModuleSymbol(followedSymbol)) {\n      if (!includeModuleSymbols) {\n        return undefined;\n      }\n      return new DeclarationReference(this._sourceFileToModuleSource(sourceFile));\n    }\n\n    // Do not generate a declaration reference for a type parameter.\n    if (followedSymbol.flags & ts.SymbolFlags.TypeParameter) {\n      return undefined;\n    }\n\n    let parentRef: DeclarationReference | undefined = this._getParentReference(followedSymbol);\n    if (!parentRef) {\n      return undefined;\n    }\n\n    let localName: string = followedSymbol.name;\n    const entity: CollectorEntity | undefined = this._collector.tryGetEntityForSymbol(followedSymbol);\n    if (entity?.nameForEmit) {\n      localName = entity.nameForEmit;\n    }\n\n    if (followedSymbol.escapedName === ts.InternalSymbolName.Constructor) {\n      localName = 'constructor';\n    } else {\n      const wellKnownName: string | undefined = TypeScriptHelpers.tryDecodeWellKnownSymbolName(\n        followedSymbol.escapedName\n      );\n      if (wellKnownName) {\n        // TypeScript binds well-known ECMAScript symbols like 'Symbol.iterator' as '__@iterator'.\n        // This converts a string like '__@iterator' into the property name '[Symbol.iterator]'.\n        localName = wellKnownName;\n      } else if (TypeScriptHelpers.isUniqueSymbolName(followedSymbol.escapedName)) {\n        for (const decl of followedSymbol.declarations || []) {\n          const declName: ts.DeclarationName | undefined = ts.getNameOfDeclaration(decl);\n          if (declName && ts.isComputedPropertyName(declName)) {\n            const lateName: string | undefined = TypeScriptHelpers.tryGetLateBoundName(declName);\n            if (lateName !== undefined) {\n              localName = lateName;\n              break;\n            }\n          }\n        }\n      }\n    }\n\n    const navigation: Navigation = this._getNavigationToSymbol(followedSymbol);\n\n    // If the symbol is a global, ensure the source is global.\n    if (sourceFile && !ts.isExternalModule(sourceFile) && parentRef.source !== GlobalSource.instance) {\n      parentRef = new DeclarationReference(GlobalSource.instance);\n    }\n\n    return parentRef\n      .addNavigationStep(navigation, localName)\n      .withMeaning(DeclarationReferenceGenerator._getMeaningOfSymbol(followedSymbol, meaning));\n  }\n\n  private _getParentReference(symbol: ts.Symbol): DeclarationReference | undefined {\n    const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol);\n    const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile();\n\n    // Note that it's possible for a symbol to be exported from an entry point as well as one or more\n    // namespaces. In that case, it's not clear what to choose as its parent. Today's logic is neither\n    // perfect nor particularly stable to API items being renamed and shuffled around.\n    const entity: CollectorEntity | undefined = this._collector.tryGetEntityForSymbol(symbol);\n    if (entity) {\n      if (entity.exportedFromEntryPoint) {\n        return new DeclarationReference(this._sourceFileToModuleSource(sourceFile));\n      }\n\n      const firstExportingConsumableParent: CollectorEntity | undefined =\n        entity.getFirstExportingConsumableParent();\n      if (\n        firstExportingConsumableParent &&\n        firstExportingConsumableParent.astEntity instanceof AstNamespaceImport\n      ) {\n        const parentSymbol: ts.Symbol | undefined = TypeScriptInternals.tryGetSymbolForDeclaration(\n          firstExportingConsumableParent.astEntity.declaration,\n          this._collector.typeChecker\n        );\n        if (parentSymbol) {\n          return this._symbolToDeclarationReference(\n            parentSymbol,\n            parentSymbol.flags,\n            /*includeModuleSymbols*/ true\n          );\n        }\n      }\n    }\n\n    // Next, try to find a parent symbol via the symbol tree.\n    const parentSymbol: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol);\n    if (parentSymbol) {\n      return this._symbolToDeclarationReference(\n        parentSymbol,\n        parentSymbol.flags,\n        /*includeModuleSymbols*/ true\n      );\n    }\n\n    // If that doesn't work, try to find a parent symbol via the node tree. As far as we can tell,\n    // this logic is only needed for local symbols within namespaces. For example:\n    //\n    // ```\n    // export namespace n {\n    //   type SomeType = number;\n    //   export function someFunction(): SomeType { return 5; }\n    // }\n    // ```\n    //\n    // In the example above, `SomeType` doesn't have a parent symbol per the TS internal API above,\n    // but its reference still needs to be qualified with the parent reference for `n`.\n    const grandParent: ts.Node | undefined = declaration?.parent?.parent;\n    if (grandParent && ts.isModuleDeclaration(grandParent)) {\n      const grandParentSymbol: ts.Symbol | undefined = TypeScriptInternals.tryGetSymbolForDeclaration(\n        grandParent,\n        this._collector.typeChecker\n      );\n      if (grandParentSymbol) {\n        return this._symbolToDeclarationReference(\n          grandParentSymbol,\n          grandParentSymbol.flags,\n          /*includeModuleSymbols*/ true\n        );\n      }\n    }\n\n    // At this point, we have a local symbol in a module.\n    if (sourceFile && ts.isExternalModule(sourceFile)) {\n      return new DeclarationReference(this._sourceFileToModuleSource(sourceFile));\n    } else {\n      return new DeclarationReference(GlobalSource.instance);\n    }\n  }\n\n  private _getPackageName(sourceFile: ts.SourceFile): string {\n    if (this._collector.program.isSourceFileFromExternalLibrary(sourceFile)) {\n      const packageJson: INodePackageJson | undefined =\n        this._collector.packageJsonLookup.tryLoadNodePackageJsonFor(sourceFile.fileName);\n\n      if (packageJson && packageJson.name) {\n        return packageJson.name;\n      }\n      return DeclarationReferenceGenerator.unknownReference;\n    }\n    return this._collector.workingPackage.name;\n  }\n\n  private _sourceFileToModuleSource(sourceFile: ts.SourceFile | undefined): GlobalSource | ModuleSource {\n    if (sourceFile && ts.isExternalModule(sourceFile)) {\n      const packageName: string = this._getPackageName(sourceFile);\n\n      if (this._collector.bundledPackageNames.has(packageName)) {\n        // The api-extractor.json config file has a \"bundledPackages\" setting, which causes imports from\n        // certain NPM packages to be treated as part of the working project.  In this case, we need to\n        // substitute the working package name.\n        return new ModuleSource(this._collector.workingPackage.name);\n      } else {\n        return new ModuleSource(packageName);\n      }\n    }\n    return GlobalSource.instance;\n  }\n}\n"]}

package/lib-esm/generators/DtsEmitHelpers.js

@@ -0,0 +1,227 @@
+// 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 { InternalError } from '@rushstack/node-core-library';
+import { AstImport, AstImportKind } from '../analyzer/AstImport';
+import { AstDeclaration } from '../analyzer/AstDeclaration';
+import { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';
+import { TypeScriptHelpers } from '../analyzer/TypeScriptHelpers';
+/**
+ * Some common code shared between DtsRollupGenerator and ApiReportGenerator.
+ */
+export class DtsEmitHelpers {
+    static emitImport(writer, collectorEntity, astImport) {
+        const importPrefix = astImport.isTypeOnlyEverywhere ? 'import type' : 'import';
+        switch (astImport.importKind) {
+            case AstImportKind.DefaultImport:
+                if (collectorEntity.nameForEmit !== astImport.exportName) {
+                    writer.write(`${importPrefix} { default as ${collectorEntity.nameForEmit} }`);
+                }
+                else {
+                    writer.write(`${importPrefix} ${astImport.exportName}`);
+                }
+                writer.writeLine(` from '${astImport.modulePath}';`);
+                break;
+            case AstImportKind.NamedImport:
+                if (collectorEntity.nameForEmit === astImport.exportName) {
+                    writer.write(`${importPrefix} { ${astImport.exportName} }`);
+                }
+                else {
+                    writer.write(`${importPrefix} { ${astImport.exportName} as ${collectorEntity.nameForEmit} }`);
+                }
+                writer.writeLine(` from '${astImport.modulePath}';`);
+                break;
+            case AstImportKind.StarImport:
+                writer.writeLine(`${importPrefix} * as ${collectorEntity.nameForEmit} from '${astImport.modulePath}';`);
+                break;
+            case AstImportKind.EqualsImport:
+                writer.writeLine(`${importPrefix} ${collectorEntity.nameForEmit} = require('${astImport.modulePath}');`);
+                break;
+            case AstImportKind.ImportType:
+                if (!astImport.exportName) {
+                    writer.writeLine(`${importPrefix} * as ${collectorEntity.nameForEmit} from '${astImport.modulePath}';`);
+                }
+                else {
+                    const topExportName = astImport.exportName.split('.')[0];
+                    if (collectorEntity.nameForEmit === topExportName) {
+                        writer.write(`${importPrefix} { ${topExportName} }`);
+                    }
+                    else {
+                        writer.write(`${importPrefix} { ${topExportName} as ${collectorEntity.nameForEmit} }`);
+                    }
+                    writer.writeLine(` from '${astImport.modulePath}';`);
+                }
+                break;
+            default:
+                throw new InternalError('Unimplemented AstImportKind');
+        }
+    }
+    static emitNamedExport(writer, exportName, collectorEntity) {
+        if (exportName === ts.InternalSymbolName.Default) {
+            writer.writeLine(`export default ${collectorEntity.nameForEmit};`);
+        }
+        else if (collectorEntity.nameForEmit !== exportName) {
+            writer.writeLine(`export { ${collectorEntity.nameForEmit} as ${exportName} }`);
+        }
+        else {
+            writer.writeLine(`export { ${exportName} }`);
+        }
+    }
+    static emitStarExports(writer, collector) {
+        if (collector.starExportedExternalModulePaths.length > 0) {
+            writer.writeLine();
+            for (const starExportedExternalModulePath of collector.starExportedExternalModulePaths) {
+                writer.writeLine(`export * from "${starExportedExternalModulePath}";`);
+            }
+        }
+    }
+    static modifyImportTypeSpan(collector, span, astDeclaration, modifyNestedSpan) {
+        var _a, _b, _c, _d;
+        const node = span.node;
+        const referencedEntity = collector.tryGetEntityForNode(node);
+        if (referencedEntity) {
+            if (!referencedEntity.nameForEmit) {
+                // This should never happen
+                throw new InternalError('referencedEntry.nameForEmit is undefined');
+            }
+            let typeArgumentsText = '';
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                // Type arguments have to be processed and written to the document
+                const lessThanTokenPos = span.children.findIndex((childSpan) => childSpan.node.kind === ts.SyntaxKind.LessThanToken);
+                const greaterThanTokenPos = span.children.findIndex((childSpan) => childSpan.node.kind === ts.SyntaxKind.GreaterThanToken);
+                if (lessThanTokenPos < 0 || greaterThanTokenPos <= lessThanTokenPos) {
+                    throw new InternalError(`Invalid type arguments: ${node.getText()}\n` +
+                        SourceFileLocationFormatter.formatDeclaration(node));
+                }
+                const typeArgumentsSpans = span.children.slice(lessThanTokenPos + 1, greaterThanTokenPos);
+                // Apply modifications to Span elements of typeArguments
+                typeArgumentsSpans.forEach((childSpan) => {
+                    const childAstDeclaration = AstDeclaration.isSupportedSyntaxKind(childSpan.kind)
+                        ? collector.astSymbolTable.getChildAstDeclarationByNode(childSpan.node, astDeclaration)
+                        : astDeclaration;
+                    modifyNestedSpan(childSpan, childAstDeclaration);
+                });
+                const typeArgumentsStrings = typeArgumentsSpans.map((childSpan) => childSpan.getModifiedText());
+                typeArgumentsText = `<${typeArgumentsStrings.join(', ')}>`;
+            }
+            const separatorAfter = (_b = (_a = /(\s*)$/.exec(span.getText())) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : '';
+            if (referencedEntity.astEntity instanceof AstImport &&
+                referencedEntity.astEntity.importKind === AstImportKind.ImportType &&
+                referencedEntity.astEntity.exportName) {
+                // For an ImportType with a namespace chain, only the top namespace is imported.
+                // Must add the original nested qualifiers to the rolled up import.
+                const qualifiersText = (_d = (_c = node.qualifier) === null || _c === void 0 ? void 0 : _c.getText()) !== null && _d !== void 0 ? _d : '';
+                const nestedQualifiersStart = qualifiersText.indexOf('.');
+                // Including the leading "."
+                const nestedQualifiersText = nestedQualifiersStart >= 0 ? qualifiersText.substring(nestedQualifiersStart) : '';
+                const replacement = `${referencedEntity.nameForEmit}${nestedQualifiersText}${typeArgumentsText}${separatorAfter}`;
+                span.modification.skipAll();
+                span.modification.prefix = replacement;
+            }
+            else {
+                // Replace with internal symbol or AstImport
+                span.modification.skipAll();
+                span.modification.prefix = `${referencedEntity.nameForEmit}${typeArgumentsText}${separatorAfter}`;
+            }
+        }
+    }
+    /**
+     * Checks if an export keyword is part of an ExportDeclaration inside a namespace
+     * (e.g., "export { Foo, Bar };" inside "declare namespace SDK { ... }").
+     * In that case, the export keyword must be preserved, otherwise the output is invalid TypeScript.
+     */
+    static isExportKeywordInNamespaceExportDeclaration(node) {
+        if (node.parent && ts.isExportDeclaration(node.parent)) {
+            const moduleBlock = TypeScriptHelpers.findFirstParent(node, ts.SyntaxKind.ModuleBlock);
+            if (moduleBlock) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Given an array that includes some parameter nodes, this returns an array of the same length;
+     * elements that are not undefined correspond to a parameter that should be renamed.
+     */
+    static forEachParameterToNormalize(nodes, action) {
+        let actionIndex = 0;
+        // Optimistically assume that no parameters need to be normalized
+        for (actionIndex = 0; actionIndex < nodes.length; ++actionIndex) {
+            const parameter = nodes[actionIndex];
+            if (!ts.isParameter(parameter)) {
+                continue;
+            }
+            action(parameter, undefined);
+            if (ts.isObjectBindingPattern(parameter.name) || ts.isArrayBindingPattern(parameter.name)) {
+                // Our optimistic assumption was not true; we'll need to stop and calculate alreadyUsedNames
+                break;
+            }
+        }
+        if (actionIndex === nodes.length) {
+            // Our optimistic assumption was true
+            return;
+        }
+        // First, calculate alreadyUsedNames
+        const alreadyUsedNames = [];
+        for (let index = 0; index < nodes.length; ++index) {
+            const parameter = nodes[index];
+            if (!ts.isParameter(parameter)) {
+                continue;
+            }
+            if (!(ts.isObjectBindingPattern(parameter.name) || ts.isArrayBindingPattern(parameter.name))) {
+                alreadyUsedNames.push(parameter.name.text.trim());
+            }
+        }
+        // Now continue with the rest of the actions
+        for (; actionIndex < nodes.length; ++actionIndex) {
+            const parameter = nodes[actionIndex];
+            if (!ts.isParameter(parameter)) {
+                continue;
+            }
+            if (ts.isObjectBindingPattern(parameter.name) || ts.isArrayBindingPattern(parameter.name)) {
+                // Examples:
+                //
+                //      function f({ y, z }: { y: string, z: string })
+                // ---> function f(input: { y: string, z: string })
+                //
+                //      function f(x: number, [a, b]: [number, number])
+                // ---> function f(x: number, input: [number, number])
+                //
+                // Example of a naming collision:
+                //
+                //      function f({ a }: { a: string }, { b }: { b: string }, input2: string)
+                // ---> function f(input: { a: string }, input3: { b: string }, input2: string)
+                const baseName = 'input';
+                let counter = 2;
+                let syntheticName = baseName;
+                while (alreadyUsedNames.includes(syntheticName)) {
+                    syntheticName = `${baseName}${counter++}`;
+                }
+                alreadyUsedNames.push(syntheticName);
+                action(parameter, syntheticName);
+            }
+            else {
+                action(parameter, undefined);
+            }
+        }
+    }
+    static normalizeParameterNames(signatureSpan) {
+        const syntheticNamesByNode = new Map();
+        DtsEmitHelpers.forEachParameterToNormalize(signatureSpan.node.getChildren(), (parameter, syntheticName) => {
+            if (syntheticName !== undefined) {
+                syntheticNamesByNode.set(parameter.name, syntheticName);
+            }
+        });
+        if (syntheticNamesByNode.size > 0) {
+            signatureSpan.forEach((childSpan) => {
+                const syntheticName = syntheticNamesByNode.get(childSpan.node);
+                if (syntheticName !== undefined) {
+                    childSpan.modification.prefix = syntheticName;
+                    childSpan.modification.suffix = '';
+                    childSpan.modification.omitChildren = true;
+                }
+            });
+        }
+    }
+}
+//# sourceMappingURL=DtsEmitHelpers.js.map

package/lib-esm/generators/DtsEmitHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DtsEmitHelpers.js","sourceRoot":"","sources":["../../src/generators/DtsEmitHelpers.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAI5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE;;GAEG;AACH,MAAM,OAAO,cAAc;IAClB,MAAM,CAAC,UAAU,CACtB,MAAsB,EACtB,eAAgC,EAChC,SAAoB;QAEpB,MAAM,YAAY,GAAW,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;QAEvF,QAAQ,SAAS,CAAC,UAAU,EAAE,CAAC;YAC7B,KAAK,aAAa,CAAC,aAAa;gBAC9B,IAAI,eAAe,CAAC,WAAW,KAAK,SAAS,CAAC,UAAU,EAAE,CAAC;oBACzD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,iBAAiB,eAAe,CAAC,WAAW,IAAI,CAAC,CAAC;gBAChF,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,IAAI,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;gBAC1D,CAAC;gBACD,MAAM,CAAC,SAAS,CAAC,UAAU,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC;gBACrD,MAAM;YACR,KAAK,aAAa,CAAC,WAAW;gBAC5B,IAAI,eAAe,CAAC,WAAW,KAAK,SAAS,CAAC,UAAU,EAAE,CAAC;oBACzD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,MAAM,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC;gBAC9D,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,MAAM,SAAS,CAAC,UAAU,OAAO,eAAe,CAAC,WAAW,IAAI,CAAC,CAAC;gBAChG,CAAC;gBACD,MAAM,CAAC,SAAS,CAAC,UAAU,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC;gBACrD,MAAM;YACR,KAAK,aAAa,CAAC,UAAU;gBAC3B,MAAM,CAAC,SAAS,CACd,GAAG,YAAY,SAAS,eAAe,CAAC,WAAW,UAAU,SAAS,CAAC,UAAU,IAAI,CACtF,CAAC;gBACF,MAAM;YACR,KAAK,aAAa,CAAC,YAAY;gBAC7B,MAAM,CAAC,SAAS,CACd,GAAG,YAAY,IAAI,eAAe,CAAC,WAAW,eAAe,SAAS,CAAC,UAAU,KAAK,CACvF,CAAC;gBACF,MAAM;YACR,KAAK,aAAa,CAAC,UAAU;gBAC3B,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;oBAC1B,MAAM,CAAC,SAAS,CACd,GAAG,YAAY,SAAS,eAAe,CAAC,WAAW,UAAU,SAAS,CAAC,UAAU,IAAI,CACtF,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,aAAa,GAAW,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBACjE,IAAI,eAAe,CAAC,WAAW,KAAK,aAAa,EAAE,CAAC;wBAClD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,MAAM,aAAa,IAAI,CAAC,CAAC;oBACvD,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,MAAM,aAAa,OAAO,eAAe,CAAC,WAAW,IAAI,CAAC,CAAC;oBACzF,CAAC;oBACD,MAAM,CAAC,SAAS,CAAC,UAAU,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC;gBACvD,CAAC;gBACD,MAAM;YACR;gBACE,MAAM,IAAI,aAAa,CAAC,6BAA6B,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAEM,MAAM,CAAC,eAAe,CAC3B,MAAsB,EACtB,UAAkB,EAClB,eAAgC;QAEhC,IAAI,UAAU,KAAK,EAAE,CAAC,kBAAkB,CAAC,OAAO,EAAE,CAAC;YACjD,MAAM,CAAC,SAAS,CAAC,kBAAkB,eAAe,CAAC,WAAW,GAAG,CAAC,CAAC;QACrE,CAAC;aAAM,IAAI,eAAe,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;YACtD,MAAM,CAAC,SAAS,CAAC,YAAY,eAAe,CAAC,WAAW,OAAO,UAAU,IAAI,CAAC,CAAC;QACjF,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,SAAS,CAAC,YAAY,UAAU,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAEM,MAAM,CAAC,eAAe,CAAC,MAAsB,EAAE,SAAoB;QACxE,IAAI,SAAS,CAAC,+BAA+B,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzD,MAAM,CAAC,SAAS,EAAE,CAAC;YACnB,KAAK,MAAM,8BAA8B,IAAI,SAAS,CAAC,+BAA+B,EAAE,CAAC;gBACvF,MAAM,CAAC,SAAS,CAAC,kBAAkB,8BAA8B,IAAI,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;IACH,CAAC;IAEM,MAAM,CAAC,oBAAoB,CAChC,SAAoB,EACpB,IAAU,EACV,cAA8B,EAC9B,gBAAgF;;QAEhF,MAAM,IAAI,GAAsB,IAAI,CAAC,IAAyB,CAAC;QAC/D,MAAM,gBAAgB,GAAgC,SAAS,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;QAE1F,IAAI,gBAAgB,EAAE,CAAC;YACrB,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC;gBAClC,2BAA2B;gBAE3B,MAAM,IAAI,aAAa,CAAC,0CAA0C,CAAC,CAAC;YACtE,CAAC;YAED,IAAI,iBAAiB,GAAW,EAAE,CAAC;YAEnC,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxD,kEAAkE;gBAClE,MAAM,gBAAgB,GAAW,IAAI,CAAC,QAAQ,CAAC,SAAS,CACtD,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,aAAa,CACnE,CAAC;gBACF,MAAM,mBAAmB,GAAW,IAAI,CAAC,QAAQ,CAAC,SAAS,CACzD,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,gBAAgB,CACtE,CAAC;gBAEF,IAAI,gBAAgB,GAAG,CAAC,IAAI,mBAAmB,IAAI,gBAAgB,EAAE,CAAC;oBACpE,MAAM,IAAI,aAAa,CACrB,2BAA2B,IAAI,CAAC,OAAO,EAAE,IAAI;wBAC3C,2BAA2B,CAAC,iBAAiB,CAAC,IAAI,CAAC,CACtD,CAAC;gBACJ,CAAC;gBAED,MAAM,kBAAkB,GAAW,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,gBAAgB,GAAG,CAAC,EAAE,mBAAmB,CAAC,CAAC;gBAElG,wDAAwD;gBACxD,kBAAkB,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE;oBACvC,MAAM,mBAAmB,GAAmB,cAAc,CAAC,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC;wBAC9F,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,4BAA4B,CAAC,SAAS,CAAC,IAAI,EAAE,cAAc,CAAC;wBACvF,CAAC,CAAC,cAAc,CAAC;oBAEnB,gBAAgB,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;gBACnD,CAAC,CAAC,CAAC;gBAEH,MAAM,oBAAoB,GAAa,kBAAkB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAC1E,SAAS,CAAC,eAAe,EAAE,CAC5B,CAAC;gBACF,iBAAiB,GAAG,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YAC7D,CAAC;YAED,MAAM,cAAc,GAAW,MAAA,MAAA,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,0CAAG,CAAC,CAAC,mCAAI,EAAE,CAAC;YAExE,IACE,gBAAgB,CAAC,SAAS,YAAY,SAAS;gBAC/C,gBAAgB,CAAC,SAAS,CAAC,UAAU,KAAK,aAAa,CAAC,UAAU;gBAClE,gBAAgB,CAAC,SAAS,CAAC,UAAU,EACrC,CAAC;gBACD,gFAAgF;gBAChF,mEAAmE;gBACnE,MAAM,cAAc,GAAW,MAAA,MAAA,IAAI,CAAC,SAAS,0CAAE,OAAO,EAAE,mCAAI,EAAE,CAAC;gBAC/D,MAAM,qBAAqB,GAAW,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAClE,4BAA4B;gBAC5B,MAAM,oBAAoB,GACxB,qBAAqB,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAEpF,MAAM,WAAW,GAAW,GAAG,gBAAgB,CAAC,WAAW,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,cAAc,EAAE,CAAC;gBAE1H,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;gBAC5B,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,WAAW,CAAC;YACzC,CAAC;iBAAM,CAAC;gBACN,4CAA4C;gBAC5C,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;gBAC5B,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,GAAG,gBAAgB,CAAC,WAAW,GAAG,iBAAiB,GAAG,cAAc,EAAE,CAAC;YACpG,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,2CAA2C,CAAC,IAAa;QACrE,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,MAAM,WAAW,GAA+B,iBAAiB,CAAC,eAAe,CAC/E,IAAI,EACJ,EAAE,CAAC,UAAU,CAAC,WAAW,CAC1B,CAAC;YACF,IAAI,WAAW,EAAE,CAAC;gBAChB,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,2BAA2B,CACvC,KAAyB,EACzB,MAAuF;QAEvF,IAAI,WAAW,GAAW,CAAC,CAAC;QAE5B,iEAAiE;QACjE,KAAK,WAAW,GAAG,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC;YAChE,MAAM,SAAS,GAAY,KAAK,CAAC,WAAW,CAAC,CAAC;YAC9C,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,SAAS;YACX,CAAC;YACD,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YAC7B,IAAI,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1F,4FAA4F;gBAC5F,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,WAAW,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;YACjC,qCAAqC;YACrC,OAAO;QACT,CAAC;QAED,oCAAoC;QACpC,MAAM,gBAAgB,GAAa,EAAE,CAAC;QAEtC,KAAK,IAAI,KAAK,GAAW,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC;YAC1D,MAAM,SAAS,GAAY,KAAK,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,SAAS;YACX,CAAC;YAED,IAAI,CAAC,CAAC,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBAC7F,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACpD,CAAC;QACH,CAAC;QAED,4CAA4C;QAC5C,OAAO,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,WAAW,EAAE,CAAC;YACjD,MAAM,SAAS,GAAY,KAAK,CAAC,WAAW,CAAC,CAAC;YAC9C,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,SAAS;YACX,CAAC;YAED,IAAI,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1F,YAAY;gBACZ,EAAE;gBACF,sDAAsD;gBACtD,mDAAmD;gBACnD,EAAE;gBACF,uDAAuD;gBACvD,sDAAsD;gBACtD,EAAE;gBACF,iCAAiC;gBACjC,EAAE;gBACF,8EAA8E;gBAC9E,+EAA+E;gBAC/E,MAAM,QAAQ,GAAW,OAAO,CAAC;gBACjC,IAAI,OAAO,GAAW,CAAC,CAAC;gBAExB,IAAI,aAAa,GAAW,QAAQ,CAAC;gBACrC,OAAO,gBAAgB,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;oBAChD,aAAa,GAAG,GAAG,QAAQ,GAAG,OAAO,EAAE,EAAE,CAAC;gBAC5C,CAAC;gBACD,gBAAgB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;gBAErC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAEM,MAAM,CAAC,uBAAuB,CAAC,aAAmB;QACvD,MAAM,oBAAoB,GAAyB,IAAI,GAAG,EAAE,CAAC;QAE7D,cAAc,CAAC,2BAA2B,CACxC,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,EAChC,CAAC,SAAkC,EAAE,aAAiC,EAAQ,EAAE;YAC9E,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;gBAChC,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC,CACF,CAAC;QAEF,IAAI,oBAAoB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YAClC,aAAa,CAAC,OAAO,CAAC,CAAC,SAAe,EAAQ,EAAE;gBAC9C,MAAM,aAAa,GAAuB,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;gBACnF,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;oBAChC,SAAS,CAAC,YAAY,CAAC,MAAM,GAAG,aAAa,CAAC;oBAC9C,SAAS,CAAC,YAAY,CAAC,MAAM,GAAG,EAAE,CAAC;oBACnC,SAAS,CAAC,YAAY,CAAC,YAAY,GAAG,IAAI,CAAC;gBAC7C,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;IACH,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\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport type { CollectorEntity } from '../collector/CollectorEntity';\nimport { AstImport, AstImportKind } from '../analyzer/AstImport';\nimport { AstDeclaration } from '../analyzer/AstDeclaration';\nimport type { Collector } from '../collector/Collector';\nimport type { Span } from '../analyzer/Span';\nimport type { IndentedWriter } from './IndentedWriter';\nimport { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';\nimport { TypeScriptHelpers } from '../analyzer/TypeScriptHelpers';\n\n/**\n * Some common code shared between DtsRollupGenerator and ApiReportGenerator.\n */\nexport class DtsEmitHelpers {\n  public static emitImport(\n    writer: IndentedWriter,\n    collectorEntity: CollectorEntity,\n    astImport: AstImport\n  ): void {\n    const importPrefix: string = astImport.isTypeOnlyEverywhere ? 'import type' : 'import';\n\n    switch (astImport.importKind) {\n      case AstImportKind.DefaultImport:\n        if (collectorEntity.nameForEmit !== astImport.exportName) {\n          writer.write(`${importPrefix} { default as ${collectorEntity.nameForEmit} }`);\n        } else {\n          writer.write(`${importPrefix} ${astImport.exportName}`);\n        }\n        writer.writeLine(` from '${astImport.modulePath}';`);\n        break;\n      case AstImportKind.NamedImport:\n        if (collectorEntity.nameForEmit === astImport.exportName) {\n          writer.write(`${importPrefix} { ${astImport.exportName} }`);\n        } else {\n          writer.write(`${importPrefix} { ${astImport.exportName} as ${collectorEntity.nameForEmit} }`);\n        }\n        writer.writeLine(` from '${astImport.modulePath}';`);\n        break;\n      case AstImportKind.StarImport:\n        writer.writeLine(\n          `${importPrefix} * as ${collectorEntity.nameForEmit} from '${astImport.modulePath}';`\n        );\n        break;\n      case AstImportKind.EqualsImport:\n        writer.writeLine(\n          `${importPrefix} ${collectorEntity.nameForEmit} = require('${astImport.modulePath}');`\n        );\n        break;\n      case AstImportKind.ImportType:\n        if (!astImport.exportName) {\n          writer.writeLine(\n            `${importPrefix} * as ${collectorEntity.nameForEmit} from '${astImport.modulePath}';`\n          );\n        } else {\n          const topExportName: string = astImport.exportName.split('.')[0];\n          if (collectorEntity.nameForEmit === topExportName) {\n            writer.write(`${importPrefix} { ${topExportName} }`);\n          } else {\n            writer.write(`${importPrefix} { ${topExportName} as ${collectorEntity.nameForEmit} }`);\n          }\n          writer.writeLine(` from '${astImport.modulePath}';`);\n        }\n        break;\n      default:\n        throw new InternalError('Unimplemented AstImportKind');\n    }\n  }\n\n  public static emitNamedExport(\n    writer: IndentedWriter,\n    exportName: string,\n    collectorEntity: CollectorEntity\n  ): void {\n    if (exportName === ts.InternalSymbolName.Default) {\n      writer.writeLine(`export default ${collectorEntity.nameForEmit};`);\n    } else if (collectorEntity.nameForEmit !== exportName) {\n      writer.writeLine(`export { ${collectorEntity.nameForEmit} as ${exportName} }`);\n    } else {\n      writer.writeLine(`export { ${exportName} }`);\n    }\n  }\n\n  public static emitStarExports(writer: IndentedWriter, collector: Collector): void {\n    if (collector.starExportedExternalModulePaths.length > 0) {\n      writer.writeLine();\n      for (const starExportedExternalModulePath of collector.starExportedExternalModulePaths) {\n        writer.writeLine(`export * from \"${starExportedExternalModulePath}\";`);\n      }\n    }\n  }\n\n  public static modifyImportTypeSpan(\n    collector: Collector,\n    span: Span,\n    astDeclaration: AstDeclaration,\n    modifyNestedSpan: (childSpan: Span, childAstDeclaration: AstDeclaration) => void\n  ): void {\n    const node: ts.ImportTypeNode = span.node as ts.ImportTypeNode;\n    const referencedEntity: CollectorEntity | undefined = collector.tryGetEntityForNode(node);\n\n    if (referencedEntity) {\n      if (!referencedEntity.nameForEmit) {\n        // This should never happen\n\n        throw new InternalError('referencedEntry.nameForEmit is undefined');\n      }\n\n      let typeArgumentsText: string = '';\n\n      if (node.typeArguments && node.typeArguments.length > 0) {\n        // Type arguments have to be processed and written to the document\n        const lessThanTokenPos: number = span.children.findIndex(\n          (childSpan) => childSpan.node.kind === ts.SyntaxKind.LessThanToken\n        );\n        const greaterThanTokenPos: number = span.children.findIndex(\n          (childSpan) => childSpan.node.kind === ts.SyntaxKind.GreaterThanToken\n        );\n\n        if (lessThanTokenPos < 0 || greaterThanTokenPos <= lessThanTokenPos) {\n          throw new InternalError(\n            `Invalid type arguments: ${node.getText()}\\n` +\n              SourceFileLocationFormatter.formatDeclaration(node)\n          );\n        }\n\n        const typeArgumentsSpans: Span[] = span.children.slice(lessThanTokenPos + 1, greaterThanTokenPos);\n\n        // Apply modifications to Span elements of typeArguments\n        typeArgumentsSpans.forEach((childSpan) => {\n          const childAstDeclaration: AstDeclaration = AstDeclaration.isSupportedSyntaxKind(childSpan.kind)\n            ? collector.astSymbolTable.getChildAstDeclarationByNode(childSpan.node, astDeclaration)\n            : astDeclaration;\n\n          modifyNestedSpan(childSpan, childAstDeclaration);\n        });\n\n        const typeArgumentsStrings: string[] = typeArgumentsSpans.map((childSpan) =>\n          childSpan.getModifiedText()\n        );\n        typeArgumentsText = `<${typeArgumentsStrings.join(', ')}>`;\n      }\n\n      const separatorAfter: string = /(\\s*)$/.exec(span.getText())?.[1] ?? '';\n\n      if (\n        referencedEntity.astEntity instanceof AstImport &&\n        referencedEntity.astEntity.importKind === AstImportKind.ImportType &&\n        referencedEntity.astEntity.exportName\n      ) {\n        // For an ImportType with a namespace chain, only the top namespace is imported.\n        // Must add the original nested qualifiers to the rolled up import.\n        const qualifiersText: string = node.qualifier?.getText() ?? '';\n        const nestedQualifiersStart: number = qualifiersText.indexOf('.');\n        // Including the leading \".\"\n        const nestedQualifiersText: string =\n          nestedQualifiersStart >= 0 ? qualifiersText.substring(nestedQualifiersStart) : '';\n\n        const replacement: string = `${referencedEntity.nameForEmit}${nestedQualifiersText}${typeArgumentsText}${separatorAfter}`;\n\n        span.modification.skipAll();\n        span.modification.prefix = replacement;\n      } else {\n        // Replace with internal symbol or AstImport\n        span.modification.skipAll();\n        span.modification.prefix = `${referencedEntity.nameForEmit}${typeArgumentsText}${separatorAfter}`;\n      }\n    }\n  }\n\n  /**\n   * Checks if an export keyword is part of an ExportDeclaration inside a namespace\n   * (e.g., \"export { Foo, Bar };\" inside \"declare namespace SDK { ... }\").\n   * In that case, the export keyword must be preserved, otherwise the output is invalid TypeScript.\n   */\n  public static isExportKeywordInNamespaceExportDeclaration(node: ts.Node): boolean {\n    if (node.parent && ts.isExportDeclaration(node.parent)) {\n      const moduleBlock: ts.ModuleBlock | undefined = TypeScriptHelpers.findFirstParent(\n        node,\n        ts.SyntaxKind.ModuleBlock\n      );\n      if (moduleBlock) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  /**\n   * Given an array that includes some parameter nodes, this returns an array of the same length;\n   * elements that are not undefined correspond to a parameter that should be renamed.\n   */\n  public static forEachParameterToNormalize(\n    nodes: ArrayLike<ts.Node>,\n    action: (parameter: ts.ParameterDeclaration, syntheticName: string | undefined) => void\n  ): void {\n    let actionIndex: number = 0;\n\n    // Optimistically assume that no parameters need to be normalized\n    for (actionIndex = 0; actionIndex < nodes.length; ++actionIndex) {\n      const parameter: ts.Node = nodes[actionIndex];\n      if (!ts.isParameter(parameter)) {\n        continue;\n      }\n      action(parameter, undefined);\n      if (ts.isObjectBindingPattern(parameter.name) || ts.isArrayBindingPattern(parameter.name)) {\n        // Our optimistic assumption was not true; we'll need to stop and calculate alreadyUsedNames\n        break;\n      }\n    }\n\n    if (actionIndex === nodes.length) {\n      // Our optimistic assumption was true\n      return;\n    }\n\n    // First, calculate alreadyUsedNames\n    const alreadyUsedNames: string[] = [];\n\n    for (let index: number = 0; index < nodes.length; ++index) {\n      const parameter: ts.Node = nodes[index];\n      if (!ts.isParameter(parameter)) {\n        continue;\n      }\n\n      if (!(ts.isObjectBindingPattern(parameter.name) || ts.isArrayBindingPattern(parameter.name))) {\n        alreadyUsedNames.push(parameter.name.text.trim());\n      }\n    }\n\n    // Now continue with the rest of the actions\n    for (; actionIndex < nodes.length; ++actionIndex) {\n      const parameter: ts.Node = nodes[actionIndex];\n      if (!ts.isParameter(parameter)) {\n        continue;\n      }\n\n      if (ts.isObjectBindingPattern(parameter.name) || ts.isArrayBindingPattern(parameter.name)) {\n        // Examples:\n        //\n        //      function f({ y, z }: { y: string, z: string })\n        // ---> function f(input: { y: string, z: string })\n        //\n        //      function f(x: number, [a, b]: [number, number])\n        // ---> function f(x: number, input: [number, number])\n        //\n        // Example of a naming collision:\n        //\n        //      function f({ a }: { a: string }, { b }: { b: string }, input2: string)\n        // ---> function f(input: { a: string }, input3: { b: string }, input2: string)\n        const baseName: string = 'input';\n        let counter: number = 2;\n\n        let syntheticName: string = baseName;\n        while (alreadyUsedNames.includes(syntheticName)) {\n          syntheticName = `${baseName}${counter++}`;\n        }\n        alreadyUsedNames.push(syntheticName);\n\n        action(parameter, syntheticName);\n      } else {\n        action(parameter, undefined);\n      }\n    }\n  }\n\n  public static normalizeParameterNames(signatureSpan: Span): void {\n    const syntheticNamesByNode: Map<ts.Node, string> = new Map();\n\n    DtsEmitHelpers.forEachParameterToNormalize(\n      signatureSpan.node.getChildren(),\n      (parameter: ts.ParameterDeclaration, syntheticName: string | undefined): void => {\n        if (syntheticName !== undefined) {\n          syntheticNamesByNode.set(parameter.name, syntheticName);\n        }\n      }\n    );\n\n    if (syntheticNamesByNode.size > 0) {\n      signatureSpan.forEach((childSpan: Span): void => {\n        const syntheticName: string | undefined = syntheticNamesByNode.get(childSpan.node);\n        if (syntheticName !== undefined) {\n          childSpan.modification.prefix = syntheticName;\n          childSpan.modification.suffix = '';\n          childSpan.modification.omitChildren = true;\n        }\n      });\n    }\n  }\n}\n"]}