feat(helpdesk): support finding article sections via autocomplete

Author: almostSouji

src/functions/autocomplete/helpdeskAutoComplete.ts

@@ -9,6 +9,8 @@ import {
 	DISCORD_HELPDESK_DEV_BASE,
 	DJS_QUERY_SEPARATOR,
 } from '../../util/constants.js';
+import { findRelevantDocsSectionFuzzy, parseGithubDocsSections } from '../../util/discordDocs.js';
+import { helpdeskTurndownService } from '../../util/helpdeskturndown.js';
 import { prepareHeader } from '../../util/respond.js';
 import { truncate } from '../../util/truncate.js';
 
@@ -19,13 +21,28 @@ export function zendeskAutocompleteValue(article: ZendeskSearchResult, query: st
 	return `${prefix}${query.slice(0, AUTOCOMPLETE_MAX_NAME_LENGTH - prefix.length)}`;
 }
 
-function autocompleteMap(elements: ZendeskSearchResult[], query: string) {
-	return elements.map((entry) => {
-		return {
+function autocompleteMap(searchResults: ZendeskSearchResult[], query: string) {
+	const res = [];
+
+	for (const entry of searchResults) {
+		const mdParsed = helpdeskTurndownService.turndown(entry.body);
+		const parsedSections = parseGithubDocsSections(mdParsed.split(/\n+/));
+		const relevant = findRelevantDocsSectionFuzzy(parsedSections, query, false);
+
+		if (relevant?.linkAnchor) {
+			res.push({
+				name: truncate(`${entry.title} | ${relevant.headline}`, AUTOCOMPLETE_MAX_NAME_LENGTH),
+				value: zendeskAutocompleteValue(entry, relevant.linkAnchor),
+			});
+		}
+
+		res.push({
 			name: truncate(entry.title, AUTOCOMPLETE_MAX_NAME_LENGTH),
 			value: zendeskAutocompleteValue(entry, query),
-		};
-	});
+		});
+	}
+
+	return res.slice(0, AUTOCOMPLETE_MAX_ITEMS);
 }
 
 export async function zendeskQuery(query: string, developer = false) {

src/functions/helpdeskResponse.ts

@@ -1,4 +1,4 @@
-import { hyperlink, inlineCode } from '@discordjs/builders';
+import { HeadingLevel, heading, hyperlink, inlineCode } from '@discordjs/builders';
 import type { Response } from 'polka';
 import type { ZendeskArticle, ZendeskEntity } from '../types/zendesk';
 import {
@@ -15,6 +15,7 @@ import {
 import {
 	SectionPartType,
 	findRelevantDocsSectionFuzzy,
+	findSectionFromAnchor,
 	parseGithubDocsSections,
 	sectionPartToText,
 } from '../util/discordDocs.js';
@@ -42,6 +43,15 @@ async function fetchHelpdeskArticle(id: number, autocompleteTimestamp: number, d
 			);
 			return hit;
 		}
+
+		logger.debug(
+			{
+				id,
+				autocompleteTimestamp,
+				dev,
+			},
+			`cache hit but outdated for support article ${id}. refreshing...`,
+		);
 	}
 
 	const base = dev ? DISCORD_HELPDESK_DEV_ARTICLES_BASE : DISCORD_HELPDESK_ARTICLES_BASE;
@@ -61,12 +71,13 @@ export async function helpdeskResponse(
 	ephemeral?: boolean,
 	secondAttempt = false,
 ) {
-	const [articleId, timestampString, ...originalQuery] = query.split(DJS_QUERY_SEPARATOR);
+	const [articleId, timestampString, ...originalQueryParts] = query.split(DJS_QUERY_SEPARATOR);
+	const originalQuery = originalQueryParts.join(DJS_QUERY_SEPARATOR);
 
 	const numberId = Number.parseInt(articleId, 10);
 	if (Number.isNaN(numberId)) {
 		if (secondAttempt) {
-			prepareErrorResponse(res, `No documentation found for ${inlineCode(originalQuery.join(DJS_QUERY_SEPARATOR))}.`);
+			prepareErrorResponse(res, `No documentation found for ${inlineCode(originalQuery)}.`);
 			return res;
 		}
 
@@ -87,10 +98,13 @@ export async function helpdeskResponse(
 	const bodyParts = ['---', `title: ${article.title}`, '---', ...turnedDown.split(/\n+/)];
 
 	const parsedSections = parseGithubDocsSections(bodyParts);
-	const relevantSection = findRelevantDocsSectionFuzzy(parsedSections, originalQuery.join(DJS_QUERY_SEPARATOR), true);
+
+	const relevantSection = originalQuery.startsWith('#h')
+		? findSectionFromAnchor(parsedSections, originalQuery)
+		: findRelevantDocsSectionFuzzy(parsedSections, originalQuery, true);
 
 	if (!relevantSection) {
-		prepareErrorResponse(res, `No documentation found for ${inlineCode(query)}.`);
+		prepareErrorResponse(res, `No documentation found for ${inlineCode(originalQuery)}.`);
 		return res;
 	}
 

src/util/discordDocs.ts

@@ -398,8 +398,20 @@ export function sectionPartToText(part: SectionPart) {
 	}
 
 	if (part.type === SectionPartType.Admonition) {
-		const prefixed = part.lines.map((line) => quote(line));
-		return prefixed.join('\n');
+		const prefixedLines = [];
+		let first = true;
+		for (const line of part.lines) {
+			if (first) {
+				prefixedLines.push(quote(`${inlineCode(admonitionEmoji(part.admonitionType))} ${line}`));
+
+				first = false;
+				continue;
+			}
+
+			prefixedLines.push(quote(line));
+		}
+
+		return prefixedLines.join('\n');
 	}
 
 	if (part.type === SectionPartType.Code) {
@@ -434,6 +446,14 @@ export function findRelevantDocsSection(sections: Section[], query: string, defa
 	}
 }
 
+export function findSectionFromAnchor(sections: Section[], anchor: string) {
+	for (const section of sections) {
+		if (anchor === section.linkAnchor) {
+			return section;
+		}
+	}
+}
+
 export function findRelevantDocsSectionFuzzy(sections: Section[], query: string, defaultFirst = false) {
 	const lowerQuery = query.trim().toLowerCase();
 	const headingMatches = [];