{"version":3,"file":"PackageMetadataManager.js","sourceRoot":"","sources":["../../src/analyzer/PackageMetadataManager.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 'path';\n\nimport {\n  type PackageJsonLookup,\n  FileSystem,\n  JsonFile,\n  type NewlineKind,\n  type INodePackageJson,\n  type JsonObject\n} from '@rushstack/node-core-library';\nimport { Extractor } from '../api/Extractor';\nimport type { MessageRouter } from '../collector/MessageRouter';\nimport { ConsoleMessageId } from '../api/ConsoleMessageId';\n\n/**\n * Represents analyzed information for a package.json file.\n * This object is constructed and returned by PackageMetadataManager.\n */\nexport class PackageMetadata {\n  /**\n   * The absolute path to the package.json file being analyzed.\n   */\n  public readonly packageJsonPath: string;\n  /**\n   * The parsed contents of package.json.  Note that PackageJsonLookup\n   * only includes essential fields.\n   */\n  public readonly packageJson: INodePackageJson;\n  /**\n   * If true, then the package's documentation comments can be assumed\n   * to contain API Extractor compatible TSDoc tags.\n   */\n  public readonly aedocSupported: boolean;\n\n  public constructor(packageJsonPath: string, packageJson: INodePackageJson, aedocSupported: boolean) {\n    this.packageJsonPath = packageJsonPath;\n    this.packageJson = packageJson;\n    this.aedocSupported = aedocSupported;\n  }\n}\n\n/**\n * This class maintains a cache of analyzed information obtained from package.json\n * files.  It is built on top of the PackageJsonLookup class.\n *\n * @remarks\n *\n * IMPORTANT: Don't use PackageMetadataManager to analyze source files from the current project:\n * 1. Files such as tsdoc-metadata.json may not have been built yet, and thus may contain incorrect information.\n * 2. The current project is not guaranteed to have a package.json file at all.  For example, API Extractor can\n *    be invoked on a bare .d.ts file.\n *\n * Use ts.program.isSourceFileFromExternalLibrary() to test source files before passing the to PackageMetadataManager.\n */\nexport class PackageMetadataManager {\n  public static tsdocMetadataFilename: string = 'tsdoc-metadata.json';\n\n  private readonly _packageJsonLookup: PackageJsonLookup;\n  private readonly _messageRouter: MessageRouter;\n  private readonly _packageMetadataByPackageJsonPath: Map<string, PackageMetadata> = new Map<\n    string,\n    PackageMetadata\n  >();\n\n  public constructor(packageJsonLookup: PackageJsonLookup, messageRouter: MessageRouter) {\n    this._packageJsonLookup = packageJsonLookup;\n    this._messageRouter = messageRouter;\n  }\n\n  // This feature is still being standardized: https://github.com/microsoft/tsdoc/issues/7\n  // In the future we will use the @microsoft/tsdoc library to read this file.\n  private static _resolveTsdocMetadataPathFromPackageJson(\n    packageFolder: string,\n    packageJson: INodePackageJson\n  ): string {\n    const tsdocMetadataFilename: string = PackageMetadataManager.tsdocMetadataFilename;\n\n    let tsdocMetadataRelativePath: string;\n\n    if (packageJson.tsdocMetadata) {\n      // 1. If package.json contains a field such as \"tsdocMetadata\": \"./path1/path2/tsdoc-metadata.json\",\n      // then that takes precedence.  This convention will be rarely needed, since the other rules below generally\n      // produce a good result.\n      tsdocMetadataRelativePath = packageJson.tsdocMetadata;\n    } else if (packageJson.typings) {\n      // 2. If package.json contains a field such as \"typings\": \"./path1/path2/index.d.ts\", then we look\n      // for the file under \"./path1/path2/tsdoc-metadata.json\"\n      tsdocMetadataRelativePath = path.join(path.dirname(packageJson.typings), tsdocMetadataFilename);\n    } else if (packageJson.main) {\n      // 3. If package.json contains a field such as \"main\": \"./path1/path2/index.js\", then we look for\n      // the file under \"./path1/path2/tsdoc-metadata.json\"\n      tsdocMetadataRelativePath = path.join(path.dirname(packageJson.main), tsdocMetadataFilename);\n    } else {\n      // 4. If none of the above rules apply, then by default we look for the file under \"./tsdoc-metadata.json\"\n      // since the default entry point is \"./index.js\"\n      tsdocMetadataRelativePath = tsdocMetadataFilename;\n    }\n\n    // Always resolve relative to the package folder.\n    const tsdocMetadataPath: string = path.resolve(packageFolder, tsdocMetadataRelativePath);\n    return tsdocMetadataPath;\n  }\n\n  /**\n   * @param tsdocMetadataPath - An explicit path that can be configured in api-extractor.json.\n   * If this parameter is not an empty string, it overrides the normal path calculation.\n   * @returns the absolute path to the TSDoc metadata file\n   */\n  public static resolveTsdocMetadataPath(\n    packageFolder: string,\n    packageJson: INodePackageJson,\n    tsdocMetadataPath?: string\n  ): string {\n    if (tsdocMetadataPath) {\n      return path.resolve(packageFolder, tsdocMetadataPath);\n    }\n    return PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(packageFolder, packageJson);\n  }\n\n  /**\n   * Writes the TSDoc metadata file to the specified output file.\n   */\n  public static writeTsdocMetadataFile(tsdocMetadataPath: string, newlineKind: NewlineKind): void {\n    const fileObject: JsonObject = {\n      tsdocVersion: '0.12',\n      toolPackages: [\n        {\n          packageName: '@microsoft/api-extractor',\n          packageVersion: Extractor.version\n        }\n      ]\n    };\n\n    const fileContent: string =\n      '// This file is read by tools that parse documentation comments conforming to the TSDoc standard.\\n' +\n      '// It should be published with your NPM package.  It should not be tracked by Git.\\n' +\n      JsonFile.stringify(fileObject);\n\n    FileSystem.writeFile(tsdocMetadataPath, fileContent, {\n      convertLineEndings: newlineKind,\n      ensureFolderExists: true\n    });\n  }\n\n  /**\n   * Finds the package.json in a parent folder of the specified source file, and\n   * returns a PackageMetadata object.  If no package.json was found, then undefined\n   * is returned.  The results are cached.\n   */\n  public tryFetchPackageMetadata(sourceFilePath: string): PackageMetadata | undefined {\n    const packageJsonFilePath: string | undefined =\n      this._packageJsonLookup.tryGetPackageJsonFilePathFor(sourceFilePath);\n    if (!packageJsonFilePath) {\n      return undefined;\n    }\n    let packageMetadata: PackageMetadata | undefined =\n      this._packageMetadataByPackageJsonPath.get(packageJsonFilePath);\n\n    if (!packageMetadata) {\n      const packageJson: INodePackageJson = this._packageJsonLookup.loadNodePackageJson(packageJsonFilePath);\n\n      const packageJsonFolder: string = path.dirname(packageJsonFilePath);\n\n      let aedocSupported: boolean = false;\n\n      const tsdocMetadataPath: string = PackageMetadataManager._resolveTsdocMetadataPathFromPackageJson(\n        packageJsonFolder,\n        packageJson\n      );\n\n      if (FileSystem.exists(tsdocMetadataPath)) {\n        this._messageRouter.logVerbose(\n          ConsoleMessageId.FoundTSDocMetadata,\n          'Found metadata in ' + tsdocMetadataPath\n        );\n        // If the file exists at all, assume it was written by API Extractor\n        aedocSupported = true;\n      }\n\n      packageMetadata = new PackageMetadata(packageJsonFilePath, packageJson, aedocSupported);\n      this._packageMetadataByPackageJsonPath.set(packageJsonFilePath, packageMetadata);\n    }\n\n    return packageMetadata;\n  }\n\n  /**\n   * Returns true if the source file is part of a package whose .d.ts files support AEDoc annotations.\n   */\n  public isAedocSupportedFor(sourceFilePath: string): boolean {\n    const packageMetadata: PackageMetadata | undefined = this.tryFetchPackageMetadata(sourceFilePath);\n    if (!packageMetadata) {\n      return false;\n    }\n    return packageMetadata.aedocSupported;\n  }\n}\n"]}