@microsoft/api-extractor-model 7.24.4 → 7.25.1

package/dist/rollup.d.ts

@@ -10,6 +10,7 @@
 import { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
 import { DocDeclarationReference } from '@microsoft/tsdoc';
 import { IJsonFileSaveOptions } from '@rushstack/node-core-library';
+import { JsonObject } from '@rushstack/node-core-library';
 import * as tsdoc from '@microsoft/tsdoc';
 import { TSDocConfiguration } from '@microsoft/tsdoc';
 import { TSDocTagDefinition } from '@microsoft/tsdoc';
@@ -221,6 +222,8 @@ declare const ApiConstructSignature_base: typeof ApiDeclaredItem & (new (...args
 export declare class ApiDeclaredItem extends ApiDocumentedItem {
     private _excerptTokens;
     private _excerpt;
+    private _fileUrlPath?;
+    private _sourceLocation?;
     constructor(options: IApiDeclaredItemOptions);
     /** @override */
     static onDeserializeInto(options: Partial<IApiDeclaredItemOptions>, context: DeserializerContext, jsonObject: IApiDeclaredItemJson): void;
@@ -232,6 +235,16 @@ export declare class ApiDeclaredItem extends ApiDocumentedItem {
      * The individual source code tokens that comprise the main excerpt.
      */
     get excerptTokens(): ReadonlyArray<ExcerptToken>;
+    /**
+     * The file URL path relative to the `projectFolder` and `projectFolderURL` fields
+     * as defined in the `api-extractor.json` config. Is `undefined` if the path is
+     * the same as the parent API item's.
+     */
+    get fileUrlPath(): string | undefined;
+    /**
+     * Returns the source location where the API item is declared.
+     */
+    get sourceLocation(): SourceLocation;
     /**
      * If the API item has certain important modifier tags such as `@sealed`, `@virtual`, or `@override`,
      * this prepends them as a doc comment above the excerpt.
@@ -243,6 +256,10 @@ export declare class ApiDeclaredItem extends ApiDocumentedItem {
      * Constructs a new {@link Excerpt} corresponding to the provided token range.
      */
     buildExcerpt(tokenRange: IExcerptTokenRange): Excerpt;
+    /**
+     * Builds the cached object used by the `sourceLocation` property.
+     */
+    private _buildSourceLocation;
 }
 
 /**
@@ -990,13 +1007,19 @@ declare enum ApiJsonSchemaVersion {
      * When loading older JSON files, the values defaults to `false`.
      */
     V_1009 = 1009,
+    /**
+     * Add a `fileUrlPath` field to `ApiDeclaredItem` to track the URL to a declared item's source file.
+     *
+     * When loading older JSON files, the value defaults to `undefined`.
+     */
+    V_1010 = 1010,
     /**
      * The current latest .api.json schema version.
      *
      * IMPORTANT: When incrementing this number, consider whether `OLDEST_SUPPORTED` or `OLDEST_FORWARDS_COMPATIBLE`
      * should be updated.
      */
-    LATEST = 1009,
+    LATEST = 1010,
     /**
      * The oldest .api.json schema version that is still supported for backwards compatibility.
      *
@@ -1315,7 +1338,10 @@ export declare namespace ApiOptionalMixin {
  */
 export declare class ApiPackage extends ApiPackage_base {
     private readonly _tsdocConfiguration;
+    private readonly _projectFolderUrl?;
     constructor(options: IApiPackageOptions);
+    /** @override */
+    static onDeserializeInto(options: Partial<IApiPackageOptions>, context: DeserializerContext, jsonObject: IApiPackageJson): void;
     static loadFromJsonFile(apiJsonFilename: string): ApiPackage;
     /** @override */
     get kind(): ApiItemKind;
@@ -1331,6 +1357,7 @@ export declare class ApiPackage extends ApiPackage_base {
      * in the .api.json file so that doc comments can be parsed accurately when loading the file.
      */
     get tsdocConfiguration(): TSDocConfiguration;
+    get projectFolderUrl(): string | undefined;
     /** @override */
     addMember(member: ApiEntryPoint): void;
     findEntryPointsByPath(importPath: string): ReadonlyArray<ApiEntryPoint>;
@@ -2201,6 +2228,7 @@ export declare interface IApiConstructSignatureOptions extends IApiTypeParameter
 
 declare interface IApiDeclaredItemJson extends IApiDocumentedItemJson {
     excerptTokens: IExcerptToken[];
+    fileUrlPath?: string;
 }
 
 /**
@@ -2209,6 +2237,7 @@ declare interface IApiDeclaredItemJson extends IApiDocumentedItemJson {
  */
 export declare interface IApiDeclaredItemOptions extends IApiDocumentedItemOptions {
     excerptTokens: IExcerptToken[];
+    fileUrlPath?: string;
 }
 
 declare interface IApiDocumentedItemJson extends IApiItemJson {
@@ -2367,12 +2396,69 @@ export declare interface IApiOptionalMixinOptions extends IApiItemOptions {
     isOptional: boolean;
 }
 
+declare interface IApiPackageJson extends IApiItemJson {
+    /**
+     * A file header that stores metadata about the tool that wrote the *.api.json file.
+     */
+    metadata: IApiPackageMetadataJson;
+    /**
+     * The base URL where the project's source code can be viewed on a website such as GitHub or
+     * Azure DevOps. This URL path corresponds to the `<projectFolder>` path on disk. Provided via the
+     * `api-extractor.json` config.
+     */
+    projectFolderUrl?: string;
+}
+
+declare interface IApiPackageMetadataJson {
+    /**
+     * The NPM package name for the tool that wrote the *.api.json file.
+     * For informational purposes only.
+     */
+    toolPackage: string;
+    /**
+     * The NPM package version for the tool that wrote the *.api.json file.
+     * For informational purposes only.
+     */
+    toolVersion: string;
+    /**
+     * The schema version for the .api.json file format.  Used for determining whether the file format is
+     * supported, and for backwards compatibility.
+     */
+    schemaVersion: ApiJsonSchemaVersion;
+    /**
+     * To support forwards compatibility, the `oldestForwardsCompatibleVersion` field tracks the oldest schema version
+     * whose corresponding deserializer could safely load this file.
+     *
+     * @remarks
+     * Normally api-extractor-model should refuse to load a schema version that is newer than the latest version
+     * that its deserializer understands.  However, sometimes a schema change may merely introduce some new fields
+     * without modifying or removing any existing fields.  In this case, an older api-extractor-model library can
+     * safely deserialize the newer version (by ignoring the extra fields that it doesn't recognize).  The newer
+     * serializer can use this field to communicate that.
+     *
+     * If present, the `oldestForwardsCompatibleVersion` must be less than or equal to
+     * `IApiPackageMetadataJson.schemaVersion`.
+     */
+    oldestForwardsCompatibleVersion?: ApiJsonSchemaVersion;
+    /**
+     * The TSDoc configuration that was used when analyzing the API for this package.
+     *
+     * @remarks
+     *
+     * The structure of this objet is defined by the `@microsoft/tsdoc-config` library.
+     * Normally this configuration is loaded from the project's tsdoc.json file.  It is stored
+     * in the .api.json file so that doc comments can be parsed accurately when loading the file.
+     */
+    tsdocConfig: JsonObject;
+}
+
 /**
  * Constructor options for {@link ApiPackage}.
  * @public
  */
 export declare interface IApiPackageOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiDocumentedItemOptions {
     tsdocConfiguration: TSDocConfiguration;
+    projectFolderUrl?: string;
 }
 
 /**
@@ -2630,6 +2716,23 @@ export declare interface IResolveDeclarationReferenceResult {
     errorMessage: string | undefined;
 }
 
+/**
+ * Constructor options for `SourceLocation`.
+ * @public
+ */
+export declare interface ISourceLocationOptions {
+    /**
+     * The project folder URL as defined by the `api-extractor.json` config `projectFolderUrl`
+     * setting.
+     */
+    projectFolderUrl?: string;
+    /**
+     * The file URL path relative to the `projectFolder` and `projectFolderURL` fields as
+     * defined in the `api-extractor.json` config.
+     */
+    fileUrlPath?: string;
+}
+
 /**
  * Constructor options for {@link TypeParameter}.
  * @public
@@ -2756,6 +2859,27 @@ export declare namespace ReleaseTag {
     export function compare(a: ReleaseTag, b: ReleaseTag): number;
 }
 
+/**
+ * The source location where a given API item is declared.
+ *
+ * @remarks
+ * The source location points to the `.ts` source file where the API item was originally
+ declared. However, in some cases, if source map resolution fails, it falls back to pointing
+ to the `.d.ts` file instead.
+ *
+ * @public
+ */
+export declare class SourceLocation {
+    private readonly _projectFolderUrl?;
+    private readonly _fileUrlPath?;
+    constructor(options: ISourceLocationOptions);
+    /**
+     * Returns the file URL to the given source location. Returns `undefined` if the file URL
+     * cannot be determined.
+     */
+    get fileUrl(): string | undefined;
+}
+
 /**
  * Represents a named type parameter for a generic declaration.
  *

package/lib/index.d.ts

@@ -50,4 +50,5 @@ export { ITypeParameterOptions, TypeParameter } from './model/TypeParameter';
 export { IApiVariableOptions, ApiVariable } from './model/ApiVariable';
 export { IResolveDeclarationReferenceResult } from './model/ModelReferenceResolver';
 export { HeritageType } from './model/HeritageType';
+export { ISourceLocationOptions, SourceLocation } from './model/SourceLocation';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -2,7 +2,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HeritageType = exports.ApiVariable = exports.TypeParameter = exports.ApiTypeAlias = exports.ApiPropertySignature = exports.ApiProperty = exports.Parameter = exports.ApiPackage = exports.ApiNamespace = exports.ApiModel = exports.ApiMethodSignature = exports.ApiMethod = exports.ApiInterface = exports.ApiIndexSignature = exports.ApiFunction = exports.EnumMemberOrder = exports.ApiEnumMember = exports.ApiEnum = exports.ApiEntryPoint = exports.ApiConstructSignature = exports.ApiConstructor = exports.ApiClass = exports.ApiCallSignature = exports.Excerpt = exports.ExcerptToken = exports.ExcerptTokenKind = exports.FindApiItemsMessageId = exports.ApiExportedMixin = exports.ApiInitializerMixin = exports.ApiReadonlyMixin = exports.ApiOptionalMixin = exports.ApiNameMixin = exports.ApiStaticMixin = exports.ApiReturnTypeMixin = exports.ApiReleaseTagMixin = exports.ApiProtectedMixin = exports.ApiItemContainerMixin = exports.ApiTypeParameterListMixin = exports.ApiParameterListMixin = exports.ApiPropertyItem = exports.ApiItem = exports.ApiItemKind = exports.ApiDocumentedItem = exports.ApiDeclaredItem = exports.ReleaseTag = exports.AedocDefinitions = void 0;
+exports.SourceLocation = exports.HeritageType = exports.ApiVariable = exports.TypeParameter = exports.ApiTypeAlias = exports.ApiPropertySignature = exports.ApiProperty = exports.Parameter = exports.ApiPackage = exports.ApiNamespace = exports.ApiModel = exports.ApiMethodSignature = exports.ApiMethod = exports.ApiInterface = exports.ApiIndexSignature = exports.ApiFunction = exports.EnumMemberOrder = exports.ApiEnumMember = exports.ApiEnum = exports.ApiEntryPoint = exports.ApiConstructSignature = exports.ApiConstructor = exports.ApiClass = exports.ApiCallSignature = exports.Excerpt = exports.ExcerptToken = exports.ExcerptTokenKind = exports.FindApiItemsMessageId = exports.ApiExportedMixin = exports.ApiInitializerMixin = exports.ApiReadonlyMixin = exports.ApiOptionalMixin = exports.ApiNameMixin = exports.ApiStaticMixin = exports.ApiReturnTypeMixin = exports.ApiReleaseTagMixin = exports.ApiProtectedMixin = exports.ApiItemContainerMixin = exports.ApiTypeParameterListMixin = exports.ApiParameterListMixin = exports.ApiPropertyItem = exports.ApiItem = exports.ApiItemKind = exports.ApiDocumentedItem = exports.ApiDeclaredItem = exports.ReleaseTag = exports.AedocDefinitions = void 0;
 /**
  * Use this library to read and write *.api.json files as defined by the
  * {@link https://api-extractor.com/ | API Extractor}  tool.  These files are used to generate a documentation
@@ -102,4 +102,6 @@ var ApiVariable_1 = require("./model/ApiVariable");
 Object.defineProperty(exports, "ApiVariable", { enumerable: true, get: function () { return ApiVariable_1.ApiVariable; } });
 var HeritageType_1 = require("./model/HeritageType");
 Object.defineProperty(exports, "HeritageType", { enumerable: true, get: function () { return HeritageType_1.HeritageType; } });
+var SourceLocation_1 = require("./model/SourceLocation");
+Object.defineProperty(exports, "SourceLocation", { enumerable: true, get: function () { return SourceLocation_1.SourceLocation; } });
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D;;;;;;;GAOG;AAEH,6DAA4D;AAAnD,oHAAA,gBAAgB,OAAA;AACzB,iDAAgD;AAAvC,wGAAA,UAAU,OAAA;AAEnB,QAAQ;AACR,2DAAmF;AAAjD,kHAAA,eAAe,OAAA;AACjD,+DAAyF;AAArD,sHAAA,iBAAiB,OAAA;AACrD,2CAA6F;AAApF,sGAAA,WAAW,OAAA;AAAmB,kGAAA,OAAO,OAAA;AAC9C,2DAAmF;AAAjD,kHAAA,eAAe,OAAA;AAEjD,SAAS;AACT,wEAIwC;AADtC,8HAAA,qBAAqB,OAAA;AAEvB,gFAI4C;AAD1C,sIAAA,yBAAyB,OAAA;AAE3B,wEAAsG;AAA9D,8HAAA,qBAAqB,OAAA;AAC7D,gEAA0F;AAAtD,sHAAA,iBAAiB,OAAA;AACrD,kEAA6F;AAAxD,wHAAA,kBAAkB,OAAA;AACvD,kEAA6F;AAAxD,wHAAA,kBAAkB,OAAA;AACvD,0DAAiF;AAAhD,gHAAA,cAAc,OAAA;AAC/C,sDAA2E;AAA5C,4GAAA,YAAY,OAAA;AAC3C,8DAAuF;AAApD,oHAAA,gBAAgB,OAAA;AACnD,8DAAuF;AAApD,oHAAA,gBAAgB,OAAA;AACnD,oEAAgG;AAA1D,0HAAA,mBAAmB,OAAA;AACzD,8DAAuF;AAApD,oHAAA,gBAAgB,OAAA;AACnD,oEAIsC;AADpC,4HAAA,qBAAqB,OAAA;AAGvB,4CAA8G;AAArG,2GAAA,gBAAgB,OAAA;AAAqC,uGAAA,YAAY,OAAA;AAAE,kGAAA,OAAO,OAAA;AAGnF,QAAQ;AACR,6DAAsF;AAAnD,oHAAA,gBAAgB,OAAA;AACnD,6CAA8D;AAAnC,oGAAA,QAAQ,OAAA;AACnC,yDAAgF;AAA/C,gHAAA,cAAc,OAAA;AAC/C,uEAAqG;AAA7D,8HAAA,qBAAqB,OAAA;AAC7D,uDAA6E;AAA7C,8GAAA,aAAa,OAAA;AAC7C,2CAA2D;AAAjC,kGAAA,OAAO,OAAA;AACjC,uDAA8F;AAA9D,8GAAA,aAAa,OAAA;AAAE,gHAAA,eAAe,OAAA;AAC9D,mDAAuE;AAAzC,0GAAA,WAAW,OAAA;AACzC,+DAAyF;AAArD,sHAAA,iBAAiB,OAAA;AACrD,qDAA0E;AAA3C,4GAAA,YAAY,OAAA;AAC3C,+CAAiE;AAArC,sGAAA,SAAS,OAAA;AACrC,iEAA4F;AAAvD,wHAAA,kBAAkB,OAAA;AACvD,6CAA4C;AAAnC,oGAAA,QAAQ,OAAA;AACjB,qDAA0E;AAA3C,4GAAA,YAAY,OAAA;AAC3C,iDAA4F;AAA/D,wGAAA,UAAU,OAAA;AACvC,+CAAiE;AAArC,sGAAA,SAAS,OAAA;AACrC,mDAAuE;AAAzC,0GAAA,WAAW,OAAA;AACzC,qEAAkG;AAA3D,4HAAA,oBAAoB,OAAA;AAC3D,qDAA0E;AAA3C,4GAAA,YAAY,OAAA;AAC3C,uDAA6E;AAA7C,8GAAA,aAAa,OAAA;AAC7C,mDAAuE;AAAzC,0GAAA,WAAW,OAAA;AAEzC,qDAAoD;AAA3C,4GAAA,YAAY,OAAA","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 * Use this library to read and write *.api.json files as defined by the\n * {@link https://api-extractor.com/ | API Extractor}  tool.  These files are used to generate a documentation\n * website for your TypeScript package.  The files store the API signatures and doc comments that were extracted\n * from your package.\n *\n * @packageDocumentation\n */\n\nexport { AedocDefinitions } from './aedoc/AedocDefinitions';\nexport { ReleaseTag } from './aedoc/ReleaseTag';\n\n// items\nexport { IApiDeclaredItemOptions, ApiDeclaredItem } from './items/ApiDeclaredItem';\nexport { IApiDocumentedItemOptions, ApiDocumentedItem } from './items/ApiDocumentedItem';\nexport { ApiItemKind, IApiItemOptions, ApiItem, IApiItemConstructor } from './items/ApiItem';\nexport { IApiPropertyItemOptions, ApiPropertyItem } from './items/ApiPropertyItem';\n\n// mixins\nexport {\n  IApiParameterListMixinOptions,\n  IApiParameterOptions,\n  ApiParameterListMixin\n} from './mixins/ApiParameterListMixin';\nexport {\n  IApiTypeParameterOptions,\n  IApiTypeParameterListMixinOptions,\n  ApiTypeParameterListMixin\n} from './mixins/ApiTypeParameterListMixin';\nexport { IApiItemContainerMixinOptions, ApiItemContainerMixin } from './mixins/ApiItemContainerMixin';\nexport { IApiProtectedMixinOptions, ApiProtectedMixin } from './mixins/ApiProtectedMixin';\nexport { IApiReleaseTagMixinOptions, ApiReleaseTagMixin } from './mixins/ApiReleaseTagMixin';\nexport { IApiReturnTypeMixinOptions, ApiReturnTypeMixin } from './mixins/ApiReturnTypeMixin';\nexport { IApiStaticMixinOptions, ApiStaticMixin } from './mixins/ApiStaticMixin';\nexport { IApiNameMixinOptions, ApiNameMixin } from './mixins/ApiNameMixin';\nexport { IApiOptionalMixinOptions, ApiOptionalMixin } from './mixins/ApiOptionalMixin';\nexport { IApiReadonlyMixinOptions, ApiReadonlyMixin } from './mixins/ApiReadonlyMixin';\nexport { IApiInitializerMixinOptions, ApiInitializerMixin } from './mixins/ApiInitializerMixin';\nexport { IApiExportedMixinOptions, ApiExportedMixin } from './mixins/ApiExportedMixin';\nexport {\n  IFindApiItemsResult,\n  IFindApiItemsMessage,\n  FindApiItemsMessageId\n} from './mixins/IFindApiItemsResult';\n\nexport { ExcerptTokenKind, IExcerptTokenRange, IExcerptToken, ExcerptToken, Excerpt } from './mixins/Excerpt';\nexport { Constructor, PropertiesOf } from './mixins/Mixin';\n\n// model\nexport { IApiCallSignatureOptions, ApiCallSignature } from './model/ApiCallSignature';\nexport { IApiClassOptions, ApiClass } from './model/ApiClass';\nexport { IApiConstructorOptions, ApiConstructor } from './model/ApiConstructor';\nexport { IApiConstructSignatureOptions, ApiConstructSignature } from './model/ApiConstructSignature';\nexport { IApiEntryPointOptions, ApiEntryPoint } from './model/ApiEntryPoint';\nexport { IApiEnumOptions, ApiEnum } from './model/ApiEnum';\nexport { IApiEnumMemberOptions, ApiEnumMember, EnumMemberOrder } from './model/ApiEnumMember';\nexport { IApiFunctionOptions, ApiFunction } from './model/ApiFunction';\nexport { IApiIndexSignatureOptions, ApiIndexSignature } from './model/ApiIndexSignature';\nexport { IApiInterfaceOptions, ApiInterface } from './model/ApiInterface';\nexport { IApiMethodOptions, ApiMethod } from './model/ApiMethod';\nexport { IApiMethodSignatureOptions, ApiMethodSignature } from './model/ApiMethodSignature';\nexport { ApiModel } from './model/ApiModel';\nexport { IApiNamespaceOptions, ApiNamespace } from './model/ApiNamespace';\nexport { IApiPackageOptions, ApiPackage, IApiPackageSaveOptions } from './model/ApiPackage';\nexport { IParameterOptions, Parameter } from './model/Parameter';\nexport { IApiPropertyOptions, ApiProperty } from './model/ApiProperty';\nexport { IApiPropertySignatureOptions, ApiPropertySignature } from './model/ApiPropertySignature';\nexport { IApiTypeAliasOptions, ApiTypeAlias } from './model/ApiTypeAlias';\nexport { ITypeParameterOptions, TypeParameter } from './model/TypeParameter';\nexport { IApiVariableOptions, ApiVariable } from './model/ApiVariable';\nexport { IResolveDeclarationReferenceResult } from './model/ModelReferenceResolver';\nexport { HeritageType } from './model/HeritageType';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D;;;;;;;GAOG;AAEH,6DAA4D;AAAnD,oHAAA,gBAAgB,OAAA;AACzB,iDAAgD;AAAvC,wGAAA,UAAU,OAAA;AAEnB,QAAQ;AACR,2DAAmF;AAAjD,kHAAA,eAAe,OAAA;AACjD,+DAAyF;AAArD,sHAAA,iBAAiB,OAAA;AACrD,2CAA6F;AAApF,sGAAA,WAAW,OAAA;AAAmB,kGAAA,OAAO,OAAA;AAC9C,2DAAmF;AAAjD,kHAAA,eAAe,OAAA;AAEjD,SAAS;AACT,wEAIwC;AADtC,8HAAA,qBAAqB,OAAA;AAEvB,gFAI4C;AAD1C,sIAAA,yBAAyB,OAAA;AAE3B,wEAAsG;AAA9D,8HAAA,qBAAqB,OAAA;AAC7D,gEAA0F;AAAtD,sHAAA,iBAAiB,OAAA;AACrD,kEAA6F;AAAxD,wHAAA,kBAAkB,OAAA;AACvD,kEAA6F;AAAxD,wHAAA,kBAAkB,OAAA;AACvD,0DAAiF;AAAhD,gHAAA,cAAc,OAAA;AAC/C,sDAA2E;AAA5C,4GAAA,YAAY,OAAA;AAC3C,8DAAuF;AAApD,oHAAA,gBAAgB,OAAA;AACnD,8DAAuF;AAApD,oHAAA,gBAAgB,OAAA;AACnD,oEAAgG;AAA1D,0HAAA,mBAAmB,OAAA;AACzD,8DAAuF;AAApD,oHAAA,gBAAgB,OAAA;AACnD,oEAIsC;AADpC,4HAAA,qBAAqB,OAAA;AAGvB,4CAA8G;AAArG,2GAAA,gBAAgB,OAAA;AAAqC,uGAAA,YAAY,OAAA;AAAE,kGAAA,OAAO,OAAA;AAGnF,QAAQ;AACR,6DAAsF;AAAnD,oHAAA,gBAAgB,OAAA;AACnD,6CAA8D;AAAnC,oGAAA,QAAQ,OAAA;AACnC,yDAAgF;AAA/C,gHAAA,cAAc,OAAA;AAC/C,uEAAqG;AAA7D,8HAAA,qBAAqB,OAAA;AAC7D,uDAA6E;AAA7C,8GAAA,aAAa,OAAA;AAC7C,2CAA2D;AAAjC,kGAAA,OAAO,OAAA;AACjC,uDAA8F;AAA9D,8GAAA,aAAa,OAAA;AAAE,gHAAA,eAAe,OAAA;AAC9D,mDAAuE;AAAzC,0GAAA,WAAW,OAAA;AACzC,+DAAyF;AAArD,sHAAA,iBAAiB,OAAA;AACrD,qDAA0E;AAA3C,4GAAA,YAAY,OAAA;AAC3C,+CAAiE;AAArC,sGAAA,SAAS,OAAA;AACrC,iEAA4F;AAAvD,wHAAA,kBAAkB,OAAA;AACvD,6CAA4C;AAAnC,oGAAA,QAAQ,OAAA;AACjB,qDAA0E;AAA3C,4GAAA,YAAY,OAAA;AAC3C,iDAA4F;AAA/D,wGAAA,UAAU,OAAA;AACvC,+CAAiE;AAArC,sGAAA,SAAS,OAAA;AACrC,mDAAuE;AAAzC,0GAAA,WAAW,OAAA;AACzC,qEAAkG;AAA3D,4HAAA,oBAAoB,OAAA;AAC3D,qDAA0E;AAA3C,4GAAA,YAAY,OAAA;AAC3C,uDAA6E;AAA7C,8GAAA,aAAa,OAAA;AAC7C,mDAAuE;AAAzC,0GAAA,WAAW,OAAA;AAEzC,qDAAoD;AAA3C,4GAAA,YAAY,OAAA;AACrB,yDAAgF;AAA/C,gHAAA,cAAc,OAAA","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 * Use this library to read and write *.api.json files as defined by the\n * {@link https://api-extractor.com/ | API Extractor}  tool.  These files are used to generate a documentation\n * website for your TypeScript package.  The files store the API signatures and doc comments that were extracted\n * from your package.\n *\n * @packageDocumentation\n */\n\nexport { AedocDefinitions } from './aedoc/AedocDefinitions';\nexport { ReleaseTag } from './aedoc/ReleaseTag';\n\n// items\nexport { IApiDeclaredItemOptions, ApiDeclaredItem } from './items/ApiDeclaredItem';\nexport { IApiDocumentedItemOptions, ApiDocumentedItem } from './items/ApiDocumentedItem';\nexport { ApiItemKind, IApiItemOptions, ApiItem, IApiItemConstructor } from './items/ApiItem';\nexport { IApiPropertyItemOptions, ApiPropertyItem } from './items/ApiPropertyItem';\n\n// mixins\nexport {\n  IApiParameterListMixinOptions,\n  IApiParameterOptions,\n  ApiParameterListMixin\n} from './mixins/ApiParameterListMixin';\nexport {\n  IApiTypeParameterOptions,\n  IApiTypeParameterListMixinOptions,\n  ApiTypeParameterListMixin\n} from './mixins/ApiTypeParameterListMixin';\nexport { IApiItemContainerMixinOptions, ApiItemContainerMixin } from './mixins/ApiItemContainerMixin';\nexport { IApiProtectedMixinOptions, ApiProtectedMixin } from './mixins/ApiProtectedMixin';\nexport { IApiReleaseTagMixinOptions, ApiReleaseTagMixin } from './mixins/ApiReleaseTagMixin';\nexport { IApiReturnTypeMixinOptions, ApiReturnTypeMixin } from './mixins/ApiReturnTypeMixin';\nexport { IApiStaticMixinOptions, ApiStaticMixin } from './mixins/ApiStaticMixin';\nexport { IApiNameMixinOptions, ApiNameMixin } from './mixins/ApiNameMixin';\nexport { IApiOptionalMixinOptions, ApiOptionalMixin } from './mixins/ApiOptionalMixin';\nexport { IApiReadonlyMixinOptions, ApiReadonlyMixin } from './mixins/ApiReadonlyMixin';\nexport { IApiInitializerMixinOptions, ApiInitializerMixin } from './mixins/ApiInitializerMixin';\nexport { IApiExportedMixinOptions, ApiExportedMixin } from './mixins/ApiExportedMixin';\nexport {\n  IFindApiItemsResult,\n  IFindApiItemsMessage,\n  FindApiItemsMessageId\n} from './mixins/IFindApiItemsResult';\n\nexport { ExcerptTokenKind, IExcerptTokenRange, IExcerptToken, ExcerptToken, Excerpt } from './mixins/Excerpt';\nexport { Constructor, PropertiesOf } from './mixins/Mixin';\n\n// model\nexport { IApiCallSignatureOptions, ApiCallSignature } from './model/ApiCallSignature';\nexport { IApiClassOptions, ApiClass } from './model/ApiClass';\nexport { IApiConstructorOptions, ApiConstructor } from './model/ApiConstructor';\nexport { IApiConstructSignatureOptions, ApiConstructSignature } from './model/ApiConstructSignature';\nexport { IApiEntryPointOptions, ApiEntryPoint } from './model/ApiEntryPoint';\nexport { IApiEnumOptions, ApiEnum } from './model/ApiEnum';\nexport { IApiEnumMemberOptions, ApiEnumMember, EnumMemberOrder } from './model/ApiEnumMember';\nexport { IApiFunctionOptions, ApiFunction } from './model/ApiFunction';\nexport { IApiIndexSignatureOptions, ApiIndexSignature } from './model/ApiIndexSignature';\nexport { IApiInterfaceOptions, ApiInterface } from './model/ApiInterface';\nexport { IApiMethodOptions, ApiMethod } from './model/ApiMethod';\nexport { IApiMethodSignatureOptions, ApiMethodSignature } from './model/ApiMethodSignature';\nexport { ApiModel } from './model/ApiModel';\nexport { IApiNamespaceOptions, ApiNamespace } from './model/ApiNamespace';\nexport { IApiPackageOptions, ApiPackage, IApiPackageSaveOptions } from './model/ApiPackage';\nexport { IParameterOptions, Parameter } from './model/Parameter';\nexport { IApiPropertyOptions, ApiProperty } from './model/ApiProperty';\nexport { IApiPropertySignatureOptions, ApiPropertySignature } from './model/ApiPropertySignature';\nexport { IApiTypeAliasOptions, ApiTypeAlias } from './model/ApiTypeAlias';\nexport { ITypeParameterOptions, TypeParameter } from './model/TypeParameter';\nexport { IApiVariableOptions, ApiVariable } from './model/ApiVariable';\nexport { IResolveDeclarationReferenceResult } from './model/ModelReferenceResolver';\nexport { HeritageType } from './model/HeritageType';\nexport { ISourceLocationOptions, SourceLocation } from './model/SourceLocation';\n"]}

package/lib/items/ApiDeclaredItem.d.ts

@@ -1,15 +1,18 @@
 import { ApiDocumentedItem, IApiDocumentedItemJson, IApiDocumentedItemOptions } from './ApiDocumentedItem';
 import { Excerpt, ExcerptToken, IExcerptTokenRange, IExcerptToken } from '../mixins/Excerpt';
 import { DeserializerContext } from '../model/DeserializerContext';
+import { SourceLocation } from '../model/SourceLocation';
 /**
  * Constructor options for {@link ApiDeclaredItem}.
  * @public
  */
 export interface IApiDeclaredItemOptions extends IApiDocumentedItemOptions {
     excerptTokens: IExcerptToken[];
+    fileUrlPath?: string;
 }
 export interface IApiDeclaredItemJson extends IApiDocumentedItemJson {
     excerptTokens: IExcerptToken[];
+    fileUrlPath?: string;
 }
 /**
  * The base class for API items that have an associated source code excerpt containing a TypeScript declaration.
@@ -27,6 +30,8 @@ export interface IApiDeclaredItemJson extends IApiDocumentedItemJson {
 export declare class ApiDeclaredItem extends ApiDocumentedItem {
     private _excerptTokens;
     private _excerpt;
+    private _fileUrlPath?;
+    private _sourceLocation?;
     constructor(options: IApiDeclaredItemOptions);
     /** @override */
     static onDeserializeInto(options: Partial<IApiDeclaredItemOptions>, context: DeserializerContext, jsonObject: IApiDeclaredItemJson): void;
@@ -38,6 +43,16 @@ export declare class ApiDeclaredItem extends ApiDocumentedItem {
      * The individual source code tokens that comprise the main excerpt.
      */
     get excerptTokens(): ReadonlyArray<ExcerptToken>;
+    /**
+     * The file URL path relative to the `projectFolder` and `projectFolderURL` fields
+     * as defined in the `api-extractor.json` config. Is `undefined` if the path is
+     * the same as the parent API item's.
+     */
+    get fileUrlPath(): string | undefined;
+    /**
+     * Returns the source location where the API item is declared.
+     */
+    get sourceLocation(): SourceLocation;
     /**
      * If the API item has certain important modifier tags such as `@sealed`, `@virtual`, or `@override`,
      * this prepends them as a doc comment above the excerpt.
@@ -49,5 +64,9 @@ export declare class ApiDeclaredItem extends ApiDocumentedItem {
      * Constructs a new {@link Excerpt} corresponding to the provided token range.
      */
     buildExcerpt(tokenRange: IExcerptTokenRange): Excerpt;
+    /**
+     * Builds the cached object used by the `sourceLocation` property.
+     */
+    private _buildSourceLocation;
 }
 //# sourceMappingURL=ApiDeclaredItem.d.ts.map

package/lib/items/ApiDeclaredItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiDeclaredItem.d.ts","sourceRoot":"","sources":["../../src/items/ApiDeclaredItem.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,yBAAyB;IACxE,aAAa,EAAE,aAAa,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,aAAa,EAAE,aAAa,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AAEH,qBAAa,eAAgB,SAAQ,iBAAiB;IACpD,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAU;gBAEP,OAAO,EAAE,uBAAuB;IAanD,gBAAgB;WACF,iBAAiB,CAC7B,OAAO,EAAE,OAAO,CAAC,uBAAuB,CAAC,EACzC,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,oBAAoB,GAC/B,IAAI;IAMP;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;OAEG;IACH,IAAW,aAAa,IAAI,aAAa,CAAC,YAAY,CAAC,CAEtD;IAED;;;OAGG;IACI,uBAAuB,IAAI,MAAM;IA0BxC,gBAAgB;IACT,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IAWrE;;OAEG;IACI,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO;CAG7D"}
+{"version":3,"file":"ApiDeclaredItem.d.ts","sourceRoot":"","sources":["../../src/items/ApiDeclaredItem.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE3G,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,uBAAwB,SAAQ,yBAAyB;IACxE,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AAEH,qBAAa,eAAgB,SAAQ,iBAAiB;IACpD,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAC,CAAiB;gBAEtB,OAAO,EAAE,uBAAuB;IAcnD,gBAAgB;WACF,iBAAiB,CAC7B,OAAO,EAAE,OAAO,CAAC,uBAAuB,CAAC,EACzC,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,oBAAoB,GAC/B,IAAI;IAOP;;OAEG;IACH,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;OAEG;IACH,IAAW,aAAa,IAAI,aAAa,CAAC,YAAY,CAAC,CAEtD;IAED;;;;OAIG;IACH,IAAW,WAAW,IAAI,MAAM,GAAG,SAAS,CAE3C;IAED;;OAEG;IACH,IAAW,cAAc,IAAI,cAAc,CAK1C;IAED;;;OAGG;IACI,uBAAuB,IAAI,MAAM;IA0BxC,gBAAgB;IACT,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;IAmBrE;;OAEG;IACI,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO;IAI5D;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAgB7B"}

package/lib/items/ApiDeclaredItem.js

@@ -6,6 +6,7 @@ exports.ApiDeclaredItem = void 0;
 const DeclarationReference_1 = require("@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference");
 const ApiDocumentedItem_1 = require("./ApiDocumentedItem");
 const Excerpt_1 = require("../mixins/Excerpt");
+const SourceLocation_1 = require("../model/SourceLocation");
 /**
  * The base class for API items that have an associated source code excerpt containing a TypeScript declaration.
  *
@@ -30,11 +31,13 @@ class ApiDeclaredItem extends ApiDocumentedItem_1.ApiDocumentedItem {
             return new Excerpt_1.ExcerptToken(token.kind, token.text, canonicalReference);
         });
         this._excerpt = new Excerpt_1.Excerpt(this.excerptTokens, { startIndex: 0, endIndex: this.excerptTokens.length });
+        this._fileUrlPath = options.fileUrlPath;
     }
     /** @override */
     static onDeserializeInto(options, context, jsonObject) {
         super.onDeserializeInto(options, context, jsonObject);
         options.excerptTokens = jsonObject.excerptTokens;
+        options.fileUrlPath = jsonObject.fileUrlPath;
     }
     /**
      * The source code excerpt where the API item is declared.
@@ -48,6 +51,23 @@ class ApiDeclaredItem extends ApiDocumentedItem_1.ApiDocumentedItem {
     get excerptTokens() {
         return this._excerptTokens;
     }
+    /**
+     * The file URL path relative to the `projectFolder` and `projectFolderURL` fields
+     * as defined in the `api-extractor.json` config. Is `undefined` if the path is
+     * the same as the parent API item's.
+     */
+    get fileUrlPath() {
+        return this._fileUrlPath;
+    }
+    /**
+     * Returns the source location where the API item is declared.
+     */
+    get sourceLocation() {
+        if (!this._sourceLocation) {
+            this._sourceLocation = this._buildSourceLocation();
+        }
+        return this._sourceLocation;
+    }
     /**
      * If the API item has certain important modifier tags such as `@sealed`, `@virtual`, or `@override`,
      * this prepends them as a doc comment above the excerpt.
@@ -85,6 +105,13 @@ class ApiDeclaredItem extends ApiDocumentedItem_1.ApiDocumentedItem {
             }
             return excerptToken;
         });
+        // Only serialize this API item's file URL path if it exists and it's different from its parent's
+        // (a little optimization to keep the doc model succinct).
+        if (this.fileUrlPath) {
+            if (!(this.parent instanceof ApiDeclaredItem) || this.fileUrlPath !== this.parent.fileUrlPath) {
+                jsonObject.fileUrlPath = this.fileUrlPath;
+            }
+        }
     }
     /**
      * Constructs a new {@link Excerpt} corresponding to the provided token range.
@@ -92,6 +119,24 @@ class ApiDeclaredItem extends ApiDocumentedItem_1.ApiDocumentedItem {
     buildExcerpt(tokenRange) {
         return new Excerpt_1.Excerpt(this.excerptTokens, tokenRange);
     }
+    /**
+     * Builds the cached object used by the `sourceLocation` property.
+     */
+    _buildSourceLocation() {
+        var _a;
+        const projectFolderUrl = (_a = this.getAssociatedPackage()) === null || _a === void 0 ? void 0 : _a.projectFolderUrl;
+        let fileUrlPath;
+        for (let current = this; current !== undefined; current = current.parent) {
+            if (current instanceof ApiDeclaredItem && current.fileUrlPath) {
+                fileUrlPath = current.fileUrlPath;
+                break;
+            }
+        }
+        return new SourceLocation_1.SourceLocation({
+            projectFolderUrl: projectFolderUrl,
+            fileUrlPath: fileUrlPath
+        });
+    }
 }
 exports.ApiDeclaredItem = ApiDeclaredItem;
 //# sourceMappingURL=ApiDeclaredItem.js.map

package/lib/items/ApiDeclaredItem.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiDeclaredItem.js","sourceRoot":"","sources":["../../src/items/ApiDeclaredItem.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.s\n\nimport { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\nimport { ApiDocumentedItem, IApiDocumentedItemJson, IApiDocumentedItemOptions } from './ApiDocumentedItem';\nimport { Excerpt, ExcerptToken, IExcerptTokenRange, IExcerptToken } from '../mixins/Excerpt';\nimport { DeserializerContext } from '../model/DeserializerContext';\n\n/**\n * Constructor options for {@link ApiDeclaredItem}.\n * @public\n */\nexport interface IApiDeclaredItemOptions extends IApiDocumentedItemOptions {\n  excerptTokens: IExcerptToken[];\n}\n\nexport interface IApiDeclaredItemJson extends IApiDocumentedItemJson {\n  excerptTokens: IExcerptToken[];\n}\n\n/**\n * The base class for API items that have an associated source code excerpt containing a TypeScript declaration.\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 * Most `ApiItem` subclasses have declarations and thus extend `ApiDeclaredItem`.  Counterexamples include\n * `ApiModel` and `ApiPackage`, which do not have any corresponding TypeScript source code.\n *\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport class ApiDeclaredItem extends ApiDocumentedItem {\n  private _excerptTokens: ExcerptToken[];\n  private _excerpt: Excerpt;\n\n  public constructor(options: IApiDeclaredItemOptions) {\n    super(options);\n\n    this._excerptTokens = options.excerptTokens.map((token) => {\n      const canonicalReference: DeclarationReference | undefined =\n        token.canonicalReference === undefined\n          ? undefined\n          : DeclarationReference.parse(token.canonicalReference);\n      return new ExcerptToken(token.kind, token.text, canonicalReference);\n    });\n    this._excerpt = new Excerpt(this.excerptTokens, { startIndex: 0, endIndex: this.excerptTokens.length });\n  }\n\n  /** @override */\n  public static onDeserializeInto(\n    options: Partial<IApiDeclaredItemOptions>,\n    context: DeserializerContext,\n    jsonObject: IApiDeclaredItemJson\n  ): void {\n    super.onDeserializeInto(options, context, jsonObject);\n\n    options.excerptTokens = jsonObject.excerptTokens;\n  }\n\n  /**\n   * The source code excerpt where the API item is declared.\n   */\n  public get excerpt(): Excerpt {\n    return this._excerpt;\n  }\n\n  /**\n   * The individual source code tokens that comprise the main excerpt.\n   */\n  public get excerptTokens(): ReadonlyArray<ExcerptToken> {\n    return this._excerptTokens;\n  }\n\n  /**\n   * If the API item has certain important modifier tags such as `@sealed`, `@virtual`, or `@override`,\n   * this prepends them as a doc comment above the excerpt.\n   */\n  public getExcerptWithModifiers(): string {\n    const excerpt: string = this.excerpt.text;\n    const modifierTags: string[] = [];\n\n    if (excerpt.length > 0) {\n      if (this instanceof ApiDocumentedItem) {\n        if (this.tsdocComment) {\n          if (this.tsdocComment.modifierTagSet.isSealed()) {\n            modifierTags.push('@sealed');\n          }\n          if (this.tsdocComment.modifierTagSet.isVirtual()) {\n            modifierTags.push('@virtual');\n          }\n          if (this.tsdocComment.modifierTagSet.isOverride()) {\n            modifierTags.push('@override');\n          }\n        }\n        if (modifierTags.length > 0) {\n          return '/** ' + modifierTags.join(' ') + ' */\\n' + excerpt;\n        }\n      }\n    }\n\n    return excerpt;\n  }\n\n  /** @override */\n  public serializeInto(jsonObject: Partial<IApiDeclaredItemJson>): void {\n    super.serializeInto(jsonObject);\n    jsonObject.excerptTokens = this.excerptTokens.map((x) => {\n      const excerptToken: IExcerptToken = { kind: x.kind, text: x.text };\n      if (x.canonicalReference !== undefined) {\n        excerptToken.canonicalReference = x.canonicalReference.toString();\n      }\n      return excerptToken;\n    });\n  }\n\n  /**\n   * Constructs a new {@link Excerpt} corresponding to the provided token range.\n   */\n  public buildExcerpt(tokenRange: IExcerptTokenRange): Excerpt {\n    return new Excerpt(this.excerptTokens, tokenRange);\n  }\n}\n"]}
+{"version":3,"file":"ApiDeclaredItem.js","sourceRoot":"","sources":["../../src/items/ApiDeclaredItem.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.s\n\nimport { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';\nimport { ApiDocumentedItem, IApiDocumentedItemJson, IApiDocumentedItemOptions } from './ApiDocumentedItem';\nimport { ApiItem } from './ApiItem';\nimport { Excerpt, ExcerptToken, IExcerptTokenRange, IExcerptToken } from '../mixins/Excerpt';\nimport { DeserializerContext } from '../model/DeserializerContext';\nimport { SourceLocation } from '../model/SourceLocation';\n\n/**\n * Constructor options for {@link ApiDeclaredItem}.\n * @public\n */\nexport interface IApiDeclaredItemOptions extends IApiDocumentedItemOptions {\n  excerptTokens: IExcerptToken[];\n  fileUrlPath?: string;\n}\n\nexport interface IApiDeclaredItemJson extends IApiDocumentedItemJson {\n  excerptTokens: IExcerptToken[];\n  fileUrlPath?: string;\n}\n\n/**\n * The base class for API items that have an associated source code excerpt containing a TypeScript declaration.\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 * Most `ApiItem` subclasses have declarations and thus extend `ApiDeclaredItem`.  Counterexamples include\n * `ApiModel` and `ApiPackage`, which do not have any corresponding TypeScript source code.\n *\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport class ApiDeclaredItem extends ApiDocumentedItem {\n  private _excerptTokens: ExcerptToken[];\n  private _excerpt: Excerpt;\n  private _fileUrlPath?: string;\n  private _sourceLocation?: SourceLocation;\n\n  public constructor(options: IApiDeclaredItemOptions) {\n    super(options);\n\n    this._excerptTokens = options.excerptTokens.map((token) => {\n      const canonicalReference: DeclarationReference | undefined =\n        token.canonicalReference === undefined\n          ? undefined\n          : DeclarationReference.parse(token.canonicalReference);\n      return new ExcerptToken(token.kind, token.text, canonicalReference);\n    });\n    this._excerpt = new Excerpt(this.excerptTokens, { startIndex: 0, endIndex: this.excerptTokens.length });\n    this._fileUrlPath = options.fileUrlPath;\n  }\n\n  /** @override */\n  public static onDeserializeInto(\n    options: Partial<IApiDeclaredItemOptions>,\n    context: DeserializerContext,\n    jsonObject: IApiDeclaredItemJson\n  ): void {\n    super.onDeserializeInto(options, context, jsonObject);\n\n    options.excerptTokens = jsonObject.excerptTokens;\n    options.fileUrlPath = jsonObject.fileUrlPath;\n  }\n\n  /**\n   * The source code excerpt where the API item is declared.\n   */\n  public get excerpt(): Excerpt {\n    return this._excerpt;\n  }\n\n  /**\n   * The individual source code tokens that comprise the main excerpt.\n   */\n  public get excerptTokens(): ReadonlyArray<ExcerptToken> {\n    return this._excerptTokens;\n  }\n\n  /**\n   * The file URL path relative to the `projectFolder` and `projectFolderURL` fields\n   * as defined in the `api-extractor.json` config. Is `undefined` if the path is\n   * the same as the parent API item's.\n   */\n  public get fileUrlPath(): string | undefined {\n    return this._fileUrlPath;\n  }\n\n  /**\n   * Returns the source location where the API item is declared.\n   */\n  public get sourceLocation(): SourceLocation {\n    if (!this._sourceLocation) {\n      this._sourceLocation = this._buildSourceLocation();\n    }\n    return this._sourceLocation;\n  }\n\n  /**\n   * If the API item has certain important modifier tags such as `@sealed`, `@virtual`, or `@override`,\n   * this prepends them as a doc comment above the excerpt.\n   */\n  public getExcerptWithModifiers(): string {\n    const excerpt: string = this.excerpt.text;\n    const modifierTags: string[] = [];\n\n    if (excerpt.length > 0) {\n      if (this instanceof ApiDocumentedItem) {\n        if (this.tsdocComment) {\n          if (this.tsdocComment.modifierTagSet.isSealed()) {\n            modifierTags.push('@sealed');\n          }\n          if (this.tsdocComment.modifierTagSet.isVirtual()) {\n            modifierTags.push('@virtual');\n          }\n          if (this.tsdocComment.modifierTagSet.isOverride()) {\n            modifierTags.push('@override');\n          }\n        }\n        if (modifierTags.length > 0) {\n          return '/** ' + modifierTags.join(' ') + ' */\\n' + excerpt;\n        }\n      }\n    }\n\n    return excerpt;\n  }\n\n  /** @override */\n  public serializeInto(jsonObject: Partial<IApiDeclaredItemJson>): void {\n    super.serializeInto(jsonObject);\n    jsonObject.excerptTokens = this.excerptTokens.map((x) => {\n      const excerptToken: IExcerptToken = { kind: x.kind, text: x.text };\n      if (x.canonicalReference !== undefined) {\n        excerptToken.canonicalReference = x.canonicalReference.toString();\n      }\n      return excerptToken;\n    });\n\n    // Only serialize this API item's file URL path if it exists and it's different from its parent's\n    // (a little optimization to keep the doc model succinct).\n    if (this.fileUrlPath) {\n      if (!(this.parent instanceof ApiDeclaredItem) || this.fileUrlPath !== this.parent.fileUrlPath) {\n        jsonObject.fileUrlPath = this.fileUrlPath;\n      }\n    }\n  }\n\n  /**\n   * Constructs a new {@link Excerpt} corresponding to the provided token range.\n   */\n  public buildExcerpt(tokenRange: IExcerptTokenRange): Excerpt {\n    return new Excerpt(this.excerptTokens, tokenRange);\n  }\n\n  /**\n   * Builds the cached object used by the `sourceLocation` property.\n   */\n  private _buildSourceLocation(): SourceLocation {\n    const projectFolderUrl: string | undefined = this.getAssociatedPackage()?.projectFolderUrl;\n\n    let fileUrlPath: string | undefined;\n    for (let current: ApiItem | undefined = this; current !== undefined; current = current.parent) {\n      if (current instanceof ApiDeclaredItem && current.fileUrlPath) {\n        fileUrlPath = current.fileUrlPath;\n        break;\n      }\n    }\n\n    return new SourceLocation({\n      projectFolderUrl: projectFolderUrl,\n      fileUrlPath: fileUrlPath\n    });\n  }\n}\n"]}

package/lib/model/ApiPackage.d.ts

@@ -5,7 +5,7 @@ import { IJsonFileSaveOptions, JsonObject } from '@rushstack/node-core-library';
 import { ApiDocumentedItem, IApiDocumentedItemOptions } from '../items/ApiDocumentedItem';
 import { ApiEntryPoint } from './ApiEntryPoint';
 import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';
-import { ApiJsonSchemaVersion } from './DeserializerContext';
+import { DeserializerContext, ApiJsonSchemaVersion } from './DeserializerContext';
 import { TSDocConfiguration } from '@microsoft/tsdoc';
 /**
  * Constructor options for {@link ApiPackage}.
@@ -13,6 +13,7 @@ import { TSDocConfiguration } from '@microsoft/tsdoc';
  */
 export interface IApiPackageOptions extends IApiItemContainerMixinOptions, IApiNameMixinOptions, IApiDocumentedItemOptions {
     tsdocConfiguration: TSDocConfiguration;
+    projectFolderUrl?: string;
 }
 export interface IApiPackageMetadataJson {
     /**
@@ -61,6 +62,12 @@ export interface IApiPackageJson extends IApiItemJson {
      * A file header that stores metadata about the tool that wrote the *.api.json file.
      */
     metadata: IApiPackageMetadataJson;
+    /**
+     * The base URL where the project's source code can be viewed on a website such as GitHub or
+     * Azure DevOps. This URL path corresponds to the `<projectFolder>` path on disk. Provided via the
+     * `api-extractor.json` config.
+     */
+    projectFolderUrl?: string;
 }
 /**
  * Options for {@link ApiPackage.saveToJsonFile}.
@@ -99,7 +106,10 @@ declare const ApiPackage_base: typeof ApiDocumentedItem & (new (...args: any[])
  */
 export declare class ApiPackage extends ApiPackage_base {
     private readonly _tsdocConfiguration;
+    private readonly _projectFolderUrl?;
     constructor(options: IApiPackageOptions);
+    /** @override */
+    static onDeserializeInto(options: Partial<IApiPackageOptions>, context: DeserializerContext, jsonObject: IApiPackageJson): void;
     static loadFromJsonFile(apiJsonFilename: string): ApiPackage;
     /** @override */
     get kind(): ApiItemKind;
@@ -115,6 +125,7 @@ export declare class ApiPackage extends ApiPackage_base {
      * in the .api.json file so that doc comments can be parsed accurately when loading the file.
      */
     get tsdocConfiguration(): TSDocConfiguration;
+    get projectFolderUrl(): string | undefined;
     /** @override */
     addMember(member: ApiEntryPoint): void;
     findEntryPointsByPath(importPath: string): ReadonlyArray<ApiEntryPoint>;

package/lib/model/ApiPackage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiPackage.d.ts","sourceRoot":"","sources":["../../src/model/ApiPackage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yDAAyD,CAAC;AAC/F,OAAO,EAAW,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AACvG,OAAO,EAEL,oBAAoB,EAGpB,UAAU,EACX,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAuB,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,kBACf,SAAQ,6BAA6B,EACnC,oBAAoB,EACpB,yBAAyB;IAC3B,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,EAAE,oBAAoB,CAAC;IAEpC;;;;;;;;;;;;;OAaG;IACH,+BAA+B,CAAC,EAAE,oBAAoB,CAAC;IAEvD;;;;;;;;OAQG;IACH,WAAW,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD;;OAEG;IACH,QAAQ,EAAE,uBAAuB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,eAAsD;IACpF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;gBAEtC,OAAO,EAAE,kBAAkB;WAMhC,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,UAAU;IAwEnE,gBAAgB;IAChB,IAAW,IAAI,IAAI,WAAW,CAE7B;IAED,gBAAgB;IAChB,IAAW,YAAY,IAAI,MAAM,CAGhC;IAED,IAAW,WAAW,IAAI,aAAa,CAAC,aAAa,CAAC,CAErD;IAED;;;;;;;OAOG;IACH,IAAW,kBAAkB,IAAI,kBAAkB,CAElD;IAED,gBAAgB;IACT,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAOtC,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAC,aAAa,CAAC;IAIvE,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI;IAyBtF,sBAAsB;IACf,uBAAuB,IAAI,oBAAoB;CAGvD"}
+{"version":3,"file":"ApiPackage.d.ts","sourceRoot":"","sources":["../../src/model/ApiPackage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yDAAyD,CAAC;AAC/F,OAAO,EAAW,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AACvG,OAAO,EAEL,oBAAoB,EAGpB,UAAU,EACX,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,kBACf,SAAQ,6BAA6B,EACnC,oBAAoB,EACpB,yBAAyB;IAC3B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,EAAE,oBAAoB,CAAC;IAEpC;;;;;;;;;;;;;OAaG;IACH,+BAA+B,CAAC,EAAE,oBAAoB,CAAC;IAEvD;;;;;;;;OAQG;IACH,WAAW,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD;;OAEG;IACH,QAAQ,EAAE,uBAAuB,CAAC;IAElC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,eAAsD;IACpF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;gBAEzB,OAAO,EAAE,kBAAkB;IAO9C,gBAAgB;WACF,iBAAiB,CAC7B,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,EACpC,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,eAAe,GAC1B,IAAI;WAMO,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,UAAU;IAwEnE,gBAAgB;IAChB,IAAW,IAAI,IAAI,WAAW,CAE7B;IAED,gBAAgB;IAChB,IAAW,YAAY,IAAI,MAAM,CAGhC;IAED,IAAW,WAAW,IAAI,aAAa,CAAC,aAAa,CAAC,CAErD;IAED;;;;;;;OAOG;IACH,IAAW,kBAAkB,IAAI,kBAAkB,CAElD;IAED,IAAW,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAEhD;IAED,gBAAgB;IACT,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAOtC,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAAC,aAAa,CAAC;IAIvE,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI;IA8BtF,sBAAsB;IACf,uBAAuB,IAAI,oBAAoB;CAGvD"}

package/lib/model/ApiPackage.js

@@ -26,6 +26,12 @@ class ApiPackage extends (0, ApiItemContainerMixin_1.ApiItemContainerMixin)((0,
     constructor(options) {
         super(options);
         this._tsdocConfiguration = options.tsdocConfiguration;
+        this._projectFolderUrl = options.projectFolderUrl;
+    }
+    /** @override */
+    static onDeserializeInto(options, context, jsonObject) {
+        super.onDeserializeInto(options, context, jsonObject);
+        options.projectFolderUrl = jsonObject.projectFolderUrl;
     }
     static loadFromJsonFile(apiJsonFilename) {
         const jsonObject = node_core_library_1.JsonFile.load(apiJsonFilename);
@@ -100,6 +106,9 @@ class ApiPackage extends (0, ApiItemContainerMixin_1.ApiItemContainerMixin)((0,
     get tsdocConfiguration() {
         return this._tsdocConfiguration;
     }
+    get projectFolderUrl() {
+        return this._projectFolderUrl;
+    }
     /** @override */
     addMember(member) {
         if (member.kind !== ApiItem_1.ApiItemKind.EntryPoint) {
@@ -128,6 +137,9 @@ class ApiPackage extends (0, ApiItemContainerMixin_1.ApiItemContainerMixin)((0,
                 tsdocConfig
             }
         };
+        if (this.projectFolderUrl) {
+            jsonObject.projectFolderUrl = this.projectFolderUrl;
+        }
         this.serializeInto(jsonObject);
         node_core_library_1.JsonFile.save(jsonObject, apiJsonFilename, options);
     }

package/lib/model/ApiPackage.js.map

@@ -1 +1 @@
-{"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, IApiItemJson } from '../items/ApiItem';\nimport { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin';\nimport {\n  JsonFile,\n  IJsonFileSaveOptions,\n  PackageJsonLookup,\n  IPackageJson,\n  JsonObject\n} from '@rushstack/node-core-library';\nimport { ApiDocumentedItem, IApiDocumentedItemOptions } from '../items/ApiDocumentedItem';\nimport { ApiEntryPoint } from './ApiEntryPoint';\nimport { 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}\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/**\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\n  public constructor(options: IApiPackageOptions) {\n    super(options);\n\n    this._tsdocConfiguration = options.tsdocConfiguration;\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  /** @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    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"]}
+{"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, IApiItemJson } from '../items/ApiItem';\nimport { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin';\nimport {\n  JsonFile,\n  IJsonFileSaveOptions,\n  PackageJsonLookup,\n  IPackageJson,\n  JsonObject\n} from '@rushstack/node-core-library';\nimport { ApiDocumentedItem, IApiDocumentedItemOptions } from '../items/ApiDocumentedItem';\nimport { ApiEntryPoint } from './ApiEntryPoint';\nimport { 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"]}

package/lib/model/Deserializer.js.map

@@ -1 +1 @@
-{"version":3,"file":"Deserializer.js","sourceRoot":"","sources":["../../src/model/Deserializer.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 { IApiItemJson, IApiItemOptions, ApiItem, ApiItemKind } from '../items/ApiItem';\nimport { ApiClass, IApiClassOptions, IApiClassJson } from './ApiClass';\nimport { ApiEntryPoint, IApiEntryPointOptions } from './ApiEntryPoint';\nimport { ApiMethod, IApiMethodOptions } from './ApiMethod';\nimport { ApiModel } from './ApiModel';\nimport { ApiNamespace, IApiNamespaceOptions } from './ApiNamespace';\nimport { ApiPackage, IApiPackageOptions } from './ApiPackage';\nimport { ApiInterface, IApiInterfaceOptions, IApiInterfaceJson } from './ApiInterface';\nimport { ApiPropertySignature, IApiPropertySignatureOptions } from './ApiPropertySignature';\nimport { ApiMethodSignature, IApiMethodSignatureOptions } from './ApiMethodSignature';\nimport { ApiProperty, IApiPropertyOptions } from './ApiProperty';\nimport { ApiEnumMember, IApiEnumMemberOptions } from './ApiEnumMember';\nimport { ApiEnum, IApiEnumOptions } from './ApiEnum';\nimport { IApiPropertyItemJson } from '../items/ApiPropertyItem';\nimport { ApiConstructor, IApiConstructorOptions } from './ApiConstructor';\nimport { ApiConstructSignature, IApiConstructSignatureOptions } from './ApiConstructSignature';\nimport { ApiFunction, IApiFunctionOptions } from './ApiFunction';\nimport { ApiCallSignature, IApiCallSignatureOptions } from './ApiCallSignature';\nimport { ApiIndexSignature, IApiIndexSignatureOptions } from './ApiIndexSignature';\nimport { ApiTypeAlias, IApiTypeAliasOptions, IApiTypeAliasJson } from './ApiTypeAlias';\nimport { ApiVariable, IApiVariableOptions, IApiVariableJson } from './ApiVariable';\nimport { IApiDeclaredItemJson } from '../items/ApiDeclaredItem';\nimport { DeserializerContext } from './DeserializerContext';\n\nexport class Deserializer {\n  public static deserialize(context: DeserializerContext, jsonObject: IApiItemJson): ApiItem {\n    const options: Partial<IApiItemOptions> = {};\n\n    switch (jsonObject.kind) {\n      case ApiItemKind.Class:\n        ApiClass.onDeserializeInto(options, context, jsonObject as IApiClassJson);\n        return new ApiClass(options as IApiClassOptions);\n      case ApiItemKind.CallSignature:\n        ApiCallSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiCallSignature(options as IApiCallSignatureOptions);\n      case ApiItemKind.Constructor:\n        ApiConstructor.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiConstructor(options as IApiConstructorOptions);\n      case ApiItemKind.ConstructSignature:\n        ApiConstructSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiConstructSignature(options as IApiConstructSignatureOptions);\n      case ApiItemKind.EntryPoint:\n        ApiEntryPoint.onDeserializeInto(options, context, jsonObject);\n        return new ApiEntryPoint(options as IApiEntryPointOptions);\n      case ApiItemKind.Enum:\n        ApiEnum.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiEnum(options as IApiEnumOptions);\n      case ApiItemKind.EnumMember:\n        ApiEnumMember.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiEnumMember(options as IApiEnumMemberOptions);\n      case ApiItemKind.Function:\n        ApiFunction.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiFunction(options as IApiFunctionOptions);\n      case ApiItemKind.IndexSignature:\n        ApiIndexSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiIndexSignature(options as IApiIndexSignatureOptions);\n      case ApiItemKind.Interface:\n        ApiInterface.onDeserializeInto(options, context, jsonObject as IApiInterfaceJson);\n        return new ApiInterface(options as IApiInterfaceOptions);\n      case ApiItemKind.Method:\n        ApiMethod.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiMethod(options as IApiMethodOptions);\n      case ApiItemKind.MethodSignature:\n        ApiMethodSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiMethodSignature(options as IApiMethodSignatureOptions);\n      case ApiItemKind.Model:\n        return new ApiModel();\n      case ApiItemKind.Namespace:\n        ApiNamespace.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiNamespace(options as IApiNamespaceOptions);\n      case ApiItemKind.Package:\n        ApiPackage.onDeserializeInto(options, context, jsonObject);\n        return new ApiPackage(options as IApiPackageOptions);\n      case ApiItemKind.Property:\n        ApiProperty.onDeserializeInto(options, context, jsonObject as IApiPropertyItemJson);\n        return new ApiProperty(options as IApiPropertyOptions);\n      case ApiItemKind.PropertySignature:\n        ApiPropertySignature.onDeserializeInto(options, context, jsonObject as IApiPropertyItemJson);\n        return new ApiPropertySignature(options as IApiPropertySignatureOptions);\n      case ApiItemKind.TypeAlias:\n        ApiTypeAlias.onDeserializeInto(options, context, jsonObject as IApiTypeAliasJson);\n        return new ApiTypeAlias(options as IApiTypeAliasOptions);\n      case ApiItemKind.Variable:\n        ApiVariable.onDeserializeInto(options, context, jsonObject as IApiVariableJson);\n        return new ApiVariable(options as IApiVariableOptions);\n      default:\n        throw new Error(`Failed to deserialize unsupported API item type ${JSON.stringify(jsonObject.kind)}`);\n    }\n  }\n}\n"]}
+{"version":3,"file":"Deserializer.js","sourceRoot":"","sources":["../../src/model/Deserializer.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D,8CAAuF;AACvF,yCAAuE;AACvE,mDAAuE;AACvE,2CAA2D;AAC3D,yCAAsC;AACtC,iDAAoE;AACpE,6CAA+E;AAC/E,iDAAuF;AACvF,iEAA4F;AAC5F,6DAAsF;AACtF,+CAAiE;AACjE,mDAAuE;AACvE,uCAAqD;AAErD,qDAA0E;AAC1E,mEAA+F;AAC/F,+CAAiE;AACjE,yDAAgF;AAChF,2DAAmF;AACnF,iDAAuF;AACvF,+CAAmF;AAInF,MAAa,YAAY;IAChB,MAAM,CAAC,WAAW,CAAC,OAA4B,EAAE,UAAwB;QAC9E,MAAM,OAAO,GAA6B,EAAE,CAAC;QAE7C,QAAQ,UAAU,CAAC,IAAI,EAAE;YACvB,KAAK,qBAAW,CAAC,KAAK;gBACpB,mBAAQ,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAA2B,CAAC,CAAC;gBAC1E,OAAO,IAAI,mBAAQ,CAAC,OAA2B,CAAC,CAAC;YACnD,KAAK,qBAAW,CAAC,aAAa;gBAC5B,mCAAgB,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBACzF,OAAO,IAAI,mCAAgB,CAAC,OAAmC,CAAC,CAAC;YACnE,KAAK,qBAAW,CAAC,WAAW;gBAC1B,+BAAc,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBACvF,OAAO,IAAI,+BAAc,CAAC,OAAiC,CAAC,CAAC;YAC/D,KAAK,qBAAW,CAAC,kBAAkB;gBACjC,6CAAqB,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBAC9F,OAAO,IAAI,6CAAqB,CAAC,OAAwC,CAAC,CAAC;YAC7E,KAAK,qBAAW,CAAC,UAAU;gBACzB,6BAAa,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC9D,OAAO,IAAI,6BAAa,CAAC,OAAgC,CAAC,CAAC;YAC7D,KAAK,qBAAW,CAAC,IAAI;gBACnB,iBAAO,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBAChF,OAAO,IAAI,iBAAO,CAAC,OAA0B,CAAC,CAAC;YACjD,KAAK,qBAAW,CAAC,UAAU;gBACzB,6BAAa,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBACtF,OAAO,IAAI,6BAAa,CAAC,OAAgC,CAAC,CAAC;YAC7D,KAAK,qBAAW,CAAC,QAAQ;gBACvB,yBAAW,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBACpF,OAAO,IAAI,yBAAW,CAAC,OAA8B,CAAC,CAAC;YACzD,KAAK,qBAAW,CAAC,cAAc;gBAC7B,qCAAiB,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBAC1F,OAAO,IAAI,qCAAiB,CAAC,OAAoC,CAAC,CAAC;YACrE,KAAK,qBAAW,CAAC,SAAS;gBACxB,2BAAY,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAA+B,CAAC,CAAC;gBAClF,OAAO,IAAI,2BAAY,CAAC,OAA+B,CAAC,CAAC;YAC3D,KAAK,qBAAW,CAAC,MAAM;gBACrB,qBAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBAClF,OAAO,IAAI,qBAAS,CAAC,OAA4B,CAAC,CAAC;YACrD,KAAK,qBAAW,CAAC,eAAe;gBAC9B,uCAAkB,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBAC3F,OAAO,IAAI,uCAAkB,CAAC,OAAqC,CAAC,CAAC;YACvE,KAAK,qBAAW,CAAC,KAAK;gBACpB,OAAO,IAAI,mBAAQ,EAAE,CAAC;YACxB,KAAK,qBAAW,CAAC,SAAS;gBACxB,2BAAY,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBACrF,OAAO,IAAI,2BAAY,CAAC,OAA+B,CAAC,CAAC;YAC3D,KAAK,qBAAW,CAAC,OAAO;gBACtB,uBAAU,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAA6B,CAAC,CAAC;gBAC9E,OAAO,IAAI,uBAAU,CAAC,OAA6B,CAAC,CAAC;YACvD,KAAK,qBAAW,CAAC,QAAQ;gBACvB,yBAAW,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBACpF,OAAO,IAAI,yBAAW,CAAC,OAA8B,CAAC,CAAC;YACzD,KAAK,qBAAW,CAAC,iBAAiB;gBAChC,2CAAoB,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAkC,CAAC,CAAC;gBAC7F,OAAO,IAAI,2CAAoB,CAAC,OAAuC,CAAC,CAAC;YAC3E,KAAK,qBAAW,CAAC,SAAS;gBACxB,2BAAY,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAA+B,CAAC,CAAC;gBAClF,OAAO,IAAI,2BAAY,CAAC,OAA+B,CAAC,CAAC;YAC3D,KAAK,qBAAW,CAAC,QAAQ;gBACvB,yBAAW,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,UAA8B,CAAC,CAAC;gBAChF,OAAO,IAAI,yBAAW,CAAC,OAA8B,CAAC,CAAC;YACzD;gBACE,MAAM,IAAI,KAAK,CAAC,mDAAmD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SACzG;IACH,CAAC;CACF;AAjED,oCAiEC","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 { IApiItemJson, IApiItemOptions, ApiItem, ApiItemKind } from '../items/ApiItem';\nimport { ApiClass, IApiClassOptions, IApiClassJson } from './ApiClass';\nimport { ApiEntryPoint, IApiEntryPointOptions } from './ApiEntryPoint';\nimport { ApiMethod, IApiMethodOptions } from './ApiMethod';\nimport { ApiModel } from './ApiModel';\nimport { ApiNamespace, IApiNamespaceOptions } from './ApiNamespace';\nimport { ApiPackage, IApiPackageOptions, IApiPackageJson } from './ApiPackage';\nimport { ApiInterface, IApiInterfaceOptions, IApiInterfaceJson } from './ApiInterface';\nimport { ApiPropertySignature, IApiPropertySignatureOptions } from './ApiPropertySignature';\nimport { ApiMethodSignature, IApiMethodSignatureOptions } from './ApiMethodSignature';\nimport { ApiProperty, IApiPropertyOptions } from './ApiProperty';\nimport { ApiEnumMember, IApiEnumMemberOptions } from './ApiEnumMember';\nimport { ApiEnum, IApiEnumOptions } from './ApiEnum';\nimport { IApiPropertyItemJson } from '../items/ApiPropertyItem';\nimport { ApiConstructor, IApiConstructorOptions } from './ApiConstructor';\nimport { ApiConstructSignature, IApiConstructSignatureOptions } from './ApiConstructSignature';\nimport { ApiFunction, IApiFunctionOptions } from './ApiFunction';\nimport { ApiCallSignature, IApiCallSignatureOptions } from './ApiCallSignature';\nimport { ApiIndexSignature, IApiIndexSignatureOptions } from './ApiIndexSignature';\nimport { ApiTypeAlias, IApiTypeAliasOptions, IApiTypeAliasJson } from './ApiTypeAlias';\nimport { ApiVariable, IApiVariableOptions, IApiVariableJson } from './ApiVariable';\nimport { IApiDeclaredItemJson } from '../items/ApiDeclaredItem';\nimport { DeserializerContext } from './DeserializerContext';\n\nexport class Deserializer {\n  public static deserialize(context: DeserializerContext, jsonObject: IApiItemJson): ApiItem {\n    const options: Partial<IApiItemOptions> = {};\n\n    switch (jsonObject.kind) {\n      case ApiItemKind.Class:\n        ApiClass.onDeserializeInto(options, context, jsonObject as IApiClassJson);\n        return new ApiClass(options as IApiClassOptions);\n      case ApiItemKind.CallSignature:\n        ApiCallSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiCallSignature(options as IApiCallSignatureOptions);\n      case ApiItemKind.Constructor:\n        ApiConstructor.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiConstructor(options as IApiConstructorOptions);\n      case ApiItemKind.ConstructSignature:\n        ApiConstructSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiConstructSignature(options as IApiConstructSignatureOptions);\n      case ApiItemKind.EntryPoint:\n        ApiEntryPoint.onDeserializeInto(options, context, jsonObject);\n        return new ApiEntryPoint(options as IApiEntryPointOptions);\n      case ApiItemKind.Enum:\n        ApiEnum.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiEnum(options as IApiEnumOptions);\n      case ApiItemKind.EnumMember:\n        ApiEnumMember.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiEnumMember(options as IApiEnumMemberOptions);\n      case ApiItemKind.Function:\n        ApiFunction.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiFunction(options as IApiFunctionOptions);\n      case ApiItemKind.IndexSignature:\n        ApiIndexSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiIndexSignature(options as IApiIndexSignatureOptions);\n      case ApiItemKind.Interface:\n        ApiInterface.onDeserializeInto(options, context, jsonObject as IApiInterfaceJson);\n        return new ApiInterface(options as IApiInterfaceOptions);\n      case ApiItemKind.Method:\n        ApiMethod.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiMethod(options as IApiMethodOptions);\n      case ApiItemKind.MethodSignature:\n        ApiMethodSignature.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiMethodSignature(options as IApiMethodSignatureOptions);\n      case ApiItemKind.Model:\n        return new ApiModel();\n      case ApiItemKind.Namespace:\n        ApiNamespace.onDeserializeInto(options, context, jsonObject as IApiDeclaredItemJson);\n        return new ApiNamespace(options as IApiNamespaceOptions);\n      case ApiItemKind.Package:\n        ApiPackage.onDeserializeInto(options, context, jsonObject as IApiPackageJson);\n        return new ApiPackage(options as IApiPackageOptions);\n      case ApiItemKind.Property:\n        ApiProperty.onDeserializeInto(options, context, jsonObject as IApiPropertyItemJson);\n        return new ApiProperty(options as IApiPropertyOptions);\n      case ApiItemKind.PropertySignature:\n        ApiPropertySignature.onDeserializeInto(options, context, jsonObject as IApiPropertyItemJson);\n        return new ApiPropertySignature(options as IApiPropertySignatureOptions);\n      case ApiItemKind.TypeAlias:\n        ApiTypeAlias.onDeserializeInto(options, context, jsonObject as IApiTypeAliasJson);\n        return new ApiTypeAlias(options as IApiTypeAliasOptions);\n      case ApiItemKind.Variable:\n        ApiVariable.onDeserializeInto(options, context, jsonObject as IApiVariableJson);\n        return new ApiVariable(options as IApiVariableOptions);\n      default:\n        throw new Error(`Failed to deserialize unsupported API item type ${JSON.stringify(jsonObject.kind)}`);\n    }\n  }\n}\n"]}

package/lib/model/DeserializerContext.d.ts

@@ -61,13 +61,19 @@ export declare enum ApiJsonSchemaVersion {
      * When loading older JSON files, the values defaults to `false`.
      */
     V_1009 = 1009,
+    /**
+     * Add a `fileUrlPath` field to `ApiDeclaredItem` to track the URL to a declared item's source file.
+     *
+     * When loading older JSON files, the value defaults to `undefined`.
+     */
+    V_1010 = 1010,
     /**
      * The current latest .api.json schema version.
      *
      * IMPORTANT: When incrementing this number, consider whether `OLDEST_SUPPORTED` or `OLDEST_FORWARDS_COMPATIBLE`
      * should be updated.
      */
-    LATEST = 1009,
+    LATEST = 1010,
     /**
      * The oldest .api.json schema version that is still supported for backwards compatibility.
      *

package/lib/model/DeserializerContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeserializerContext.d.ts","sourceRoot":"","sources":["../../src/model/DeserializerContext.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,oBAAY,oBAAoB;IAC9B;;OAEG;IACH,MAAM,OAAO;IAEb;;OAEG;IACH,MAAM,OAAO;IAEb;;OAEG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;;;;;OAQG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAS;IAEf;;;;;OAKG;IACH,gBAAgB,OAAS;IAEzB;;;;;;OAMG;IACH,0BAA0B,OAAS;CACpC;AAED,qBAAa,mBAAmB;IAC9B;;OAEG;IACH,SAAgB,eAAe,EAAE,MAAM,CAAC;IAExC;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,SAAgB,oBAAoB,EAAE,oBAAoB,CAAC;IAE3D;;OAEG;IACH,SAAgB,kBAAkB,EAAE,kBAAkB,CAAC;gBAEpC,OAAO,EAAE,mBAAmB;CAOhD"}
+{"version":3,"file":"DeserializerContext.d.ts","sourceRoot":"","sources":["../../src/model/DeserializerContext.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,oBAAY,oBAAoB;IAC9B;;OAEG;IACH,MAAM,OAAO;IAEb;;OAEG;IACH,MAAM,OAAO;IAEb;;OAEG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;;;;;OAQG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;OAIG;IACH,MAAM,OAAO;IAEb;;;;;OAKG;IACH,MAAM,OAAS;IAEf;;;;;OAKG;IACH,gBAAgB,OAAS;IAEzB;;;;;;OAMG;IACH,0BAA0B,OAAS;CACpC;AAED,qBAAa,mBAAmB;IAC9B;;OAEG;IACH,SAAgB,eAAe,EAAE,MAAM,CAAC;IAExC;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;OAEG;IACH,SAAgB,oBAAoB,EAAE,oBAAoB,CAAC;IAE3D;;OAEG;IACH,SAAgB,kBAAkB,EAAE,kBAAkB,CAAC;gBAEpC,OAAO,EAAE,mBAAmB;CAOhD"}

package/lib/model/DeserializerContext.js

@@ -66,13 +66,19 @@ var ApiJsonSchemaVersion;
      * When loading older JSON files, the values defaults to `false`.
      */
     ApiJsonSchemaVersion[ApiJsonSchemaVersion["V_1009"] = 1009] = "V_1009";
+    /**
+     * Add a `fileUrlPath` field to `ApiDeclaredItem` to track the URL to a declared item's source file.
+     *
+     * When loading older JSON files, the value defaults to `undefined`.
+     */
+    ApiJsonSchemaVersion[ApiJsonSchemaVersion["V_1010"] = 1010] = "V_1010";
     /**
      * The current latest .api.json schema version.
      *
      * IMPORTANT: When incrementing this number, consider whether `OLDEST_SUPPORTED` or `OLDEST_FORWARDS_COMPATIBLE`
      * should be updated.
      */
-    ApiJsonSchemaVersion[ApiJsonSchemaVersion["LATEST"] = 1009] = "LATEST";
+    ApiJsonSchemaVersion[ApiJsonSchemaVersion["LATEST"] = 1010] = "LATEST";
     /**
      * The oldest .api.json schema version that is still supported for backwards compatibility.
      *

package/lib/model/DeserializerContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeserializerContext.js","sourceRoot":"","sources":["../../src/model/DeserializerContext.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAI3D,IAAY,oBAgGX;AAhGD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,sEAAa,CAAA;IAEb;;OAEG;IACH,sEAAa,CAAA;IAEb;;OAEG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;;;;;OAQG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAe,CAAA;IAEf;;;;;OAKG;IACH,0FAAyB,CAAA;IAEzB;;;;;;OAMG;IACH,8GAAmC,CAAA;AACrC,CAAC,EAhGW,oBAAoB,GAApB,4BAAoB,KAApB,4BAAoB,QAgG/B;AAED,MAAa,mBAAmB;IA0B9B,YAAmB,OAA4B;QAC7C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;QACzD,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IACvD,CAAC;CACF;AAjCD,kDAiCC","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 { TSDocConfiguration } from '@microsoft/tsdoc';\n\nexport enum ApiJsonSchemaVersion {\n  /**\n   * The initial release.\n   */\n  V_1000 = 1000,\n\n  /**\n   * Add support for type parameters and type alias types.\n   */\n  V_1001 = 1001,\n\n  /**\n   * Remove `canonicalReference` field.  This field was for diagnostic purposes only and was never deserialized.\n   */\n  V_1002 = 1002,\n\n  /**\n   * Reintroduce the `canonicalReference` field using the experimental new TSDoc declaration reference notation.\n   *\n   * This is not a breaking change because this field is never deserialized; it is provided for informational\n   * purposes only.\n   */\n  V_1003 = 1003,\n\n  /**\n   * Add a `tsdocConfig` field that tracks the TSDoc configuration for parsing doc comments.\n   *\n   * This is not a breaking change because an older implementation will still work correctly.  The\n   * custom tags will be skipped over by the parser.\n   */\n  V_1004 = 1004,\n\n  /**\n   * Add an `isOptional` field to `Parameter` and `TypeParameter` to track whether a function parameter is optional.\n   *\n   * When loading older JSON files, the value defaults to `false`.\n   */\n  V_1005 = 1005,\n\n  /**\n   * Add an `isProtected` field to `ApiConstructor`, `ApiMethod`, and `ApiProperty` to\n   * track whether a class member has the `protected` modifier.\n   *\n   * Add an `isReadonly` field to `ApiProperty`, `ApiPropertySignature`, and `ApiVariable` to\n   * track whether the item is readonly.\n   *\n   * When loading older JSON files, the values default to `false`.\n   */\n  V_1006 = 1006,\n\n  /**\n   * Add `ApiItemContainerMixin.preserveMemberOrder` to support enums that preserve their original sort order.\n   *\n   * When loading older JSON files, the value default to `false`.\n   */\n  V_1007 = 1007,\n\n  /**\n   * Add an `initializerTokenRange` field to `ApiProperty` and `ApiVariable` to track the item's\n   * initializer.\n   *\n   * When loading older JSON files, this range is empty.\n   */\n  V_1008 = 1008,\n\n  /**\n   * Add an `isReadonly` field to `ApiIndexSignature` to track whether the item is readonly.\n   *\n   * When loading older JSON files, the values defaults to `false`.\n   */\n  V_1009 = 1009,\n\n  /**\n   * The current latest .api.json schema version.\n   *\n   * IMPORTANT: When incrementing this number, consider whether `OLDEST_SUPPORTED` or `OLDEST_FORWARDS_COMPATIBLE`\n   * should be updated.\n   */\n  LATEST = V_1009,\n\n  /**\n   * The oldest .api.json schema version that is still supported for backwards compatibility.\n   *\n   * This must be updated if you change to the file format and do not implement compatibility logic for\n   * deserializing the older representation.\n   */\n  OLDEST_SUPPORTED = V_1001,\n\n  /**\n   * Used to assign `IApiPackageMetadataJson.oldestForwardsCompatibleVersion`.\n   *\n   * This value must be \\<= `ApiJsonSchemaVersion.LATEST`.  It must be reset to the `LATEST` value\n   * if the older library would not be able to deserialize your new file format.  Adding a nonessential field\n   * is generally okay.  Removing, modifying, or reinterpreting existing fields is NOT safe.\n   */\n  OLDEST_FORWARDS_COMPATIBLE = V_1001\n}\n\nexport class DeserializerContext {\n  /**\n   * The path of the file being deserialized, which may be useful for diagnostic purposes.\n   */\n  public readonly apiJsonFilename: string;\n\n  /**\n   * Metadata from `IApiPackageMetadataJson.toolPackage`.\n   */\n  public readonly toolPackage: string;\n\n  /**\n   * Metadata from `IApiPackageMetadataJson.toolVersion`.\n   */\n  public readonly toolVersion: string;\n\n  /**\n   * The version of the schema being deserialized, as obtained from `IApiPackageMetadataJson.schemaVersion`.\n   */\n  public readonly versionToDeserialize: ApiJsonSchemaVersion;\n\n  /**\n   * The TSDoc configuration for the context.\n   */\n  public readonly tsdocConfiguration: TSDocConfiguration;\n\n  public constructor(options: DeserializerContext) {\n    this.apiJsonFilename = options.apiJsonFilename;\n    this.toolPackage = options.toolPackage;\n    this.toolVersion = options.toolVersion;\n    this.versionToDeserialize = options.versionToDeserialize;\n    this.tsdocConfiguration = options.tsdocConfiguration;\n  }\n}\n"]}
+{"version":3,"file":"DeserializerContext.js","sourceRoot":"","sources":["../../src/model/DeserializerContext.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAI3D,IAAY,oBAuGX;AAvGD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,sEAAa,CAAA;IAEb;;OAEG;IACH,sEAAa,CAAA;IAEb;;OAEG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;;;;;OAQG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;OAIG;IACH,sEAAa,CAAA;IAEb;;;;;OAKG;IACH,sEAAe,CAAA;IAEf;;;;;OAKG;IACH,0FAAyB,CAAA;IAEzB;;;;;;OAMG;IACH,8GAAmC,CAAA;AACrC,CAAC,EAvGW,oBAAoB,GAApB,4BAAoB,KAApB,4BAAoB,QAuG/B;AAED,MAAa,mBAAmB;IA0B9B,YAAmB,OAA4B;QAC7C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;QACzD,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IACvD,CAAC;CACF;AAjCD,kDAiCC","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 { TSDocConfiguration } from '@microsoft/tsdoc';\n\nexport enum ApiJsonSchemaVersion {\n  /**\n   * The initial release.\n   */\n  V_1000 = 1000,\n\n  /**\n   * Add support for type parameters and type alias types.\n   */\n  V_1001 = 1001,\n\n  /**\n   * Remove `canonicalReference` field.  This field was for diagnostic purposes only and was never deserialized.\n   */\n  V_1002 = 1002,\n\n  /**\n   * Reintroduce the `canonicalReference` field using the experimental new TSDoc declaration reference notation.\n   *\n   * This is not a breaking change because this field is never deserialized; it is provided for informational\n   * purposes only.\n   */\n  V_1003 = 1003,\n\n  /**\n   * Add a `tsdocConfig` field that tracks the TSDoc configuration for parsing doc comments.\n   *\n   * This is not a breaking change because an older implementation will still work correctly.  The\n   * custom tags will be skipped over by the parser.\n   */\n  V_1004 = 1004,\n\n  /**\n   * Add an `isOptional` field to `Parameter` and `TypeParameter` to track whether a function parameter is optional.\n   *\n   * When loading older JSON files, the value defaults to `false`.\n   */\n  V_1005 = 1005,\n\n  /**\n   * Add an `isProtected` field to `ApiConstructor`, `ApiMethod`, and `ApiProperty` to\n   * track whether a class member has the `protected` modifier.\n   *\n   * Add an `isReadonly` field to `ApiProperty`, `ApiPropertySignature`, and `ApiVariable` to\n   * track whether the item is readonly.\n   *\n   * When loading older JSON files, the values default to `false`.\n   */\n  V_1006 = 1006,\n\n  /**\n   * Add `ApiItemContainerMixin.preserveMemberOrder` to support enums that preserve their original sort order.\n   *\n   * When loading older JSON files, the value default to `false`.\n   */\n  V_1007 = 1007,\n\n  /**\n   * Add an `initializerTokenRange` field to `ApiProperty` and `ApiVariable` to track the item's\n   * initializer.\n   *\n   * When loading older JSON files, this range is empty.\n   */\n  V_1008 = 1008,\n\n  /**\n   * Add an `isReadonly` field to `ApiIndexSignature` to track whether the item is readonly.\n   *\n   * When loading older JSON files, the values defaults to `false`.\n   */\n  V_1009 = 1009,\n\n  /**\n   * Add a `fileUrlPath` field to `ApiDeclaredItem` to track the URL to a declared item's source file.\n   *\n   * When loading older JSON files, the value defaults to `undefined`.\n   */\n  V_1010 = 1010,\n\n  /**\n   * The current latest .api.json schema version.\n   *\n   * IMPORTANT: When incrementing this number, consider whether `OLDEST_SUPPORTED` or `OLDEST_FORWARDS_COMPATIBLE`\n   * should be updated.\n   */\n  LATEST = V_1010,\n\n  /**\n   * The oldest .api.json schema version that is still supported for backwards compatibility.\n   *\n   * This must be updated if you change to the file format and do not implement compatibility logic for\n   * deserializing the older representation.\n   */\n  OLDEST_SUPPORTED = V_1001,\n\n  /**\n   * Used to assign `IApiPackageMetadataJson.oldestForwardsCompatibleVersion`.\n   *\n   * This value must be \\<= `ApiJsonSchemaVersion.LATEST`.  It must be reset to the `LATEST` value\n   * if the older library would not be able to deserialize your new file format.  Adding a nonessential field\n   * is generally okay.  Removing, modifying, or reinterpreting existing fields is NOT safe.\n   */\n  OLDEST_FORWARDS_COMPATIBLE = V_1001\n}\n\nexport class DeserializerContext {\n  /**\n   * The path of the file being deserialized, which may be useful for diagnostic purposes.\n   */\n  public readonly apiJsonFilename: string;\n\n  /**\n   * Metadata from `IApiPackageMetadataJson.toolPackage`.\n   */\n  public readonly toolPackage: string;\n\n  /**\n   * Metadata from `IApiPackageMetadataJson.toolVersion`.\n   */\n  public readonly toolVersion: string;\n\n  /**\n   * The version of the schema being deserialized, as obtained from `IApiPackageMetadataJson.schemaVersion`.\n   */\n  public readonly versionToDeserialize: ApiJsonSchemaVersion;\n\n  /**\n   * The TSDoc configuration for the context.\n   */\n  public readonly tsdocConfiguration: TSDocConfiguration;\n\n  public constructor(options: DeserializerContext) {\n    this.apiJsonFilename = options.apiJsonFilename;\n    this.toolPackage = options.toolPackage;\n    this.toolVersion = options.toolVersion;\n    this.versionToDeserialize = options.versionToDeserialize;\n    this.tsdocConfiguration = options.tsdocConfiguration;\n  }\n}\n"]}

package/lib/model/SourceLocation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Constructor options for `SourceLocation`.
+ * @public
+ */
+export interface ISourceLocationOptions {
+    /**
+     * The project folder URL as defined by the `api-extractor.json` config `projectFolderUrl`
+     * setting.
+     */
+    projectFolderUrl?: string;
+    /**
+     * The file URL path relative to the `projectFolder` and `projectFolderURL` fields as
+     * defined in the `api-extractor.json` config.
+     */
+    fileUrlPath?: string;
+}
+/**
+ * The source location where a given API item is declared.
+ *
+ * @remarks
+ * The source location points to the `.ts` source file where the API item was originally
+   declared. However, in some cases, if source map resolution fails, it falls back to pointing
+   to the `.d.ts` file instead.
+ *
+ * @public
+ */
+export declare class SourceLocation {
+    private readonly _projectFolderUrl?;
+    private readonly _fileUrlPath?;
+    constructor(options: ISourceLocationOptions);
+    /**
+     * Returns the file URL to the given source location. Returns `undefined` if the file URL
+     * cannot be determined.
+     */
+    get fileUrl(): string | undefined;
+}
+//# sourceMappingURL=SourceLocation.d.ts.map

package/lib/model/SourceLocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceLocation.d.ts","sourceRoot":"","sources":["../../src/model/SourceLocation.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;gBAEpB,OAAO,EAAE,sBAAsB;IAKlD;;;OAGG;IACH,IAAW,OAAO,IAAI,MAAM,GAAG,SAAS,CAYvC;CACF"}

package/lib/model/SourceLocation.js

@@ -0,0 +1,39 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceLocation = void 0;
+const url_1 = require("url");
+/**
+ * The source location where a given API item is declared.
+ *
+ * @remarks
+ * The source location points to the `.ts` source file where the API item was originally
+   declared. However, in some cases, if source map resolution fails, it falls back to pointing
+   to the `.d.ts` file instead.
+ *
+ * @public
+ */
+class SourceLocation {
+    constructor(options) {
+        this._projectFolderUrl = options.projectFolderUrl;
+        this._fileUrlPath = options.fileUrlPath;
+    }
+    /**
+     * Returns the file URL to the given source location. Returns `undefined` if the file URL
+     * cannot be determined.
+     */
+    get fileUrl() {
+        if (this._projectFolderUrl === undefined || this._fileUrlPath === undefined) {
+            return undefined;
+        }
+        let projectFolderUrl = this._projectFolderUrl;
+        if (!projectFolderUrl.endsWith('/')) {
+            projectFolderUrl += '/';
+        }
+        const url = new url_1.URL(this._fileUrlPath, projectFolderUrl);
+        return url.href;
+    }
+}
+exports.SourceLocation = SourceLocation;
+//# sourceMappingURL=SourceLocation.js.map

package/lib/model/SourceLocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceLocation.js","sourceRoot":"","sources":["../../src/model/SourceLocation.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D,6BAA0B;AAoB1B;;;;;;;;;GASG;AACH,MAAa,cAAc;IAIzB,YAAmB,OAA+B;QAChD,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QAClD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,IAAW,OAAO;QAChB,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE;YAC3E,OAAO,SAAS,CAAC;SAClB;QAED,IAAI,gBAAgB,GAAW,IAAI,CAAC,iBAAiB,CAAC;QACtD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;YACnC,gBAAgB,IAAI,GAAG,CAAC;SACzB;QAED,MAAM,GAAG,GAAQ,IAAI,SAAG,CAAC,IAAI,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;QAC9D,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;CACF;AA1BD,wCA0BC","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 { URL } from 'url';\n\n/**\n * Constructor options for `SourceLocation`.\n * @public\n */\nexport interface ISourceLocationOptions {\n  /**\n   * The project folder URL as defined by the `api-extractor.json` config `projectFolderUrl`\n   * setting.\n   */\n  projectFolderUrl?: string;\n\n  /**\n   * The file URL path relative to the `projectFolder` and `projectFolderURL` fields as\n   * defined in the `api-extractor.json` config.\n   */\n  fileUrlPath?: string;\n}\n\n/**\n * The source location where a given API item is declared.\n *\n * @remarks\n * The source location points to the `.ts` source file where the API item was originally\n   declared. However, in some cases, if source map resolution fails, it falls back to pointing\n   to the `.d.ts` file instead.\n *\n * @public\n */\nexport class SourceLocation {\n  private readonly _projectFolderUrl?: string;\n  private readonly _fileUrlPath?: string;\n\n  public constructor(options: ISourceLocationOptions) {\n    this._projectFolderUrl = options.projectFolderUrl;\n    this._fileUrlPath = options.fileUrlPath;\n  }\n\n  /**\n   * Returns the file URL to the given source location. Returns `undefined` if the file URL\n   * cannot be determined.\n   */\n  public get fileUrl(): string | undefined {\n    if (this._projectFolderUrl === undefined || this._fileUrlPath === undefined) {\n      return undefined;\n    }\n\n    let projectFolderUrl: string = this._projectFolderUrl;\n    if (!projectFolderUrl.endsWith('/')) {\n      projectFolderUrl += '/';\n    }\n\n    const url: URL = new URL(this._fileUrlPath, projectFolderUrl);\n    return url.href;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/api-extractor-model",
-  "version": "7.24.4",
+  "version": "7.25.1",
   "description": "A helper library for loading and saving the .api.json files created by API Extractor",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   "dependencies": {
     "@microsoft/tsdoc": "0.14.1",
     "@microsoft/tsdoc-config": "~0.16.1",
-    "@rushstack/node-core-library": "3.53.1"
+    "@rushstack/node-core-library": "3.53.2"
   },
   "devDependencies": {
     "@rushstack/eslint-config": "3.1.1",