Merge branch 'main' into docs/type-param-links

discordjs · Oct 18, 2024 · 885bc51 · 885bc51
2 parents cea0578 + 93b84ae
commit 885bc51
Show file tree

Hide file tree

Showing 9 changed files with 121 additions and 123 deletions.
diff --git a/.github/.kodiak.toml b/.github/.kodiak.toml
@@ -2,7 +2,7 @@ version = 1
 
 [merge]
 require_automerge_label = false
-blocking_labels = ['blocked', 'in review']
+blocking_labels = ['blocked', 'in review', 'semver:major']
 method = 'squash'
 
 [merge.message]

diff --git a/packages/api-extractor-model/src/mixins/ApiItemContainerMixin.ts b/packages/api-extractor-model/src/mixins/ApiItemContainerMixin.ts
@@ -2,7 +2,15 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { TSDocConfiguration } from '@microsoft/tsdoc';
+import {
+	type DocNode,
+	type DocPlainText,
+	DocDeclarationReference,
+	DocNodeKind,
+	TSDocConfiguration,
+	DocMemberReference,
+	DocMemberIdentifier,
+} from '@microsoft/tsdoc';
 import type { DeclarationReference } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference.js';
 import { InternalError } from '@rushstack/node-core-library';
 import type { IExcerptToken, IExcerptTokenRange } from '../index.js';
@@ -42,6 +50,11 @@ export interface IApiItemContainerJson extends IApiItemJson {
 	preserveMemberOrder?: boolean;
 }
 
+interface Mixin {
+	declarationReference: DocDeclarationReference;
+	typeParameters: IExcerptTokenRange[];
+}
+
 interface ExcerptTokenRangeInDeclaredItem {
 	item: ApiDeclaredItem;
 	range: IExcerptTokenRange;
@@ -393,14 +406,52 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 					}
 				}
 
+				const findPlainTextNode = (node: DocNode): DocPlainText | undefined => {
+					switch (node.kind) {
+						case DocNodeKind.PlainText:
+							return node as DocPlainText;
+						default:
+							for (const child of node.getChildNodes()) {
+								const result = findPlainTextNode(child);
+								if (result) return result;
+							}
+					}
+
+					return undefined;
+				};
+
 				// Interfaces can extend multiple interfaces, so iterate through all of them.
+				// Also Classes can have multiple mixins
 				const extendedItems: IMappedTypeParameters[] = [];
-				let extendsTypes: readonly HeritageType[] | undefined;
+				let extendsTypes: readonly (HeritageType | Mixin)[] | undefined;
 
 				switch (next.item.kind) {
 					case ApiItemKind.Class: {
 						const apiClass: ApiClass = next.item as ApiClass;
-						extendsTypes = apiClass.extendsType ? [apiClass.extendsType] : [];
+						const configuration = apiClass.tsdocComment?.configuration ?? new TSDocConfiguration();
+						const mixins =
+							apiClass.tsdocComment?.customBlocks
+								.filter(
+									(block) => block.blockTag.tagName === '@mixes', // &&
+									// block.getChildNodes().some((node) => node.kind === DocNodeKind.PlainText),
+								)
+								.map(findPlainTextNode)
+								.filter((block) => block !== undefined)
+								.map((block) => ({
+									declarationReference: new DocDeclarationReference({
+										configuration,
+										memberReferences: block.text.split('.').map(
+											(part, index) =>
+												new DocMemberReference({
+													configuration,
+													hasDot: index > 0,
+													memberIdentifier: new DocMemberIdentifier({ configuration, identifier: part }),
+												}),
+										),
+									}),
+									typeParameters: [] as IExcerptTokenRange[],
+								})) ?? [];
+						extendsTypes = apiClass.extendsType ? [apiClass.extendsType, ...mixins] : [...mixins];
 						break;
 					}
 
@@ -425,30 +476,38 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 				}
 
 				for (const extendsType of extendsTypes) {
-					// We want to find the reference token associated with the actual inherited declaration.
-					// In every case we support, this is the first reference token. For example:
-					//
-					// ```
-					// export class A extends B {}
-					//                        ^
-					// export class A extends B<C> {}
-					//                        ^
-					// export class A extends B.C {}
-					//                        ^^^
-					// ```
-					const firstReferenceToken: ExcerptToken | undefined = extendsType.excerpt.spannedTokens.find(
-						(token: ExcerptToken) => {
-							return token.kind === ExcerptTokenKind.Reference && token.canonicalReference;
-						},
-					);
+					let canonicalReference: DeclarationReference | DocDeclarationReference;
+					if ('excerpt' in extendsType) {
+						// We want to find the reference token associated with the actual inherited declaration.
+						// In every case we support, this is the first reference token. For example:
+						//
+						// ```
+						// export class A extends B {}
+						//                        ^
+						// export class A extends B<C> {}
+						//                        ^
+						// export class A extends B.C {}
+						//                        ^^^
+						// ```
+						const firstReferenceToken: ExcerptToken | undefined = extendsType.excerpt.spannedTokens.find(
+							(token: ExcerptToken) => {
+								return token.kind === ExcerptTokenKind.Reference && token.canonicalReference;
+							},
+						);
+
+						if (!firstReferenceToken) {
+							messages.push({
+								messageId: FindApiItemsMessageId.ExtendsClauseMissingReference,
+								text: `Unable to analyze extends clause ${extendsType.excerpt.text} of API item ${next.item.displayName} because no canonical reference was found`,
+							});
+							maybeIncompleteResult = true;
+							continue;
+						}
 
-					if (!firstReferenceToken) {
-						messages.push({
-							messageId: FindApiItemsMessageId.ExtendsClauseMissingReference,
-							text: `Unable to analyze extends clause ${extendsType.excerpt.text} of API item ${next.item.displayName} because no canonical reference was found`,
-						});
-						maybeIncompleteResult = true;
-						continue;
+						canonicalReference = firstReferenceToken.canonicalReference!;
+					} else {
+						// extendsType is a Mixin
+						canonicalReference = extendsType.declarationReference;
 					}
 
 					const apiModel: ApiModel | undefined = this.getAssociatedModel();
@@ -461,10 +520,9 @@ export function ApiItemContainerMixin<TBaseClass extends IApiItemConstructor>(
 						continue;
 					}
 
-					const canonicalReference: DeclarationReference = firstReferenceToken.canonicalReference!;
 					const apiItemResult: IResolveDeclarationReferenceResult = apiModel.resolveDeclarationReference(
 						canonicalReference,
-						undefined,
+						this,
 					);
 
 					const apiItem: ApiItem | undefined = apiItemResult.resolvedApiItem;

diff --git a/packages/api-extractor-model/src/model/ApiPackage.ts b/packages/api-extractor-model/src/model/ApiPackage.ts
@@ -294,7 +294,7 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
 
 		const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
 
-		if (versionToDeserialize >= ApiJsonSchemaVersion.V_1004 && 'tsdocConfiguration' in jsonObject) {
+		if (versionToDeserialize >= ApiJsonSchemaVersion.V_1004 && 'tsdocConfig' in jsonObject.metadata) {
 			const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadFromObject(jsonObject.metadata.tsdocConfig);
 			if (tsdocConfigFile.hasErrors) {
 				throw new Error(`Error loading ${apiJsonFilename}:\n` + tsdocConfigFile.getErrorSummary());
@@ -421,6 +421,8 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
 				for (const key of Object.keys(item)) {
 					if (key === 'dependencies') {
 						result[MinifyJSONMapping.dependencies] = item.dependencies;
+					} else if (key === 'tsdocConfig') {
+						result[MinifyJSONMapping.tsdocConfig] = item.tsdocConfig;
 					} else
 						result[MinifyJSONMapping[key as keyof typeof MinifyJSONMapping]] =
 							typeof item[key] === 'object' ? mapper(item[key]) : item[key];
@@ -441,6 +443,8 @@ export class ApiPackage extends ApiItemContainerMixin(ApiNameMixin(ApiDocumented
 				for (const key of Object.keys(item)) {
 					if (key === MinifyJSONMapping.dependencies) {
 						result.dependencies = item[MinifyJSONMapping.dependencies];
+					} else if (key === MinifyJSONMapping.tsdocConfig) {
+						result.tsdocConfig = item[MinifyJSONMapping.tsdocConfig];
 					} else
 						result[
 							Object.keys(MinifyJSONMapping).find(

diff --git a/packages/api-extractor/extends/tsdoc-base.json b/packages/api-extractor/extends/tsdoc-base.json
@@ -32,6 +32,10 @@
 		{
 			"tagName": "@preapproved",
 			"syntaxKind": "modifier"
+		},
+		{
+			"tagName": "@mixes",
+			"syntaxKind": "block"
 		}
 	],
 

diff --git a/packages/builders/src/interactions/commands/chatInput/ChatInputCommand.ts b/packages/builders/src/interactions/commands/chatInput/ChatInputCommand.ts
@@ -9,6 +9,11 @@ import { SharedChatInputCommandSubcommands } from './mixins/SharedSubcommands.js
 
 /**
  * A builder that creates API-compatible JSON data for chat input commands.
+ *
+ * @mixes CommandBuilder<RESTPostAPIChatInputApplicationCommandsJSONBody>
+ * @mixes SharedChatInputCommandOptions
+ * @mixes SharedNameAndDescription
+ * @mixes SharedChatInputCommandSubcommands
  */
 export class ChatInputCommandBuilder extends Mixin(
 	CommandBuilder<RESTPostAPIChatInputApplicationCommandsJSONBody>,

diff --git a/packages/builders/tsdoc.json b/packages/builders/tsdoc.json
@@ -0,0 +1,9 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+	"tagDefinitions": [
+		{
+			"tagName": "@mixes",
+			"syntaxKind": "block"
+		}
+	]
+}
diff --git a/packages/discord.js/src/client/Client.js b/packages/discord.js/src/client/Client.js
@@ -105,14 +105,6 @@ class Client extends BaseClient {
      */
     this.actions = new ActionsManager(this);
 
-    /**
-     * Shard helpers for the client (only if the process was spawned from a {@link ShardingManager})
-     * @type {?ShardClientUtil}
-     */
-    this.shard = process.env.SHARDING_MANAGER
-      ? ShardClientUtil.singleton(this, process.env.SHARDING_MANAGER_MODE)
-      : null;
-
     /**
      * The user manager of this client
      * @type {UserManager}
@@ -170,6 +162,14 @@ class Client extends BaseClient {
      */
     this.ws = new WebSocketManager(wsOptions);
 
+    /**
+     * Shard helpers for the client (only if the process was spawned from a {@link ShardingManager})
+     * @type {?ShardClientUtil}
+     */
+    this.shard = process.env.SHARDING_MANAGER
+      ? ShardClientUtil.singleton(this, process.env.SHARDING_MANAGER_MODE)
+      : null;
+
     /**
      * The voice manager of the client
      * @type {ClientVoiceManager}
@@ -414,12 +414,11 @@ class Client extends BaseClient {
 
   /**
    * The average ping of all WebSocketShards
-   * @type {number}
+   * @type {?number}
    * @readonly
    */
   get ping() {
-    const sum = this.pings.reduce((a, b) => a + b, 0);
-    return sum / this.pings.size;
+    return this.pings.size ? this.pings.reduce((a, b) => a + b, 0) / this.pings.size : null;
   }
 
   /**