1 line
15 KiB
Plaintext
1 line
15 KiB
Plaintext
{"version":3,"file":"ApiPackage.js","sourceRoot":"","sources":["../../src/model/ApiPackage.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 { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\nimport { ApiItem, ApiItemKind, type IApiItemJson } from '../items/ApiItem';\nimport { ApiItemContainerMixin, type IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin';\nimport {\n JsonFile,\n type IJsonFileSaveOptions,\n PackageJsonLookup,\n type IPackageJson,\n type JsonObject\n} from '@rushstack/node-core-library';\nimport { ApiDocumentedItem, type IApiDocumentedItemOptions } from '../items/ApiDocumentedItem';\nimport type { ApiEntryPoint } from './ApiEntryPoint';\nimport { type IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';\nimport { DeserializerContext, ApiJsonSchemaVersion } from './DeserializerContext';\nimport { TSDocConfiguration } from '@microsoft/tsdoc';\nimport { TSDocConfigFile } from '@microsoft/tsdoc-config';\n\n/**\n * Constructor options for {@link ApiPackage}.\n * @public\n */\nexport interface IApiPackageOptions\n extends IApiItemContainerMixinOptions,\n IApiNameMixinOptions,\n IApiDocumentedItemOptions {\n tsdocConfiguration: TSDocConfiguration;\n projectFolderUrl?: string;\n}\n\nexport interface IApiPackageMetadataJson {\n /**\n * The NPM package name for the tool that wrote the *.api.json file.\n * For informational purposes only.\n */\n toolPackage: string;\n\n /**\n * The NPM package version for the tool that wrote the *.api.json file.\n * For informational purposes only.\n */\n toolVersion: string;\n\n /**\n * The schema version for the .api.json file format. Used for determining whether the file format is\n * supported, and for backwards compatibility.\n */\n schemaVersion: ApiJsonSchemaVersion;\n\n /**\n * To support forwards compatibility, the `oldestForwardsCompatibleVersion` field tracks the oldest schema version\n * whose corresponding deserializer could safely load this file.\n *\n * @remarks\n * Normally api-extractor-model should refuse to load a schema version that is newer than the latest version\n * that its deserializer understands. However, sometimes a schema change may merely introduce some new fields\n * without modifying or removing any existing fields. In this case, an older api-extractor-model library can\n * safely deserialize the newer version (by ignoring the extra fields that it doesn't recognize). The newer\n * serializer can use this field to communicate that.\n *\n * If present, the `oldestForwardsCompatibleVersion` must be less than or equal to\n * `IApiPackageMetadataJson.schemaVersion`.\n */\n oldestForwardsCompatibleVersion?: ApiJsonSchemaVersion;\n\n /**\n * The TSDoc configuration that was used when analyzing the API for this package.\n *\n * @remarks\n *\n * The structure of this objet is defined by the `@microsoft/tsdoc-config` library.\n * Normally this configuration is loaded from the project's tsdoc.json file. It is stored\n * in the .api.json file so that doc comments can be parsed accurately when loading the file.\n */\n tsdocConfig: JsonObject;\n}\n\nexport interface IApiPackageJson extends IApiItemJson {\n /**\n * A file header that stores metadata about the tool that wrote the *.api.json file.\n */\n metadata: IApiPackageMetadataJson;\n\n /**\n * The base URL where the project's source code can be viewed on a website such as GitHub or\n * Azure DevOps. This URL path corresponds to the `<projectFolder>` path on disk. Provided via the\n * `api-extractor.json` config.\n */\n projectFolderUrl?: string;\n}\n\n/**\n * Options for {@link ApiPackage.saveToJsonFile}.\n * @public\n */\nexport interface IApiPackageSaveOptions extends IJsonFileSaveOptions {\n /**\n * Optionally specifies a value for the \"toolPackage\" field in the output .api.json data file;\n * otherwise, the value will be \"api-extractor-model\".\n */\n toolPackage?: string;\n\n /**\n * Optionally specifies a value for the \"toolVersion\" field in the output .api.json data file;\n * otherwise, the value will be the current version of the api-extractor-model package.\n */\n toolVersion?: string;\n\n /**\n * Set to true only when invoking API Extractor's test harness.\n *\n * @remarks\n * When `testMode` is true, the `toolVersion` field in the .api.json file is assigned an empty string\n * to prevent spurious diffs in output files tracked for tests.\n */\n testMode?: boolean;\n}\n\n/**\n * Represents an NPM package containing API declarations.\n *\n * @remarks\n *\n * This is part of the {@link ApiModel} hierarchy of classes, which are serializable representations of\n * API declarations.\n *\n * @public\n */\nexport class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumentedItem)) {\n private readonly _tsdocConfiguration: TSDocConfiguration;\n private readonly _projectFolderUrl?: string;\n\n public constructor(options: IApiPackageOptions) {\n super(options);\n\n this._tsdocConfiguration = options.tsdocConfiguration;\n this._projectFolderUrl = options.projectFolderUrl;\n }\n\n /** @override */\n public static onDeserializeInto(\n options: Partial<IApiPackageOptions>,\n context: DeserializerContext,\n jsonObject: IApiPackageJson\n ): void {\n super.onDeserializeInto(options, context, jsonObject);\n\n options.projectFolderUrl = jsonObject.projectFolderUrl;\n }\n\n public static loadFromJsonFile(apiJsonFilename: string): ApiPackage {\n const jsonObject: IApiPackageJson = JsonFile.load(apiJsonFilename);\n\n if (!jsonObject || !jsonObject.metadata || typeof jsonObject.metadata.schemaVersion !== 'number') {\n throw new Error(\n `Error loading ${apiJsonFilename}:` +\n `\\nThe file format is not recognized; the \"metadata.schemaVersion\" field is missing or invalid`\n );\n }\n\n const schemaVersion: number = jsonObject.metadata.schemaVersion;\n\n if (schemaVersion < ApiJsonSchemaVersion.OLDEST_SUPPORTED) {\n throw new Error(\n `Error loading ${apiJsonFilename}:` +\n `\\nThe file format is version ${schemaVersion},` +\n ` whereas ${ApiJsonSchemaVersion.OLDEST_SUPPORTED} is the oldest version supported by this tool`\n );\n }\n\n let oldestForwardsCompatibleVersion: number = schemaVersion;\n if (jsonObject.metadata.oldestForwardsCompatibleVersion) {\n // Sanity check\n if (jsonObject.metadata.oldestForwardsCompatibleVersion > schemaVersion) {\n throw new Error(\n `Error loading ${apiJsonFilename}:` +\n `\\nInvalid file format; \"oldestForwardsCompatibleVersion\" cannot be newer than \"schemaVersion\"`\n );\n }\n oldestForwardsCompatibleVersion = jsonObject.metadata.oldestForwardsCompatibleVersion;\n }\n\n let versionToDeserialize: number = schemaVersion;\n if (versionToDeserialize > ApiJsonSchemaVersion.LATEST) {\n // If the file format is too new, can we treat it as some earlier compatible version\n // as indicated by oldestForwardsCompatibleVersion?\n versionToDeserialize = Math.max(oldestForwardsCompatibleVersion, ApiJsonSchemaVersion.LATEST);\n\n if (versionToDeserialize > ApiJsonSchemaVersion.LATEST) {\n // Nope, still too new\n throw new Error(\n `Error loading ${apiJsonFilename}:` +\n `\\nThe file format version ${schemaVersion} was written by a newer release of` +\n ` the api-extractor-model library; you may need to upgrade your software`\n );\n }\n }\n\n const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();\n\n if (versionToDeserialize >= ApiJsonSchemaVersion.V_1004) {\n const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromObject(\n jsonObject.metadata.tsdocConfig\n );\n if (tsdocConfigFile.hasErrors) {\n throw new Error(`Error loading ${apiJsonFilename}:\\n` + tsdocConfigFile.getErrorSummary());\n }\n\n tsdocConfigFile.configureParser(tsdocConfiguration);\n }\n\n const context: DeserializerContext = new DeserializerContext({\n apiJsonFilename,\n toolPackage: jsonObject.metadata.toolPackage,\n toolVersion: jsonObject.metadata.toolVersion,\n versionToDeserialize: versionToDeserialize,\n tsdocConfiguration\n });\n\n return ApiItem.deserialize(jsonObject, context) as ApiPackage;\n }\n\n /** @override */\n public get kind(): ApiItemKind {\n return ApiItemKind.Package;\n }\n\n /** @override */\n public get containerKey(): string {\n // No prefix needed, because ApiPackage is the only possible member of an ApiModel\n return this.name;\n }\n\n public get entryPoints(): ReadonlyArray<ApiEntryPoint> {\n return this.members as ReadonlyArray<ApiEntryPoint>;\n }\n\n /**\n * The TSDoc configuration that was used when analyzing the API for this package.\n *\n * @remarks\n *\n * Normally this configuration is loaded from the project's tsdoc.json file. It is stored\n * in the .api.json file so that doc comments can be parsed accurately when loading the file.\n */\n public get tsdocConfiguration(): TSDocConfiguration {\n return this._tsdocConfiguration;\n }\n\n public get projectFolderUrl(): string | undefined {\n return this._projectFolderUrl;\n }\n\n /** @override */\n public addMember(member: ApiEntryPoint): void {\n if (member.kind !== ApiItemKind.EntryPoint) {\n throw new Error('Only items of type ApiEntryPoint may be added to an ApiPackage');\n }\n super.addMember(member);\n }\n\n public findEntryPointsByPath(importPath: string): ReadonlyArray<ApiEntryPoint> {\n return this.findMembersByName(importPath) as ReadonlyArray<ApiEntryPoint>;\n }\n\n public saveToJsonFile(apiJsonFilename: string, options?: IApiPackageSaveOptions): void {\n if (!options) {\n options = {};\n }\n\n const packageJson: IPackageJson = PackageJsonLookup.loadOwnPackageJson(__dirname);\n\n const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromParser(this.tsdocConfiguration);\n const tsdocConfig: JsonObject = tsdocConfigFile.saveToObject();\n\n const jsonObject: IApiPackageJson = {\n metadata: {\n toolPackage: options.toolPackage || packageJson.name,\n // In test mode, we don't write the real version, since that would cause spurious diffs whenever\n // the version is bumped. Instead we write a placeholder string.\n toolVersion: options.testMode ? '[test mode]' : options.toolVersion || packageJson.version,\n schemaVersion: ApiJsonSchemaVersion.LATEST,\n oldestForwardsCompatibleVersion: ApiJsonSchemaVersion.OLDEST_FORWARDS_COMPATIBLE,\n tsdocConfig\n }\n } as IApiPackageJson;\n\n if (this.projectFolderUrl) {\n jsonObject.projectFolderUrl = this.projectFolderUrl;\n }\n\n this.serializeInto(jsonObject);\n JsonFile.save(jsonObject, apiJsonFilename, options);\n }\n\n /** @beta @override */\n public buildCanonicalReference(): DeclarationReference {\n return DeclarationReference.package(this.name);\n }\n}\n"]} |