rspress-plugin-api-extractor 0.14.0 → 0.15.0

package/markdown/page-generators/namespace-page.js

@@ -1,277 +0,0 @@
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
-import { linkProse } from "../prose-linker.js";
-import { ApiItemKind } from "@microsoft/api-extractor-model";
-import { ApiItems, Signature, Tsdoc, TypeReferenceExtractor } from "@tsdoctor/model";
-
-//#region src/markdown/page-generators/namespace-page.ts
-/**
-* Generates MDX documentation pages for TypeScript namespaces.
-*
-* This class transforms API Extractor namespace models into rich MDX documentation pages
-* with syntax-highlighted signatures, cross-linked type references, and member listings.
-*
-* **Page Structure:**
-* 1. Frontmatter with title, description, and Open Graph metadata
-* 2. Component imports (SourceCode, ApiSignature, etc.)
-* 3. Page title (H1) and summary
-* 4. Optional deprecation warning and release tag badge
-* 5. Source code link toolbar
-* 6. Full namespace signature block showing all members
-* 7. Member sections: Classes, Interfaces, Functions, Variables, Types, Enums, Namespaces
-* 8. Examples section with Twoslash-enabled code blocks
-* 9. See Also references
-*
-* **Member Rendering:**
-* Each member section lists members with links to their individual documentation pages.
-*
-* **Relationships:**
-* - Created and invoked by {@link ApiExtractorPlugin} during page generation
-* - Uses `Signature.format` from `@tsdoctor/model` for formatting type signatures
-* - Uses the `Tsdoc` / `ApiItems` modules from `@tsdoctor/model` for extracting documentation
-* - Uses the per-build prose linker (`linkProse`) for adding type reference links
-*
-* @example
-* ```ts
-* const generator = new NamespacePageGenerator();
-* const { routePath, content } = await generator.generate(
-*   apiNamespace,
-*   "/api/my-package",
-*   "my-package",
-*   "Namespace",
-*   "My Package",
-*   sourceConfig,
-*   true, // suppressExampleErrors
-*   undefined, // llmsPlugin
-*   "my-scope"
-* );
-* ```
-*
-* @see {@link ClassPageGenerator} for class documentation
-* @see {@link InterfacePageGenerator} for interface documentation
-*/
-var NamespacePageGenerator = class {
-	/**
-	* Generate a markdown page for a namespace
-	*
-	* @param apiScope - API scope identifier for VFS lookup
-	*/
-	async generate(apiNamespace, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
-		const shouldSuppressErrors = suppressExampleErrors ?? true;
-		const name = apiNamespace.displayName;
-		const summary = Tsdoc.summary(apiNamespace) || "No description available.";
-		const releaseTag = Tsdoc.releaseTag(apiNamespace);
-		let content = generateFrontmatter(name, summary, singularName, apiName);
-		content += `import { SourceCode } from "@rspress/core/theme";\n`;
-		content += `import { ApiSignature, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
-		content += `# ${name}\n\n`;
-		const deprecation = Tsdoc.deprecation(apiNamespace);
-		if (deprecation) {
-			const message = escapeMdxGenerics(linkProse(deprecation.message));
-			content += `> **Deprecated:** ${message}\n\n`;
-		}
-		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
-		content += `${summary}\n\n`;
-		content += generateAvailableFrom(packageName, availableFrom);
-		const sourceLink = ApiItems.sourceLink(apiNamespace, sourceConfig);
-		if (sourceLink) {
-			content += `<div className="api-docs-toolbar">\n`;
-			content += `  <div className="api-docs-toolbar-left">\n`;
-			content += `    <SourceCode href="${sourceLink}" />\n`;
-			content += `  </div>\n`;
-			if (llmsPlugin?.enabled) {
-				content += `  <div className="api-docs-toolbar-right">\n`;
-				content += `  </div>\n`;
-			}
-			content += `</div>\n\n`;
-		}
-		const skeleton = this.generateNamespaceSkeletonWithTwoslash(apiNamespace, packageName);
-		const displayCode = stripTwoslashDirectives(skeleton);
-		content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(skeleton)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
-		const grouped = this.groupNamespaceMembers(apiNamespace.members);
-		content += this.renderMemberSection("Classes", grouped.classes, baseRoute, "class", name);
-		content += this.renderMemberSection("Interfaces", grouped.interfaces, baseRoute, "interface", name);
-		content += this.renderMemberSection("Functions", grouped.functions, baseRoute, "function", name);
-		content += this.renderMemberSection("Variables", grouped.variables, baseRoute, "variable", name);
-		content += this.renderMemberSection("Types", grouped.typeAliases, baseRoute, "type", name);
-		content += this.renderMemberSection("Enums", grouped.enums, baseRoute, "enum", name);
-		content += this.renderMemberSection("Namespaces", grouped.namespaces, baseRoute, "namespace", name);
-		const examples = Tsdoc.examples(apiNamespace);
-		if (examples.length > 0) {
-			content += `## Examples\n\n`;
-			for (const example of examples) {
-				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
-				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
-					api: packageName,
-					blockType: "example"
-				});
-				if (prepared.isTypeScript) {
-					const displayCode = stripTwoslashDirectives(formattedCode);
-					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
-				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
-			}
-		}
-		const seeReferences = Tsdoc.seeReferences(apiNamespace);
-		if (seeReferences.length > 0) {
-			content += `## See Also\n\n`;
-			for (const reference of seeReferences) {
-				const refText = escapeMdxGenerics(linkProse(reference.text));
-				content += `- ${refText}\n`;
-			}
-			content += `\n`;
-		}
-		return {
-			routePath: `${baseRoute}/namespace/${name.toLowerCase()}`,
-			content
-		};
-	}
-	/**
-	* Group namespace members by their type
-	*/
-	groupNamespaceMembers(members) {
-		const classes = [];
-		const interfaces = [];
-		const functions = [];
-		const variables = [];
-		const typeAliases = [];
-		const enums = [];
-		const namespaces = [];
-		for (const member of members) switch (member.kind) {
-			case ApiItemKind.Class:
-				classes.push(member);
-				break;
-			case ApiItemKind.Interface:
-				interfaces.push(member);
-				break;
-			case ApiItemKind.Function:
-				functions.push(member);
-				break;
-			case ApiItemKind.Variable:
-				variables.push(member);
-				break;
-			case ApiItemKind.TypeAlias:
-				typeAliases.push(member);
-				break;
-			case ApiItemKind.Enum:
-				enums.push(member);
-				break;
-			case ApiItemKind.Namespace: namespaces.push(member);
-		}
-		return {
-			classes,
-			interfaces,
-			functions,
-			variables,
-			typeAliases,
-			enums,
-			namespaces
-		};
-	}
-	/**
-	* Render a section of members with links to their pages
-	* @param title - Section heading
-	* @param members - Array of API items to list
-	* @param baseRoute - Base API route (e.g., /api/package)
-	* @param categoryFolder - Category folder name (e.g., "class", "function")
-	* @param namespaceName - Parent namespace name for qualified routes
-	*/
-	renderMemberSection(title, members, baseRoute, categoryFolder, namespaceName) {
-		if (members.length === 0) return "";
-		let section = `## ${title}\n\n`;
-		for (const member of members) {
-			const memberName = member.displayName;
-			const memberSummary = Tsdoc.summary(member);
-			const memberRoute = `${baseRoute}/${categoryFolder}/${`${namespaceName}.${memberName}`.toLowerCase()}`;
-			if (memberSummary) {
-				const escapedSummary = escapeMdxGenerics(linkProse(memberSummary));
-				section += `- [${memberName}](${memberRoute}) - ${escapedSummary}\n`;
-			} else section += `- [${memberName}](${memberRoute})\n`;
-		}
-		section += `\n`;
-		return section;
-	}
-	/**
-	* Generate a namespace skeleton for signature blocks
-	* Includes hidden imports with cut directive for external type resolution
-	*/
-	generateNamespaceSkeletonWithTwoslash(apiNamespace, packageName) {
-		const skeleton = this.generateNamespaceSkeleton(apiNamespace);
-		const apiPackage = apiNamespace.getAssociatedPackage?.();
-		if (apiPackage) {
-			const imports = new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiNamespace);
-			return prependHiddenImports(skeleton, imports);
-		}
-		return skeleton;
-	}
-	/**
-	* Generate a complete namespace skeleton showing all members
-	*/
-	generateNamespaceSkeleton(apiNamespace) {
-		const lines = [];
-		const namespaceName = apiNamespace.displayName;
-		lines.push(`namespace ${namespaceName} {`);
-		const grouped = this.groupNamespaceMembers(apiNamespace.members);
-		for (const cls of grouped.classes) {
-			const clsItem = cls;
-			if (clsItem.excerpt?.text) {
-				const signature = Signature.format(clsItem.excerpt).trim();
-				lines.push(`    ${this.abbreviateDeclaration(signature, "class")} { }`);
-			}
-		}
-		for (const iface of grouped.interfaces) {
-			const ifaceItem = iface;
-			if (ifaceItem.excerpt?.text) {
-				const signature = Signature.format(ifaceItem.excerpt).trim();
-				lines.push(`    ${this.abbreviateDeclaration(signature, "interface")} { }`);
-			}
-		}
-		for (const func of grouped.functions) {
-			const funcItem = func;
-			if (funcItem.excerpt?.text) {
-				const signature = Signature.format(funcItem.excerpt).trim();
-				lines.push(`    ${signature}`);
-			}
-		}
-		for (const variable of grouped.variables) {
-			const varItem = variable;
-			if (varItem.excerpt?.text) {
-				const signature = Signature.format(varItem.excerpt).trim();
-				lines.push(`    ${signature}`);
-			}
-		}
-		for (const typeAlias of grouped.typeAliases) {
-			const typeItem = typeAlias;
-			if (typeItem.excerpt?.text) {
-				const signature = Signature.format(typeItem.excerpt).trim();
-				lines.push(`    ${signature}`);
-			}
-		}
-		for (const enumItem of grouped.enums) {
-			const enumDeclItem = enumItem;
-			if (enumDeclItem.excerpt?.text) {
-				const signature = Signature.format(enumDeclItem.excerpt).trim();
-				lines.push(`    ${this.abbreviateDeclaration(signature, "enum")} { }`);
-			}
-		}
-		for (const ns of grouped.namespaces) {
-			const nsItem = ns;
-			if (nsItem.excerpt?.text) {
-				const signature = Signature.format(nsItem.excerpt).trim();
-				lines.push(`    ${this.abbreviateDeclaration(signature, "namespace")} { }`);
-			}
-		}
-		lines.push("}");
-		return lines.join("\n");
-	}
-	/**
-	* Abbreviate a full declaration to just its header
-	* For example, `class Foo extends Bar implements Baz \{ ... \}` becomes `class Foo extends Bar implements Baz`
-	*/
-	abbreviateDeclaration(signature, _keyword) {
-		const braceIndex = signature.indexOf("{");
-		if (braceIndex === -1) return signature;
-		return signature.substring(0, braceIndex).trim();
-	}
-};
-
-//#endregion
-export { NamespacePageGenerator };

package/markdown/page-generators/type-alias-page.js

@@ -1,110 +0,0 @@
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
-import { linkProse } from "../prose-linker.js";
-import { ApiItems, Signature, Tsdoc, TypeReferenceExtractor } from "@tsdoctor/model";
-
-//#region src/markdown/page-generators/type-alias-page.ts
-/**
-* Generates MDX documentation pages for TypeScript type aliases.
-*
-* This class transforms API Extractor type alias models into rich MDX documentation
-* pages with syntax-highlighted signatures and cross-linked type references.
-*
-* **Page Structure:**
-* 1. Frontmatter with title, description, and Open Graph metadata
-* 2. Component imports
-* 3. Page title (H1) and summary
-* 4. Optional deprecation warning and release tag badge
-* 5. Source code link toolbar
-* 6. Type alias signature block (full type definition)
-* 7. Examples section with Twoslash-enabled code blocks
-* 8. See Also references
-*
-* **Relationships:**
-* - Created and invoked by {@link ApiExtractorPlugin} during page generation
-* - Uses `Signature.format` from `@tsdoctor/model` for formatting type signatures
-* - Uses the `Tsdoc` / `ApiItems` modules from `@tsdoctor/model` for extracting documentation
-* - Uses the per-build prose linker (`linkProse`) for adding type reference links
-*
-* @see {@link InterfacePageGenerator} for interface documentation
-* @see {@link EnumPageGenerator} for enum documentation
-*/
-var TypeAliasPageGenerator = class {
-	/**
-	* Generate a markdown page for a type alias
-	*
-	* @param apiScope - API scope identifier for VFS lookup
-	*/
-	async generate(apiTypeAlias, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
-		const shouldSuppressErrors = suppressExampleErrors ?? true;
-		const name = apiTypeAlias.displayName;
-		const summary = Tsdoc.summary(apiTypeAlias) || "No description available.";
-		const releaseTag = Tsdoc.releaseTag(apiTypeAlias);
-		let content = generateFrontmatter(name, summary, singularName, apiName);
-		content += `import { SourceCode } from "@rspress/core/theme";\n`;
-		content += `import { ParametersTable } from "rspress-plugin-api-extractor/runtime";\n`;
-		content += `import { ApiSignature, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
-		content += `# ${name}\n\n`;
-		const deprecation = Tsdoc.deprecation(apiTypeAlias);
-		if (deprecation) {
-			const message = escapeMdxGenerics(linkProse(deprecation.message));
-			content += `> ⚠️ **Deprecated:** ${message}\n\n`;
-		}
-		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
-		content += `${summary}\n\n`;
-		content += generateAvailableFrom(packageName, availableFrom);
-		const sourceLink = ApiItems.sourceLink(apiTypeAlias, sourceConfig);
-		if (sourceLink) {
-			content += `<div className="api-docs-toolbar">\n`;
-			content += `  <div className="api-docs-toolbar-left">\n`;
-			content += `    <SourceCode href="${sourceLink}" />\n`;
-			content += `  </div>\n`;
-			if (llmsPlugin?.enabled) {
-				content += `  <div className="api-docs-toolbar-right">\n`;
-				content += `  </div>\n`;
-			}
-			content += `</div>\n\n`;
-		}
-		if (apiTypeAlias.excerpt.text) {
-			const signature = Signature.format(apiTypeAlias.excerpt).trim();
-			let signatureWithImports = signature;
-			const apiPackage = apiTypeAlias.getAssociatedPackage?.();
-			if (apiPackage) {
-				const imports = new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiTypeAlias);
-				signatureWithImports = prependHiddenImports(signature, imports);
-			}
-			const displayCode = stripTwoslashDirectives(signatureWithImports);
-			content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(signatureWithImports)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
-		}
-		const examples = Tsdoc.examples(apiTypeAlias);
-		if (examples.length > 0) {
-			content += `## Examples\n\n`;
-			for (const example of examples) {
-				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
-				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
-					api: packageName,
-					blockType: "example"
-				});
-				if (prepared.isTypeScript) {
-					const displayCode = stripTwoslashDirectives(formattedCode);
-					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
-				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
-			}
-		}
-		const seeReferences = Tsdoc.seeReferences(apiTypeAlias);
-		if (seeReferences.length > 0) {
-			content += `## See Also\n\n`;
-			for (const reference of seeReferences) {
-				const refText = escapeMdxGenerics(linkProse(reference.text));
-				content += `- ${refText}\n`;
-			}
-			content += `\n`;
-		}
-		return {
-			routePath: `${baseRoute}/type/${name.toLowerCase()}`,
-			content
-		};
-	}
-};
-
-//#endregion
-export { TypeAliasPageGenerator };

package/markdown/page-generators/variable-page.js

@@ -1,110 +0,0 @@
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
-import { linkProse } from "../prose-linker.js";
-import { ApiItems, Signature, Tsdoc, TypeReferenceExtractor } from "@tsdoctor/model";
-
-//#region src/markdown/page-generators/variable-page.ts
-/**
-* Generates MDX documentation pages for exported variables and constants.
-*
-* This class transforms API Extractor variable models into rich MDX documentation
-* pages with syntax-highlighted signatures and cross-linked type references.
-*
-* **Page Structure:**
-* 1. Frontmatter with title, description, and Open Graph metadata
-* 2. Component imports
-* 3. Page title (H1) and summary
-* 4. Optional deprecation warning and release tag badge
-* 5. Source code link toolbar
-* 6. Variable signature block (const/let declaration with type)
-* 7. Examples section with Twoslash-enabled code blocks
-* 8. See Also references
-*
-* **Relationships:**
-* - Created and invoked by {@link ApiExtractorPlugin} during page generation
-* - Uses `Signature.format` from `@tsdoctor/model` for formatting type signatures
-* - Uses the `Tsdoc` / `ApiItems` modules from `@tsdoctor/model` for extracting documentation
-* - Uses the per-build prose linker (`linkProse`) for adding type reference links
-*
-* @see {@link FunctionPageGenerator} for function documentation
-* @see {@link EnumPageGenerator} for enum documentation
-*/
-var VariablePageGenerator = class {
-	/**
-	* Generate a markdown page for a variable
-	*
-	* @param apiScope - API scope identifier for VFS lookup
-	*/
-	async generate(apiVariable, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
-		const shouldSuppressErrors = suppressExampleErrors ?? true;
-		const name = apiVariable.displayName;
-		const summary = Tsdoc.summary(apiVariable) || "No description available.";
-		const releaseTag = Tsdoc.releaseTag(apiVariable);
-		let content = generateFrontmatter(name, summary, singularName, apiName);
-		content += `import { SourceCode } from "@rspress/core/theme";\n`;
-		content += `import { ParametersTable } from "rspress-plugin-api-extractor/runtime";\n`;
-		content += `import { ApiSignature, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
-		content += `# ${name}\n\n`;
-		const deprecation = Tsdoc.deprecation(apiVariable);
-		if (deprecation) {
-			const message = escapeMdxGenerics(linkProse(deprecation.message));
-			content += `> ⚠️ **Deprecated:** ${message}\n\n`;
-		}
-		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
-		content += `${summary}\n\n`;
-		content += generateAvailableFrom(packageName, availableFrom);
-		const sourceLink = ApiItems.sourceLink(apiVariable, sourceConfig);
-		if (sourceLink) {
-			content += `<div className="api-docs-toolbar">\n`;
-			content += `  <div className="api-docs-toolbar-left">\n`;
-			content += `    <SourceCode href="${sourceLink}" />\n`;
-			content += `  </div>\n`;
-			if (llmsPlugin?.enabled) {
-				content += `  <div className="api-docs-toolbar-right">\n`;
-				content += `  </div>\n`;
-			}
-			content += `</div>\n\n`;
-		}
-		if (apiVariable.excerpt.text) {
-			const signature = Signature.format(apiVariable.excerpt).trim();
-			let signatureWithImports = signature;
-			const apiPackage = apiVariable.getAssociatedPackage?.();
-			if (apiPackage) {
-				const imports = new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiVariable);
-				signatureWithImports = prependHiddenImports(signature, imports);
-			}
-			const displayCode = stripTwoslashDirectives(signatureWithImports);
-			content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(signatureWithImports)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
-		}
-		const examples = Tsdoc.examples(apiVariable);
-		if (examples.length > 0) {
-			content += `## Examples\n\n`;
-			for (const example of examples) {
-				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
-				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
-					api: packageName,
-					blockType: "example"
-				});
-				if (prepared.isTypeScript) {
-					const displayCode = stripTwoslashDirectives(formattedCode);
-					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
-				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
-			}
-		}
-		const seeReferences = Tsdoc.seeReferences(apiVariable);
-		if (seeReferences.length > 0) {
-			content += `## See Also\n\n`;
-			for (const reference of seeReferences) {
-				const refText = escapeMdxGenerics(linkProse(reference.text));
-				content += `- ${refText}\n`;
-			}
-			content += `\n`;
-		}
-		return {
-			routePath: `${baseRoute}/variable/${name.toLowerCase()}`,
-			content
-		};
-	}
-};
-
-//#endregion
-export { VariablePageGenerator };

package/markdown/prose-linker.js

@@ -1,22 +0,0 @@
-import { CrossLinker } from "@tsdoctor/model";
-
-//#region src/markdown/prose-linker.ts
-/**
-* Per-build prose cross-linker holder. Adapter wiring, not logic: the build
-* program installs the immutable `@tsdoctor/model` CrossLinker built from the
-* routes `prepareWorkItems` computed, and page generators link prose through
-* it. Page generators run synchronously outside any service context, hence
-* the module-level holder (the same shape as the sync-island event emitters).
-*/
-let current = CrossLinker.empty;
-/** Install the cross-linker for the current API build from its route map. */
-function setProseLinker(routes) {
-	current = CrossLinker.fromRoutes(routes);
-}
-/** Cross-link prose text with the currently installed linker. */
-function linkProse(text) {
-	return current.link(text);
-}
-
-//#endregion
-export { linkProse, setProseLinker };