@microsoft/api-extractor 7.56.2 → 7.57.0

package/lib-esm/collector/SourceMapper.js

@@ -0,0 +1,171 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as path from 'node:path';
+import { SourceMapConsumer } from 'source-map';
+import { FileSystem, InternalError, JsonFile, NewlineKind } from '@rushstack/node-core-library';
+export class SourceMapper {
+    constructor() {
+        // Map from .d.ts file path --> ISourceMap if a source map was found, or null if not found
+        this._sourceMapByFilePath = new Map();
+        // Cache the FileSystem.exists() result for mapped .ts files
+        this._originalFileInfoByPath = new Map();
+    }
+    /**
+     * Given a `.d.ts` source file and a specific position within the file, return the corresponding
+     * `ISourceLocation`.
+     */
+    getSourceLocation(options) {
+        const lineAndCharacter = options.sourceFile.getLineAndCharacterOfPosition(options.pos);
+        const sourceLocation = {
+            sourceFilePath: options.sourceFile.fileName,
+            sourceFileLine: lineAndCharacter.line + 1,
+            sourceFileColumn: lineAndCharacter.character + 1
+        };
+        if (options.useDtsLocation) {
+            return sourceLocation;
+        }
+        const mappedSourceLocation = this._getMappedSourceLocation(sourceLocation);
+        return mappedSourceLocation || sourceLocation;
+    }
+    _getMappedSourceLocation(sourceLocation) {
+        const { sourceFilePath, sourceFileLine, sourceFileColumn } = sourceLocation;
+        if (!FileSystem.exists(sourceFilePath)) {
+            // Sanity check
+            throw new InternalError('The referenced path was not found: ' + sourceFilePath);
+        }
+        const sourceMap = this._getSourceMap(sourceFilePath);
+        if (!sourceMap)
+            return;
+        const nearestMappingItem = SourceMapper._findNearestMappingItem(sourceMap.mappingItems, {
+            line: sourceFileLine,
+            column: sourceFileColumn
+        });
+        if (!nearestMappingItem)
+            return;
+        const mappedFilePath = path.resolve(path.dirname(sourceFilePath), nearestMappingItem.source);
+        // Does the mapped filename exist?  Use a cache to remember the answer.
+        let originalFileInfo = this._originalFileInfoByPath.get(mappedFilePath);
+        if (originalFileInfo === undefined) {
+            originalFileInfo = {
+                fileExists: FileSystem.exists(mappedFilePath),
+                maxColumnForLine: []
+            };
+            if (originalFileInfo.fileExists) {
+                // Read the file and measure the length of each line
+                originalFileInfo.maxColumnForLine = FileSystem.readFile(mappedFilePath, {
+                    convertLineEndings: NewlineKind.Lf
+                })
+                    .split('\n')
+                    .map((x) => x.length + 1); // +1 since columns are 1-based
+                originalFileInfo.maxColumnForLine.unshift(0); // Extra item since lines are 1-based
+            }
+            this._originalFileInfoByPath.set(mappedFilePath, originalFileInfo);
+        }
+        // Don't translate coordinates to a file that doesn't exist
+        if (!originalFileInfo.fileExists)
+            return;
+        // The nearestMappingItem anchor may be above/left of the real position, due to gaps in the mapping.  Calculate
+        // the delta and apply it to the original position.
+        const guessedPosition = {
+            line: nearestMappingItem.originalLine + sourceFileLine - nearestMappingItem.generatedLine,
+            column: nearestMappingItem.originalColumn + sourceFileColumn - nearestMappingItem.generatedColumn
+        };
+        // Verify that the result is not out of bounds, in cause our heuristic failed
+        if (guessedPosition.line >= 1 &&
+            guessedPosition.line < originalFileInfo.maxColumnForLine.length &&
+            guessedPosition.column >= 1 &&
+            guessedPosition.column <= originalFileInfo.maxColumnForLine[guessedPosition.line]) {
+            return {
+                sourceFilePath: mappedFilePath,
+                sourceFileLine: guessedPosition.line,
+                sourceFileColumn: guessedPosition.column
+            };
+        }
+        else {
+            // The guessed position was out of bounds, so use the nearestMappingItem position instead.
+            return {
+                sourceFilePath: mappedFilePath,
+                sourceFileLine: nearestMappingItem.originalLine,
+                sourceFileColumn: nearestMappingItem.originalColumn
+            };
+        }
+    }
+    _getSourceMap(sourceFilePath) {
+        let sourceMap = this._sourceMapByFilePath.get(sourceFilePath);
+        if (sourceMap === undefined) {
+            // Normalize the path and redo the lookup
+            const normalizedPath = FileSystem.getRealPath(sourceFilePath);
+            sourceMap = this._sourceMapByFilePath.get(normalizedPath);
+            if (sourceMap !== undefined) {
+                // Copy the result from the normalized to the non-normalized key
+                this._sourceMapByFilePath.set(sourceFilePath, sourceMap);
+            }
+            else {
+                // Given "folder/file.d.ts", check for a corresponding "folder/file.d.ts.map"
+                const sourceMapPath = normalizedPath + '.map';
+                if (FileSystem.exists(sourceMapPath)) {
+                    // Load up the source map
+                    const rawSourceMap = JsonFile.load(sourceMapPath);
+                    const sourceMapConsumer = new SourceMapConsumer(rawSourceMap);
+                    const mappingItems = [];
+                    // Extract the list of mapping items
+                    sourceMapConsumer.eachMapping((mappingItem) => {
+                        mappingItems.push({
+                            ...mappingItem,
+                            // The "source-map" package inexplicably uses 1-based line numbers but 0-based column numbers.
+                            // Fix that up proactively so we don't have to deal with it later.
+                            generatedColumn: mappingItem.generatedColumn + 1,
+                            originalColumn: mappingItem.originalColumn + 1
+                        });
+                    }, this, SourceMapConsumer.GENERATED_ORDER);
+                    sourceMap = { sourceMapConsumer, mappingItems };
+                }
+                else {
+                    // No source map for this filename
+                    sourceMap = null;
+                }
+                this._sourceMapByFilePath.set(normalizedPath, sourceMap);
+                if (sourceFilePath !== normalizedPath) {
+                    // Add both keys to the map
+                    this._sourceMapByFilePath.set(sourceFilePath, sourceMap);
+                }
+            }
+        }
+        return sourceMap;
+    }
+    // The `mappingItems` array is sorted by generatedLine/generatedColumn (GENERATED_ORDER).
+    // The _findNearestMappingItem() lookup is a simple binary search that returns the previous item
+    // if there is no exact match.
+    static _findNearestMappingItem(mappingItems, position) {
+        if (mappingItems.length === 0) {
+            return undefined;
+        }
+        let startIndex = 0;
+        let endIndex = mappingItems.length - 1;
+        while (startIndex <= endIndex) {
+            const middleIndex = startIndex + Math.floor((endIndex - startIndex) / 2);
+            const diff = SourceMapper._compareMappingItem(mappingItems[middleIndex], position);
+            if (diff < 0) {
+                startIndex = middleIndex + 1;
+            }
+            else if (diff > 0) {
+                endIndex = middleIndex - 1;
+            }
+            else {
+                // Exact match
+                return mappingItems[middleIndex];
+            }
+        }
+        // If we didn't find an exact match, then endIndex < startIndex.
+        // Take endIndex because it's the smaller value.
+        return mappingItems[endIndex];
+    }
+    static _compareMappingItem(mappingItem, position) {
+        const diff = mappingItem.generatedLine - position.line;
+        if (diff !== 0) {
+            return diff;
+        }
+        return mappingItem.generatedColumn - position.column;
+    }
+}
+//# sourceMappingURL=SourceMapper.js.map

package/lib-esm/collector/SourceMapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceMapper.js","sourceRoot":"","sources":["../../src/collector/SourceMapper.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 path from 'node:path';\n\nimport { SourceMapConsumer, type RawSourceMap, type MappingItem, type Position } from 'source-map';\nimport type ts from 'typescript';\n\nimport { FileSystem, InternalError, JsonFile, NewlineKind } from '@rushstack/node-core-library';\n\ninterface ISourceMap {\n  sourceMapConsumer: SourceMapConsumer;\n\n  // SourceMapConsumer.originalPositionFor() is useless because the mapping contains numerous gaps,\n  // and the API provides no way to find the nearest match.  So instead we extract all the mapping items\n  // and search them using SourceMapper._findNearestMappingItem().\n  mappingItems: MappingItem[];\n}\n\ninterface IOriginalFileInfo {\n  // Whether the .ts file exists\n  fileExists: boolean;\n\n  // This is used to check whether the guessed position is out of bounds.\n  // Since column/line numbers are 1-based, the 0th item in this array is unused.\n  maxColumnForLine: number[];\n}\n\nexport interface ISourceLocation {\n  /**\n   * The absolute path to the source file.\n   */\n  sourceFilePath: string;\n\n  /**\n   * The line number in the source file. The first line number is 1.\n   */\n  sourceFileLine: number;\n\n  /**\n   * The column number in the source file. The first column number is 1.\n   */\n  sourceFileColumn: number;\n}\n\nexport interface IGetSourceLocationOptions {\n  /**\n   * The source file to get the source location from.\n   */\n  sourceFile: ts.SourceFile;\n\n  /**\n   * The position within the source file to get the source location from.\n   */\n  pos: number;\n\n  /**\n   * If `false` or not provided, then we attempt to follow source maps in order to resolve the\n   * location to the original `.ts` file. If resolution isn't possible for some reason, we fall\n   * back to the `.d.ts` location.\n   *\n   * If `true`, then we don't bother following source maps, and the location refers to the `.d.ts`\n   * location.\n   */\n  useDtsLocation?: boolean;\n}\n\nexport class SourceMapper {\n  // Map from .d.ts file path --> ISourceMap if a source map was found, or null if not found\n  private _sourceMapByFilePath: Map<string, ISourceMap | null> = new Map<string, ISourceMap | null>();\n\n  // Cache the FileSystem.exists() result for mapped .ts files\n  private _originalFileInfoByPath: Map<string, IOriginalFileInfo> = new Map<string, IOriginalFileInfo>();\n\n  /**\n   * Given a `.d.ts` source file and a specific position within the file, return the corresponding\n   * `ISourceLocation`.\n   */\n  public getSourceLocation(options: IGetSourceLocationOptions): ISourceLocation {\n    const lineAndCharacter: ts.LineAndCharacter = options.sourceFile.getLineAndCharacterOfPosition(\n      options.pos\n    );\n    const sourceLocation: ISourceLocation = {\n      sourceFilePath: options.sourceFile.fileName,\n      sourceFileLine: lineAndCharacter.line + 1,\n      sourceFileColumn: lineAndCharacter.character + 1\n    };\n\n    if (options.useDtsLocation) {\n      return sourceLocation;\n    }\n\n    const mappedSourceLocation: ISourceLocation | undefined = this._getMappedSourceLocation(sourceLocation);\n    return mappedSourceLocation || sourceLocation;\n  }\n\n  private _getMappedSourceLocation(sourceLocation: ISourceLocation): ISourceLocation | undefined {\n    const { sourceFilePath, sourceFileLine, sourceFileColumn } = sourceLocation;\n\n    if (!FileSystem.exists(sourceFilePath)) {\n      // Sanity check\n      throw new InternalError('The referenced path was not found: ' + sourceFilePath);\n    }\n\n    const sourceMap: ISourceMap | null = this._getSourceMap(sourceFilePath);\n    if (!sourceMap) return;\n\n    const nearestMappingItem: MappingItem | undefined = SourceMapper._findNearestMappingItem(\n      sourceMap.mappingItems,\n      {\n        line: sourceFileLine,\n        column: sourceFileColumn\n      }\n    );\n\n    if (!nearestMappingItem) return;\n\n    const mappedFilePath: string = path.resolve(path.dirname(sourceFilePath), nearestMappingItem.source);\n\n    // Does the mapped filename exist?  Use a cache to remember the answer.\n    let originalFileInfo: IOriginalFileInfo | undefined = this._originalFileInfoByPath.get(mappedFilePath);\n    if (originalFileInfo === undefined) {\n      originalFileInfo = {\n        fileExists: FileSystem.exists(mappedFilePath),\n        maxColumnForLine: []\n      };\n\n      if (originalFileInfo.fileExists) {\n        // Read the file and measure the length of each line\n        originalFileInfo.maxColumnForLine = FileSystem.readFile(mappedFilePath, {\n          convertLineEndings: NewlineKind.Lf\n        })\n          .split('\\n')\n          .map((x) => x.length + 1); // +1 since columns are 1-based\n        originalFileInfo.maxColumnForLine.unshift(0); // Extra item since lines are 1-based\n      }\n\n      this._originalFileInfoByPath.set(mappedFilePath, originalFileInfo);\n    }\n\n    // Don't translate coordinates to a file that doesn't exist\n    if (!originalFileInfo.fileExists) return;\n\n    // The nearestMappingItem anchor may be above/left of the real position, due to gaps in the mapping.  Calculate\n    // the delta and apply it to the original position.\n    const guessedPosition: Position = {\n      line: nearestMappingItem.originalLine + sourceFileLine - nearestMappingItem.generatedLine,\n      column: nearestMappingItem.originalColumn + sourceFileColumn - nearestMappingItem.generatedColumn\n    };\n\n    // Verify that the result is not out of bounds, in cause our heuristic failed\n    if (\n      guessedPosition.line >= 1 &&\n      guessedPosition.line < originalFileInfo.maxColumnForLine.length &&\n      guessedPosition.column >= 1 &&\n      guessedPosition.column <= originalFileInfo.maxColumnForLine[guessedPosition.line]\n    ) {\n      return {\n        sourceFilePath: mappedFilePath,\n        sourceFileLine: guessedPosition.line,\n        sourceFileColumn: guessedPosition.column\n      };\n    } else {\n      // The guessed position was out of bounds, so use the nearestMappingItem position instead.\n      return {\n        sourceFilePath: mappedFilePath,\n        sourceFileLine: nearestMappingItem.originalLine,\n        sourceFileColumn: nearestMappingItem.originalColumn\n      };\n    }\n  }\n\n  private _getSourceMap(sourceFilePath: string): ISourceMap | null {\n    let sourceMap: ISourceMap | null | undefined = this._sourceMapByFilePath.get(sourceFilePath);\n\n    if (sourceMap === undefined) {\n      // Normalize the path and redo the lookup\n      const normalizedPath: string = FileSystem.getRealPath(sourceFilePath);\n\n      sourceMap = this._sourceMapByFilePath.get(normalizedPath);\n      if (sourceMap !== undefined) {\n        // Copy the result from the normalized to the non-normalized key\n        this._sourceMapByFilePath.set(sourceFilePath, sourceMap);\n      } else {\n        // Given \"folder/file.d.ts\", check for a corresponding \"folder/file.d.ts.map\"\n        const sourceMapPath: string = normalizedPath + '.map';\n        if (FileSystem.exists(sourceMapPath)) {\n          // Load up the source map\n          const rawSourceMap: RawSourceMap = JsonFile.load(sourceMapPath) as RawSourceMap;\n\n          const sourceMapConsumer: SourceMapConsumer = new SourceMapConsumer(rawSourceMap);\n          const mappingItems: MappingItem[] = [];\n\n          // Extract the list of mapping items\n          sourceMapConsumer.eachMapping(\n            (mappingItem: MappingItem) => {\n              mappingItems.push({\n                ...mappingItem,\n                // The \"source-map\" package inexplicably uses 1-based line numbers but 0-based column numbers.\n                // Fix that up proactively so we don't have to deal with it later.\n                generatedColumn: mappingItem.generatedColumn + 1,\n                originalColumn: mappingItem.originalColumn + 1\n              });\n            },\n            this,\n            SourceMapConsumer.GENERATED_ORDER\n          );\n\n          sourceMap = { sourceMapConsumer, mappingItems };\n        } else {\n          // No source map for this filename\n          sourceMap = null;\n        }\n\n        this._sourceMapByFilePath.set(normalizedPath, sourceMap);\n        if (sourceFilePath !== normalizedPath) {\n          // Add both keys to the map\n          this._sourceMapByFilePath.set(sourceFilePath, sourceMap);\n        }\n      }\n    }\n\n    return sourceMap;\n  }\n\n  // The `mappingItems` array is sorted by generatedLine/generatedColumn (GENERATED_ORDER).\n  // The _findNearestMappingItem() lookup is a simple binary search that returns the previous item\n  // if there is no exact match.\n  private static _findNearestMappingItem(\n    mappingItems: MappingItem[],\n    position: Position\n  ): MappingItem | undefined {\n    if (mappingItems.length === 0) {\n      return undefined;\n    }\n\n    let startIndex: number = 0;\n    let endIndex: number = mappingItems.length - 1;\n\n    while (startIndex <= endIndex) {\n      const middleIndex: number = startIndex + Math.floor((endIndex - startIndex) / 2);\n\n      const diff: number = SourceMapper._compareMappingItem(mappingItems[middleIndex], position);\n\n      if (diff < 0) {\n        startIndex = middleIndex + 1;\n      } else if (diff > 0) {\n        endIndex = middleIndex - 1;\n      } else {\n        // Exact match\n        return mappingItems[middleIndex];\n      }\n    }\n\n    // If we didn't find an exact match, then endIndex < startIndex.\n    // Take endIndex because it's the smaller value.\n    return mappingItems[endIndex];\n  }\n\n  private static _compareMappingItem(mappingItem: MappingItem, position: Position): number {\n    const diff: number = mappingItem.generatedLine - position.line;\n    if (diff !== 0) {\n      return diff;\n    }\n    return mappingItem.generatedColumn - position.column;\n  }\n}\n"]}

package/lib-esm/collector/SymbolMetadata.js

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Stores the Collector's additional analysis for an `AstSymbol`.  This object is assigned to `AstSymbol.metadata`
+ * but consumers must always obtain it by calling `Collector.fetchSymbolMetadata()`.
+ */
+export class SymbolMetadata {
+    constructor(options) {
+        this.maxEffectiveReleaseTag = options.maxEffectiveReleaseTag;
+    }
+}
+//# sourceMappingURL=SymbolMetadata.js.map

package/lib-esm/collector/SymbolMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SymbolMetadata.js","sourceRoot":"","sources":["../../src/collector/SymbolMetadata.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAW3D;;;GAGG;AACH,MAAM,OAAO,cAAc;IAKzB,YAAmB,OAA+B;QAChD,IAAI,CAAC,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC/D,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 { ReleaseTag } from '@microsoft/api-extractor-model';\n\n/**\n * Constructor parameters for `SymbolMetadata`.\n */\nexport interface ISymbolMetadataOptions {\n  maxEffectiveReleaseTag: ReleaseTag;\n}\n\n/**\n * Stores the Collector's additional analysis for an `AstSymbol`.  This object is assigned to `AstSymbol.metadata`\n * but consumers must always obtain it by calling `Collector.fetchSymbolMetadata()`.\n */\nexport class SymbolMetadata {\n  // For all declarations associated with this symbol, this is the\n  // `ApiItemMetadata.effectiveReleaseTag` value that is most public.\n  public readonly maxEffectiveReleaseTag: ReleaseTag;\n\n  public constructor(options: ISymbolMetadataOptions) {\n    this.maxEffectiveReleaseTag = options.maxEffectiveReleaseTag;\n  }\n}\n"]}

package/lib-esm/collector/VisitorState.js

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Keeps track of a directed graph traversal that needs to detect cycles.
+ */
+export var VisitorState;
+(function (VisitorState) {
+    /**
+     * We have not visited the node yet.
+     */
+    VisitorState[VisitorState["Unvisited"] = 0] = "Unvisited";
+    /**
+     * We have visited the node, but have not finished traversing its references yet.
+     * If we reach a node that is already in the `Visiting` state, this means we have
+     * encountered a cyclic reference.
+     */
+    VisitorState[VisitorState["Visiting"] = 1] = "Visiting";
+    /**
+     * We are finished vising the node and all its references.
+     */
+    VisitorState[VisitorState["Visited"] = 2] = "Visited";
+})(VisitorState || (VisitorState = {}));
+//# sourceMappingURL=VisitorState.js.map

package/lib-esm/collector/VisitorState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VisitorState.js","sourceRoot":"","sources":["../../src/collector/VisitorState.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;GAEG;AACH,MAAM,CAAN,IAAY,YAiBX;AAjBD,WAAY,YAAY;IACtB;;OAEG;IACH,yDAAa,CAAA;IAEb;;;;OAIG;IACH,uDAAY,CAAA;IAEZ;;OAEG;IACH,qDAAW,CAAA;AACb,CAAC,EAjBW,YAAY,KAAZ,YAAY,QAiBvB","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 * Keeps track of a directed graph traversal that needs to detect cycles.\n */\nexport enum VisitorState {\n  /**\n   * We have not visited the node yet.\n   */\n  Unvisited = 0,\n\n  /**\n   * We have visited the node, but have not finished traversing its references yet.\n   * If we reach a node that is already in the `Visiting` state, this means we have\n   * encountered a cyclic reference.\n   */\n  Visiting = 1,\n\n  /**\n   * We are finished vising the node and all its references.\n   */\n  Visited = 2\n}\n"]}

package/lib-esm/collector/WorkingPackage.js

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Information about the working package for a particular invocation of API Extractor.
+ *
+ * @remarks
+ * API Extractor tries to model the world as a collection of NPM packages, such that each
+ * .d.ts file belongs to at most one package.  When API Extractor is invoked on a project,
+ * we refer to that project as being the "working package".  There is exactly one
+ * "working package" for the duration of this analysis.  Any files that do not belong to
+ * the working package are referred to as "external":  external declarations belonging to
+ * external packages.
+ *
+ * If API Extractor is invoked on a standalone .d.ts file, the "working package" may not
+ * have an actual package.json file on disk, but we still refer to it in concept.
+ */
+export class WorkingPackage {
+    constructor(options) {
+        this.packageFolder = options.packageFolder;
+        this.packageJson = options.packageJson;
+        this.entryPointSourceFile = options.entryPointSourceFile;
+    }
+    /**
+     * Returns the full name of the working package.
+     */
+    get name() {
+        return this.packageJson.name;
+    }
+}
+//# sourceMappingURL=WorkingPackage.js.map

package/lib-esm/collector/WorkingPackage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkingPackage.js","sourceRoot":"","sources":["../../src/collector/WorkingPackage.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAgB3D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IAmCzB,YAAmB,OAA+B;QAChD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,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 * as tsdoc from '@microsoft/tsdoc';\nimport type { INodePackageJson } from '@rushstack/node-core-library';\n\n/**\n * Constructor options for WorkingPackage\n */\nexport interface IWorkingPackageOptions {\n  packageFolder: string;\n  packageJson: INodePackageJson;\n  entryPointSourceFile: ts.SourceFile;\n}\n\n/**\n * Information about the working package for a particular invocation of API Extractor.\n *\n * @remarks\n * API Extractor tries to model the world as a collection of NPM packages, such that each\n * .d.ts file belongs to at most one package.  When API Extractor is invoked on a project,\n * we refer to that project as being the \"working package\".  There is exactly one\n * \"working package\" for the duration of this analysis.  Any files that do not belong to\n * the working package are referred to as \"external\":  external declarations belonging to\n * external packages.\n *\n * If API Extractor is invoked on a standalone .d.ts file, the \"working package\" may not\n * have an actual package.json file on disk, but we still refer to it in concept.\n */\nexport class WorkingPackage {\n  /**\n   * Returns the folder for the package.json file of the working package.\n   *\n   * @remarks\n   * If the entry point is `C:\\Folder\\project\\src\\index.ts` and the nearest package.json\n   * is `C:\\Folder\\project\\package.json`, then the packageFolder is `C:\\Folder\\project`\n   */\n  public readonly packageFolder: string;\n\n  /**\n   * The parsed package.json file for the working package.\n   */\n  public readonly packageJson: INodePackageJson;\n\n  /**\n   * The entry point being processed during this invocation of API Extractor.\n   *\n   * @remarks\n   * The working package may have multiple entry points; however, today API Extractor\n   * only processes a single entry point during an invocation.  This will be improved\n   * in the future.\n   */\n  public readonly entryPointSourceFile: ts.SourceFile;\n\n  /**\n   * The `@packageDocumentation` comment, if any, for the working package.\n   */\n  public tsdocComment: tsdoc.DocComment | undefined;\n\n  /**\n   * Additional parser information for `WorkingPackage.tsdocComment`.\n   */\n  public tsdocParserContext: tsdoc.ParserContext | undefined;\n\n  public constructor(options: IWorkingPackageOptions) {\n    this.packageFolder = options.packageFolder;\n    this.packageJson = options.packageJson;\n    this.entryPointSourceFile = options.entryPointSourceFile;\n  }\n\n  /**\n   * Returns the full name of the working package.\n   */\n  public get name(): string {\n    return this.packageJson.name;\n  }\n}\n"]}

package/lib-esm/enhancers/DocCommentEnhancer.js

@@ -0,0 +1,213 @@
+// 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 { ReleaseTag } from '@microsoft/api-extractor-model';
+import { AstSymbol } from '../analyzer/AstSymbol';
+import { ExtractorMessageId } from '../api/ExtractorMessageId';
+import { VisitorState } from '../collector/VisitorState';
+import { ResolverFailure } from '../analyzer/AstReferenceResolver';
+export class DocCommentEnhancer {
+    constructor(collector) {
+        this._collector = collector;
+    }
+    static analyze(collector) {
+        const docCommentEnhancer = new DocCommentEnhancer(collector);
+        docCommentEnhancer.analyze();
+    }
+    analyze() {
+        for (const entity of this._collector.entities) {
+            if (entity.astEntity instanceof AstSymbol) {
+                if (entity.consumable ||
+                    this._collector.extractorConfig.apiReportIncludeForgottenExports ||
+                    this._collector.extractorConfig.docModelIncludeForgottenExports) {
+                    entity.astEntity.forEachDeclarationRecursive((astDeclaration) => {
+                        this._analyzeApiItem(astDeclaration);
+                    });
+                }
+            }
+        }
+    }
+    _analyzeApiItem(astDeclaration) {
+        const metadata = this._collector.fetchApiItemMetadata(astDeclaration);
+        if (metadata.docCommentEnhancerVisitorState === VisitorState.Visited) {
+            return;
+        }
+        if (metadata.docCommentEnhancerVisitorState === VisitorState.Visiting) {
+            this._collector.messageRouter.addAnalyzerIssue(ExtractorMessageId.CyclicInheritDoc, `The @inheritDoc tag for "${astDeclaration.astSymbol.localName}" refers to its own declaration`, astDeclaration);
+            return;
+        }
+        metadata.docCommentEnhancerVisitorState = VisitorState.Visiting;
+        if (metadata.tsdocComment && metadata.tsdocComment.inheritDocTag) {
+            this._applyInheritDoc(astDeclaration, metadata.tsdocComment, metadata.tsdocComment.inheritDocTag);
+        }
+        this._analyzeNeedsDocumentation(astDeclaration, metadata);
+        this._checkForBrokenLinks(astDeclaration, metadata);
+        metadata.docCommentEnhancerVisitorState = VisitorState.Visited;
+    }
+    _analyzeNeedsDocumentation(astDeclaration, metadata) {
+        if (astDeclaration.declaration.kind === ts.SyntaxKind.Constructor) {
+            // Constructors always do pretty much the same thing, so it's annoying to require people to write
+            // descriptions for them.  Instead, if the constructor lacks a TSDoc summary, then API Extractor
+            // will auto-generate one.
+            metadata.undocumented = false;
+            // The class that contains this constructor
+            const classDeclaration = astDeclaration.parent;
+            const configuration = this._collector.extractorConfig.tsdocConfiguration;
+            if (!metadata.tsdocComment) {
+                metadata.tsdocComment = new tsdoc.DocComment({ configuration });
+            }
+            if (!tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection)) {
+                metadata.tsdocComment.summarySection.appendNodesInParagraph([
+                    new tsdoc.DocPlainText({ configuration, text: 'Constructs a new instance of the ' }),
+                    new tsdoc.DocCodeSpan({
+                        configuration,
+                        code: classDeclaration.astSymbol.localName
+                    }),
+                    new tsdoc.DocPlainText({ configuration, text: ' class' })
+                ]);
+            }
+            const apiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
+            if (apiItemMetadata.effectiveReleaseTag === ReleaseTag.Internal) {
+                // If the constructor is marked as internal, then add a boilerplate notice for the containing class
+                const classMetadata = this._collector.fetchApiItemMetadata(classDeclaration);
+                if (!classMetadata.tsdocComment) {
+                    classMetadata.tsdocComment = new tsdoc.DocComment({ configuration });
+                }
+                if (classMetadata.tsdocComment.remarksBlock === undefined) {
+                    classMetadata.tsdocComment.remarksBlock = new tsdoc.DocBlock({
+                        configuration,
+                        blockTag: new tsdoc.DocBlockTag({
+                            configuration,
+                            tagName: tsdoc.StandardTags.remarks.tagName
+                        })
+                    });
+                }
+                classMetadata.tsdocComment.remarksBlock.content.appendNode(new tsdoc.DocParagraph({ configuration }, [
+                    new tsdoc.DocPlainText({
+                        configuration,
+                        text: `The constructor for this class is marked as internal. Third-party code should not` +
+                            ` call the constructor directly or create subclasses that extend the `
+                    }),
+                    new tsdoc.DocCodeSpan({
+                        configuration,
+                        code: classDeclaration.astSymbol.localName
+                    }),
+                    new tsdoc.DocPlainText({ configuration, text: ' class.' })
+                ]));
+            }
+            return;
+        }
+        else {
+            // For non-constructor items, we will determine whether or not the item is documented as follows:
+            // 1. If it contains a summary section with at least 10 characters, then it is considered "documented".
+            // 2. If it contains an @inheritDoc tag, then it *may* be considered "documented", depending on whether or not
+            //    the tag resolves to a "documented" API member.
+            //    - Note: for external members, we cannot currently determine this, so we will consider the "documented"
+            //      status to be unknown.
+            if (metadata.tsdocComment) {
+                if (tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection, 10)) {
+                    // If the API item has a summary comment block (with at least 10 characters), mark it as "documented".
+                    metadata.undocumented = false;
+                }
+                else if (metadata.tsdocComment.inheritDocTag) {
+                    if (this._refersToDeclarationInWorkingPackage(metadata.tsdocComment.inheritDocTag.declarationReference)) {
+                        // If the API item has an `@inheritDoc` comment that points to an API item in the working package,
+                        // then the documentation contents should have already been copied from the target via `_applyInheritDoc`.
+                        // The continued existence of the tag indicates that the declaration reference was invalid, and not
+                        // documentation contents could be copied.
+                        // An analyzer issue will have already been logged for this.
+                        // We will treat such an API as "undocumented".
+                        metadata.undocumented = true;
+                    }
+                    else {
+                        // If the API item has an `@inheritDoc` comment that points to an external API item, we cannot currently
+                        // determine whether or not the target is "documented", so we cannot say definitively that this is "undocumented".
+                        metadata.undocumented = false;
+                    }
+                }
+                else {
+                    // If the API item has neither a summary comment block, nor an `@inheritDoc` comment, mark it as "undocumented".
+                    metadata.undocumented = true;
+                }
+            }
+            else {
+                // If there is no tsdoc comment at all, mark "undocumented".
+                metadata.undocumented = true;
+            }
+        }
+    }
+    _checkForBrokenLinks(astDeclaration, metadata) {
+        if (!metadata.tsdocComment) {
+            return;
+        }
+        this._checkForBrokenLinksRecursive(astDeclaration, metadata.tsdocComment);
+    }
+    _checkForBrokenLinksRecursive(astDeclaration, node) {
+        if (node instanceof tsdoc.DocLinkTag) {
+            if (node.codeDestination) {
+                // Is it referring to the working package?  If not, we don't do any link validation, because
+                // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).
+                // Tracked by:  https://github.com/microsoft/rushstack/issues/1195
+                if (this._refersToDeclarationInWorkingPackage(node.codeDestination)) {
+                    const referencedAstDeclaration = this._collector.astReferenceResolver.resolve(node.codeDestination);
+                    if (referencedAstDeclaration instanceof ResolverFailure) {
+                        this._collector.messageRouter.addAnalyzerIssue(ExtractorMessageId.UnresolvedLink, 'The @link reference could not be resolved: ' + referencedAstDeclaration.reason, astDeclaration);
+                    }
+                }
+            }
+        }
+        for (const childNode of node.getChildNodes()) {
+            this._checkForBrokenLinksRecursive(astDeclaration, childNode);
+        }
+    }
+    /**
+     * Follow an `{@inheritDoc ___}` reference and copy the content that we find in the referenced comment.
+     */
+    _applyInheritDoc(astDeclaration, docComment, inheritDocTag) {
+        if (!inheritDocTag.declarationReference) {
+            this._collector.messageRouter.addAnalyzerIssue(ExtractorMessageId.UnresolvedInheritDocBase, 'The @inheritDoc tag needs a TSDoc declaration reference; signature matching is not supported yet', astDeclaration);
+            return;
+        }
+        if (!this._refersToDeclarationInWorkingPackage(inheritDocTag.declarationReference)) {
+            // The `@inheritDoc` tag is referencing an external package. Skip it, since AstReferenceResolver doesn't
+            // support it yet.  As a workaround, this tag will get handled later by api-documenter.
+            // Tracked by:  https://github.com/microsoft/rushstack/issues/1195
+            return;
+        }
+        const referencedAstDeclaration = this._collector.astReferenceResolver.resolve(inheritDocTag.declarationReference);
+        if (referencedAstDeclaration instanceof ResolverFailure) {
+            this._collector.messageRouter.addAnalyzerIssue(ExtractorMessageId.UnresolvedInheritDocReference, 'The @inheritDoc reference could not be resolved: ' + referencedAstDeclaration.reason, astDeclaration);
+            return;
+        }
+        this._analyzeApiItem(referencedAstDeclaration);
+        const referencedMetadata = this._collector.fetchApiItemMetadata(referencedAstDeclaration);
+        if (referencedMetadata.tsdocComment) {
+            this._copyInheritedDocs(docComment, referencedMetadata.tsdocComment);
+        }
+    }
+    /**
+     * Copy the content from `sourceDocComment` to `targetDocComment`.
+     */
+    _copyInheritedDocs(targetDocComment, sourceDocComment) {
+        targetDocComment.summarySection = sourceDocComment.summarySection;
+        targetDocComment.remarksBlock = sourceDocComment.remarksBlock;
+        targetDocComment.params.clear();
+        for (const param of sourceDocComment.params) {
+            targetDocComment.params.add(param);
+        }
+        for (const typeParam of sourceDocComment.typeParams) {
+            targetDocComment.typeParams.add(typeParam);
+        }
+        targetDocComment.returnsBlock = sourceDocComment.returnsBlock;
+        targetDocComment.inheritDocTag = undefined;
+    }
+    /**
+     * Determines whether or not the provided declaration reference points to an item in the working package.
+     */
+    _refersToDeclarationInWorkingPackage(declarationReference) {
+        return ((declarationReference === null || declarationReference === void 0 ? void 0 : declarationReference.packageName) === undefined ||
+            declarationReference.packageName === this._collector.workingPackage.name);
+    }
+}
+//# sourceMappingURL=DocCommentEnhancer.js.map

package/lib-esm/enhancers/DocCommentEnhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocCommentEnhancer.js","sourceRoot":"","sources":["../../src/enhancers/DocCommentEnhancer.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';\nimport { ReleaseTag } from '@microsoft/api-extractor-model';\n\nimport type { Collector } from '../collector/Collector';\nimport { AstSymbol } from '../analyzer/AstSymbol';\nimport type { AstDeclaration } from '../analyzer/AstDeclaration';\nimport type { ApiItemMetadata } from '../collector/ApiItemMetadata';\nimport { ExtractorMessageId } from '../api/ExtractorMessageId';\nimport { VisitorState } from '../collector/VisitorState';\nimport { ResolverFailure } from '../analyzer/AstReferenceResolver';\n\nexport class DocCommentEnhancer {\n  private readonly _collector: Collector;\n\n  public constructor(collector: Collector) {\n    this._collector = collector;\n  }\n\n  public static analyze(collector: Collector): void {\n    const docCommentEnhancer: DocCommentEnhancer = new DocCommentEnhancer(collector);\n    docCommentEnhancer.analyze();\n  }\n\n  public analyze(): void {\n    for (const entity of this._collector.entities) {\n      if (entity.astEntity instanceof AstSymbol) {\n        if (\n          entity.consumable ||\n          this._collector.extractorConfig.apiReportIncludeForgottenExports ||\n          this._collector.extractorConfig.docModelIncludeForgottenExports\n        ) {\n          entity.astEntity.forEachDeclarationRecursive((astDeclaration: AstDeclaration) => {\n            this._analyzeApiItem(astDeclaration);\n          });\n        }\n      }\n    }\n  }\n\n  private _analyzeApiItem(astDeclaration: AstDeclaration): void {\n    const metadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);\n    if (metadata.docCommentEnhancerVisitorState === VisitorState.Visited) {\n      return;\n    }\n\n    if (metadata.docCommentEnhancerVisitorState === VisitorState.Visiting) {\n      this._collector.messageRouter.addAnalyzerIssue(\n        ExtractorMessageId.CyclicInheritDoc,\n        `The @inheritDoc tag for \"${astDeclaration.astSymbol.localName}\" refers to its own declaration`,\n        astDeclaration\n      );\n      return;\n    }\n    metadata.docCommentEnhancerVisitorState = VisitorState.Visiting;\n\n    if (metadata.tsdocComment && metadata.tsdocComment.inheritDocTag) {\n      this._applyInheritDoc(astDeclaration, metadata.tsdocComment, metadata.tsdocComment.inheritDocTag);\n    }\n\n    this._analyzeNeedsDocumentation(astDeclaration, metadata);\n\n    this._checkForBrokenLinks(astDeclaration, metadata);\n\n    metadata.docCommentEnhancerVisitorState = VisitorState.Visited;\n  }\n\n  private _analyzeNeedsDocumentation(astDeclaration: AstDeclaration, metadata: ApiItemMetadata): void {\n    if (astDeclaration.declaration.kind === ts.SyntaxKind.Constructor) {\n      // Constructors always do pretty much the same thing, so it's annoying to require people to write\n      // descriptions for them.  Instead, if the constructor lacks a TSDoc summary, then API Extractor\n      // will auto-generate one.\n      metadata.undocumented = false;\n\n      // The class that contains this constructor\n      const classDeclaration: AstDeclaration = astDeclaration.parent!;\n\n      const configuration: tsdoc.TSDocConfiguration = this._collector.extractorConfig.tsdocConfiguration;\n\n      if (!metadata.tsdocComment) {\n        metadata.tsdocComment = new tsdoc.DocComment({ configuration });\n      }\n\n      if (!tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection)) {\n        metadata.tsdocComment.summarySection.appendNodesInParagraph([\n          new tsdoc.DocPlainText({ configuration, text: 'Constructs a new instance of the ' }),\n          new tsdoc.DocCodeSpan({\n            configuration,\n            code: classDeclaration.astSymbol.localName\n          }),\n          new tsdoc.DocPlainText({ configuration, text: ' class' })\n        ]);\n      }\n\n      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);\n      if (apiItemMetadata.effectiveReleaseTag === ReleaseTag.Internal) {\n        // If the constructor is marked as internal, then add a boilerplate notice for the containing class\n        const classMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(classDeclaration);\n\n        if (!classMetadata.tsdocComment) {\n          classMetadata.tsdocComment = new tsdoc.DocComment({ configuration });\n        }\n\n        if (classMetadata.tsdocComment.remarksBlock === undefined) {\n          classMetadata.tsdocComment.remarksBlock = new tsdoc.DocBlock({\n            configuration,\n            blockTag: new tsdoc.DocBlockTag({\n              configuration,\n              tagName: tsdoc.StandardTags.remarks.tagName\n            })\n          });\n        }\n\n        classMetadata.tsdocComment.remarksBlock.content.appendNode(\n          new tsdoc.DocParagraph({ configuration }, [\n            new tsdoc.DocPlainText({\n              configuration,\n              text:\n                `The constructor for this class is marked as internal. Third-party code should not` +\n                ` call the constructor directly or create subclasses that extend the `\n            }),\n            new tsdoc.DocCodeSpan({\n              configuration,\n              code: classDeclaration.astSymbol.localName\n            }),\n            new tsdoc.DocPlainText({ configuration, text: ' class.' })\n          ])\n        );\n      }\n      return;\n    } else {\n      // For non-constructor items, we will determine whether or not the item is documented as follows:\n      // 1. If it contains a summary section with at least 10 characters, then it is considered \"documented\".\n      // 2. If it contains an @inheritDoc tag, then it *may* be considered \"documented\", depending on whether or not\n      //    the tag resolves to a \"documented\" API member.\n      //    - Note: for external members, we cannot currently determine this, so we will consider the \"documented\"\n      //      status to be unknown.\n      if (metadata.tsdocComment) {\n        if (tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection, 10)) {\n          // If the API item has a summary comment block (with at least 10 characters), mark it as \"documented\".\n          metadata.undocumented = false;\n        } else if (metadata.tsdocComment.inheritDocTag) {\n          if (\n            this._refersToDeclarationInWorkingPackage(\n              metadata.tsdocComment.inheritDocTag.declarationReference\n            )\n          ) {\n            // If the API item has an `@inheritDoc` comment that points to an API item in the working package,\n            // then the documentation contents should have already been copied from the target via `_applyInheritDoc`.\n            // The continued existence of the tag indicates that the declaration reference was invalid, and not\n            // documentation contents could be copied.\n            // An analyzer issue will have already been logged for this.\n            // We will treat such an API as \"undocumented\".\n            metadata.undocumented = true;\n          } else {\n            // If the API item has an `@inheritDoc` comment that points to an external API item, we cannot currently\n            // determine whether or not the target is \"documented\", so we cannot say definitively that this is \"undocumented\".\n            metadata.undocumented = false;\n          }\n        } else {\n          // If the API item has neither a summary comment block, nor an `@inheritDoc` comment, mark it as \"undocumented\".\n          metadata.undocumented = true;\n        }\n      } else {\n        // If there is no tsdoc comment at all, mark \"undocumented\".\n        metadata.undocumented = true;\n      }\n    }\n  }\n\n  private _checkForBrokenLinks(astDeclaration: AstDeclaration, metadata: ApiItemMetadata): void {\n    if (!metadata.tsdocComment) {\n      return;\n    }\n    this._checkForBrokenLinksRecursive(astDeclaration, metadata.tsdocComment);\n  }\n\n  private _checkForBrokenLinksRecursive(astDeclaration: AstDeclaration, node: tsdoc.DocNode): void {\n    if (node instanceof tsdoc.DocLinkTag) {\n      if (node.codeDestination) {\n        // Is it referring to the working package?  If not, we don't do any link validation, because\n        // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).\n        // Tracked by:  https://github.com/microsoft/rushstack/issues/1195\n        if (this._refersToDeclarationInWorkingPackage(node.codeDestination)) {\n          const referencedAstDeclaration: AstDeclaration | ResolverFailure =\n            this._collector.astReferenceResolver.resolve(node.codeDestination);\n\n          if (referencedAstDeclaration instanceof ResolverFailure) {\n            this._collector.messageRouter.addAnalyzerIssue(\n              ExtractorMessageId.UnresolvedLink,\n              'The @link reference could not be resolved: ' + referencedAstDeclaration.reason,\n              astDeclaration\n            );\n          }\n        }\n      }\n    }\n    for (const childNode of node.getChildNodes()) {\n      this._checkForBrokenLinksRecursive(astDeclaration, childNode);\n    }\n  }\n\n  /**\n   * Follow an `{@inheritDoc ___}` reference and copy the content that we find in the referenced comment.\n   */\n  private _applyInheritDoc(\n    astDeclaration: AstDeclaration,\n    docComment: tsdoc.DocComment,\n    inheritDocTag: tsdoc.DocInheritDocTag\n  ): void {\n    if (!inheritDocTag.declarationReference) {\n      this._collector.messageRouter.addAnalyzerIssue(\n        ExtractorMessageId.UnresolvedInheritDocBase,\n        'The @inheritDoc tag needs a TSDoc declaration reference; signature matching is not supported yet',\n        astDeclaration\n      );\n      return;\n    }\n\n    if (!this._refersToDeclarationInWorkingPackage(inheritDocTag.declarationReference)) {\n      // The `@inheritDoc` tag is referencing an external package. Skip it, since AstReferenceResolver doesn't\n      // support it yet.  As a workaround, this tag will get handled later by api-documenter.\n      // Tracked by:  https://github.com/microsoft/rushstack/issues/1195\n      return;\n    }\n\n    const referencedAstDeclaration: AstDeclaration | ResolverFailure =\n      this._collector.astReferenceResolver.resolve(inheritDocTag.declarationReference);\n\n    if (referencedAstDeclaration instanceof ResolverFailure) {\n      this._collector.messageRouter.addAnalyzerIssue(\n        ExtractorMessageId.UnresolvedInheritDocReference,\n        'The @inheritDoc reference could not be resolved: ' + referencedAstDeclaration.reason,\n        astDeclaration\n      );\n      return;\n    }\n\n    this._analyzeApiItem(referencedAstDeclaration);\n\n    const referencedMetadata: ApiItemMetadata =\n      this._collector.fetchApiItemMetadata(referencedAstDeclaration);\n\n    if (referencedMetadata.tsdocComment) {\n      this._copyInheritedDocs(docComment, referencedMetadata.tsdocComment);\n    }\n  }\n\n  /**\n   * Copy the content from `sourceDocComment` to `targetDocComment`.\n   */\n  private _copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {\n    targetDocComment.summarySection = sourceDocComment.summarySection;\n    targetDocComment.remarksBlock = sourceDocComment.remarksBlock;\n\n    targetDocComment.params.clear();\n    for (const param of sourceDocComment.params) {\n      targetDocComment.params.add(param);\n    }\n    for (const typeParam of sourceDocComment.typeParams) {\n      targetDocComment.typeParams.add(typeParam);\n    }\n    targetDocComment.returnsBlock = sourceDocComment.returnsBlock;\n\n    targetDocComment.inheritDocTag = undefined;\n  }\n\n  /**\n   * Determines whether or not the provided declaration reference points to an item in the working package.\n   */\n  private _refersToDeclarationInWorkingPackage(\n    declarationReference: tsdoc.DocDeclarationReference | undefined\n  ): boolean {\n    return (\n      declarationReference?.packageName === undefined ||\n      declarationReference.packageName === this._collector.workingPackage.name\n    );\n  }\n}\n"]}