[api-extractor] Add an experimental new ApiItem.canonicalReference property

apps/api-extractor-model/src/items/ApiItem.ts

@@ -1,10 +1,12 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { Constructor, PropertiesOf } from '../mixins/Mixin';
 import { ApiPackage } from '../model/ApiPackage';
 import { ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
 import { DeserializerContext } from '../model/DeserializerContext';
+import { InternalError } from '@microsoft/node-core-library';
 
 /**
  * The type returned by the {@link ApiItem.kind} property, which can be used to easily distinguish subclasses of
@@ -44,14 +46,13 @@ export interface IApiItemOptions {
 
 export interface IApiItemJson {
   kind: ApiItemKind;
+  canonicalReference: string;
 }
 
-/**
- * PRIVATE
- * Allows ApiItemContainerMixin to assign the parent.
- */
+// PRIVATE - Allows ApiItemContainerMixin to assign the parent.
+//
 // tslint:disable-next-line:variable-name
-export const ApiItem_parent: unique symbol = Symbol('ApiItem._parent');
+export const ApiItem_setParent: unique symbol = Symbol('ApiItem._setParent');
 
 /**
  * The abstract base class for all members of an `ApiModel` object.
@@ -62,7 +63,8 @@ export const ApiItem_parent: unique symbol = Symbol('ApiItem._parent');
  * @public
  */
 export class ApiItem {
-  public [ApiItem_parent]: ApiItem | undefined;
+  private _canonicalReference: DeclarationReference | undefined;
+  private _parent: ApiItem | undefined;
 
   public static deserialize(jsonObject: IApiItemJson, context: DeserializerContext): ApiItem {
     // The Deserializer class is coupled with a ton of other classes, so  we delay loading it
@@ -84,6 +86,7 @@ export class ApiItem {
   /** @virtual */
   public serializeInto(jsonObject: Partial<IApiItemJson>): void {
     jsonObject.kind = this.kind;
+    jsonObject.canonicalReference = this.canonicalReference.toString();
   }
 
   /**
@@ -94,6 +97,22 @@ export class ApiItem {
     throw new Error('ApiItem.kind was not implemented by the child class');
   }
 
+  /**
+   * Warning: This API is used internally by API extractor but is not yet ready for general usage.
+   *
+   * @remarks
+   *
+   * Returns a `DeclarationReference` object using the experimental new declaration reference notation.
+   *
+   * @beta
+   */
+  public get canonicalReference(): DeclarationReference {
+    if (!this._canonicalReference) {
+      this._canonicalReference = this.buildCanonicalReference();
+    }
+    return this._canonicalReference;
+  }
+
   /**
    * Returns a string key that can be used to efficiently retrieve an `ApiItem` from an `ApiItemContainerMixin`.
    * The key is unique within the container.  Its format is undocumented and may change at any time.
@@ -105,7 +124,7 @@ export class ApiItem {
    * @virtual
    */
   public get containerKey(): string {
-    throw new Error('ApiItem.containerKey was not implemented by the child class');
+    throw new InternalError('ApiItem.containerKey was not implemented by the child class');
   }
 
   /**
@@ -135,7 +154,7 @@ export class ApiItem {
    * @virtual
    */
   public get parent(): ApiItem | undefined {
-    return this[ApiItem_parent];
+    return this._parent;
   }
 
   /**
@@ -215,6 +234,27 @@ export class ApiItem {
   public getSortKey(): string {
     return this.containerKey;
   }
+
+  /**
+   * PRIVATE
+   *
+   * @privateRemarks
+   * Allows ApiItemContainerMixin to assign the parent.
+   *
+   * @internal
+   */
+  public [ApiItem_setParent](parent: ApiItem | undefined): void {
+    this._parent = parent;
+    this._canonicalReference = undefined;
+  }
+
+  /**
+   * Builds the cached object used by the `canonicalReference` property.
+   * @virtual
+   */
+  protected buildCanonicalReference(): DeclarationReference {
+    throw new InternalError('ApiItem.canonicalReference was not implemented by the child class');
+  }
 }
 
 /**

apps/api-extractor-model/src/mixins/ApiItemContainerMixin.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.s
 
-import { ApiItem, ApiItem_parent, IApiItemJson, IApiItemOptions, IApiItemConstructor } from '../items/ApiItem';
+import { ApiItem, ApiItem_setParent, IApiItemJson, IApiItemOptions, IApiItemConstructor } from '../items/ApiItem';
 import { ApiNameMixin } from './ApiNameMixin';
 import { DeserializerContext } from '../model/DeserializerContext';
 
@@ -135,7 +135,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
         throw new Error('Another member has already been added with the same name and containerKey');
       }
 
-      const existingParent: ApiItem | undefined = member[ApiItem_parent];
+      const existingParent: ApiItem | undefined = member.parent;
       if (existingParent !== undefined) {
         throw new Error(`This item has already been added to another container: "${existingParent.displayName}"`);
       }
@@ -145,7 +145,7 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(ba
       this[_membersSorted] = false;
       this[_membersByContainerKey].set(member.containerKey, member);
 
-      member[ApiItem_parent] = this;
+      member[ApiItem_setParent](this);
     }
 
     public tryGetMemberByKey(containerKey: string): ApiItem | undefined {

apps/api-extractor-model/src/mixins/ApiNameMixin.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.s
 
+import { StringChecks } from '@microsoft/tsdoc/lib/parser/StringChecks';
 import { ApiItem, IApiItemJson, IApiItemConstructor, IApiItemOptions } from '../items/ApiItem';
 import { DeserializerContext } from '../model/DeserializerContext';
 
@@ -46,6 +47,9 @@ export interface ApiNameMixin extends ApiItem {
 
   /** @override */
   serializeInto(jsonObject: Partial<IApiItemJson>): void;
+
+  /** @internal */
+  _getCanonicalReferenceName(): string;
 }
 
 /**
@@ -94,6 +98,17 @@ export function ApiNameMixin<TBaseClass extends IApiItemConstructor>(baseClass:
 
       jsonObject.name = this.name;
     }
+
+    /** @internal */
+    public _getCanonicalReferenceName(): string {
+      // TODO: This is a temporary workaround for a limitation of the experimental DeclarationReference API.
+      // We will remove this when the final implementation is in place.
+      if (StringChecks.explainIfInvalidUnquotedIdentifier(this.name)) {
+        return JSON.stringify(this.name);
+      } else {
+        return this.name;
+      }
+    }
   }
 
   return MixedClass;

apps/api-extractor-model/src/model/ApiCallSignature.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { IApiDeclaredItemOptions, ApiDeclaredItem } from '../items/ApiDeclaredItem';
 import { IApiParameterListMixinOptions, ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
@@ -69,4 +70,15 @@ export class ApiCallSignature extends ApiTypeParameterListMixin(ApiParameterList
   public get containerKey(): string {
     return ApiCallSignature.getContainerKey(this.overloadIndex);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    const parent: DeclarationReference = this.parent
+      ? this.parent.canonicalReference
+      // .withMeaning() requires some kind of component
+      : DeclarationReference.empty().addNavigationStep(Navigation.Members, '(parent)');
+    return parent
+      .withMeaning(Meaning.Signature)
+      .withOverloadIndex(this.overloadIndex);
+  }
 }

apps/api-extractor-model/src/model/ApiClass.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { ApiDeclaredItem, IApiDeclaredItemOptions, IApiDeclaredItemJson } from '../items/ApiDeclaredItem';
 import { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin';
@@ -116,4 +117,11 @@ export class ApiClass extends ApiItemContainerMixin(ApiNameMixin(ApiTypeParamete
 
     jsonObject.implementsTokenRanges = this.implementsTypes.map(x => x.excerpt.tokenRange);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    return (this.parent ? this.parent.canonicalReference : DeclarationReference.empty())
+      .addNavigationStep(Navigation.Exports, this.name)
+      .withMeaning(Meaning.Class);
+  }
 }

apps/api-extractor-model/src/model/ApiConstructSignature.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { IApiDeclaredItemOptions, ApiDeclaredItem } from '../items/ApiDeclaredItem';
 import { IApiParameterListMixinOptions, ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
@@ -82,4 +83,15 @@ export class ApiConstructSignature extends ApiTypeParameterListMixin(ApiParamete
   public get containerKey(): string {
     return ApiConstructSignature.getContainerKey(this.overloadIndex);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    const parent: DeclarationReference = this.parent
+      ? this.parent.canonicalReference
+      // .withMeaning() requires some kind of component
+      : DeclarationReference.empty().addNavigationStep(Navigation.Members, '(parent)');
+    return parent
+      .withMeaning(Meaning.Signature)
+      .withOverloadIndex(this.overloadIndex);
+  }
 }

apps/api-extractor-model/src/model/ApiConstructor.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { IApiDeclaredItemOptions, ApiDeclaredItem } from '../items/ApiDeclaredItem';
 import { IApiParameterListMixinOptions, ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
@@ -62,4 +63,15 @@ export class ApiConstructor extends ApiParameterListMixin(ApiReleaseTagMixin(Api
   public get containerKey(): string {
     return ApiConstructor.getContainerKey(this.overloadIndex);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    const parent: DeclarationReference = this.parent
+      ? this.parent.canonicalReference
+      // .withMeaning() requires some kind of component
+      : DeclarationReference.empty().addNavigationStep(Navigation.Members, '(parent)');
+    return parent
+      .withMeaning(Meaning.Constructor)
+      .withOverloadIndex(this.overloadIndex);
+  }
 }

apps/api-extractor-model/src/model/ApiEntryPoint.ts

@@ -1,9 +1,11 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, ModuleSource } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItem, ApiItemKind } from '../items/ApiItem';
 import { ApiItemContainerMixin, IApiItemContainerMixinOptions } from '../mixins/ApiItemContainerMixin';
 import { IApiNameMixinOptions, ApiNameMixin } from '../mixins/ApiNameMixin';
+import { ApiPackage } from './ApiPackage';
 
 /**
  * Constructor options for {@link ApiEntryPoint}.
@@ -51,4 +53,23 @@ export class ApiEntryPoint extends ApiItemContainerMixin(ApiNameMixin(ApiItem))
     // No prefix needed, because ApiEntryPoint is the only possible member of an ApiPackage
     return this.name;
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    let modulePath: string = '';
+
+    if (this.parent instanceof ApiPackage) {
+      modulePath = this.parent.name;
+    }
+
+    if (this.name) {
+      modulePath += this.name;
+    }
+
+    if (modulePath) {
+      return new DeclarationReference(new ModuleSource(modulePath));
+    }
+
+    return DeclarationReference.empty();
+  }
 }

apps/api-extractor-model/src/model/ApiEnum.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { ApiDeclaredItem, IApiDeclaredItemOptions } from '../items/ApiDeclaredItem';
 import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiReleaseTagMixin';
@@ -71,4 +72,11 @@ export class ApiEnum extends ApiItemContainerMixin(ApiNameMixin(ApiReleaseTagMix
     }
     super.addMember(member);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    return (this.parent ? this.parent.canonicalReference : DeclarationReference.empty())
+      .addNavigationStep(Navigation.Exports, this._getCanonicalReferenceName())
+      .withMeaning(Meaning.Enum);
+  }
 }

apps/api-extractor-model/src/model/ApiEnumMember.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { ApiDeclaredItem, IApiDeclaredItemOptions, IApiDeclaredItemJson } from '../items/ApiDeclaredItem';
 import { ApiReleaseTagMixin, IApiReleaseTagMixinOptions } from '../mixins/ApiReleaseTagMixin';
@@ -86,4 +87,11 @@ export class ApiEnumMember extends ApiNameMixin(ApiReleaseTagMixin(ApiDeclaredIt
 
     jsonObject.initializerTokenRange = this.initializerExcerpt.tokenRange;
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    return (this.parent ? this.parent.canonicalReference : DeclarationReference.empty())
+      .addNavigationStep(Navigation.Exports, this._getCanonicalReferenceName())
+      .withMeaning(Meaning.EnumMember);
+  }
 }

apps/api-extractor-model/src/model/ApiFunction.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { IApiDeclaredItemOptions, ApiDeclaredItem } from '../items/ApiDeclaredItem';
 import { IApiParameterListMixinOptions, ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
@@ -63,4 +64,12 @@ export class ApiFunction extends ApiNameMixin(ApiTypeParameterListMixin(ApiParam
   public get containerKey(): string {
     return ApiFunction.getContainerKey(this.name, this.overloadIndex);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    return (this.parent ? this.parent.canonicalReference : DeclarationReference.empty())
+      .addNavigationStep(Navigation.Exports, this._getCanonicalReferenceName())
+      .withMeaning(Meaning.Function)
+      .withOverloadIndex(this.overloadIndex);
+  }
 }

apps/api-extractor-model/src/model/ApiIndexSignature.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
+import { DeclarationReference, Meaning, Navigation } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
 import { ApiItemKind } from '../items/ApiItem';
 import { IApiDeclaredItemOptions, ApiDeclaredItem } from '../items/ApiDeclaredItem';
 import { IApiParameterListMixinOptions, ApiParameterListMixin } from '../mixins/ApiParameterListMixin';
@@ -59,4 +60,15 @@ export class ApiIndexSignature extends ApiParameterListMixin(ApiReleaseTagMixin(
   public get containerKey(): string {
     return ApiIndexSignature.getContainerKey(this.overloadIndex);
   }
+
+  /** @beta @override */
+  public buildCanonicalReference(): DeclarationReference {
+    const parent: DeclarationReference = this.parent
+      ? this.parent.canonicalReference
+      // .withMeaning() requires some kind of component
+      : DeclarationReference.empty().addNavigationStep(Navigation.Members, '(parent)');
+    return parent
+      .withMeaning(Meaning.Signature)
+      .withOverloadIndex(this.overloadIndex);
+  }
 }