@microsoft/api-extractor 7.56.3 → 7.57.1

package/CHANGELOG.json

@@ -1,6 +1,64 @@
 {
   "name": "@microsoft/api-extractor",
   "entries": [
+    {
+      "version": "7.57.1",
+      "tag": "@microsoft/api-extractor_v7.57.1",
+      "date": "Fri, 20 Feb 2026 00:15:03 GMT",
+      "comments": {
+        "patch": [
+          {
+            "comment": "Add `\"node\"` condition before `\"import\"` in the `\"exports\"` map so that Node.js uses the CJS output (which handles extensionless imports), while bundlers still use ESM via `\"import\"`. Fixes https://github.com/microsoft/rushstack/issues/5644."
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.33.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.20.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/rig-package\" to `0.7.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.22.1`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/ts-command-line\" to `5.3.1`"
+          }
+        ]
+      }
+    },
+    {
+      "version": "7.57.0",
+      "tag": "@microsoft/api-extractor_v7.57.0",
+      "date": "Thu, 19 Feb 2026 00:04:52 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Normalize package layout. CommonJS is now under `lib-commonjs`, DTS is now under `lib-dts`, and ESM is now under `lib-esm`. Imports to `lib` still work as before, handled by the `\"exports\"` field in `package.json`."
+          }
+        ],
+        "dependency": [
+          {
+            "comment": "Updating dependency \"@microsoft/api-extractor-model\" to `7.33.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/node-core-library\" to `5.20.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/rig-package\" to `0.7.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/terminal\" to `0.22.0`"
+          },
+          {
+            "comment": "Updating dependency \"@rushstack/ts-command-line\" to `5.3.0`"
+          }
+        ]
+      }
+    },
     {
       "version": "7.56.3",
       "tag": "@microsoft/api-extractor_v7.56.3",

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Change Log - @microsoft/api-extractor
 
-This log was last generated on Sat, 07 Feb 2026 01:13:26 GMT and should not be manually modified.
+This log was last generated on Fri, 20 Feb 2026 00:15:03 GMT and should not be manually modified.
+
+## 7.57.1
+Fri, 20 Feb 2026 00:15:03 GMT
+
+### Patches
+
+- Add `"node"` condition before `"import"` in the `"exports"` map so that Node.js uses the CJS output (which handles extensionless imports), while bundlers still use ESM via `"import"`. Fixes https://github.com/microsoft/rushstack/issues/5644.
+
+## 7.57.0
+Thu, 19 Feb 2026 00:04:52 GMT
+
+### Minor changes
+
+- Normalize package layout. CommonJS is now under `lib-commonjs`, DTS is now under `lib-dts`, and ESM is now under `lib-esm`. Imports to `lib` still work as before, handled by the `"exports"` field in `package.json`.
 
 ## 7.56.3
 Sat, 07 Feb 2026 01:13:26 GMT

package/bin/api-extractor

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-require('../lib/start.js');
+require('../lib-commonjs/start.js');

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.55.2"
+      "packageVersion": "7.57.0"
     }
   ]
 }

package/lib-esm/aedoc/PackageDocComment.js

@@ -0,0 +1,56 @@
+// 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 { ExtractorMessageId } from '../api/ExtractorMessageId';
+export class PackageDocComment {
+    /**
+     * For the given source file, see if it starts with a TSDoc comment containing the `@packageDocumentation` tag.
+     */
+    static tryFindInSourceFile(sourceFile, collector) {
+        // The @packageDocumentation comment is special because it is not attached to an AST
+        // definition.  Instead, it is part of the "trivia" tokens that the compiler treats
+        // as irrelevant white space.
+        //
+        // WARNING: If the comment doesn't precede an export statement, the compiler will omit
+        // it from the *.d.ts file, and API Extractor won't find it.  If this happens, you need
+        // to rearrange your statements to ensure it is passed through.
+        //
+        // This implementation assumes that the "@packageDocumentation" will be in the first TSDoc comment
+        // that appears in the entry point *.d.ts file.  We could possibly look in other places,
+        // but the above warning suggests enforcing a standardized layout.  This design choice is open
+        // to feedback.
+        let packageCommentRange = undefined; // empty string
+        for (const commentRange of ts.getLeadingCommentRanges(sourceFile.text, sourceFile.getFullStart()) || []) {
+            if (commentRange.kind === ts.SyntaxKind.MultiLineCommentTrivia) {
+                const commentBody = sourceFile.text.substring(commentRange.pos, commentRange.end);
+                // Choose the first JSDoc-style comment
+                if (/^\s*\/\*\*/.test(commentBody)) {
+                    // But only if it looks like it's trying to be @packageDocumentation
+                    // (The TSDoc parser will validate this more rigorously)
+                    if (/\@packageDocumentation/i.test(commentBody)) {
+                        packageCommentRange = commentRange;
+                    }
+                    break;
+                }
+            }
+        }
+        if (!packageCommentRange) {
+            // If we didn't find the @packageDocumentation tag in the expected place, is it in some
+            // wrong place?  This sanity check helps people to figure out why there comment isn't working.
+            for (const statement of sourceFile.statements) {
+                const ranges = [];
+                ranges.push(...(ts.getLeadingCommentRanges(sourceFile.text, statement.getFullStart()) || []));
+                ranges.push(...(ts.getTrailingCommentRanges(sourceFile.text, statement.getEnd()) || []));
+                for (const commentRange of ranges) {
+                    const commentBody = sourceFile.text.substring(commentRange.pos, commentRange.end);
+                    if (/\@packageDocumentation/i.test(commentBody)) {
+                        collector.messageRouter.addAnalyzerIssueForPosition(ExtractorMessageId.MisplacedPackageTag, 'The @packageDocumentation comment must appear at the top of entry point *.d.ts file', sourceFile, commentRange.pos);
+                        break;
+                    }
+                }
+            }
+        }
+        return packageCommentRange;
+    }
+}
+//# sourceMappingURL=PackageDocComment.js.map

package/lib-esm/aedoc/PackageDocComment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackageDocComment.js","sourceRoot":"","sources":["../../src/aedoc/PackageDocComment.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,OAAO,iBAAiB;IAC5B;;OAEG;IACI,MAAM,CAAC,mBAAmB,CAC/B,UAAyB,EACzB,SAAoB;QAEpB,oFAAoF;QACpF,mFAAmF;QACnF,6BAA6B;QAC7B,EAAE;QACF,sFAAsF;QACtF,uFAAuF;QACvF,+DAA+D;QAC/D,EAAE;QACF,kGAAkG;QAClG,wFAAwF;QACxF,8FAA8F;QAC9F,eAAe;QACf,IAAI,mBAAmB,GAA6B,SAAS,CAAC,CAAC,eAAe;QAE9E,KAAK,MAAM,YAAY,IAAI,EAAE,CAAC,uBAAuB,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;YACxG,IAAI,YAAY,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC;gBAC/D,MAAM,WAAW,GAAW,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;gBAE1F,uCAAuC;gBACvC,IAAI,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;oBACnC,oEAAoE;oBACpE,wDAAwD;oBACxD,IAAI,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;wBAChD,mBAAmB,GAAG,YAAY,CAAC;oBACrC,CAAC;oBACD,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACzB,uFAAuF;YACvF,8FAA8F;YAC9F,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC;gBAC9C,MAAM,MAAM,GAAsB,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,uBAAuB,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC9F,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,wBAAwB,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAEzF,KAAK,MAAM,YAAY,IAAI,MAAM,EAAE,CAAC;oBAClC,MAAM,WAAW,GAAW,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;oBAE1F,IAAI,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;wBAChD,SAAS,CAAC,aAAa,CAAC,2BAA2B,CACjD,kBAAkB,CAAC,mBAAmB,EACtC,qFAAqF,EACrF,UAAU,EACV,YAAY,CAAC,GAAG,CACjB,CAAC;wBACF,MAAM;oBACR,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,mBAAmB,CAAC;IAC7B,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 type { Collector } from '../collector/Collector';\nimport { ExtractorMessageId } from '../api/ExtractorMessageId';\n\nexport class PackageDocComment {\n  /**\n   * For the given source file, see if it starts with a TSDoc comment containing the `@packageDocumentation` tag.\n   */\n  public static tryFindInSourceFile(\n    sourceFile: ts.SourceFile,\n    collector: Collector\n  ): ts.TextRange | undefined {\n    // The @packageDocumentation comment is special because it is not attached to an AST\n    // definition.  Instead, it is part of the \"trivia\" tokens that the compiler treats\n    // as irrelevant white space.\n    //\n    // WARNING: If the comment doesn't precede an export statement, the compiler will omit\n    // it from the *.d.ts file, and API Extractor won't find it.  If this happens, you need\n    // to rearrange your statements to ensure it is passed through.\n    //\n    // This implementation assumes that the \"@packageDocumentation\" will be in the first TSDoc comment\n    // that appears in the entry point *.d.ts file.  We could possibly look in other places,\n    // but the above warning suggests enforcing a standardized layout.  This design choice is open\n    // to feedback.\n    let packageCommentRange: ts.TextRange | undefined = undefined; // empty string\n\n    for (const commentRange of ts.getLeadingCommentRanges(sourceFile.text, sourceFile.getFullStart()) || []) {\n      if (commentRange.kind === ts.SyntaxKind.MultiLineCommentTrivia) {\n        const commentBody: string = sourceFile.text.substring(commentRange.pos, commentRange.end);\n\n        // Choose the first JSDoc-style comment\n        if (/^\\s*\\/\\*\\*/.test(commentBody)) {\n          // But only if it looks like it's trying to be @packageDocumentation\n          // (The TSDoc parser will validate this more rigorously)\n          if (/\\@packageDocumentation/i.test(commentBody)) {\n            packageCommentRange = commentRange;\n          }\n          break;\n        }\n      }\n    }\n\n    if (!packageCommentRange) {\n      // If we didn't find the @packageDocumentation tag in the expected place, is it in some\n      // wrong place?  This sanity check helps people to figure out why there comment isn't working.\n      for (const statement of sourceFile.statements) {\n        const ranges: ts.CommentRange[] = [];\n        ranges.push(...(ts.getLeadingCommentRanges(sourceFile.text, statement.getFullStart()) || []));\n        ranges.push(...(ts.getTrailingCommentRanges(sourceFile.text, statement.getEnd()) || []));\n\n        for (const commentRange of ranges) {\n          const commentBody: string = sourceFile.text.substring(commentRange.pos, commentRange.end);\n\n          if (/\\@packageDocumentation/i.test(commentBody)) {\n            collector.messageRouter.addAnalyzerIssueForPosition(\n              ExtractorMessageId.MisplacedPackageTag,\n              'The @packageDocumentation comment must appear at the top of entry point *.d.ts file',\n              sourceFile,\n              commentRange.pos\n            );\n            break;\n          }\n        }\n      }\n    }\n\n    return packageCommentRange;\n  }\n}\n"]}

package/lib-esm/analyzer/AstDeclaration.js

@@ -0,0 +1,214 @@
+// 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 { Span } from './Span';
+/**
+ * The AstDeclaration and AstSymbol classes are API Extractor's equivalent of the compiler's
+ * ts.Declaration and ts.Symbol objects.  They are created by the `AstSymbolTable` class.
+ *
+ * @remarks
+ * The AstDeclaration represents one or more syntax components of a symbol.  Usually there is
+ * only one AstDeclaration per AstSymbol, but certain TypeScript constructs can have multiple
+ * declarations (e.g. overloaded functions, merged declarations, etc.).
+ *
+ * Because of this, the `AstDeclaration` manages the parent/child nesting hierarchy (e.g. with
+ * declaration merging, each declaration has its own children) and becomes the main focus
+ * of analyzing AEDoc and emitting *.d.ts files.
+ *
+ * The AstDeclarations correspond to items from the compiler's ts.Node hierarchy, but
+ * omitting/skipping any nodes that don't match the AstDeclaration.isSupportedSyntaxKind()
+ * criteria.  This simplification makes the other API Extractor stages easier to implement.
+ */
+export class AstDeclaration {
+    constructor(options) {
+        // NOTE: This array becomes immutable after astSymbol.analyze() sets astSymbol.analyzed=true
+        this._analyzedChildren = [];
+        this._analyzedReferencedAstEntitiesSet = new Set();
+        // Reverse lookup used by findChildrenWithName()
+        this._childrenByName = undefined;
+        this.declaration = options.declaration;
+        this.astSymbol = options.astSymbol;
+        this.parent = options.parent;
+        this.astSymbol._notifyDeclarationAttach(this);
+        if (this.parent) {
+            this.parent._notifyChildAttach(this);
+        }
+        this.modifierFlags = ts.getCombinedModifierFlags(this.declaration);
+        // Check for ECMAScript private fields, for example:
+        //
+        //    class Person { #name: string; }
+        //
+        const declarationName = ts.getNameOfDeclaration(this.declaration);
+        if (declarationName) {
+            if (ts.isPrivateIdentifier(declarationName)) {
+                // eslint-disable-next-line no-bitwise
+                this.modifierFlags |= ts.ModifierFlags.Private;
+            }
+        }
+    }
+    /**
+     * Returns the children for this AstDeclaration.
+     * @remarks
+     * The collection will be empty until AstSymbol.analyzed is true.
+     */
+    get children() {
+        return this.astSymbol.analyzed ? this._analyzedChildren : [];
+    }
+    /**
+     * Returns the AstEntity objects referenced by this node.
+     * @remarks
+     * NOTE: The collection will be empty until AstSymbol.analyzed is true.
+     *
+     * Since we assume references are always collected by a traversal starting at the
+     * root of the nesting declarations, this array omits the following items because they
+     * would be redundant:
+     * - symbols corresponding to parents of this declaration (e.g. a method that returns its own class)
+     * - symbols already listed in the referencedAstSymbols property for parents of this declaration
+     *   (e.g. a method that returns its own class's base class)
+     * - symbols that are referenced only by nested children of this declaration
+     *   (e.g. if a method returns an enum, this doesn't imply that the method's class references that enum)
+     */
+    get referencedAstEntities() {
+        return this.astSymbol.analyzed ? [...this._analyzedReferencedAstEntitiesSet] : [];
+    }
+    /**
+     * This is an internal callback used when the AstSymbolTable attaches a new
+     * child AstDeclaration to this object.
+     * @internal
+     */
+    _notifyChildAttach(child) {
+        if (child.parent !== this) {
+            throw new InternalError('Invalid call to notifyChildAttach()');
+        }
+        if (this.astSymbol.analyzed) {
+            throw new InternalError('_notifyChildAttach() called after analysis is already complete');
+        }
+        this._analyzedChildren.push(child);
+    }
+    /**
+     * Returns a diagnostic dump of the tree, which reports the hierarchy of
+     * AstDefinition objects.
+     */
+    getDump(indent = '') {
+        const declarationKind = ts.SyntaxKind[this.declaration.kind];
+        let result = indent + `+ ${this.astSymbol.localName} (${declarationKind})`;
+        if (this.astSymbol.nominalAnalysis) {
+            result += ' (nominal)';
+        }
+        result += '\n';
+        for (const referencedAstEntity of this._analyzedReferencedAstEntitiesSet.values()) {
+            result += indent + `  ref: ${referencedAstEntity.localName}\n`;
+        }
+        for (const child of this.children) {
+            result += child.getDump(indent + '  ');
+        }
+        return result;
+    }
+    /**
+     * Returns a diagnostic dump using Span.getDump(), which reports the detailed
+     * compiler structure.
+     */
+    getSpanDump(indent = '') {
+        const span = new Span(this.declaration);
+        return span.getDump(indent);
+    }
+    /**
+     * This is an internal callback used when AstSymbolTable.analyze() discovers a new
+     * type reference associated with this declaration.
+     * @internal
+     */
+    _notifyReferencedAstEntity(referencedAstEntity) {
+        if (this.astSymbol.analyzed) {
+            throw new InternalError('_notifyReferencedAstEntity() called after analysis is already complete');
+        }
+        for (let current = this; current; current = current.parent) {
+            // Don't add references to symbols that are already referenced by a parent
+            if (current._analyzedReferencedAstEntitiesSet.has(referencedAstEntity)) {
+                return;
+            }
+            // Don't add the symbols of parents either
+            if (referencedAstEntity === current.astSymbol) {
+                return;
+            }
+        }
+        this._analyzedReferencedAstEntitiesSet.add(referencedAstEntity);
+    }
+    /**
+     * Visits all the current declaration and all children recursively in a depth-first traversal,
+     * and performs the specified action for each one.
+     */
+    forEachDeclarationRecursive(action) {
+        action(this);
+        for (const child of this.children) {
+            child.forEachDeclarationRecursive(action);
+        }
+    }
+    /**
+     * Returns the list of child declarations whose `AstSymbol.localName` matches the provided `name`.
+     *
+     * @remarks
+     * This is an efficient O(1) lookup.
+     */
+    findChildrenWithName(name) {
+        // The children property returns:
+        //
+        //    return this.astSymbol.analyzed ? this._analyzedChildren : [];
+        //
+        if (!this.astSymbol.analyzed || this._analyzedChildren.length === 0) {
+            return [];
+        }
+        if (this._childrenByName === undefined) {
+            // Build the lookup table
+            const childrenByName = new Map();
+            for (const child of this._analyzedChildren) {
+                const childName = child.astSymbol.localName;
+                let array = childrenByName.get(childName);
+                if (array === undefined) {
+                    array = [];
+                    childrenByName.set(childName, array);
+                }
+                array.push(child);
+            }
+            this._childrenByName = childrenByName;
+        }
+        return this._childrenByName.get(name) || [];
+    }
+    /**
+     * This function determines which ts.Node kinds will generate an AstDeclaration.
+     * These correspond to the definitions that we can add AEDoc to.
+     */
+    static isSupportedSyntaxKind(kind) {
+        // (alphabetical order)
+        switch (kind) {
+            case ts.SyntaxKind.CallSignature:
+            case ts.SyntaxKind.ClassDeclaration:
+            case ts.SyntaxKind.ConstructSignature: // Example: "new(x: number): IMyClass"
+            case ts.SyntaxKind.Constructor: // Example: "constructor(x: number)"
+            case ts.SyntaxKind.EnumDeclaration:
+            case ts.SyntaxKind.EnumMember:
+            case ts.SyntaxKind.FunctionDeclaration: // Example: "(x: number): number"
+            case ts.SyntaxKind.GetAccessor:
+            case ts.SyntaxKind.SetAccessor:
+            case ts.SyntaxKind.IndexSignature: // Example: "[key: string]: string"
+            case ts.SyntaxKind.InterfaceDeclaration:
+            case ts.SyntaxKind.MethodDeclaration:
+            case ts.SyntaxKind.MethodSignature:
+            case ts.SyntaxKind.ModuleDeclaration: // Used for both "module" and "namespace" declarations
+            case ts.SyntaxKind.PropertyDeclaration:
+            case ts.SyntaxKind.PropertySignature:
+            case ts.SyntaxKind.TypeAliasDeclaration: // Example: "type Shape = Circle | Square"
+            case ts.SyntaxKind.VariableDeclaration:
+                return true;
+            // NOTE: Prior to TypeScript 3.7, in the emitted .d.ts files, the compiler would merge a GetAccessor/SetAccessor
+            // pair into a single PropertyDeclaration.
+            // NOTE: In contexts where a source file is treated as a module, we do create "nominal analysis"
+            // AstSymbol objects corresponding to a ts.SyntaxKind.SourceFile node.  However, a source file
+            // is NOT considered a nesting structure, and it does NOT act as a root for the declarations
+            // appearing in the file.  This is because the *.d.ts generator is in the business of rolling up
+            // source files, and thus wants to ignore them in general.
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=AstDeclaration.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstDeclaration.js","sourceRoot":"","sources":["../../src/analyzer/AstDeclaration.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\nimport * as ts from 'typescript';\n\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport type { AstSymbol } from './AstSymbol';\nimport { Span } from './Span';\nimport type { AstEntity } from './AstEntity';\n\n/**\n * Constructor options for AstDeclaration\n */\nexport interface IAstDeclarationOptions {\n  readonly declaration: ts.Declaration;\n  readonly astSymbol: AstSymbol;\n  readonly parent: AstDeclaration | undefined;\n}\n\n/**\n * The AstDeclaration and AstSymbol classes are API Extractor's equivalent of the compiler's\n * ts.Declaration and ts.Symbol objects.  They are created by the `AstSymbolTable` class.\n *\n * @remarks\n * The AstDeclaration represents one or more syntax components of a symbol.  Usually there is\n * only one AstDeclaration per AstSymbol, but certain TypeScript constructs can have multiple\n * declarations (e.g. overloaded functions, merged declarations, etc.).\n *\n * Because of this, the `AstDeclaration` manages the parent/child nesting hierarchy (e.g. with\n * declaration merging, each declaration has its own children) and becomes the main focus\n * of analyzing AEDoc and emitting *.d.ts files.\n *\n * The AstDeclarations correspond to items from the compiler's ts.Node hierarchy, but\n * omitting/skipping any nodes that don't match the AstDeclaration.isSupportedSyntaxKind()\n * criteria.  This simplification makes the other API Extractor stages easier to implement.\n */\nexport class AstDeclaration {\n  public readonly declaration: ts.Declaration;\n\n  public readonly astSymbol: AstSymbol;\n\n  /**\n   * The parent, if this object is nested inside another AstDeclaration.\n   */\n  public readonly parent: AstDeclaration | undefined;\n\n  /**\n   * A bit set of TypeScript modifiers such as \"private\", \"protected\", etc.\n   */\n  public readonly modifierFlags: ts.ModifierFlags;\n\n  /**\n   * Additional information that is calculated later by the `Collector`.  The actual type is `DeclarationMetadata`,\n   * but we declare it as `unknown` because consumers must obtain this object by calling\n   * `Collector.fetchDeclarationMetadata()`.\n   */\n  public declarationMetadata: unknown;\n\n  /**\n   * Additional information that is calculated later by the `Collector`.  The actual type is `ApiItemMetadata`,\n   * but we declare it as `unknown` because consumers must obtain this object by calling\n   * `Collector.fetchApiItemMetadata()`.\n   */\n  public apiItemMetadata: unknown;\n\n  // NOTE: This array becomes immutable after astSymbol.analyze() sets astSymbol.analyzed=true\n  private readonly _analyzedChildren: AstDeclaration[] = [];\n\n  private readonly _analyzedReferencedAstEntitiesSet: Set<AstEntity> = new Set<AstEntity>();\n\n  // Reverse lookup used by findChildrenWithName()\n  private _childrenByName: Map<string, AstDeclaration[]> | undefined = undefined;\n\n  public constructor(options: IAstDeclarationOptions) {\n    this.declaration = options.declaration;\n    this.astSymbol = options.astSymbol;\n    this.parent = options.parent;\n\n    this.astSymbol._notifyDeclarationAttach(this);\n\n    if (this.parent) {\n      this.parent._notifyChildAttach(this);\n    }\n\n    this.modifierFlags = ts.getCombinedModifierFlags(this.declaration);\n\n    // Check for ECMAScript private fields, for example:\n    //\n    //    class Person { #name: string; }\n    //\n    const declarationName: ts.DeclarationName | undefined = ts.getNameOfDeclaration(this.declaration);\n    if (declarationName) {\n      if (ts.isPrivateIdentifier(declarationName)) {\n        // eslint-disable-next-line no-bitwise\n        this.modifierFlags |= ts.ModifierFlags.Private;\n      }\n    }\n  }\n\n  /**\n   * Returns the children for this AstDeclaration.\n   * @remarks\n   * The collection will be empty until AstSymbol.analyzed is true.\n   */\n  public get children(): ReadonlyArray<AstDeclaration> {\n    return this.astSymbol.analyzed ? this._analyzedChildren : [];\n  }\n\n  /**\n   * Returns the AstEntity objects referenced by this node.\n   * @remarks\n   * NOTE: The collection will be empty until AstSymbol.analyzed is true.\n   *\n   * Since we assume references are always collected by a traversal starting at the\n   * root of the nesting declarations, this array omits the following items because they\n   * would be redundant:\n   * - symbols corresponding to parents of this declaration (e.g. a method that returns its own class)\n   * - symbols already listed in the referencedAstSymbols property for parents of this declaration\n   *   (e.g. a method that returns its own class's base class)\n   * - symbols that are referenced only by nested children of this declaration\n   *   (e.g. if a method returns an enum, this doesn't imply that the method's class references that enum)\n   */\n  public get referencedAstEntities(): ReadonlyArray<AstEntity> {\n    return this.astSymbol.analyzed ? [...this._analyzedReferencedAstEntitiesSet] : [];\n  }\n\n  /**\n   * This is an internal callback used when the AstSymbolTable attaches a new\n   * child AstDeclaration to this object.\n   * @internal\n   */\n  public _notifyChildAttach(child: AstDeclaration): void {\n    if (child.parent !== this) {\n      throw new InternalError('Invalid call to notifyChildAttach()');\n    }\n\n    if (this.astSymbol.analyzed) {\n      throw new InternalError('_notifyChildAttach() called after analysis is already complete');\n    }\n\n    this._analyzedChildren.push(child);\n  }\n\n  /**\n   * Returns a diagnostic dump of the tree, which reports the hierarchy of\n   * AstDefinition objects.\n   */\n  public getDump(indent: string = ''): string {\n    const declarationKind: string = ts.SyntaxKind[this.declaration.kind];\n    let result: string = indent + `+ ${this.astSymbol.localName} (${declarationKind})`;\n    if (this.astSymbol.nominalAnalysis) {\n      result += ' (nominal)';\n    }\n    result += '\\n';\n\n    for (const referencedAstEntity of this._analyzedReferencedAstEntitiesSet.values()) {\n      result += indent + `  ref: ${referencedAstEntity.localName}\\n`;\n    }\n\n    for (const child of this.children) {\n      result += child.getDump(indent + '  ');\n    }\n\n    return result;\n  }\n\n  /**\n   * Returns a diagnostic dump using Span.getDump(), which reports the detailed\n   * compiler structure.\n   */\n  public getSpanDump(indent: string = ''): string {\n    const span: Span = new Span(this.declaration);\n    return span.getDump(indent);\n  }\n\n  /**\n   * This is an internal callback used when AstSymbolTable.analyze() discovers a new\n   * type reference associated with this declaration.\n   * @internal\n   */\n  public _notifyReferencedAstEntity(referencedAstEntity: AstEntity): void {\n    if (this.astSymbol.analyzed) {\n      throw new InternalError('_notifyReferencedAstEntity() called after analysis is already complete');\n    }\n\n    for (let current: AstDeclaration | undefined = this; current; current = current.parent) {\n      // Don't add references to symbols that are already referenced by a parent\n      if (current._analyzedReferencedAstEntitiesSet.has(referencedAstEntity)) {\n        return;\n      }\n      // Don't add the symbols of parents either\n      if (referencedAstEntity === current.astSymbol) {\n        return;\n      }\n    }\n\n    this._analyzedReferencedAstEntitiesSet.add(referencedAstEntity);\n  }\n\n  /**\n   * Visits all the current declaration and all children recursively in a depth-first traversal,\n   * and performs the specified action for each one.\n   */\n  public forEachDeclarationRecursive(action: (astDeclaration: AstDeclaration) => void): void {\n    action(this);\n    for (const child of this.children) {\n      child.forEachDeclarationRecursive(action);\n    }\n  }\n\n  /**\n   * Returns the list of child declarations whose `AstSymbol.localName` matches the provided `name`.\n   *\n   * @remarks\n   * This is an efficient O(1) lookup.\n   */\n  public findChildrenWithName(name: string): ReadonlyArray<AstDeclaration> {\n    // The children property returns:\n    //\n    //    return this.astSymbol.analyzed ? this._analyzedChildren : [];\n    //\n    if (!this.astSymbol.analyzed || this._analyzedChildren.length === 0) {\n      return [];\n    }\n\n    if (this._childrenByName === undefined) {\n      // Build the lookup table\n      const childrenByName: Map<string, AstDeclaration[]> = new Map<string, AstDeclaration[]>();\n\n      for (const child of this._analyzedChildren) {\n        const childName: string = child.astSymbol.localName;\n        let array: AstDeclaration[] | undefined = childrenByName.get(childName);\n        if (array === undefined) {\n          array = [];\n          childrenByName.set(childName, array);\n        }\n        array.push(child);\n      }\n      this._childrenByName = childrenByName;\n    }\n\n    return this._childrenByName.get(name) || [];\n  }\n\n  /**\n   * This function determines which ts.Node kinds will generate an AstDeclaration.\n   * These correspond to the definitions that we can add AEDoc to.\n   */\n  public static isSupportedSyntaxKind(kind: ts.SyntaxKind): boolean {\n    // (alphabetical order)\n    switch (kind) {\n      case ts.SyntaxKind.CallSignature:\n      case ts.SyntaxKind.ClassDeclaration:\n      case ts.SyntaxKind.ConstructSignature: // Example: \"new(x: number): IMyClass\"\n      case ts.SyntaxKind.Constructor: // Example: \"constructor(x: number)\"\n      case ts.SyntaxKind.EnumDeclaration:\n      case ts.SyntaxKind.EnumMember:\n      case ts.SyntaxKind.FunctionDeclaration: // Example: \"(x: number): number\"\n      case ts.SyntaxKind.GetAccessor:\n      case ts.SyntaxKind.SetAccessor:\n      case ts.SyntaxKind.IndexSignature: // Example: \"[key: string]: string\"\n      case ts.SyntaxKind.InterfaceDeclaration:\n      case ts.SyntaxKind.MethodDeclaration:\n      case ts.SyntaxKind.MethodSignature:\n      case ts.SyntaxKind.ModuleDeclaration: // Used for both \"module\" and \"namespace\" declarations\n      case ts.SyntaxKind.PropertyDeclaration:\n      case ts.SyntaxKind.PropertySignature:\n      case ts.SyntaxKind.TypeAliasDeclaration: // Example: \"type Shape = Circle | Square\"\n      case ts.SyntaxKind.VariableDeclaration:\n        return true;\n\n      // NOTE: Prior to TypeScript 3.7, in the emitted .d.ts files, the compiler would merge a GetAccessor/SetAccessor\n      // pair into a single PropertyDeclaration.\n\n      // NOTE: In contexts where a source file is treated as a module, we do create \"nominal analysis\"\n      // AstSymbol objects corresponding to a ts.SyntaxKind.SourceFile node.  However, a source file\n      // is NOT considered a nesting structure, and it does NOT act as a root for the declarations\n      // appearing in the file.  This is because the *.d.ts generator is in the business of rolling up\n      // source files, and thus wants to ignore them in general.\n    }\n\n    return false;\n  }\n}\n"]}

package/lib-esm/analyzer/AstEntity.js

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * `AstEntity` is the abstract base class for analyzer objects that can become a `CollectorEntity`.
+ *
+ * @remarks
+ *
+ * The subclasses are:
+ * ```
+ * - AstEntity
+ *   - AstSymbol
+ *   - AstSyntheticEntity
+ *     - AstImport
+ *     - AstNamespaceImport
+ * ```
+ */
+export class AstEntity {
+}
+/**
+ * `AstSyntheticEntity` is the abstract base class for analyzer objects whose emitted declarations
+ * are not text transformations performed by the `Span` helper.
+ *
+ * @remarks
+ * Most of API Extractor's output is produced by using the using the `Span` utility to regurgitate strings from
+ * the input .d.ts files.  If we need to rename an identifier, the `Span` visitor can pick out an interesting
+ * node and rewrite its string, but otherwise the transformation operates on dumb text and not compiler concepts.
+ * (Historically we did this because the compiler's emitter was an internal API, but it still has some advantages,
+ * for example preserving syntaxes generated by an older compiler to avoid incompatibilities.)
+ *
+ * This strategy does not work for cases where the output looks very different from the input.  Today these
+ * cases are always kinds of `import` statements, but that may change in the future.
+ */
+export class AstSyntheticEntity extends AstEntity {
+}
+//# sourceMappingURL=AstEntity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstEntity.js","sourceRoot":"","sources":["../../src/analyzer/AstEntity.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,SAAS;CAY9B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,kBAAmB,SAAQ,SAAS;CAAG","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/**\n * `AstEntity` is the abstract base class for analyzer objects that can become a `CollectorEntity`.\n *\n * @remarks\n *\n * The subclasses are:\n * ```\n * - AstEntity\n *   - AstSymbol\n *   - AstSyntheticEntity\n *     - AstImport\n *     - AstNamespaceImport\n * ```\n */\nexport abstract class AstEntity {\n  /**\n   * The original name of the symbol, as exported from the module (i.e. source file)\n   * containing the original TypeScript definition.  Constructs such as\n   * `import { X as Y } from` may introduce other names that differ from the local name.\n   *\n   * @remarks\n   * For the most part, `localName` corresponds to `followedSymbol.name`, but there\n   * are some edge cases.  For example, the ts.Symbol.name for `export default class X { }`\n   * is actually `\"default\"`, not `\"X\"`.\n   */\n  public abstract readonly localName: string;\n}\n\n/**\n * `AstSyntheticEntity` is the abstract base class for analyzer objects whose emitted declarations\n * are not text transformations performed by the `Span` helper.\n *\n * @remarks\n * Most of API Extractor's output is produced by using the using the `Span` utility to regurgitate strings from\n * the input .d.ts files.  If we need to rename an identifier, the `Span` visitor can pick out an interesting\n * node and rewrite its string, but otherwise the transformation operates on dumb text and not compiler concepts.\n * (Historically we did this because the compiler's emitter was an internal API, but it still has some advantages,\n * for example preserving syntaxes generated by an older compiler to avoid incompatibilities.)\n *\n * This strategy does not work for cases where the output looks very different from the input.  Today these\n * cases are always kinds of `import` statements, but that may change in the future.\n */\nexport abstract class AstSyntheticEntity extends AstEntity {}\n"]}

package/lib-esm/analyzer/AstImport.js

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { InternalError } from '@rushstack/node-core-library';
+import { AstSyntheticEntity } from './AstEntity';
+/**
+ * Indicates the import kind for an `AstImport`.
+ */
+export var AstImportKind;
+(function (AstImportKind) {
+    /**
+     * An import statement such as `import X from "y";`.
+     */
+    AstImportKind[AstImportKind["DefaultImport"] = 0] = "DefaultImport";
+    /**
+     * An import statement such as `import { X } from "y";`.
+     */
+    AstImportKind[AstImportKind["NamedImport"] = 1] = "NamedImport";
+    /**
+     * An import statement such as `import * as x from "y";`.
+     */
+    AstImportKind[AstImportKind["StarImport"] = 2] = "StarImport";
+    /**
+     * An import statement such as `import x = require("y");`.
+     */
+    AstImportKind[AstImportKind["EqualsImport"] = 3] = "EqualsImport";
+    /**
+     * An import statement such as `interface foo { foo: import("bar").a.b.c }`.
+     */
+    AstImportKind[AstImportKind["ImportType"] = 4] = "ImportType";
+})(AstImportKind || (AstImportKind = {}));
+/**
+ * For a symbol that was imported from an external package, this tracks the import
+ * statement that was used to reach it.
+ */
+export class AstImport extends AstSyntheticEntity {
+    constructor(options) {
+        super();
+        this.importKind = options.importKind;
+        this.modulePath = options.modulePath;
+        this.exportName = options.exportName;
+        // We start with this assumption, but it may get changed later if non-type-only import is encountered.
+        this.isTypeOnlyEverywhere = options.isTypeOnly;
+        this.key = AstImport.getKey(options);
+    }
+    /** {@inheritdoc} */
+    get localName() {
+        // abstract
+        return this.exportName;
+    }
+    /**
+     * Calculates the lookup key used with `AstImport.key`
+     */
+    static getKey(options) {
+        switch (options.importKind) {
+            case AstImportKind.DefaultImport:
+                return `${options.modulePath}:${options.exportName}`;
+            case AstImportKind.NamedImport:
+                return `${options.modulePath}:${options.exportName}`;
+            case AstImportKind.StarImport:
+                return `${options.modulePath}:*`;
+            case AstImportKind.EqualsImport:
+                return `${options.modulePath}:=`;
+            case AstImportKind.ImportType: {
+                const subKey = !options.exportName
+                    ? '*' // Equivalent to StarImport
+                    : options.exportName.includes('.') // Equivalent to a named export
+                        ? options.exportName.split('.')[0]
+                        : options.exportName;
+                return `${options.modulePath}:${subKey}`;
+            }
+            default:
+                throw new InternalError('Unknown AstImportKind');
+        }
+    }
+}
+//# sourceMappingURL=AstImport.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstImport.js","sourceRoot":"","sources":["../../src/analyzer/AstImport.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAN,IAAY,aAyBX;AAzBD,WAAY,aAAa;IACvB;;OAEG;IACH,mEAAa,CAAA;IAEb;;OAEG;IACH,+DAAW,CAAA;IAEX;;OAEG;IACH,6DAAU,CAAA;IAEV;;OAEG;IACH,iEAAY,CAAA;IAEZ;;OAEG;IACH,6DAAU,CAAA;AACZ,CAAC,EAzBW,aAAa,KAAb,aAAa,QAyBxB;AAkBD;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,kBAAkB;IA+D/C,YAAmB,OAA0B;QAC3C,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QAErC,sGAAsG;QACtG,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC;QAE/C,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,oBAAoB;IACpB,IAAW,SAAS;QAClB,WAAW;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,MAAM,CAAC,OAA0B;QAC7C,QAAQ,OAAO,CAAC,UAAU,EAAE,CAAC;YAC3B,KAAK,aAAa,CAAC,aAAa;gBAC9B,OAAO,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvD,KAAK,aAAa,CAAC,WAAW;gBAC5B,OAAO,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvD,KAAK,aAAa,CAAC,UAAU;gBAC3B,OAAO,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC;YACnC,KAAK,aAAa,CAAC,YAAY;gBAC7B,OAAO,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC;YACnC,KAAK,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;gBAC9B,MAAM,MAAM,GAAW,CAAC,OAAO,CAAC,UAAU;oBACxC,CAAC,CAAC,GAAG,CAAC,2BAA2B;oBACjC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,+BAA+B;wBAChE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;wBAClC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;gBACzB,OAAO,GAAG,OAAO,CAAC,UAAU,IAAI,MAAM,EAAE,CAAC;YAC3C,CAAC;YACD;gBACE,MAAM,IAAI,aAAa,CAAC,uBAAuB,CAAC,CAAC;QACrD,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 { InternalError } from '@rushstack/node-core-library';\n\nimport type { AstSymbol } from './AstSymbol';\nimport { AstSyntheticEntity } from './AstEntity';\n\n/**\n * Indicates the import kind for an `AstImport`.\n */\nexport enum AstImportKind {\n  /**\n   * An import statement such as `import X from \"y\";`.\n   */\n  DefaultImport,\n\n  /**\n   * An import statement such as `import { X } from \"y\";`.\n   */\n  NamedImport,\n\n  /**\n   * An import statement such as `import * as x from \"y\";`.\n   */\n  StarImport,\n\n  /**\n   * An import statement such as `import x = require(\"y\");`.\n   */\n  EqualsImport,\n\n  /**\n   * An import statement such as `interface foo { foo: import(\"bar\").a.b.c }`.\n   */\n  ImportType\n}\n\n/**\n * Constructor parameters for AstImport\n *\n * @privateRemarks\n * Our naming convention is to use I____Parameters for constructor options and\n * I____Options for general function options.  However the word \"parameters\" is\n * confusingly similar to the terminology for function parameters modeled by API Extractor,\n * so we use I____Options for both cases in this code base.\n */\nexport interface IAstImportOptions {\n  readonly importKind: AstImportKind;\n  readonly modulePath: string;\n  readonly exportName: string;\n  readonly isTypeOnly: boolean;\n}\n\n/**\n * For a symbol that was imported from an external package, this tracks the import\n * statement that was used to reach it.\n */\nexport class AstImport extends AstSyntheticEntity {\n  public readonly importKind: AstImportKind;\n\n  /**\n   * The name of the external package (and possibly module path) that this definition\n   * was imported from.\n   *\n   * Example: \"@rushstack/node-core-library/lib/FileSystem\"\n   */\n  public readonly modulePath: string;\n\n  /**\n   * The name of the symbol being imported.\n   *\n   * @remarks\n   *\n   * The name depends on the type of import:\n   *\n   * ```ts\n   * // For AstImportKind.DefaultImport style, exportName would be \"X\" in this example:\n   * import X from \"y\";\n   *\n   * // For AstImportKind.NamedImport style, exportName would be \"X\" in this example:\n   * import { X } from \"y\";\n   *\n   * // For AstImportKind.StarImport style, exportName would be \"x\" in this example:\n   * import * as x from \"y\";\n   *\n   * // For AstImportKind.EqualsImport style, exportName would be \"x\" in this example:\n   * import x = require(\"y\");\n   *\n   * // For AstImportKind.ImportType style, exportName would be \"a.b.c\" in this example:\n   * interface foo { foo: import('bar').a.b.c };\n   * ```\n   */\n  public readonly exportName: string;\n\n  /**\n   * Whether it is a type-only import, for example:\n   *\n   * ```ts\n   * import type { X } from \"y\";\n   * ```\n   *\n   * This is set to true ONLY if the type-only form is used in *every* reference to this AstImport.\n   */\n  public isTypeOnlyEverywhere: boolean;\n\n  /**\n   * If this import statement refers to an API from an external package that is tracked by API Extractor\n   * (according to `PackageMetadataManager.isAedocSupportedFor()`), then this property will return the\n   * corresponding AstSymbol.  Otherwise, it is undefined.\n   */\n  public astSymbol: AstSymbol | undefined;\n\n  /**\n   * If modulePath and exportName are defined, then this is a dictionary key\n   * that combines them with a colon (\":\").\n   *\n   * Example: \"@rushstack/node-core-library/lib/FileSystem:FileSystem\"\n   */\n  public readonly key: string;\n\n  public constructor(options: IAstImportOptions) {\n    super();\n\n    this.importKind = options.importKind;\n    this.modulePath = options.modulePath;\n    this.exportName = options.exportName;\n\n    // We start with this assumption, but it may get changed later if non-type-only import is encountered.\n    this.isTypeOnlyEverywhere = options.isTypeOnly;\n\n    this.key = AstImport.getKey(options);\n  }\n\n  /** {@inheritdoc} */\n  public get localName(): string {\n    // abstract\n    return this.exportName;\n  }\n\n  /**\n   * Calculates the lookup key used with `AstImport.key`\n   */\n  public static getKey(options: IAstImportOptions): string {\n    switch (options.importKind) {\n      case AstImportKind.DefaultImport:\n        return `${options.modulePath}:${options.exportName}`;\n      case AstImportKind.NamedImport:\n        return `${options.modulePath}:${options.exportName}`;\n      case AstImportKind.StarImport:\n        return `${options.modulePath}:*`;\n      case AstImportKind.EqualsImport:\n        return `${options.modulePath}:=`;\n      case AstImportKind.ImportType: {\n        const subKey: string = !options.exportName\n          ? '*' // Equivalent to StarImport\n          : options.exportName.includes('.') // Equivalent to a named export\n            ? options.exportName.split('.')[0]\n            : options.exportName;\n        return `${options.modulePath}:${subKey}`;\n      }\n      default:\n        throw new InternalError('Unknown AstImportKind');\n    }\n  }\n}\n"]}

package/lib-esm/analyzer/AstModule.js

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * An internal data structure that represents a source file that is analyzed by AstSymbolTable.
+ */
+export class AstModule {
+    constructor(options) {
+        this.sourceFile = options.sourceFile;
+        this.moduleSymbol = options.moduleSymbol;
+        this.externalModulePath = options.externalModulePath;
+        this.starExportedModules = new Set();
+        this.cachedExportedEntities = new Map();
+        this.astModuleExportInfo = undefined;
+    }
+    /**
+     * If false, then this source file is part of the working package being processed by the `Collector`.
+     */
+    get isExternal() {
+        return this.externalModulePath !== undefined;
+    }
+}
+//# sourceMappingURL=AstModule.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstModule.js","sourceRoot":"","sources":["../../src/analyzer/AstModule.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AA+B3D;;GAEG;AACH,MAAM,OAAO,SAAS;IAkCpB,YAAmB,OAA0B;QAC3C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QAEzC,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;QAErD,IAAI,CAAC,mBAAmB,GAAG,IAAI,GAAG,EAAa,CAAC;QAEhD,IAAI,CAAC,sBAAsB,GAAG,IAAI,GAAG,EAAqB,CAAC;QAE3D,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,IAAW,UAAU;QACnB,OAAO,IAAI,CAAC,kBAAkB,KAAK,SAAS,CAAC;IAC/C,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 type * as ts from 'typescript';\n\nimport type { AstSymbol } from './AstSymbol';\nimport type { AstEntity } from './AstEntity';\n\n/**\n * Represents information collected by {@link AstSymbolTable.fetchAstModuleExportInfo}\n */\nexport interface IAstModuleExportInfo {\n  readonly visitedAstModules: Set<AstModule>;\n  readonly exportedLocalEntities: Map<string, AstEntity>;\n  readonly starExportedExternalModules: Set<AstModule>;\n}\n\n/**\n * Constructor parameters for AstModule\n *\n * @privateRemarks\n * Our naming convention is to use I____Parameters for constructor options and\n * I____Options for general function options.  However the word \"parameters\" is\n * confusingly similar to the terminology for function parameters modeled by API Extractor,\n * so we use I____Options for both cases in this code base.\n */\nexport interface IAstModuleOptions {\n  sourceFile: ts.SourceFile;\n  moduleSymbol: ts.Symbol;\n  externalModulePath: string | undefined;\n}\n\n/**\n * An internal data structure that represents a source file that is analyzed by AstSymbolTable.\n */\nexport class AstModule {\n  /**\n   * The source file that declares this TypeScript module.  In most cases, the source file's\n   * top-level exports constitute the module.\n   */\n  public readonly sourceFile: ts.SourceFile;\n\n  /**\n   * The symbol for the module.  Typically this corresponds to ts.SourceFile itself, however\n   * in some cases the ts.SourceFile may contain multiple modules declared using the `module` keyword.\n   */\n  public readonly moduleSymbol: ts.Symbol;\n\n  /**\n   * Example:  \"@rushstack/node-core-library/lib/FileSystem\"\n   * but never: \"./FileSystem\"\n   */\n  public readonly externalModulePath: string | undefined;\n\n  /**\n   * A list of other `AstModule` objects that appear in `export * from \"___\";` statements.\n   */\n  public readonly starExportedModules: Set<AstModule>;\n\n  /**\n   * A partial map of entities exported by this module.  The key is the exported name.\n   */\n  public readonly cachedExportedEntities: Map<string, AstEntity>; // exportName --> entity\n\n  /**\n   * Additional state calculated by `AstSymbolTable.fetchWorkingPackageModule()`.\n   */\n  public astModuleExportInfo: IAstModuleExportInfo | undefined;\n\n  public constructor(options: IAstModuleOptions) {\n    this.sourceFile = options.sourceFile;\n    this.moduleSymbol = options.moduleSymbol;\n\n    this.externalModulePath = options.externalModulePath;\n\n    this.starExportedModules = new Set<AstModule>();\n\n    this.cachedExportedEntities = new Map<string, AstSymbol>();\n\n    this.astModuleExportInfo = undefined;\n  }\n\n  /**\n   * If false, then this source file is part of the working package being processed by the `Collector`.\n   */\n  public get isExternal(): boolean {\n    return this.externalModulePath !== undefined;\n  }\n}\n"]}

package/lib-esm/analyzer/AstNamespaceExport.js

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { AstNamespaceImport } from './AstNamespaceImport';
+/**
+ * `AstNamespaceExport` represents a namespace that is created implicitly and exported by a statement
+ * such as `export * as example from "./file";`
+ *
+ * @remarks
+ *
+ * A typical input looks like this:
+ * ```ts
+ * // Suppose that example.ts exports two functions f1() and f2().
+ * export * as example from "./file";
+ * ```
+ *
+ * API Extractor's .d.ts rollup will transform it into an explicit namespace, like this:
+ * ```ts
+ * declare f1(): void;
+ * declare f2(): void;
+ *
+ * export declare namespace example {
+ *   export {
+ *     f1,
+ *     f2
+ *   }
+ * }
+ * ```
+ *
+ * The current implementation does not attempt to relocate f1()/f2() to be inside the `namespace`
+ * because other type signatures may reference them directly (without using the namespace qualifier).
+ * The AstNamespaceExports behaves the same as AstNamespaceImport, it just also has the inline export for the craeted namespace.
+ */
+export class AstNamespaceExport extends AstNamespaceImport {
+    constructor(options) {
+        super(options);
+    }
+}
+//# sourceMappingURL=AstNamespaceExport.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstNamespaceExport.js","sourceRoot":"","sources":["../../src/analyzer/AstNamespaceExport.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D,OAAO,EAAE,kBAAkB,EAAmC,MAAM,sBAAsB,CAAC;AAI3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,OAAO,kBAAmB,SAAQ,kBAAkB;IACxD,YAAmB,OAAmC;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,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 { AstNamespaceImport, type IAstNamespaceImportOptions } from './AstNamespaceImport';\n\nexport interface IAstNamespaceExportOptions extends IAstNamespaceImportOptions {}\n\n/**\n * `AstNamespaceExport` represents a namespace that is created implicitly and exported by a statement\n * such as `export * as example from \"./file\";`\n *\n * @remarks\n *\n * A typical input looks like this:\n * ```ts\n * // Suppose that example.ts exports two functions f1() and f2().\n * export * as example from \"./file\";\n * ```\n *\n * API Extractor's .d.ts rollup will transform it into an explicit namespace, like this:\n * ```ts\n * declare f1(): void;\n * declare f2(): void;\n *\n * export declare namespace example {\n *   export {\n *     f1,\n *     f2\n *   }\n * }\n * ```\n *\n * The current implementation does not attempt to relocate f1()/f2() to be inside the `namespace`\n * because other type signatures may reference them directly (without using the namespace qualifier).\n * The AstNamespaceExports behaves the same as AstNamespaceImport, it just also has the inline export for the craeted namespace.\n */\n\nexport class AstNamespaceExport extends AstNamespaceImport {\n  public constructor(options: IAstNamespaceExportOptions) {\n    super(options);\n  }\n}\n"]}