feat: add util package for generating search indices (#8571)

packages/api-extractor-utils/src/tsdoc/CommentBlock.ts

@@ -0,0 +1,18 @@
+import type { ApiModel, ApiItem } from '@microsoft/api-extractor-model';
+import type { DocBlock } from '@microsoft/tsdoc';
+import { createCommentNode } from '.';
+import { blockTag, type DocBlockTagJSON } from './CommentBlockTag';
+import { type AnyDocNodeJSON, type DocNodeJSON, node } from './CommentNode';
+
+export interface DocBlockJSON extends DocNodeJSON {
+	content: AnyDocNodeJSON[];
+	tag: DocBlockTagJSON;
+}
+
+export function block(block: DocBlock, model: ApiModel, version: string, parentItem?: ApiItem) {
+	return {
+		...node(block),
+		content: block.content.nodes.map((node) => createCommentNode(node, model, version, parentItem)),
+		tag: blockTag(block.blockTag),
+	};
+}

packages/api-extractor-utils/src/tsdoc/CommentBlockTag.ts

@@ -0,0 +1,13 @@
+import type { DocBlockTag } from '@microsoft/tsdoc';
+import { type DocNodeJSON, node } from './CommentNode';
+
+export interface DocBlockTagJSON extends DocNodeJSON {
+	tagName: string;
+}
+
+export function blockTag(blockTag: DocBlockTag): DocBlockTagJSON {
+	return {
+		...node(blockTag),
+		tagName: blockTag.tagName,
+	};
+}

packages/api-extractor-utils/src/tsdoc/CommentCodeSpan.ts

@@ -0,0 +1,13 @@
+import type { DocCodeSpan } from '@microsoft/tsdoc';
+import { type DocNodeJSON, node } from './CommentNode';
+
+export interface DocCodeSpanJSON extends DocNodeJSON {
+	code: string;
+}
+
+export function codeSpan(codeSpan: DocCodeSpan): DocCodeSpanJSON {
+	return {
+		...node(codeSpan),
+		code: codeSpan.code,
+	};
+}

packages/api-extractor-utils/src/tsdoc/CommentNode.ts

@@ -0,0 +1,28 @@
+import type { DocNode, DocNodeKind } from '@microsoft/tsdoc';
+import type { DocBlockJSON } from './CommentBlock';
+import type { DocCodeSpanJSON } from './CommentCodeSpan';
+import type { DocNodeContainerJSON } from './CommentNodeContainer';
+import type { DocFencedCodeJSON } from './FencedCodeCommentNode';
+import type { DocLinkTagJSON } from './LinkTagCommentNode';
+import type { DocPlainTextJSON } from './PlainTextCommentNode';
+import type { DocCommentJSON } from './RootComment';
+
+export interface DocNodeJSON {
+	kind: DocNodeKind;
+}
+
+export type AnyDocNodeJSON =
+	| DocNodeJSON
+	| DocPlainTextJSON
+	| DocNodeContainerJSON
+	| DocLinkTagJSON
+	| DocFencedCodeJSON
+	| DocBlockJSON
+	| DocCommentJSON
+	| DocCodeSpanJSON;
+
+export function node(node: DocNode): DocNodeJSON {
+	return {
+		kind: node.kind as DocNodeKind,
+	};
+}

packages/api-extractor-utils/src/tsdoc/CommentNodeContainer.ts

@@ -0,0 +1,20 @@
+import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
+import type { DocNodeContainer } from '@microsoft/tsdoc';
+import { createCommentNode } from '.';
+import { type AnyDocNodeJSON, type DocNodeJSON, node } from './CommentNode';
+
+export interface DocNodeContainerJSON extends DocNodeJSON {
+	nodes: AnyDocNodeJSON[];
+}
+
+export function nodeContainer(
+	container: DocNodeContainer,
+	model: ApiModel,
+	version: string,
+	parentItem?: ApiItem,
+): DocNodeContainerJSON {
+	return {
+		...node(container),
+		nodes: container.nodes.map((node) => createCommentNode(node, model, version, parentItem)),
+	};
+}

packages/api-extractor-utils/src/tsdoc/FencedCodeCommentNode.ts

@@ -0,0 +1,15 @@
+import type { DocFencedCode } from '@microsoft/tsdoc';
+import { type DocNodeJSON, node } from './CommentNode';
+
+export interface DocFencedCodeJSON extends DocNodeJSON {
+	code: string;
+	language: string;
+}
+
+export function fencedCode(fencedCode: DocFencedCode) {
+	return {
+		...node(fencedCode),
+		language: fencedCode.language,
+		code: fencedCode.code,
+	};
+}

packages/api-extractor-utils/src/tsdoc/LinkTagCommentNode.ts

@@ -0,0 +1,60 @@
+import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
+import type { DocDeclarationReference, DocLinkTag } from '@microsoft/tsdoc';
+import { type DocNodeJSON, node } from './CommentNode';
+import { resolveName, generatePath } from '../parse';
+
+interface LinkTagCodeLink {
+	name: string;
+	kind: string;
+	path: string;
+}
+
+export interface DocLinkTagJSON extends DocNodeJSON {
+	text: string | null;
+	codeDestination: LinkTagCodeLink | null;
+	urlDestination: string | null;
+}
+
+export function genLinkToken(
+	model: ApiModel,
+	ref: DocDeclarationReference,
+	context: ApiItem | null,
+	version: string,
+): LinkTagCodeLink | null {
+	const item = model.resolveDeclarationReference(ref, context ?? undefined).resolvedApiItem ?? null;
+
+	if (!item) {
+		return null;
+	}
+
+	return {
+		name: resolveName(item),
+		kind: item.kind,
+		path: generatePath(item.getHierarchy(), version),
+	};
+}
+
+export function linkTagNode(
+	linkNode: DocLinkTag,
+	model: ApiModel,
+	version: string,
+	parentItem?: ApiItem,
+): DocLinkTagJSON {
+	// If we weren't provided a parent object, fallback to the package entrypoint.
+	const packageEntryPoint = linkNode.codeDestination?.importPath
+		? model.getAssociatedPackage()?.findEntryPointsByPath(linkNode.codeDestination.importPath)[0]
+		: null;
+
+	const codeDestination = linkNode.codeDestination
+		? genLinkToken(model, linkNode.codeDestination, parentItem ?? packageEntryPoint ?? null, version)
+		: null;
+	const text = linkNode.linkText ?? null;
+	const urlDestination = linkNode.urlDestination ?? null;
+
+	return {
+		...node(linkNode),
+		text,
+		codeDestination,
+		urlDestination,
+	};
+}

packages/api-extractor-utils/src/tsdoc/ParamBlock.ts

@@ -0,0 +1,19 @@
+import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
+import type { DocParamBlock } from '@microsoft/tsdoc';
+import { block, type DocBlockJSON } from './CommentBlock';
+
+interface DocParamBlockJSON extends DocBlockJSON {
+	name: string;
+}
+
+export function paramBlock(
+	paramBlock: DocParamBlock,
+	model: ApiModel,
+	version: string,
+	parentItem?: ApiItem,
+): DocParamBlockJSON {
+	return {
+		...block(paramBlock, model, version, parentItem),
+		name: paramBlock.parameterName,
+	};
+}

packages/api-extractor-utils/src/tsdoc/PlainTextCommentNode.ts

@@ -0,0 +1,13 @@
+import type { DocPlainText } from '@microsoft/tsdoc';
+import { type DocNodeJSON, node } from './CommentNode';
+
+export interface DocPlainTextJSON extends DocNodeJSON {
+	text: string;
+}
+
+export function plainTextNode(plainTextNode: DocPlainText): DocPlainTextJSON {
+	return {
+		...node(plainTextNode),
+		text: plainTextNode.text,
+	};
+}

packages/api-extractor-utils/src/tsdoc/RootComment.ts

@@ -0,0 +1,24 @@
+import type { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
+import type { DocComment } from '@microsoft/tsdoc';
+import { createCommentNode } from '.';
+import { block, type DocBlockJSON } from './CommentBlock';
+import { type DocNodeJSON, node } from './CommentNode';
+
+export interface DocCommentJSON extends DocNodeJSON {
+	summary: DocNodeJSON[];
+	remarks: DocNodeJSON[];
+	deprecated: DocNodeJSON[];
+	customBlocks: DocBlockJSON[];
+}
+
+export function comment(comment: DocComment, model: ApiModel, version: string, parentItem?: ApiItem): DocCommentJSON {
+	return {
+		...node(comment),
+		summary: comment.summarySection.nodes.map((node) => createCommentNode(node, model, version, parentItem)),
+		remarks:
+			comment.remarksBlock?.content.nodes.map((node) => createCommentNode(node, model, version, parentItem)) ?? [],
+		deprecated:
+			comment.deprecatedBlock?.content.nodes.map((node) => createCommentNode(node, model, version, parentItem)) ?? [],
+		customBlocks: comment.customBlocks.map((_block) => block(_block, model, version, parentItem)),
+	};
+}

packages/api-extractor-utils/src/tsdoc/index.ts

@@ -0,0 +1,63 @@
+import type { ApiModel, ApiItem } from '@microsoft/api-extractor-model';
+import {
+	type DocNode,
+	type DocPlainText,
+	type DocLinkTag,
+	type DocParagraph,
+	type DocFencedCode,
+	DocNodeKind,
+	type DocBlock,
+	type DocComment,
+	type DocCodeSpan,
+	type DocParamBlock,
+} from '@microsoft/tsdoc';
+import { block } from './CommentBlock';
+import { codeSpan } from './CommentCodeSpan';
+import type { AnyDocNodeJSON } from './CommentNode';
+import { node as _node } from './CommentNode';
+import { nodeContainer } from './CommentNodeContainer';
+import { fencedCode } from './FencedCodeCommentNode';
+import { linkTagNode } from './LinkTagCommentNode';
+import { paramBlock } from './ParamBlock';
+import { plainTextNode } from './PlainTextCommentNode';
+import { comment } from './RootComment';
+
+export function createCommentNode(
+	node: DocNode,
+	model: ApiModel,
+	version: string,
+	parentItem?: ApiItem,
+): AnyDocNodeJSON {
+	switch (node.kind) {
+		case DocNodeKind.PlainText:
+			return plainTextNode(node as DocPlainText);
+		case DocNodeKind.LinkTag:
+			return linkTagNode(node as DocLinkTag, model, version, parentItem);
+		case DocNodeKind.Paragraph:
+		case DocNodeKind.Section:
+			return nodeContainer(node as DocParagraph, model, version, parentItem);
+		case DocNodeKind.FencedCode:
+			return fencedCode(node as DocFencedCode);
+		case DocNodeKind.CodeSpan:
+			return codeSpan(node as DocCodeSpan);
+		case DocNodeKind.Block:
+			return block(node as DocBlock, model, version, parentItem);
+		case DocNodeKind.ParamBlock:
+			return paramBlock(node as DocParamBlock, model, version, parentItem);
+		case DocNodeKind.Comment:
+			return comment(node as DocComment, model, version, parentItem);
+		default:
+			return _node(node);
+	}
+}
+
+export * from './CommentNode';
+export * from './CommentNodeContainer';
+export * from './CommentBlock';
+export * from './CommentBlockTag';
+export * from './CommentCodeSpan';
+export * from './FencedCodeCommentNode';
+export * from './LinkTagCommentNode';
+export * from './ParamBlock';
+export * from './PlainTextCommentNode';
+export * from './RootComment';