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

packages/api-extractor-utils/src/ApiNodeJSONEncoder.ts

@@ -0,0 +1,392 @@
+import {
+	type ApiModel,
+	ApiDeclaredItem,
+	type ApiPropertyItem,
+	type ApiMethod,
+	type ApiParameterListMixin,
+	type ApiTypeParameterListMixin,
+	type ApiClass,
+	type ApiFunction,
+	ApiItemKind,
+	type ApiTypeAlias,
+	type ApiEnum,
+	type ApiInterface,
+	type ApiMethodSignature,
+	type ApiPropertySignature,
+	type ApiVariable,
+	type ApiItem,
+	type ApiConstructor,
+	type ApiItemContainerMixin,
+} from '@microsoft/api-extractor-model';
+import { generateTypeParamData } from './TypeParameterJSONEncoder';
+import { type TokenDocumentation, resolveName, genReference, genToken, genParameter, generatePath } from './parse';
+import { createCommentNode } from './tsdoc';
+import type { DocBlockJSON } from './tsdoc/CommentBlock';
+import type { AnyDocNodeJSON } from './tsdoc/CommentNode';
+import { type DocNodeContainerJSON, nodeContainer } from './tsdoc/CommentNodeContainer';
+
+export interface ReferenceData {
+	name: string;
+	path: string;
+}
+
+export interface InheritanceData {
+	parentName: string;
+	path: string;
+	parentKey: string;
+}
+
+export interface ApiInheritableJSON {
+	inheritanceData: InheritanceData | null;
+}
+
+export interface ApiItemJSON {
+	kind: string;
+	name: string;
+	referenceData: ReferenceData;
+	excerpt: string;
+	excerptTokens: TokenDocumentation[];
+	remarks: DocNodeContainerJSON | null;
+	summary: DocNodeContainerJSON | null;
+	deprecated: DocNodeContainerJSON | null;
+	comment: AnyDocNodeJSON | null;
+	containerKey: string;
+	path: string[];
+}
+
+export interface ApiPropertyItemJSON extends ApiItemJSON, ApiInheritableJSON {
+	propertyTypeTokens: TokenDocumentation[];
+	readonly: boolean;
+	optional: boolean;
+}
+
+export interface ApiTypeParameterListJSON {
+	typeParameters: ApiTypeParameterJSON[];
+}
+
+export interface ApiTypeParameterJSON {
+	name: string;
+	constraintTokens: TokenDocumentation[];
+	defaultTokens: TokenDocumentation[];
+	optional: boolean;
+	commentBlock: DocBlockJSON | null;
+}
+
+export interface ApiParameterListJSON {
+	parameters: ApiParameterJSON[];
+}
+
+export interface ApiMethodSignatureJSON
+	extends ApiItemJSON,
+		ApiTypeParameterListJSON,
+		ApiParameterListJSON,
+		ApiInheritableJSON {
+	returnTypeTokens: TokenDocumentation[];
+	optional: boolean;
+	overloadIndex: number;
+}
+
+export interface ApiMethodJSON extends ApiMethodSignatureJSON {
+	static: boolean;
+	protected: boolean;
+}
+
+export interface ApiParameterJSON {
+	name: string;
+	isOptional: boolean;
+	tokens: TokenDocumentation[];
+	paramCommentBlock: DocBlockJSON | null;
+}
+
+export interface ApiClassJSON extends ApiItemJSON, ApiTypeParameterListJSON {
+	constructor: ApiConstructorJSON | null;
+	properties: ApiPropertyItemJSON[];
+	methods: ApiMethodJSON[];
+	extendsTokens: TokenDocumentation[];
+	implementsTokens: TokenDocumentation[][];
+}
+
+export interface ApiTypeAliasJSON extends ApiItemJSON, ApiTypeParameterListJSON {
+	typeTokens: TokenDocumentation[];
+}
+
+export interface EnumMemberData {
+	name: string;
+	initializerTokens: TokenDocumentation[];
+	summary: DocNodeContainerJSON | null;
+}
+
+export interface ApiEnumJSON extends ApiItemJSON {
+	members: EnumMemberData[];
+}
+
+export interface ApiInterfaceJSON extends ApiItemJSON, ApiTypeParameterListJSON {
+	properties: ApiPropertyItemJSON[];
+	methods: ApiMethodSignatureJSON[];
+	extendsTokens: TokenDocumentation[][] | null;
+}
+
+export interface ApiVariableJSON extends ApiItemJSON {
+	typeTokens: TokenDocumentation[];
+	readonly: boolean;
+}
+
+export interface ApiFunctionJSON extends ApiItemJSON, ApiTypeParameterListJSON, ApiParameterListJSON {
+	returnTypeTokens: TokenDocumentation[];
+	overloadIndex: number;
+}
+
+export interface ApiConstructorJSON extends ApiItemJSON, ApiParameterListJSON {
+	protected: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export class ApiNodeJSONEncoder {
+	public static encode(model: ApiModel, node: ApiItem, version: string) {
+		if (!(node instanceof ApiDeclaredItem)) {
+			console.log(`Cannot serialize node of type ${node.kind}`);
+			return undefined;
+		}
+
+		switch (node.kind) {
+			case ApiItemKind.Class:
+				return this.encodeClass(model, node as ApiClass, version);
+			case ApiItemKind.Function:
+				return this.encodeFunction(model, node as ApiFunction, version);
+			case ApiItemKind.Interface:
+				return this.encodeInterface(model, node as ApiInterface, version);
+			case ApiItemKind.TypeAlias:
+				return this.encodeTypeAlias(model, node as ApiTypeAlias, version);
+			case ApiItemKind.Enum:
+				return this.encodeEnum(model, node as ApiEnum, version);
+			case ApiItemKind.Variable:
+				return this.encodeVariable(model, node as ApiVariable, version);
+			default:
+				console.log(`Unknown API item kind: ${node.kind}`);
+				return undefined;
+		}
+	}
+
+	public static encodeItem(model: ApiModel, item: ApiDeclaredItem, version: string): ApiItemJSON {
+		const path = [];
+		for (const _item of item.getHierarchy()) {
+			switch (_item.kind) {
+				case 'None':
+				case 'EntryPoint':
+				case 'Model':
+					break;
+				default:
+					path.push(resolveName(_item));
+			}
+		}
+
+		return {
+			kind: item.kind,
+			name: resolveName(item),
+			referenceData: genReference(item, version),
+			excerpt: item.excerpt.text,
+			excerptTokens: item.excerpt.spannedTokens.map((token) => genToken(model, token, version)),
+			remarks: item.tsdocComment?.remarksBlock
+				? (createCommentNode(item.tsdocComment.remarksBlock, model, version, item.parent) as DocNodeContainerJSON)
+				: null,
+			summary: item.tsdocComment?.summarySection
+				? (createCommentNode(item.tsdocComment.summarySection, model, version, item.parent) as DocNodeContainerJSON)
+				: null,
+			deprecated: item.tsdocComment?.deprecatedBlock
+				? (createCommentNode(item.tsdocComment.deprecatedBlock, model, version, item.parent) as DocNodeContainerJSON)
+				: null,
+			path,
+			containerKey: item.containerKey,
+			comment: item.tsdocComment ? createCommentNode(item.tsdocComment, model, version, item.parent) : null,
+		};
+	}
+
+	public static encodeParameterList(
+		model: ApiModel,
+		item: ApiParameterListMixin & ApiDeclaredItem,
+		version: string,
+	): { parameters: ApiParameterJSON[] } {
+		return {
+			parameters: item.parameters.map((param) => genParameter(model, param, version)),
+		};
+	}
+
+	public static encodeTypeParameterList(
+		model: ApiModel,
+		item: ApiTypeParameterListMixin & ApiDeclaredItem,
+		version: string,
+	): ApiTypeParameterListJSON {
+		return {
+			typeParameters: item.typeParameters.map((param) => generateTypeParamData(model, param, version, item.parent)),
+		};
+	}
+
+	public static encodeProperty(
+		model: ApiModel,
+		item: ApiPropertyItem,
+		parent: ApiItemContainerMixin,
+		version: string,
+	): ApiPropertyItemJSON {
+		return {
+			...this.encodeItem(model, item, version),
+			...this.encodeInheritanceData(item, parent, version),
+			propertyTypeTokens: item.propertyTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
+			readonly: item.isReadonly,
+			optional: item.isOptional,
+		};
+	}
+
+	public static encodeInheritanceData(
+		item: ApiDeclaredItem,
+		parent: ApiItemContainerMixin,
+		version: string,
+	): ApiInheritableJSON {
+		return {
+			inheritanceData:
+				item.parent && item.parent.containerKey !== parent.containerKey
+					? {
+							parentKey: item.parent.containerKey,
+							parentName: item.parent.displayName,
+							path: generatePath(item.parent.getHierarchy(), version),
+					  }
+					: null,
+		};
+	}
+
+	public static encodeFunction(model: ApiModel, item: ApiFunction, version: string): ApiFunctionJSON {
+		return {
+			...this.encodeItem(model, item, version),
+			...this.encodeParameterList(model, item, version),
+			...this.encodeTypeParameterList(model, item, version),
+			returnTypeTokens: item.returnTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
+			overloadIndex: item.overloadIndex,
+		};
+	}
+
+	public static encodeMethodSignature(
+		model: ApiModel,
+		item: ApiMethodSignature,
+		parent: ApiItemContainerMixin,
+		version: string,
+	): ApiMethodSignatureJSON {
+		return {
+			...this.encodeFunction(model, item, version),
+			...this.encodeInheritanceData(item, parent, version),
+			optional: item.isOptional,
+		};
+	}
+
+	public static encodeMethod(
+		model: ApiModel,
+		item: ApiMethod,
+		parent: ApiItemContainerMixin,
+		version: string,
+	): ApiMethodJSON {
+		return {
+			...this.encodeMethodSignature(model, item, parent, version),
+			static: item.isStatic,
+			protected: item.isProtected,
+		};
+	}
+
+	public static encodeClass(model: ApiModel, item: ApiClass, version: string): ApiClassJSON {
+		const extendsExcerpt = item.extendsType?.excerpt;
+
+		const methods: ApiMethodJSON[] = [];
+		const properties: ApiPropertyItemJSON[] = [];
+
+		let constructor: ApiConstructor | undefined;
+
+		for (const member of item.findMembersWithInheritance().items) {
+			switch (member.kind) {
+				case ApiItemKind.Method:
+					methods.push(this.encodeMethod(model, member as ApiMethod, item, version));
+					break;
+				case ApiItemKind.Property:
+					properties.push(this.encodeProperty(model, member as ApiPropertyItem, item, version));
+					break;
+				case ApiItemKind.Constructor:
+					constructor = member as ApiConstructor;
+					break;
+				default:
+					break;
+			}
+		}
+
+		return {
+			...this.encodeItem(model, item, version),
+			...this.encodeTypeParameterList(model, item, version),
+			constructor: constructor ? this.encodeConstructor(model, constructor, version) : null,
+			extendsTokens: extendsExcerpt ? extendsExcerpt.spannedTokens.map((token) => genToken(model, token, version)) : [],
+			implementsTokens: item.implementsTypes.map((excerpt) =>
+				excerpt.excerpt.spannedTokens.map((token) => genToken(model, token, version)),
+			),
+			methods,
+			properties,
+		};
+	}
+
+	public static encodeTypeAlias(model: ApiModel, item: ApiTypeAlias, version: string): ApiTypeAliasJSON {
+		return {
+			...this.encodeItem(model, item, version),
+			...this.encodeTypeParameterList(model, item, version),
+			typeTokens: item.typeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
+		};
+	}
+
+	public static encodeEnum(model: ApiModel, item: ApiEnum, version: string): ApiEnumJSON {
+		return {
+			...this.encodeItem(model, item, version),
+			members: item.members.map((member) => ({
+				name: member.name,
+				initializerTokens:
+					member.initializerExcerpt?.spannedTokens.map((token) => genToken(model, token, version)) ?? [],
+				summary: member.tsdocComment ? nodeContainer(member.tsdocComment.summarySection, model, version, member) : null,
+			})),
+		};
+	}
+
+	public static encodeInterface(model: ApiModel, item: ApiInterface, version: string): ApiInterfaceJSON {
+		const methods: ApiMethodSignatureJSON[] = [];
+		const properties: ApiPropertyItemJSON[] = [];
+
+		for (const member of item.findMembersWithInheritance().items) {
+			switch (member.kind) {
+				case ApiItemKind.MethodSignature:
+					methods.push(this.encodeMethodSignature(model, member as ApiMethodSignature, item, version));
+					break;
+				case ApiItemKind.PropertySignature:
+					properties.push(this.encodeProperty(model, member as ApiPropertySignature, item, version));
+					break;
+				default:
+					break;
+			}
+		}
+
+		return {
+			...this.encodeItem(model, item, version),
+			...this.encodeTypeParameterList(model, item, version),
+			extendsTokens: item.extendsTypes.map((excerpt) =>
+				excerpt.excerpt.spannedTokens.map((token) => genToken(model, token, version)),
+			),
+			methods,
+			properties,
+		};
+	}
+
+	public static encodeVariable(model: ApiModel, item: ApiVariable, version: string): ApiVariableJSON {
+		return {
+			...this.encodeItem(model, item, version),
+			typeTokens: item.variableTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
+			readonly: item.isReadonly,
+		};
+	}
+
+	public static encodeConstructor(model: ApiModel, item: ApiConstructor, version: string): ApiConstructorJSON {
+		return {
+			...this.encodeItem(model, item, version),
+			...this.encodeParameterList(model, item, version),
+			protected: item.isProtected,
+		};
+	}
+}

packages/api-extractor-utils/src/TypeParameterJSONEncoder.ts

@@ -0,0 +1,31 @@
+import type { TypeParameter, ApiModel, ApiItem } from '@microsoft/api-extractor-model';
+import { type TokenDocumentation, genToken } from './parse';
+import { type DocBlockJSON, block } from './tsdoc/CommentBlock';
+
+export interface TypeParameterData {
+	name: string;
+	constraintTokens: TokenDocumentation[];
+	defaultTokens: TokenDocumentation[];
+	optional: boolean;
+	commentBlock: DocBlockJSON | null;
+}
+
+export function generateTypeParamData(
+	model: ApiModel,
+	typeParam: TypeParameter,
+	version: string,
+	parentItem?: ApiItem,
+): TypeParameterData {
+	const constraintTokens = typeParam.constraintExcerpt.spannedTokens.map((token) => genToken(model, token, version));
+	const defaultTokens = typeParam.defaultTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version));
+
+	return {
+		name: typeParam.name,
+		constraintTokens,
+		defaultTokens,
+		optional: typeParam.isOptional,
+		commentBlock: typeParam.tsdocTypeParamBlock
+			? block(typeParam.tsdocTypeParamBlock, model, version, parentItem)
+			: null,
+	};
+}

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

@@ -0,0 +1,4 @@
+export * from './ApiNodeJSONEncoder';
+export * from './parse';
+export * from './tsdoc';
+export * from './TypeParameterJSONEncoder';

packages/api-extractor-utils/src/parse.ts

@@ -0,0 +1,224 @@
+import {
+	type ApiModel,
+	type ApiPackage,
+	type ApiItem,
+	ApiItemKind,
+	ApiDocumentedItem,
+	type Excerpt,
+	ExcerptTokenKind,
+	ApiNameMixin,
+	type ApiPropertyItem,
+	type ExcerptToken,
+	type Parameter,
+	type ApiFunction,
+} from '@microsoft/api-extractor-model';
+import type { DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
+import { type Meaning, ModuleSource } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
+import { createCommentNode } from './tsdoc';
+import type { DocBlockJSON } from './tsdoc/CommentBlock';
+
+export function findPackage(model: ApiModel, name: string): ApiPackage | undefined {
+	return (model.findMembersByName(name)[0] ?? model.findMembersByName(`@discordjs/${name}`)[0]) as
+		| ApiPackage
+		| undefined;
+}
+
+export function generatePath(items: readonly ApiItem[], version: string) {
+	let path = '/docs/packages';
+
+	for (const item of items) {
+		switch (item.kind) {
+			case ApiItemKind.Model:
+			case ApiItemKind.EntryPoint:
+			case ApiItemKind.EnumMember:
+				break;
+			case ApiItemKind.Package:
+				path += `/${item.displayName}`;
+				break;
+			case ApiItemKind.Function:
+				// eslint-disable-next-line no-case-declarations
+				const functionItem = item as ApiFunction;
+				path += `/${functionItem.displayName}${
+					functionItem.overloadIndex && functionItem.overloadIndex > 1 ? `:${functionItem.overloadIndex}` : ''
+				}:${item.kind}`;
+				break;
+			case ApiItemKind.Property:
+			case ApiItemKind.Method:
+			case ApiItemKind.MethodSignature:
+			case ApiItemKind.PropertySignature:
+				// TODO: Take overloads into account
+				path += `#${item.displayName}:${item.kind}`;
+				break;
+			default:
+				path += `/${item.displayName}:${item.kind}`;
+		}
+	}
+
+	return path.replace(/@discordjs\/(.*)\/(.*)?/, `$1/${version}/$2`);
+}
+
+export function resolveDocComment(item: ApiDocumentedItem) {
+	if (!(item instanceof ApiDocumentedItem)) {
+		return null;
+	}
+
+	const { tsdocComment } = item;
+
+	if (!tsdocComment) {
+		return null;
+	}
+
+	const { summarySection } = tsdocComment;
+
+	function recurseNodes(nodes: readonly DocNode[] | undefined): string | null {
+		if (!nodes) {
+			return null;
+		}
+
+		for (const node of nodes) {
+			switch (node.kind) {
+				case 'Paragraph':
+					return recurseNodes((node as DocParagraph).nodes);
+				case 'PlainText':
+					return (node as DocPlainText).text;
+				default:
+					return null;
+			}
+		}
+
+		return null;
+	}
+
+	return recurseNodes(summarySection.nodes);
+}
+
+export function findReferences(model: ApiModel, excerpt: Excerpt) {
+	const retVal: Set<ApiItem> = new Set();
+
+	for (const token of excerpt.spannedTokens) {
+		switch (token.kind) {
+			case ExcerptTokenKind.Reference: {
+				const item = model.resolveDeclarationReference(token.canonicalReference!, undefined).resolvedApiItem;
+				if (!item) {
+					break;
+				}
+
+				retVal.add(item);
+
+				break;
+			}
+			default:
+				break;
+		}
+	}
+
+	return retVal;
+}
+
+export function resolveName(item: ApiItem) {
+	if (ApiNameMixin.isBaseClassOf(item)) {
+		return item.name;
+	}
+
+	return item.displayName;
+}
+
+export function getProperties(item: ApiItem) {
+	const properties: ApiPropertyItem[] = [];
+	for (const member of item.members) {
+		switch (member.kind) {
+			case ApiItemKind.Property:
+			case ApiItemKind.PropertySignature:
+			case ApiItemKind.Method:
+			case ApiItemKind.MethodSignature:
+				properties.push(member as ApiPropertyItem);
+				break;
+			default:
+				break;
+		}
+	}
+
+	return properties;
+}
+
+export interface TokenDocumentation {
+	text: string;
+	path: string | null;
+	kind: string;
+}
+
+export interface ParameterDocumentation {
+	name: string;
+	isOptional: boolean;
+	tokens: TokenDocumentation[];
+	paramCommentBlock: DocBlockJSON | null;
+}
+
+function createDapiTypesURL(meaning: Meaning, name: string) {
+	const base = 'https://discord-api-types.dev/api/discord-api-types-v10';
+
+	switch (meaning) {
+		case 'type':
+			return `${base}#${name}`;
+		default:
+			return `${base}/${meaning}/${name}`;
+	}
+}
+
+export function genReference(item: ApiItem, version: string) {
+	return {
+		name: resolveName(item),
+		path: generatePath(item.getHierarchy(), version),
+	};
+}
+
+export function genToken(model: ApiModel, token: ExcerptToken, version: string) {
+	if (token.canonicalReference) {
+		// @ts-expect-error
+		token.canonicalReference._navigation = '.';
+	}
+
+	if (
+		token.canonicalReference?.source instanceof ModuleSource &&
+		token.canonicalReference.symbol &&
+		token.canonicalReference.source.packageName === 'discord-api-types' &&
+		token.canonicalReference.symbol.meaning
+	) {
+		return {
+			kind: token.kind,
+			text: token.text,
+			path: createDapiTypesURL(token.canonicalReference.symbol.meaning, token.text),
+		};
+	}
+
+	const item = token.canonicalReference
+		? model.resolveDeclarationReference(token.canonicalReference, undefined).resolvedApiItem ?? null
+		: null;
+
+	return {
+		kind: token.kind,
+		text: token.text,
+		path: item ? generatePath(item.getHierarchy(), version) : null,
+	};
+}
+
+export function genParameter(model: ApiModel, param: Parameter, version: string): ParameterDocumentation {
+	return {
+		name: param.name,
+		isOptional: param.isOptional,
+		tokens: param.parameterTypeExcerpt.spannedTokens.map((token) => genToken(model, token, version)),
+		paramCommentBlock: param.tsdocParamBlock
+			? (createCommentNode(param.tsdocParamBlock, model, version) as DocBlockJSON)
+			: null,
+	};
+}
+
+export function getMembers(pkg: ApiPackage, version: string) {
+	return pkg.members[0]!.members.map((member) => ({
+		name: member.displayName,
+		kind: member.kind as string,
+		path: generatePath(member.getHierarchy(), version),
+		containerKey: member.containerKey,
+		overloadIndex: member.kind === 'Function' ? (member as ApiFunction).overloadIndex : null,
+	}));
+}

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';