rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/loader.js

@@ -0,0 +1,186 @@
+import { ApiDocumentedItem, ApiItemKind } from "@microsoft/api-extractor-model";
+import { extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag } from "api-extractor-llms";
+
+//#region src/loader.ts
+/**
+* Parser for extracting and analyzing information from API Extractor models and TSDoc comments
+*/
+var ApiParser = class ApiParser {
+	/**
+	* Private constructor to prevent instantiation
+	*/
+	constructor() {}
+	/**
+	* Check if an API item has a custom modifier tag
+	*/
+	static hasModifierTag(item, tagName) {
+		return hasModifierTag(item, tagName);
+	}
+	/**
+	* Extract all API items from a package (or resolved entry items) and categorize them based on configuration.
+	*
+	* When passed a `ResolvedEntryItem[]`, uses the items directly (multi-entry support).
+	* When passed an `ApiPackage`, reads from `entryPoints[0]` (legacy single-entry behavior).
+	*/
+	static categorizeApiItems(source, categories) {
+		const items = {};
+		for (const categoryKey of Object.keys(categories)) items[categoryKey] = [];
+		let members;
+		if (Array.isArray(source)) members = source.map((r) => r.item);
+		else {
+			const entryPoint = source.entryPoints[0];
+			if (!entryPoint) return items;
+			members = entryPoint.members;
+		}
+		const sortedCategories = Object.entries(categories).sort((a, b) => {
+			const [, configA] = a;
+			const [, configB] = b;
+			if (configA.tsdocModifier && !configB.tsdocModifier) return -1;
+			if (!configA.tsdocModifier && configB.tsdocModifier) return 1;
+			return 0;
+		});
+		for (const member of members) {
+			let categorized = false;
+			for (const [categoryKey, config] of sortedCategories) {
+				if (config.tsdocModifier && ApiParser.hasModifierTag(member, config.tsdocModifier)) {
+					items[categoryKey].push(member);
+					categorized = true;
+					break;
+				}
+				if (config.itemKinds?.includes(member.kind)) {
+					items[categoryKey].push(member);
+					categorized = true;
+					break;
+				}
+			}
+			if (!categorized && typeof process !== "undefined" && !process.env.VITEST) console.warn(`⚠️  API item "${member.displayName}" (kind: ${member.kind}) not categorized`);
+		}
+		return items;
+	}
+	/**
+	* Extract all members from namespaces in a package (or resolved entry items).
+	* Returns a flat list of namespace members with their qualified names.
+	*
+	* When passed a `ResolvedEntryItem[]`, scans those items for namespaces (multi-entry support).
+	* When passed an `ApiPackage`, reads from `entryPoints[0]` (legacy single-entry behavior).
+	*
+	* @param source - The API package or resolved entry items to extract from
+	* @returns Array of namespace members with qualified names
+	*/
+	static extractNamespaceMembers(source) {
+		const members = [];
+		let topLevelItems;
+		if (Array.isArray(source)) topLevelItems = source.map((r) => r.item);
+		else {
+			const entryPoint = source.entryPoints[0];
+			if (!entryPoint) return members;
+			topLevelItems = entryPoint.members;
+		}
+		for (const item of topLevelItems) if (item.kind === ApiItemKind.Namespace) {
+			const namespace = item;
+			for (const member of namespace.members) members.push({
+				item: member,
+				namespace,
+				qualifiedName: `${namespace.displayName}.${member.displayName}`
+			});
+		}
+		return members;
+	}
+	/**
+	* Extract plain text from a TSDoc DocNode tree (prose form).
+	*
+	* Delegates to api-extractor-llms `extractPlainText`. Used internally for
+	* `@see` reference text, where `{@link}` targets are flattened to display text.
+	*/
+	static extractPlainText(node) {
+		return extractPlainText(node);
+	}
+	/**
+	* Get the summary text from an API item's TSDoc comment
+	*/
+	static getSummary(item) {
+		return getSummary(item);
+	}
+	/**
+	* Get the release tag (public, beta, alpha, internal) from an API item
+	*/
+	static getReleaseTag(item) {
+		return getReleaseTag(item);
+	}
+	/**
+	* Get parameter documentation from an API item's TSDoc comment
+	*/
+	static getParams(item) {
+		return getParams(item);
+	}
+	/**
+	* Get return value documentation from an API item's TSDoc comment
+	*/
+	static getReturns(item) {
+		return getReturns(item);
+	}
+	/**
+	* Get code examples from an API item's TSDoc comment
+	*/
+	static getExamples(item) {
+		return getExamples(item);
+	}
+	/**
+	* Get deprecation message from an API item's TSDoc comment
+	*/
+	static getDeprecation(item) {
+		return getDeprecation(item);
+	}
+	/**
+	* Get inheritance information from a class or interface
+	*/
+	static getInheritance(item) {
+		const result = {};
+		if (item.kind === ApiItemKind.Class) {
+			const apiClass = item;
+			if (apiClass.extendsType) result.extends = [apiClass.extendsType.excerpt.text];
+			const implementsTypes = apiClass.implementsTypes || [];
+			if (implementsTypes.length > 0) result.implements = implementsTypes.map((type) => type.excerpt.text);
+		} else if (item.kind === ApiItemKind.Interface) {
+			const extendsTypes = item.extendsTypes || [];
+			if (extendsTypes.length > 0) result.extends = extendsTypes.map((type) => type.excerpt.text);
+		}
+		return result;
+	}
+	/**
+	* Get see also references from an API item's TSDoc comment
+	*/
+	static getSeeReferences(item) {
+		if (item instanceof ApiDocumentedItem) {
+			const tsdoc = item.tsdocComment;
+			const references = [];
+			for (const seeBlock of tsdoc?.seeBlocks || []) {
+				const content = seeBlock.content;
+				const text = ApiParser.extractPlainText(content);
+				if (text.trim()) references.push({ text: text.replace(/\s+/g, " ").trim() });
+			}
+			return references;
+		}
+		return [];
+	}
+	/**
+	* Get source code link for an API item
+	* @param item - The API item
+	* @param sourceConfig - Source configuration with repository URL and ref
+	* @returns Source code URL with line number, or null if not available
+	*/
+	static getSourceLink(item, sourceConfig) {
+		if (!sourceConfig) return null;
+		const itemAny = item;
+		const filePath = itemAny.fileUrlPath || itemAny.filePath;
+		if (!filePath) return null;
+		const lineNumber = itemAny.fileLineNumber || itemAny.line;
+		const ref = sourceConfig.ref || "blob/main";
+		const baseUrl = `${sourceConfig.url}/${ref}`;
+		if (lineNumber) return `${baseUrl}/${filePath}#L${lineNumber}`;
+		return `${baseUrl}/${filePath}`;
+	}
+};
+
+//#endregion
+export { ApiParser };

package/markdown/cross-linker.js

@@ -0,0 +1,156 @@
+import { CrossLinker } from "api-extractor-llms";
+
+//#region src/markdown/cross-linker.ts
+/**
+* A cross-linking utility for markdown API documentation.
+*
+* This class maintains a mapping of API item names to their documentation routes,
+* enabling automatic cross-linking of type references in markdown content. It supports
+* both top-level exports and class/interface members.
+*
+* **How it works:**
+* 1. During initialization, it builds a route map from all API items in a package
+* 2. For classes and interfaces, it also maps their members (e.g., `ClassName.methodName`)
+* 3. When processing text, it replaces type names with markdown or HTML links
+*
+* **Relationships:**
+* - Initialized by {@link ApiExtractorPlugin} with categorized API items
+* - Used by page generators to add cross-links in documentation text
+* - Provides route/kind data to {@link ShikiCrossLinker} for code block linking
+*
+* **Link Formats:**
+* - Markdown: `[TypeName](/path/to/type)` - for use in .mdx content
+* - HTML: anchor tags with href - for use in JSX/components
+*
+* @example Initialization
+* ```ts
+* const crossLinker = new MarkdownCrossLinker();
+* const { routes, kinds } = crossLinker.initialize(
+*   categorizedItems,
+*   "/api/my-package",
+*   categories
+* );
+* ```
+*
+* @example Adding cross-links
+* ```ts
+* // Markdown format
+* const text = crossLinker.addCrossLinks("Returns a MyClass instance");
+* // Result: "Returns a [MyClass](/api/my-package/class/myclass) instance"
+*
+* // HTML format (for JSX)
+* const html = crossLinker.addCrossLinksHtml("Returns a MyClass instance");
+* // Result: "Returns a anchor-linked MyClass instance"
+* ```
+*
+* @see {@link ShikiCrossLinker} for code block cross-linking
+*/
+var MarkdownCrossLinker = class {
+	/**
+	* Map of API item names to their route paths for cross-linking
+	*/
+	apiItemRoutes = /* @__PURE__ */ new Map();
+	/**
+	* Clear all accumulated routes. Call at the start of each build.
+	*/
+	clear() {
+		this.apiItemRoutes.clear();
+	}
+	/**
+	* Add routes for API items. Accumulates across multiple calls.
+	* Call clear() first if starting a fresh build.
+	* @returns Object with routes map and kinds map for semantic highlighting
+	*/
+	addRoutes(items, baseRoute, categories) {
+		const apiItemKinds = /* @__PURE__ */ new Map();
+		for (const [categoryKey, categoryConfig] of Object.entries(categories)) {
+			const categoryItems = items[categoryKey] || [];
+			for (const item of categoryItems) {
+				const itemRoute = `${baseRoute}/${categoryConfig.folderName}/${item.displayName.toLowerCase()}`;
+				this.apiItemRoutes.set(item.displayName, itemRoute);
+				apiItemKinds.set(item.displayName, item.kind);
+				if ((item.kind === "Class" || item.kind === "Interface") && item.members) for (const member of item.members) {
+					const memberName = member.displayName;
+					const memberId = this.sanitizeId(memberName);
+					const fullMemberName = `${item.displayName}.${memberName}`;
+					const memberRoute = `${itemRoute}#${memberId}`;
+					this.apiItemRoutes.set(fullMemberName, memberRoute);
+					apiItemKinds.set(fullMemberName, member.kind);
+				}
+			}
+		}
+		return {
+			routes: this.apiItemRoutes,
+			kinds: apiItemKinds
+		};
+	}
+	/**
+	* Initialize the cross-link map with all API items.
+	* @deprecated Use clear() + addRoutes() instead.
+	* @returns Object with routes map and kinds map for semantic highlighting
+	*/
+	initialize(items, baseRoute, categories) {
+		this.clear();
+		return this.addRoutes(items, baseRoute, categories);
+	}
+	/**
+	* Set routes directly from pre-built route maps (e.g., from prepareWorkItems).
+	* Replaces all existing routes.
+	*/
+	setRoutes(routes) {
+		this.apiItemRoutes.clear();
+		for (const [name, route] of routes) this.apiItemRoutes.set(name, route);
+	}
+	/**
+	* Add cross-links to type references in code (markdown format).
+	*
+	* Skips matches inside backtick code spans and existing markdown links.
+	*/
+	addCrossLinks(text) {
+		if (this.apiItemRoutes.size === 0) return text;
+		return new CrossLinker(Array.from(this.apiItemRoutes.keys()).map((name) => ({
+			name,
+			kind: "type",
+			slug: name.toLowerCase()
+		})), (ref) => this.apiItemRoutes.get(ref.name) ?? "").addLinks(text);
+	}
+	/**
+	* Add cross-links to type references in code (HTML format)
+	* Use this when the text will be rendered as HTML (e.g., in React components)
+	*
+	* Note: intentionally hand-rolled and test-only — the upstream library's
+	* CrossLinker emits markdown links only, so the HTML path has no library
+	* equivalent.
+	*/
+	addCrossLinksHtml(text) {
+		let result = text;
+		const sortedNames = Array.from(this.apiItemRoutes.keys()).sort((a, b) => b.length - a.length);
+		for (const name of sortedNames) {
+			const route = this.apiItemRoutes.get(name);
+			if (!route) continue;
+			const regex = new RegExp(`\\b${name}\\b(?![a-zA-Z])`, "g");
+			result = result.replace(regex, (match, offset) => {
+				const beforeMatch = result.substring(0, offset);
+				if (beforeMatch.includes("<a") && !beforeMatch.includes("</a>")) return match;
+				return `<a href="${route}">${match}</a>`;
+			});
+		}
+		return result;
+	}
+	/**
+	* Sanitize a display name to create a valid HTML ID
+	* Converts to lowercase, replaces spaces/special chars with hyphens
+	*/
+	sanitizeId(displayName, prefix = "") {
+		const sanitized = displayName.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/^-+|-+$/g, "");
+		return prefix ? `${prefix}-${sanitized}` : sanitized;
+	}
+};
+/**
+* Module-level instance used by internal generator functions.
+* External callers should create their own instance or use this one.
+*/
+const markdownCrossLinker = new MarkdownCrossLinker();
+
+//#endregion
+export { MarkdownCrossLinker, markdownCrossLinker };

package/markdown/helpers.js

@@ -0,0 +1,364 @@
+import { classifyCutDirective, isTwoslashDirective } from "../twoslash-patterns.js";
+import { formatCode } from "../prettier-formatter.js";
+import { TypeReferenceExtractor } from "../type-reference-extractor.js";
+
+//#region src/markdown/helpers.ts
+/* v8 ignore start -- markdown generation helpers, tested via page generator integration tests */
+/**
+* Helper utilities for generating markdown API documentation.
+*
+* This module provides shared utility functions used by the page generators
+* for common tasks like preparing Twoslash examples, generating frontmatter,
+* escaping special characters, and sanitizing IDs.
+*
+* @packageDocumentation
+*/
+/**
+* Generate an "Available from" line for items exported from multiple entry points.
+* Returns empty string if only one entry point or none provided.
+*/
+function generateAvailableFrom(packageName, availableFrom) {
+	if (!availableFrom || availableFrom.length <= 1) return "";
+	return `Available from: ${availableFrom.map((ep) => ep === "default" ? `\`${packageName}\`` : `\`${packageName}/${ep}\``).join(", ")}\n\n`;
+}
+/**
+* Prepare example code for Twoslash rendering.
+*
+* Prepares the code with imports and error directives but does NOT render HTML.
+* Use this for raw markdown output or as input to pre-rendering.
+*
+* @param example - The example with language and code
+* @param apiItemName - The name of the API item being documented
+* @param packageName - The package name for imports
+* @param suppressErrors - Whether to suppress all TypeScript errors (default: true)
+* @returns Object with prepared code and whether it's TypeScript
+*/
+function prepareExampleCode(example, apiItemName, packageName, suppressErrors = true) {
+	const { language, code } = example;
+	if (!(language === "typescript" || language === "ts" || language === "javascript" || language === "js")) return {
+		code,
+		isTypeScript: false,
+		language
+	};
+	const importLine = `import { ${apiItemName} } from "${packageName}";`;
+	const finalCode = code.includes(`from "${packageName}"`) || code.includes(`from '${packageName}'`) ? code : `${importLine}\n${code}`;
+	return {
+		code: `${suppressErrors ? "// @noErrors\n" : ""}${finalCode}`,
+		isTypeScript: true,
+		language: "typescript"
+	};
+}
+/**
+* Sanitize a display name to create a URL-safe HTML ID.
+*
+* Converts a display name (e.g., method or property name) into a valid
+* HTML ID suitable for anchor links. Handles special characters, quotes,
+* and optionally adds a prefix for disambiguation.
+*
+* @param displayName - The original display name
+* @param prefix - Optional prefix to add (e.g., "static-property")
+* @returns URL-safe ID string
+*
+* @example
+* ```ts
+* sanitizeId("myMethod");        // "mymethod"
+* sanitizeId("get value");       // "get-value"
+* sanitizeId("run", "static");   // "static-run"
+* ```
+*/
+function sanitizeId(displayName, prefix = "") {
+	const baseName = displayName.replace(/["']/g, "").replace(/[^\w-]/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+	return prefix ? `${prefix}-${baseName}` : baseName;
+}
+/**
+* Escape a YAML string value by handling special characters.
+*
+* Normalizes whitespace and wraps strings in double quotes if they contain
+* characters that could break YAML parsing (colons, quotes, hashes, pipes,
+* brackets, braces, Unicode characters, etc.).
+*
+* @param value - The string value to escape
+* @returns YAML-safe string
+*
+* @example
+* ```ts
+* escapeYamlString("Hello World");           // "Hello World"
+* escapeYamlString("Type: string");          // "\"Type: string\""
+* escapeYamlString("He said \"hello\"");     // "\"He said \\\"hello\\\"\""
+* escapeYamlString("@pkg/name。:");          // "\"@pkg/name。:\""
+* ```
+*/
+function escapeYamlString(value) {
+	const cleaned = value.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
+	if (/["':#|>&*!%@`[\]{},?-]/.test(cleaned) || /[\u0080-\uFFFF]/.test(cleaned) || /^(true|false|null|~|yes|no|on|off)$/i.test(cleaned) || /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(cleaned)) return `"${cleaned.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+	return cleaned;
+}
+/**
+* Escape generic type parameters in MDX by wrapping them in backticks.
+*
+* Prevents MDX from interpreting `<T>`, `<TEnv>`, etc. as JSX tags by
+* wrapping them in inline code backticks.
+*
+* @param text - The text containing generic type parameters
+* @returns Text with generics wrapped in backticks
+*
+* @example
+* ```ts
+* escapeMdxGenerics("Returns Promise<T>");        // "Returns Promise`<T>`"
+* escapeMdxGenerics("Map<K, V> extends...");      // "Map`<K, V>` extends..."
+* escapeMdxGenerics("`Pipeline<I, O>`");           // "`Pipeline<I, O>`" (unchanged)
+* ```
+*/
+function escapeMdxGenerics(text) {
+	return text.split(/(`[^`]+`)/g).map((part) => {
+		if (part.startsWith("`") && part.endsWith("`")) return part;
+		return part.replace(/<([A-Z][A-Za-z0-9_]*(?:\s+extends\s+[^>]+)?(?:,\s*[A-Z][A-Za-z0-9_]*(?:\s+extends\s+[^>]+)?)*)>/g, "`<$1>`");
+	}).join("");
+}
+/**
+* Build a structured page title for API documentation.
+*
+* Creates a title in the format: `{entityName} | {singularName} | API | {apiName}`
+*
+* @param entityName - The specific entity name (e.g., "MyClass")
+* @param singularName - The category singular name (e.g., "Class")
+* @param apiName - Optional API/package display name
+* @returns Formatted page title
+*
+* @example
+* ```ts
+* buildPageTitle("MyClass", "Class", "My Package");
+* // Returns: "MyClass | Class | API | My Package"
+* ```
+*/
+function buildPageTitle(entityName, singularName, apiName) {
+	const parts = [
+		entityName,
+		singularName,
+		"API"
+	];
+	if (apiName) parts.push(apiName);
+	return parts.join(" | ");
+}
+/**
+* Generate markdown frontmatter with optional Open Graph metadata.
+*
+* Creates YAML frontmatter for MDX files including title, description,
+* and comprehensive Open Graph meta tags for social sharing.
+*
+* @param entityName - The specific entity name (e.g., "MyClass")
+* @param description - Page description for SEO
+* @param singularName - The category singular name (e.g., "Class")
+* @param apiName - Optional API/package display name
+* @param ogMetadata - Optional Open Graph metadata for social sharing
+* @returns YAML frontmatter string
+*
+* @example
+* ```ts
+* const frontmatter = generateFrontmatter(
+*   "MyClass",
+*   "A utility class for...",
+*   "Class",
+*   "My Package"
+* );
+* // Returns:
+* // ---
+* // title: MyClass | Class | API | My Package
+* // description: A utility class for...
+* // ---
+* ```
+*/
+function generateFrontmatter(entityName, description, singularName, apiName, ogMetadata) {
+	const title = buildPageTitle(entityName, singularName, apiName);
+	const headEntries = [];
+	if (ogMetadata) {
+		headEntries.push(["meta", {
+			property: "og:url",
+			content: `${ogMetadata.siteUrl}${ogMetadata.pageRoute}`
+		}]);
+		headEntries.push(["meta", {
+			property: "og:type",
+			content: ogMetadata.ogType
+		}]);
+		headEntries.push(["meta", {
+			property: "og:description",
+			content: ogMetadata.description
+		}]);
+		if (ogMetadata.ogImage) {
+			headEntries.push(["meta", {
+				property: "og:image",
+				content: ogMetadata.ogImage.url
+			}]);
+			if (ogMetadata.ogImage.secureUrl) headEntries.push(["meta", {
+				property: "og:image:secure_url",
+				content: ogMetadata.ogImage.secureUrl
+			}]);
+			if (ogMetadata.ogImage.type) headEntries.push(["meta", {
+				property: "og:image:type",
+				content: ogMetadata.ogImage.type
+			}]);
+			if (ogMetadata.ogImage.width) headEntries.push(["meta", {
+				property: "og:image:width",
+				content: String(ogMetadata.ogImage.width)
+			}]);
+			if (ogMetadata.ogImage.height) headEntries.push(["meta", {
+				property: "og:image:height",
+				content: String(ogMetadata.ogImage.height)
+			}]);
+			if (ogMetadata.ogImage.alt) headEntries.push(["meta", {
+				property: "og:image:alt",
+				content: ogMetadata.ogImage.alt
+			}]);
+		}
+		headEntries.push(["meta", {
+			property: "article:published_time",
+			content: ogMetadata.publishedTime
+		}]);
+		headEntries.push(["meta", {
+			property: "article:modified_time",
+			content: ogMetadata.modifiedTime
+		}]);
+		headEntries.push(["meta", {
+			property: "article:section",
+			content: ogMetadata.section
+		}]);
+		for (const tag of ogMetadata.tags) headEntries.push(["meta", {
+			property: "article:tag",
+			content: tag
+		}]);
+	}
+	let frontmatter = `---\ntitle: ${escapeYamlString(title)}\n`;
+	frontmatter += `description: ${escapeYamlString(description)}\n`;
+	if (headEntries.length > 0) {
+		frontmatter += "head:\n";
+		for (const [tag, attrs] of headEntries) {
+			frontmatter += `  - - ${tag}\n`;
+			frontmatter += "    - ";
+			const attrPairs = Object.entries(attrs).map(([key, value]) => `${key}: ${escapeYamlString(value)}`);
+			frontmatter += attrPairs.join("\n      ");
+			frontmatter += "\n";
+		}
+	}
+	frontmatter += "---\n\n";
+	return frontmatter;
+}
+/**
+* Strip Twoslash directives from code for display purposes.
+*
+* Removes Twoslash directive comments like `// @noErrors`, `// @errors: 2304`,
+* `// @filename: ...`, etc. from code so users see clean output and don't
+* copy directives when using the copy button.
+*
+* Also handles cut directives:
+* - `// ---cut---` - Removes this line and all lines before it
+* - `// ---cut-before---` - Same as ---cut---
+* - `// ---cut-after---` - Removes this line and all lines after it
+*
+* @param code - The code containing Twoslash directives
+* @returns Code with Twoslash directives removed
+*
+* @example
+* ```ts
+* const display = stripTwoslashDirectives("// @noErrors\nconst x = 1;");
+* // Returns: "const x = 1;"
+* ```
+*/
+function stripTwoslashDirectives(code) {
+	const lines = code.split("\n");
+	let cutBeforeIndex = -1;
+	let cutAfterIndex = -1;
+	const cutRanges = [];
+	const cutStartStack = [];
+	for (let i = 0; i < lines.length; i++) {
+		const cutType = classifyCutDirective(lines[i].trim());
+		if (cutType === "cut-before") cutBeforeIndex = i;
+		else if (cutType === "cut-after") cutAfterIndex = i;
+		else if (cutType === "cut-start") cutStartStack.push(i);
+		else if (cutType === "cut-end") {
+			const startIdx = cutStartStack.pop();
+			if (startIdx !== void 0) cutRanges.push([startIdx, i]);
+		}
+	}
+	let filteredLines = lines;
+	if (cutBeforeIndex >= 0) {
+		filteredLines = filteredLines.slice(cutBeforeIndex + 1);
+		if (cutAfterIndex >= 0) cutAfterIndex = cutAfterIndex - cutBeforeIndex - 1;
+		for (const range of cutRanges) {
+			range[0] -= cutBeforeIndex + 1;
+			range[1] -= cutBeforeIndex + 1;
+		}
+	}
+	if (cutAfterIndex >= 0) filteredLines = filteredLines.slice(0, cutAfterIndex);
+	const excludedLines = /* @__PURE__ */ new Set();
+	for (const [start, end] of cutRanges) for (let i = start; i <= end; i++) if (i >= 0 && i < filteredLines.length) excludedLines.add(i);
+	return filteredLines.filter((line, i) => {
+		if (excludedLines.has(i)) return false;
+		if (isTwoslashDirective(line.trim())) return false;
+		return true;
+	}).join("\n").trim();
+}
+/**
+* Format import statements with cut directive for hidden imports.
+*
+* Prepends import statements followed by `// ---cut---` so Twoslash can
+* resolve the types but the imports are hidden from rendered output.
+*
+* @param imports - Import statements to format
+* @returns Formatted import block with cut directive, or empty string if no imports
+*
+* @example
+* ```ts
+* const imports = [{ packageName: "zod", symbols: new Set(["ZodType"]), typeOnly: true }];
+* const block = formatImportsWithCut(imports);
+* // Returns:
+* // import type { ZodType } from "zod";
+* // // ---cut---
+* ```
+*/
+function formatImportsWithCut(imports) {
+	if (imports.length === 0) return "";
+	return `${TypeReferenceExtractor.formatImports(imports).join("\n")}\n// ---cut---\n`;
+}
+/**
+* Prepend hidden imports to code using the Twoslash cut directive.
+*
+* This enables type resolution for external types while hiding the import
+* statements from rendered output. The existing `stripTwoslashDirectives()`
+* function handles removing the cut block for clipboard copying.
+*
+* @param code - The code to prepend imports to
+* @param imports - Import statements to add
+* @returns Code with imports prepended (if any), or original code if no imports
+*
+* @example
+* ```ts
+* const code = "function foo(): RsbuildPlugin";
+* const imports = [{ packageName: "@rsbuild/core", symbols: new Set(["RsbuildPlugin"]), typeOnly: true }];
+* const result = prependHiddenImports(code, imports);
+* // Returns:
+* // import type { RsbuildPlugin } from "@rsbuild/core";
+* // // ---cut---
+* // function foo(): RsbuildPlugin
+* ```
+*/
+function prependHiddenImports(code, imports) {
+	const importBlock = formatImportsWithCut(imports);
+	return importBlock ? importBlock + code : code;
+}
+/**
+* Format example code using Prettier for consistent styling.
+*
+* Wraps the Prettier formatter with error handling and context tracking.
+* If formatting fails, returns the original code (fallthrough behavior).
+*
+* @param code - The code to format
+* @param language - The code fence language (e.g., "typescript", "ts")
+* @param _context - Optional context (reserved for future use)
+* @returns The formatted code (or original if formatting fails)
+*/
+async function formatExampleCode(code, language, _context) {
+	return (await formatCode(code, language)).code;
+}
+
+//#endregion
+export { escapeMdxGenerics, escapeYamlString, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives };