| 1 | {"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 PackageJsonLookup,\n FileSystem,\n JsonFile,\n NewlineKind,\n INodePackageJson,\n JsonObject\n} from '@rushstack/node-core-library';\nimport { Extractor } from '../api/Extractor';\nimport { 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"]} |