{"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"]}