refactor(docs): use single docs command with meili multi search

Author: almostSouji

src/functions/autocomplete/docsAutoComplete.ts

@@ -1,16 +1,31 @@
-import process from 'node:process';
+import process, { versions } from 'node:process';
 import type {
 	APIApplicationCommandInteractionDataOption,
 	APIApplicationCommandInteractionDataStringOption,
-	APIApplicationCommandInteractionDataSubcommandOption,
 } from 'discord-api-types/v10';
 import { ApplicationCommandOptionType, InteractionResponseType } from 'discord-api-types/v10';
 import type { Response } from 'polka';
-import { AUTOCOMPLETE_MAX_ITEMS } from '../../util/constants.js';
-import { getDjsVersions } from '../../util/djsdocs.js';
-import { logger } from '../../util/logger.js';
-import { queryDocs } from '../docs.js';
+import { AUTOCOMPLETE_MAX_ITEMS, DJS_QUERY_SEPARATOR } from '../../util/constants.js';
+import { getCurrentMainPackageVersion, getDjsVersions } from '../../util/djsdocs.js';
+import { truncate } from '../../util/truncate.js';
 
+/**
+ * Transform dotted versions into meili search compatible version keys, stripping unwanted characters
+ * (^x.y.z -\> x-y-z)
+ *
+ * @param version - Dotted version string
+ * @returns The meili search compatible version
+ */
+export function meiliVersion(version: string) {
+	return version.replaceAll('^', '').split('.').join('-');
+}
+
+/**
+ * Dissect a discord.js documentation path into its parts
+ *
+ * @param path - The path to parse
+ * @returns The path parts
+ */
 export function parseDocsPath(path: string) {
 	// /0   /1       /2       /3   /4
 	// /docs/packages/builders/main/EmbedBuilder:Class
@@ -36,32 +51,173 @@ export function parseDocsPath(path: string) {
 	};
 }
 
-function convertToDottedName(dashed: string) {
-	return dashed.replaceAll('-', '.');
+const BASE_SEARCH = 'https://search.discordjs.dev/';
+
+export const djsDocsDependencies = new Map<string, any>();
+
+/**
+ * Fetch the discord.js dependencies for a specific verison
+ * Note: Tries to resolve from cache before hitting the API
+ * Note: Information is resolved from the package.json file in the respective package root
+ *
+ * @param version - The version to retrieve dependencies for
+ * @returns The package dependencies
+ */
+export async function fetchDjsDependencies(version: string) {
+	const hit = djsDocsDependencies.get(version);
+	const dependencies =
+		hit ??
+		(await fetch(`${process.env.DJS_BLOB_STORAGE_BASE}/rewrite/discord.js/${version}.dependencies.api.json`).then(
+			async (res) => res.json(),
+		));
+
+	if (!hit) {
+		djsDocsDependencies.set(version, dependencies);
+	}
+
+	return dependencies;
+}
+
+/**
+ * Fetch the version of a dependency based on a main package version and dependency package name
+ *
+ * @param mainPackageVersion - The main package version to use for dependencies
+ * @param _package - The package to fetch the version for
+ * @returns The version of the dependency package
+ */
+export async function fetchDependencyVersion(mainPackageVersion: string, _package: string) {
+	const dependencies = await fetchDjsDependencies(mainPackageVersion);
+
+	const version = Object.entries(dependencies).find(([key, value]) => {
+		if (typeof value !== 'string') return false;
+
+		const parts = key.split('/');
+		const packageName = parts[1];
+		return packageName === _package;
+	})?.[1] as string | undefined;
+
+	return version?.replaceAll('^', '');
+}
+
+/**
+ * Build Meili search queries for the base package and all its dependencies as defined in the documentation
+ *
+ * @param query - The query term to use across packages
+ * @param mainPackageVersion - The version to use across packages
+ * @returns Meili query objects for the provided parameters
+ */
+export async function buildMeiliQueries(query: string, mainPackageVersion: string) {
+	const dependencies = await fetchDjsDependencies(mainPackageVersion);
+	const baseQuery = {
+		// eslint-disable-next-line id-length -- Meili search denotes the query with a "q" key
+		q: query,
+		limit: 25,
+		attributesToSearchOn: ['name'],
+		sort: ['type:asc'],
+	};
+
+	const queries = [
+		{
+			indexUid: `discord-js-${meiliVersion(mainPackageVersion)}`,
+			...baseQuery,
+		},
+	];
+
+	for (const [dependencyPackageIdentifier, dependencyVersion] of Object.entries(dependencies)) {
+		if (typeof dependencyVersion !== 'string') continue;
+
+		const packageName = dependencyPackageIdentifier.split('/')[1];
+		const parts = [...packageName.split('.'), meiliVersion(dependencyVersion)];
+		const indexUid = parts.join('-');
+
+		queries.push({
+			indexUid,
+			...baseQuery,
+		});
+	}
+
+	return queries;
+}
+
+/**
+ * Remove unwanted characters from autocomplete text
+ *
+ * @param text - The input to sanitize
+ * @returns The sanitized text
+ */
+function sanitizeText(text: string) {
+	return text.replaceAll('*', '');
+}
+
+/**
+ * Search the discord.js documentation using meilisearch multi package queries
+ *
+ * @param query - The query term to use across packages
+ * @param version - The main package version to use
+ * @returns Documentation results for the provided parameters
+ */
+export async function djsMeiliSearch(query: string, version: string) {
+	const searchResult = await fetch(`${BASE_SEARCH}multi-search`, {
+		method: 'post',
+		body: JSON.stringify({
+			queries: await buildMeiliQueries(query, version),
+		}),
+		headers: {
+			'Content-Type': 'application/json',
+			Authorization: `Bearer ${process.env.DJS_DOCS_BEARER!}`,
+		},
+	});
+
+	const docsResult = (await searchResult.json()) as any;
+	const hits = docsResult.results.flatMap((res: any) => res.hits).sort((one: any, other: any) => one.id - other.id);
+
+	return {
+		...docsResult,
+		hits: hits.map((hit: any) => {
+			const parsed = parseDocsPath(hit.path);
+			const isMember = ['Property', 'Method', 'Event', 'PropertySignature', 'EnumMember'].includes(hit.kind);
+			const parts = [parsed.package, parsed.item.toLocaleLowerCase(), parsed.kind];
+
+			if (isMember && parsed.method) {
+				parts.push(parsed.method);
+			}
+
+			return {
+				...hit,
+				autoCompleteName: truncate(`${hit.name}${hit.summary ? ` - ${sanitizeText(hit.summary)}` : ''}`, 100, ' '),
+				autoCompleteValue: parts.join(DJS_QUERY_SEPARATOR),
+				isMember,
+			};
+		}),
+	};
 }
 
+/**
+ * Handle the command reponse for the discord.js docs command autocompletion
+ *
+ * @param res - Reponse to write
+ * @param options - Command options
+ * @returns The written response
+ */
 export async function djsAutoComplete(
 	res: Response,
 	options: APIApplicationCommandInteractionDataOption[],
 ): Promise<Response> {
-	const [option] = options;
-	const interactionSubcommandData = option as APIApplicationCommandInteractionDataSubcommandOption;
-	const queryOptionData = interactionSubcommandData.options?.find((option) => option.name === 'query') as
+	res.setHeader('Content-Type', 'application/json');
+	const defaultVersion = getCurrentMainPackageVersion();
+
+	const queryOptionData = options.find((option) => option.name === 'query') as
 		| APIApplicationCommandInteractionDataStringOption
 		| undefined;
-	const versionOptionData = interactionSubcommandData.options?.find((option) => option.name === 'version') as
+	const versionOptionData = options.find((option) => option.name === 'version') as
 		| APIApplicationCommandInteractionDataStringOption
 		| undefined;
 
-	const versions = getDjsVersions();
-	res.setHeader('Content-Type', 'application/json');
-
 	if (!queryOptionData) {
 		throw new Error('expected query option, none received');
 	}
 
-	const version = versionOptionData?.value ?? versions.versions.get(convertToDottedName(option.name))?.at(1) ?? 'main';
-	const docsResult = await queryDocs(queryOptionData.value, option.name, version);
+	const docsResult = await djsMeiliSearch(queryOptionData.value, versionOptionData?.value ?? defaultVersion);
 	const choices = [];
 
 	for (const hit of docsResult.hits) {
@@ -95,43 +251,37 @@ type DocsAutoCompleteData = {
 	version: string;
 };
 
-export function resolveOptionsToDocsAutoComplete(
+/**
+ * Resolve the required options (with appropriate fallbacks) from the received command options
+ *
+ * @param options - The options to resolve
+ * @returns Resolved options
+ */
+export async function resolveOptionsToDocsAutoComplete(
 	options: APIApplicationCommandInteractionDataOption[],
-): DocsAutoCompleteData | undefined {
-	const allversions = getDjsVersions();
-	const [option] = options;
-	const source = option.name;
-
-	const root = option as APIApplicationCommandInteractionDataSubcommandOption;
-	if (!root.options) {
-		return undefined;
-	}
-
-	const versions = allversions.versions.get(convertToDottedName(source));
-
+): Promise<DocsAutoCompleteData | undefined> {
 	let query = 'Client';
-	let version = versions?.at(1) ?? 'main';
-	let ephemeral;
+	let version = getCurrentMainPackageVersion();
+	let ephemeral = false;
 	let mention;
+	let source = 'discord.js';
 
-	logger.debug(
-		{
-			data: {
-				query,
-				versions,
-				version,
-				ephemeral,
-				mention,
-				source,
-			},
-		},
-		`Initial state before parsing options`,
-	);
-
-	for (const opt of root.options) {
+	for (const opt of options) {
 		if (opt.type === ApplicationCommandOptionType.String) {
 			if (opt.name === 'query' && opt.value.length) {
 				query = opt.value;
+
+				if (query.includes(DJS_QUERY_SEPARATOR)) {
+					source = query.split(DJS_QUERY_SEPARATOR)?.[0];
+				} else {
+					const searchResult = await djsMeiliSearch(query, version);
+					const bestHit = searchResult.hits[0];
+
+					if (bestHit) {
+						source = bestHit.autoCompleteValue.split(DJS_QUERY_SEPARATOR)[0];
+						query = bestHit.autoCompleteValue;
+					}
+				}
 			}
 
 			if (opt.name === 'version' && opt.value.length) {
@@ -144,6 +294,13 @@ export function resolveOptionsToDocsAutoComplete(
 		}
 	}
 
+	if (source !== 'discord.js') {
+		const dependencyVersion = await fetchDependencyVersion(version, source);
+		if (dependencyVersion) {
+			version = dependencyVersion;
+		}
+	}
+
 	return {
 		query,
 		source,