@microsoft/api-extractor 7.56.3 → 7.57.1

package/lib-esm/analyzer/AstNamespaceImport.js

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { AstSyntheticEntity } from './AstEntity';
+/**
+ * `AstNamespaceImport` represents a namespace that is created implicitly by a statement
+ * such as `import * as example from "./file";`
+ *
+ * @remarks
+ *
+ * A typical input looks like this:
+ * ```ts
+ * // Suppose that example.ts exports two functions f1() and f2().
+ * import * as example from "./file";
+ * export { example };
+ * ```
+ *
+ * API Extractor's .d.ts rollup will transform it into an explicit namespace, like this:
+ * ```ts
+ * declare f1(): void;
+ * declare f2(): void;
+ *
+ * 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 `declare namespace example` is a synthetic construct represented by `AstNamespaceImport`.
+ */
+export class AstNamespaceImport extends AstSyntheticEntity {
+    constructor(options) {
+        super();
+        /**
+         * Returns true if the AstSymbolTable.analyze() was called for this object.
+         * See that function for details.
+         */
+        this.analyzed = false;
+        this.astModule = options.astModule;
+        this.namespaceName = options.namespaceName;
+        this.declaration = options.declaration;
+        this.symbol = options.symbol;
+    }
+    /** {@inheritdoc} */
+    get localName() {
+        // abstract
+        return this.namespaceName;
+    }
+    fetchAstModuleExportInfo(collector) {
+        const astModuleExportInfo = collector.astSymbolTable.fetchAstModuleExportInfo(this.astModule);
+        return astModuleExportInfo;
+    }
+}
+//# sourceMappingURL=AstNamespaceImport.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstNamespaceImport.js","sourceRoot":"","sources":["../../src/analyzer/AstNamespaceImport.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAK3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAUjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,kBAAmB,SAAQ,kBAAkB;IA6BxD,YAAmB,OAAmC;QACpD,KAAK,EAAE,CAAC;QA7BV;;;WAGG;QACI,aAAQ,GAAY,KAAK,CAAC;QA0B/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,oBAAoB;IACpB,IAAW,SAAS;QAClB,WAAW;QACX,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAEM,wBAAwB,CAAC,SAAoB;QAClD,MAAM,mBAAmB,GAAyB,SAAS,CAAC,cAAc,CAAC,wBAAwB,CACjG,IAAI,CAAC,SAAS,CACf,CAAC;QACF,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 type * as ts from 'typescript';\n\nimport type { AstModule, IAstModuleExportInfo } from './AstModule';\nimport { AstSyntheticEntity } from './AstEntity';\nimport type { Collector } from '../collector/Collector';\n\nexport interface IAstNamespaceImportOptions {\n  readonly astModule: AstModule;\n  readonly namespaceName: string;\n  readonly declaration: ts.Declaration;\n  readonly symbol: ts.Symbol;\n}\n\n/**\n * `AstNamespaceImport` represents a namespace that is created implicitly by a statement\n * such as `import * 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 * import * as example from \"./file\";\n * export { example };\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 * 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 `declare namespace example` is a synthetic construct represented by `AstNamespaceImport`.\n */\nexport class AstNamespaceImport extends AstSyntheticEntity {\n  /**\n   * Returns true if the AstSymbolTable.analyze() was called for this object.\n   * See that function for details.\n   */\n  public analyzed: boolean = false;\n\n  /**\n   * For example, if the original statement was `import * as example from \"./file\";`\n   * then `astModule` refers to the `./file.d.ts` file.\n   */\n  public readonly astModule: AstModule;\n\n  /**\n   * For example, if the original statement was `import * as example from \"./file\";`\n   * then `namespaceName` would be `example`.\n   */\n  public readonly namespaceName: string;\n\n  /**\n   * The original `ts.SyntaxKind.NamespaceImport` which can be used as a location for error messages.\n   */\n  public readonly declaration: ts.Declaration;\n\n  /**\n   * The original `ts.SymbolFlags.Namespace` symbol.\n   */\n  public readonly symbol: ts.Symbol;\n\n  public constructor(options: IAstNamespaceImportOptions) {\n    super();\n    this.astModule = options.astModule;\n    this.namespaceName = options.namespaceName;\n    this.declaration = options.declaration;\n    this.symbol = options.symbol;\n  }\n\n  /** {@inheritdoc} */\n  public get localName(): string {\n    // abstract\n    return this.namespaceName;\n  }\n\n  public fetchAstModuleExportInfo(collector: Collector): IAstModuleExportInfo {\n    const astModuleExportInfo: IAstModuleExportInfo = collector.astSymbolTable.fetchAstModuleExportInfo(\n      this.astModule\n    );\n    return astModuleExportInfo;\n  }\n}\n"]}

package/lib-esm/analyzer/AstReferenceResolver.js

@@ -0,0 +1,202 @@
+// 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 * as tsdoc from '@microsoft/tsdoc';
+import { AstSymbol } from './AstSymbol';
+/**
+ * Used by `AstReferenceResolver` to report a failed resolution.
+ *
+ * @privateRemarks
+ * This class is similar to an `Error` object, but the intent of `ResolverFailure` is to describe
+ * why a reference could not be resolved.  This information could be used to throw an actual `Error` object,
+ * but normally it is handed off to the `MessageRouter` instead.
+ */
+export class ResolverFailure {
+    constructor(reason) {
+        this.reason = reason;
+    }
+}
+/**
+ * This resolves a TSDoc declaration reference by walking the `AstSymbolTable` compiler state.
+ *
+ * @remarks
+ *
+ * This class is analogous to `ModelReferenceResolver` from the `@microsoft/api-extractor-model` project,
+ * which resolves declaration references by walking the hierarchy loaded from an .api.json file.
+ */
+export class AstReferenceResolver {
+    constructor(collector) {
+        this._collector = collector;
+        this._astSymbolTable = collector.astSymbolTable;
+        this._workingPackage = collector.workingPackage;
+    }
+    resolve(declarationReference) {
+        // Is it referring to the working package?
+        if (declarationReference.packageName !== undefined &&
+            declarationReference.packageName !== this._workingPackage.name) {
+            return new ResolverFailure('External package references are not supported');
+        }
+        // Is it a path-based import?
+        if (declarationReference.importPath) {
+            return new ResolverFailure('Import paths are not supported');
+        }
+        const astModule = this._astSymbolTable.fetchAstModuleFromWorkingPackage(this._workingPackage.entryPointSourceFile);
+        if (declarationReference.memberReferences.length === 0) {
+            return new ResolverFailure('Package references are not supported');
+        }
+        const rootMemberReference = declarationReference.memberReferences[0];
+        const exportName = this._getMemberReferenceIdentifier(rootMemberReference);
+        if (exportName instanceof ResolverFailure) {
+            return exportName;
+        }
+        const rootAstEntity = this._astSymbolTable.tryGetExportOfAstModule(exportName, astModule);
+        if (rootAstEntity === undefined) {
+            return new ResolverFailure(`The package "${this._workingPackage.name}" does not have an export "${exportName}"`);
+        }
+        if (!(rootAstEntity instanceof AstSymbol)) {
+            return new ResolverFailure('This type of declaration is not supported yet by the resolver');
+        }
+        let currentDeclaration = this._selectDeclaration(rootAstEntity.astDeclarations, rootMemberReference, rootAstEntity.localName);
+        if (currentDeclaration instanceof ResolverFailure) {
+            return currentDeclaration;
+        }
+        for (let index = 1; index < declarationReference.memberReferences.length; ++index) {
+            const memberReference = declarationReference.memberReferences[index];
+            const memberName = this._getMemberReferenceIdentifier(memberReference);
+            if (memberName instanceof ResolverFailure) {
+                return memberName;
+            }
+            const matchingChildren = currentDeclaration.findChildrenWithName(memberName);
+            if (matchingChildren.length === 0) {
+                return new ResolverFailure(`No member was found with name "${memberName}"`);
+            }
+            const selectedDeclaration = this._selectDeclaration(matchingChildren, memberReference, memberName);
+            if (selectedDeclaration instanceof ResolverFailure) {
+                return selectedDeclaration;
+            }
+            currentDeclaration = selectedDeclaration;
+        }
+        return currentDeclaration;
+    }
+    _getMemberReferenceIdentifier(memberReference) {
+        if (memberReference.memberSymbol !== undefined) {
+            return new ResolverFailure('ECMAScript symbol selectors are not supported');
+        }
+        if (memberReference.memberIdentifier === undefined) {
+            return new ResolverFailure('The member identifier is missing in the root member reference');
+        }
+        return memberReference.memberIdentifier.identifier;
+    }
+    _selectDeclaration(astDeclarations, memberReference, astSymbolName) {
+        const memberSelector = memberReference.selector;
+        if (memberSelector === undefined) {
+            if (astDeclarations.length === 1) {
+                return astDeclarations[0];
+            }
+            else {
+                // If we found multiple matches, but the extra ones are all ancillary declarations,
+                // then return the main declaration.
+                const nonAncillaryMatch = this._tryDisambiguateAncillaryMatches(astDeclarations);
+                if (nonAncillaryMatch) {
+                    return nonAncillaryMatch;
+                }
+                return new ResolverFailure(`The reference is ambiguous because "${astSymbolName}"` +
+                    ` has more than one declaration; you need to add a TSDoc member reference selector`);
+            }
+        }
+        switch (memberSelector.selectorKind) {
+            case tsdoc.SelectorKind.System:
+                return this._selectUsingSystemSelector(astDeclarations, memberSelector, astSymbolName);
+            case tsdoc.SelectorKind.Index:
+                return this._selectUsingIndexSelector(astDeclarations, memberSelector, astSymbolName);
+        }
+        return new ResolverFailure(`The selector "${memberSelector.selector}" is not a supported selector type`);
+    }
+    _selectUsingSystemSelector(astDeclarations, memberSelector, astSymbolName) {
+        const selectorName = memberSelector.selector;
+        let selectorSyntaxKind;
+        switch (selectorName) {
+            case 'class':
+                selectorSyntaxKind = ts.SyntaxKind.ClassDeclaration;
+                break;
+            case 'enum':
+                selectorSyntaxKind = ts.SyntaxKind.EnumDeclaration;
+                break;
+            case 'function':
+                selectorSyntaxKind = ts.SyntaxKind.FunctionDeclaration;
+                break;
+            case 'interface':
+                selectorSyntaxKind = ts.SyntaxKind.InterfaceDeclaration;
+                break;
+            case 'namespace':
+                selectorSyntaxKind = ts.SyntaxKind.ModuleDeclaration;
+                break;
+            case 'type':
+                selectorSyntaxKind = ts.SyntaxKind.TypeAliasDeclaration;
+                break;
+            case 'variable':
+                selectorSyntaxKind = ts.SyntaxKind.VariableDeclaration;
+                break;
+            default:
+                return new ResolverFailure(`Unsupported system selector "${selectorName}"`);
+        }
+        const matches = astDeclarations.filter((x) => x.declaration.kind === selectorSyntaxKind);
+        if (matches.length === 0) {
+            return new ResolverFailure(`A declaration for "${astSymbolName}" was not found that matches the` +
+                ` TSDoc selector "${selectorName}"`);
+        }
+        if (matches.length > 1) {
+            // If we found multiple matches, but the extra ones are all ancillary declarations,
+            // then return the main declaration.
+            const nonAncillaryMatch = this._tryDisambiguateAncillaryMatches(matches);
+            if (nonAncillaryMatch) {
+                return nonAncillaryMatch;
+            }
+            return new ResolverFailure(`More than one declaration "${astSymbolName}" matches the TSDoc selector "${selectorName}"`);
+        }
+        return matches[0];
+    }
+    _selectUsingIndexSelector(astDeclarations, memberSelector, astSymbolName) {
+        const selectorOverloadIndex = parseInt(memberSelector.selector, 10);
+        const matches = [];
+        for (const astDeclaration of astDeclarations) {
+            const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
+            if (overloadIndex === selectorOverloadIndex) {
+                matches.push(astDeclaration);
+            }
+        }
+        if (matches.length === 0) {
+            return new ResolverFailure(`An overload for "${astSymbolName}" was not found that matches the` +
+                ` TSDoc selector ":${selectorOverloadIndex}"`);
+        }
+        if (matches.length > 1) {
+            // If we found multiple matches, but the extra ones are all ancillary declarations,
+            // then return the main declaration.
+            const nonAncillaryMatch = this._tryDisambiguateAncillaryMatches(matches);
+            if (nonAncillaryMatch) {
+                return nonAncillaryMatch;
+            }
+            return new ResolverFailure(`More than one declaration for "${astSymbolName}" matches the` +
+                ` TSDoc selector ":${selectorOverloadIndex}"`);
+        }
+        return matches[0];
+    }
+    /**
+     * This resolves an ambiguous match in the case where the extra matches are all ancillary declarations,
+     * except for one match that is the main declaration.
+     */
+    _tryDisambiguateAncillaryMatches(matches) {
+        let result = undefined;
+        for (const match of matches) {
+            const declarationMetadata = this._collector.fetchDeclarationMetadata(match);
+            if (!declarationMetadata.isAncillary) {
+                if (result) {
+                    return undefined; // more than one match
+                }
+                result = match;
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=AstReferenceResolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstReferenceResolver.js","sourceRoot":"","sources":["../../src/analyzer/AstReferenceResolver.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 * as tsdoc from '@microsoft/tsdoc';\n\nimport type { AstSymbolTable } from './AstSymbolTable';\nimport type { AstEntity } from './AstEntity';\nimport type { AstDeclaration } from './AstDeclaration';\nimport type { WorkingPackage } from '../collector/WorkingPackage';\nimport type { AstModule } from './AstModule';\nimport type { Collector } from '../collector/Collector';\nimport type { DeclarationMetadata } from '../collector/DeclarationMetadata';\nimport { AstSymbol } from './AstSymbol';\n\n/**\n * Used by `AstReferenceResolver` to report a failed resolution.\n *\n * @privateRemarks\n * This class is similar to an `Error` object, but the intent of `ResolverFailure` is to describe\n * why a reference could not be resolved.  This information could be used to throw an actual `Error` object,\n * but normally it is handed off to the `MessageRouter` instead.\n */\nexport class ResolverFailure {\n  /**\n   * Details about why the failure occurred.\n   */\n  public readonly reason: string;\n\n  public constructor(reason: string) {\n    this.reason = reason;\n  }\n}\n\n/**\n * This resolves a TSDoc declaration reference by walking the `AstSymbolTable` compiler state.\n *\n * @remarks\n *\n * This class is analogous to `ModelReferenceResolver` from the `@microsoft/api-extractor-model` project,\n * which resolves declaration references by walking the hierarchy loaded from an .api.json file.\n */\nexport class AstReferenceResolver {\n  private readonly _collector: Collector;\n  private readonly _astSymbolTable: AstSymbolTable;\n  private readonly _workingPackage: WorkingPackage;\n\n  public constructor(collector: Collector) {\n    this._collector = collector;\n    this._astSymbolTable = collector.astSymbolTable;\n    this._workingPackage = collector.workingPackage;\n  }\n\n  public resolve(declarationReference: tsdoc.DocDeclarationReference): AstDeclaration | ResolverFailure {\n    // Is it referring to the working package?\n    if (\n      declarationReference.packageName !== undefined &&\n      declarationReference.packageName !== this._workingPackage.name\n    ) {\n      return new ResolverFailure('External package references are not supported');\n    }\n\n    // Is it a path-based import?\n    if (declarationReference.importPath) {\n      return new ResolverFailure('Import paths are not supported');\n    }\n\n    const astModule: AstModule = this._astSymbolTable.fetchAstModuleFromWorkingPackage(\n      this._workingPackage.entryPointSourceFile\n    );\n\n    if (declarationReference.memberReferences.length === 0) {\n      return new ResolverFailure('Package references are not supported');\n    }\n\n    const rootMemberReference: tsdoc.DocMemberReference = declarationReference.memberReferences[0];\n\n    const exportName: string | ResolverFailure = this._getMemberReferenceIdentifier(rootMemberReference);\n    if (exportName instanceof ResolverFailure) {\n      return exportName;\n    }\n\n    const rootAstEntity: AstEntity | undefined = this._astSymbolTable.tryGetExportOfAstModule(\n      exportName,\n      astModule\n    );\n\n    if (rootAstEntity === undefined) {\n      return new ResolverFailure(\n        `The package \"${this._workingPackage.name}\" does not have an export \"${exportName}\"`\n      );\n    }\n\n    if (!(rootAstEntity instanceof AstSymbol)) {\n      return new ResolverFailure('This type of declaration is not supported yet by the resolver');\n    }\n\n    let currentDeclaration: AstDeclaration | ResolverFailure = this._selectDeclaration(\n      rootAstEntity.astDeclarations,\n      rootMemberReference,\n      rootAstEntity.localName\n    );\n\n    if (currentDeclaration instanceof ResolverFailure) {\n      return currentDeclaration;\n    }\n\n    for (let index: number = 1; index < declarationReference.memberReferences.length; ++index) {\n      const memberReference: tsdoc.DocMemberReference = declarationReference.memberReferences[index];\n\n      const memberName: string | ResolverFailure = this._getMemberReferenceIdentifier(memberReference);\n      if (memberName instanceof ResolverFailure) {\n        return memberName;\n      }\n\n      const matchingChildren: ReadonlyArray<AstDeclaration> =\n        currentDeclaration.findChildrenWithName(memberName);\n      if (matchingChildren.length === 0) {\n        return new ResolverFailure(`No member was found with name \"${memberName}\"`);\n      }\n\n      const selectedDeclaration: AstDeclaration | ResolverFailure = this._selectDeclaration(\n        matchingChildren,\n        memberReference,\n        memberName\n      );\n\n      if (selectedDeclaration instanceof ResolverFailure) {\n        return selectedDeclaration;\n      }\n\n      currentDeclaration = selectedDeclaration;\n    }\n\n    return currentDeclaration;\n  }\n\n  private _getMemberReferenceIdentifier(memberReference: tsdoc.DocMemberReference): string | ResolverFailure {\n    if (memberReference.memberSymbol !== undefined) {\n      return new ResolverFailure('ECMAScript symbol selectors are not supported');\n    }\n    if (memberReference.memberIdentifier === undefined) {\n      return new ResolverFailure('The member identifier is missing in the root member reference');\n    }\n    return memberReference.memberIdentifier.identifier;\n  }\n\n  private _selectDeclaration(\n    astDeclarations: ReadonlyArray<AstDeclaration>,\n    memberReference: tsdoc.DocMemberReference,\n    astSymbolName: string\n  ): AstDeclaration | ResolverFailure {\n    const memberSelector: tsdoc.DocMemberSelector | undefined = memberReference.selector;\n\n    if (memberSelector === undefined) {\n      if (astDeclarations.length === 1) {\n        return astDeclarations[0];\n      } else {\n        // If we found multiple matches, but the extra ones are all ancillary declarations,\n        // then return the main declaration.\n        const nonAncillaryMatch: AstDeclaration | undefined =\n          this._tryDisambiguateAncillaryMatches(astDeclarations);\n        if (nonAncillaryMatch) {\n          return nonAncillaryMatch;\n        }\n\n        return new ResolverFailure(\n          `The reference is ambiguous because \"${astSymbolName}\"` +\n            ` has more than one declaration; you need to add a TSDoc member reference selector`\n        );\n      }\n    }\n\n    switch (memberSelector.selectorKind) {\n      case tsdoc.SelectorKind.System:\n        return this._selectUsingSystemSelector(astDeclarations, memberSelector, astSymbolName);\n      case tsdoc.SelectorKind.Index:\n        return this._selectUsingIndexSelector(astDeclarations, memberSelector, astSymbolName);\n    }\n\n    return new ResolverFailure(`The selector \"${memberSelector.selector}\" is not a supported selector type`);\n  }\n\n  private _selectUsingSystemSelector(\n    astDeclarations: ReadonlyArray<AstDeclaration>,\n    memberSelector: tsdoc.DocMemberSelector,\n    astSymbolName: string\n  ): AstDeclaration | ResolverFailure {\n    const selectorName: string = memberSelector.selector;\n\n    let selectorSyntaxKind: ts.SyntaxKind;\n\n    switch (selectorName) {\n      case 'class':\n        selectorSyntaxKind = ts.SyntaxKind.ClassDeclaration;\n        break;\n      case 'enum':\n        selectorSyntaxKind = ts.SyntaxKind.EnumDeclaration;\n        break;\n      case 'function':\n        selectorSyntaxKind = ts.SyntaxKind.FunctionDeclaration;\n        break;\n      case 'interface':\n        selectorSyntaxKind = ts.SyntaxKind.InterfaceDeclaration;\n        break;\n      case 'namespace':\n        selectorSyntaxKind = ts.SyntaxKind.ModuleDeclaration;\n        break;\n      case 'type':\n        selectorSyntaxKind = ts.SyntaxKind.TypeAliasDeclaration;\n        break;\n      case 'variable':\n        selectorSyntaxKind = ts.SyntaxKind.VariableDeclaration;\n        break;\n      default:\n        return new ResolverFailure(`Unsupported system selector \"${selectorName}\"`);\n    }\n\n    const matches: AstDeclaration[] = astDeclarations.filter(\n      (x) => x.declaration.kind === selectorSyntaxKind\n    );\n    if (matches.length === 0) {\n      return new ResolverFailure(\n        `A declaration for \"${astSymbolName}\" was not found that matches the` +\n          ` TSDoc selector \"${selectorName}\"`\n      );\n    }\n    if (matches.length > 1) {\n      // If we found multiple matches, but the extra ones are all ancillary declarations,\n      // then return the main declaration.\n      const nonAncillaryMatch: AstDeclaration | undefined = this._tryDisambiguateAncillaryMatches(matches);\n      if (nonAncillaryMatch) {\n        return nonAncillaryMatch;\n      }\n\n      return new ResolverFailure(\n        `More than one declaration \"${astSymbolName}\" matches the TSDoc selector \"${selectorName}\"`\n      );\n    }\n    return matches[0];\n  }\n\n  private _selectUsingIndexSelector(\n    astDeclarations: ReadonlyArray<AstDeclaration>,\n    memberSelector: tsdoc.DocMemberSelector,\n    astSymbolName: string\n  ): AstDeclaration | ResolverFailure {\n    const selectorOverloadIndex: number = parseInt(memberSelector.selector, 10);\n\n    const matches: AstDeclaration[] = [];\n    for (const astDeclaration of astDeclarations) {\n      const overloadIndex: number = this._collector.getOverloadIndex(astDeclaration);\n      if (overloadIndex === selectorOverloadIndex) {\n        matches.push(astDeclaration);\n      }\n    }\n\n    if (matches.length === 0) {\n      return new ResolverFailure(\n        `An overload for \"${astSymbolName}\" was not found that matches the` +\n          ` TSDoc selector \":${selectorOverloadIndex}\"`\n      );\n    }\n    if (matches.length > 1) {\n      // If we found multiple matches, but the extra ones are all ancillary declarations,\n      // then return the main declaration.\n      const nonAncillaryMatch: AstDeclaration | undefined = this._tryDisambiguateAncillaryMatches(matches);\n      if (nonAncillaryMatch) {\n        return nonAncillaryMatch;\n      }\n\n      return new ResolverFailure(\n        `More than one declaration for \"${astSymbolName}\" matches the` +\n          ` TSDoc selector \":${selectorOverloadIndex}\"`\n      );\n    }\n    return matches[0];\n  }\n\n  /**\n   * This resolves an ambiguous match in the case where the extra matches are all ancillary declarations,\n   * except for one match that is the main declaration.\n   */\n  private _tryDisambiguateAncillaryMatches(\n    matches: ReadonlyArray<AstDeclaration>\n  ): AstDeclaration | undefined {\n    let result: AstDeclaration | undefined = undefined;\n\n    for (const match of matches) {\n      const declarationMetadata: DeclarationMetadata = this._collector.fetchDeclarationMetadata(match);\n      if (!declarationMetadata.isAncillary) {\n        if (result) {\n          return undefined; // more than one match\n        }\n        result = match;\n      }\n    }\n    return result;\n  }\n}\n"]}

package/lib-esm/analyzer/AstSymbol.js

@@ -0,0 +1,104 @@
+// 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 { AstEntity } from './AstEntity';
+/**
+ * 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 AstSymbol represents the ts.Symbol information for an AstDeclaration.  For example,
+ * if a method has 3 overloads, each overloaded signature will have its own AstDeclaration,
+ * but they will all share a common AstSymbol.
+ *
+ * For nested definitions, the AstSymbol has a unique parent (i.e. AstSymbol.rootAstSymbol),
+ * but the parent/children for each AstDeclaration may be different.  Consider this example:
+ *
+ * ```ts
+ * export namespace N {
+ *   export function f(): void { }
+ * }
+ *
+ * export interface N {
+ *   g(): void;
+ * }
+ * ```
+ *
+ * Note how the parent/child relationships are different for the symbol tree versus
+ * the declaration tree, and the declaration tree has two roots:
+ *
+ * ```
+ * AstSymbol tree:            AstDeclaration tree:
+ * - N                        - N (namespace)
+ *   - f                        - f
+ *   - g                      - N (interface)
+ *                              - g
+ * ```
+ */
+export class AstSymbol extends AstEntity {
+    constructor(options) {
+        super();
+        // This flag is unused if this is not the root symbol.
+        // Being "analyzed" is a property of the root symbol.
+        this._analyzed = false;
+        this.followedSymbol = options.followedSymbol;
+        this.localName = options.localName;
+        this.isExternal = options.isExternal;
+        this.nominalAnalysis = options.nominalAnalysis;
+        this.parentAstSymbol = options.parentAstSymbol;
+        this.rootAstSymbol = options.rootAstSymbol || this;
+        this._astDeclarations = [];
+    }
+    /**
+     * The one or more declarations for this symbol.
+     * @remarks
+     * For example, if this symbol is a method, then the declarations might be
+     * various method overloads.  If this symbol is a namespace, then the declarations
+     * might be separate namespace blocks with the same name that get combined via
+     * declaration merging.
+     */
+    get astDeclarations() {
+        return this._astDeclarations;
+    }
+    /**
+     * Returns true if the AstSymbolTable.analyze() was called for this object.
+     * See that function for details.
+     * @remarks
+     * AstSymbolTable.analyze() is always performed on the root AstSymbol.  This function
+     * returns true if-and-only-if the root symbol was analyzed.
+     */
+    get analyzed() {
+        return this.rootAstSymbol._analyzed;
+    }
+    /**
+     * This is an internal callback used when the AstSymbolTable attaches a new
+     * AstDeclaration to this object.
+     * @internal
+     */
+    _notifyDeclarationAttach(astDeclaration) {
+        if (this.analyzed) {
+            throw new InternalError('_notifyDeclarationAttach() called after analysis is already complete');
+        }
+        this._astDeclarations.push(astDeclaration);
+    }
+    /**
+     * This is an internal callback used when the AstSymbolTable.analyze()
+     * has processed this object.
+     * @internal
+     */
+    _notifyAnalyzed() {
+        if (this.parentAstSymbol) {
+            throw new InternalError('_notifyAnalyzed() called for an AstSymbol which is not the root');
+        }
+        this._analyzed = true;
+    }
+    /**
+     * Helper that calls AstDeclaration.forEachDeclarationRecursive() for each AstDeclaration.
+     */
+    forEachDeclarationRecursive(action) {
+        for (const astDeclaration of this.astDeclarations) {
+            astDeclaration.forEachDeclarationRecursive(action);
+        }
+    }
+}
+//# sourceMappingURL=AstSymbol.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AstSymbol.js","sourceRoot":"","sources":["../../src/analyzer/AstSymbol.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAI3D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAcxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,SAAU,SAAQ,SAAS;IA6DtC,YAAmB,OAA0B;QAC3C,KAAK,EAAE,CAAC;QALV,sDAAsD;QACtD,qDAAqD;QAC7C,cAAS,GAAY,KAAK,CAAC;QAKjC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;QACnD,IAAI,CAAC,gBAAgB,GAAG,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,IAAW,eAAe;QACxB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACH,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACI,wBAAwB,CAAC,cAA8B;QAC5D,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,aAAa,CAAC,sEAAsE,CAAC,CAAC;QAClG,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACI,eAAe;QACpB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,MAAM,IAAI,aAAa,CAAC,iEAAiE,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,2BAA2B,CAAC,MAAgD;QACjF,KAAK,MAAM,cAAc,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAClD,cAAc,CAAC,2BAA2B,CAAC,MAAM,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 type * as ts from 'typescript';\n\nimport { InternalError } from '@rushstack/node-core-library';\n\nimport type { AstDeclaration } from './AstDeclaration';\nimport { AstEntity } from './AstEntity';\n\n/**\n * Constructor options for AstSymbol\n */\nexport interface IAstSymbolOptions {\n  readonly followedSymbol: ts.Symbol;\n  readonly localName: string;\n  readonly isExternal: boolean;\n  readonly nominalAnalysis: boolean;\n  readonly parentAstSymbol: AstSymbol | undefined;\n  readonly rootAstSymbol: AstSymbol | 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 AstSymbol represents the ts.Symbol information for an AstDeclaration.  For example,\n * if a method has 3 overloads, each overloaded signature will have its own AstDeclaration,\n * but they will all share a common AstSymbol.\n *\n * For nested definitions, the AstSymbol has a unique parent (i.e. AstSymbol.rootAstSymbol),\n * but the parent/children for each AstDeclaration may be different.  Consider this example:\n *\n * ```ts\n * export namespace N {\n *   export function f(): void { }\n * }\n *\n * export interface N {\n *   g(): void;\n * }\n * ```\n *\n * Note how the parent/child relationships are different for the symbol tree versus\n * the declaration tree, and the declaration tree has two roots:\n *\n * ```\n * AstSymbol tree:            AstDeclaration tree:\n * - N                        - N (namespace)\n *   - f                        - f\n *   - g                      - N (interface)\n *                              - g\n * ```\n */\nexport class AstSymbol extends AstEntity {\n  /** {@inheritdoc} */\n  public readonly localName: string; // abstract\n\n  /**\n   * If true, then the `followedSymbol` (i.e. original declaration) of this symbol\n   * is not part of the working package.  The working package may still export this symbol,\n   * but if so it should be emitted as an alias such as `export { X } from \"package1\";`.\n   */\n  public readonly isExternal: boolean;\n\n  /**\n   * The compiler symbol where this type was defined, after following any aliases.\n   *\n   * @remarks\n   * This is a normal form that can be reached from any symbol alias by calling\n   * `TypeScriptHelpers.followAliases()`.  It can be compared to determine whether two\n   * symbols refer to the same underlying type.\n   */\n  public readonly followedSymbol: ts.Symbol;\n\n  /**\n   * If true, then this AstSymbol represents a foreign object whose structure will be\n   * ignored.  The AstDeclaration objects will not have any parent or children, and its references\n   * will not be analyzed.\n   *\n   * Nominal symbols are tracked e.g. when they are reexported by the working package.\n   */\n  public readonly nominalAnalysis: boolean;\n\n  /**\n   * Returns the symbol of the parent of this AstSymbol, or undefined if there is no parent.\n   * @remarks\n   * If a symbol has multiple declarations, we assume (as an axiom) that their parent\n   * declarations will belong to the same symbol.  This means that the \"parent\" of a\n   * symbol is a well-defined concept.  However, the \"children\" of a symbol are not very\n   * meaningful, because different declarations may have different nested members,\n   * so we usually need to traverse declarations to find children.\n   */\n  public readonly parentAstSymbol: AstSymbol | undefined;\n\n  /**\n   * Returns the symbol of the root of the AstDeclaration hierarchy.\n   * @remarks\n   * NOTE: If this AstSymbol is the root, then rootAstSymbol will point to itself.\n   */\n  public readonly rootAstSymbol: AstSymbol;\n\n  /**\n   * Additional information that is calculated later by the `Collector`.  The actual type is `SymbolMetadata`,\n   * but we declare it as `unknown` because consumers must obtain this object by calling\n   * `Collector.fetchSymbolMetadata()`.\n   */\n  public symbolMetadata: unknown;\n\n  private readonly _astDeclarations: AstDeclaration[];\n\n  // This flag is unused if this is not the root symbol.\n  // Being \"analyzed\" is a property of the root symbol.\n  private _analyzed: boolean = false;\n\n  public constructor(options: IAstSymbolOptions) {\n    super();\n\n    this.followedSymbol = options.followedSymbol;\n    this.localName = options.localName;\n    this.isExternal = options.isExternal;\n    this.nominalAnalysis = options.nominalAnalysis;\n    this.parentAstSymbol = options.parentAstSymbol;\n    this.rootAstSymbol = options.rootAstSymbol || this;\n    this._astDeclarations = [];\n  }\n\n  /**\n   * The one or more declarations for this symbol.\n   * @remarks\n   * For example, if this symbol is a method, then the declarations might be\n   * various method overloads.  If this symbol is a namespace, then the declarations\n   * might be separate namespace blocks with the same name that get combined via\n   * declaration merging.\n   */\n  public get astDeclarations(): ReadonlyArray<AstDeclaration> {\n    return this._astDeclarations;\n  }\n\n  /**\n   * Returns true if the AstSymbolTable.analyze() was called for this object.\n   * See that function for details.\n   * @remarks\n   * AstSymbolTable.analyze() is always performed on the root AstSymbol.  This function\n   * returns true if-and-only-if the root symbol was analyzed.\n   */\n  public get analyzed(): boolean {\n    return this.rootAstSymbol._analyzed;\n  }\n\n  /**\n   * This is an internal callback used when the AstSymbolTable attaches a new\n   * AstDeclaration to this object.\n   * @internal\n   */\n  public _notifyDeclarationAttach(astDeclaration: AstDeclaration): void {\n    if (this.analyzed) {\n      throw new InternalError('_notifyDeclarationAttach() called after analysis is already complete');\n    }\n    this._astDeclarations.push(astDeclaration);\n  }\n\n  /**\n   * This is an internal callback used when the AstSymbolTable.analyze()\n   * has processed this object.\n   * @internal\n   */\n  public _notifyAnalyzed(): void {\n    if (this.parentAstSymbol) {\n      throw new InternalError('_notifyAnalyzed() called for an AstSymbol which is not the root');\n    }\n    this._analyzed = true;\n  }\n\n  /**\n   * Helper that calls AstDeclaration.forEachDeclarationRecursive() for each AstDeclaration.\n   */\n  public forEachDeclarationRecursive(action: (astDeclaration: AstDeclaration) => void): void {\n    for (const astDeclaration of this.astDeclarations) {\n      astDeclaration.forEachDeclarationRecursive(action);\n    }\n  }\n}\n"]}