rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/prettier-formatter.js

@@ -0,0 +1,73 @@
+import { BuildMetrics } from "./layers/ObservabilityLive.js";
+import { addLogicalBlankLines } from "./code-post-processor.js";
+import { Effect, Metric } from "effect";
+import { format } from "prettier";
+
+//#region src/prettier-formatter.ts
+/* v8 ignore start -- Prettier integration wrapper, tested via page generator integration tests */
+/**
+* Map code fence languages to Prettier parsers
+*/
+const LANGUAGE_TO_PARSER = {
+	typescript: "typescript",
+	ts: "typescript",
+	tsx: "typescript",
+	javascript: "babel",
+	js: "babel",
+	jsx: "babel",
+	node: "babel"
+};
+/**
+* Default Prettier options for consistent formatting
+*/
+const PRETTIER_OPTIONS = {
+	printWidth: 80,
+	tabWidth: 2,
+	useTabs: false,
+	semi: true,
+	singleQuote: false,
+	trailingComma: "es5",
+	bracketSpacing: true,
+	arrowParens: "always"
+};
+/**
+* Format code using Prettier
+*
+* @param code - The code to format
+* @param language - The code fence language (e.g., "typescript", "ts", "js")
+* @returns FormatResult with formatted code and metadata
+*/
+async function formatCode(code, language) {
+	const start = performance.now();
+	const parser = LANGUAGE_TO_PARSER[language.toLowerCase()];
+	if (!parser) return {
+		code,
+		success: true,
+		formatTime: performance.now() - start
+	};
+	try {
+		const formatted = await format(code, {
+			...PRETTIER_OPTIONS,
+			parser
+		});
+		const formatTime = performance.now() - start;
+		return {
+			code: addLogicalBlankLines(formatted.trim()),
+			success: true,
+			formatTime
+		};
+	} catch (error) {
+		const formatTime = performance.now() - start;
+		const errorMsg = error instanceof Error ? error.message : String(error);
+		Effect.runSync(Metric.increment(BuildMetrics.prettierErrors));
+		return {
+			code,
+			success: false,
+			error: errorMsg,
+			formatTime
+		};
+	}
+}
+
+//#endregion
+export { formatCode };

package/public/tsconfig/rspress.json

@@ -0,0 +1,44 @@
+{
+	"$schema": "https://json.schemastore.org/tsconfig.json",
+	"compilerOptions": {
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx",
+		"lib": ["dom", "es2023"],
+		"module": "esnext",
+		"moduleDetection": "force",
+		"moduleResolution": "bundler",
+		"noEmit": true,
+		"noUncheckedSideEffectImports": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"target": "es2023",
+		"types": ["node", "react", "react-dom"],
+		"useDefineForClassFields": true,
+		"verbatimModuleSyntax": true
+	},
+	"exclude": ["${configDir}/node_modules", "${configDir}/dist", "${configDir}/.rspress"],
+	"include": [
+		"${configDir}/types/*.ts",
+		"${configDir}/package.json",
+		"${configDir}/*.ts",
+		"${configDir}/*.cts",
+		"${configDir}/*.mts",
+		"${configDir}/lib/**/*.ts",
+		"${configDir}/lib/**/*.tsx",
+		"${configDir}/lib/**/*.cts",
+		"${configDir}/lib/**/*.mts",
+		"${configDir}/docs/**/*.ts",
+		"${configDir}/docs/**/*.tsx",
+		"${configDir}/docs/**/*.mdx",
+		"${configDir}/theme/**/*.ts",
+		"${configDir}/theme/**/*.tsx",
+		"${configDir}/theme/**/*.mdx"
+	],
+	"mdx": {
+		"checkMdx": true
+	}
+}

package/remark-api-codeblocks.js

@@ -0,0 +1,130 @@
+import { VfsRegistry } from "./vfs-registry.js";
+import { generateShikiHast } from "./markdown/shiki-utils.js";
+import { visit } from "./node_modules/.pnpm/unist-util-visit@5.1.0/node_modules/unist-util-visit/lib/index.js";
+
+//#region src/remark-api-codeblocks.ts
+/**
+* Create an MDX JSX attribute value expression with proper estree AST.
+* This ensures the value is properly serialized as a JavaScript string literal.
+*
+* @param value - The string value to wrap
+* @returns An MdxJsxAttributeValueExpression node
+*/
+function createExpressionValue(value) {
+	const escaped = JSON.stringify(value);
+	return {
+		type: "mdxJsxAttributeValueExpression",
+		value: escaped,
+		data: { estree: {
+			type: "Program",
+			sourceType: "module",
+			body: [{
+				type: "ExpressionStatement",
+				expression: {
+					type: "Literal",
+					value,
+					raw: escaped
+				}
+			}]
+		} }
+	};
+}
+/**
+* Extract a string value from a JSX attribute on an MdxJsxFlowElement.
+* Handles both plain string attributes and expression attributes with estree literals.
+*
+* @param node - The JSX element node
+* @param attrName - The attribute name to extract
+* @returns The string value, or undefined if not found
+*/
+function getJsxAttrStringValue(node, attrName) {
+	for (const attr of node.attributes) {
+		if (attr.type !== "mdxJsxAttribute" || attr.name !== attrName) continue;
+		if (typeof attr.value === "string") return attr.value;
+		if (attr.value?.type === "mdxJsxAttributeValueExpression" && attr.value.data?.estree) {
+			const body = attr.value.data.estree.body;
+			if (body?.length > 0 && body[0].type === "ExpressionStatement") {
+				const expr = body[0].expression;
+				if (expr.type === "Literal" && typeof expr.value === "string") return expr.value;
+			}
+		}
+	}
+}
+/**
+* Remove named attributes from a JSX element node.
+*
+* @param node - The JSX element node
+* @param attrNames - Array of attribute names to remove
+*/
+function removeJsxAttrs(node, attrNames) {
+	const removeSet = new Set(attrNames);
+	node.attributes = node.attributes.filter((attr) => {
+		if (attr.type !== "mdxJsxAttribute") return true;
+		return !removeSet.has(attr.name);
+	});
+}
+/**
+* Remark plugin that processes API JSX components for browser rendering.
+*
+* This plugin:
+* 1. Visits JSX component nodes (ApiSignature, ApiMember, ApiExample) in the MDX tree
+* 2. Reads `source` and `apiScope` props emitted by page generators
+* 3. Looks up VFS configuration and runs Shiki with appropriate transformers
+* 4. Injects the resulting HAST as a base64-encoded `hast` prop
+* 5. Removes build-time `source` and `apiScope` props
+*
+* In SSG-MD mode, the plugin simply removes build-time props and lets the
+* components render their own clean HTML for markdown conversion.
+*/
+const remarkApiCodeblocks = () => {
+	return async function remarkTransformer(tree, file) {
+		if (!VfsRegistry.hasConfigs()) return;
+		const promises = [];
+		const isSsgMd = import.meta.env?.SSG_MD || process.env.RSBUILD_ENVIRONMENT === "node_md" || process.env.BUILD_TARGET === "node_md";
+		const currentFilePath = file.path || "unknown";
+		const jsxComponentNames = new Set([
+			"ApiSignature",
+			"ApiMember",
+			"ApiExample"
+		]);
+		visit(tree, "mdxJsxFlowElement", (node) => {
+			if (!node.name || !jsxComponentNames.has(node.name)) return;
+			const source = getJsxAttrStringValue(node, "source");
+			const apiScopeValue = getJsxAttrStringValue(node, "apiScope");
+			if (!source || !apiScopeValue) return;
+			const promise = (async () => {
+				if (isSsgMd) {
+					removeJsxAttrs(node, ["source", "apiScope"]);
+					return;
+				}
+				const vfsConfig = VfsRegistry.get(apiScopeValue);
+				if (!vfsConfig) {
+					console.warn(`[remark-api-codeblocks] No VFS config found for scope "${apiScopeValue}" in ${currentFilePath}`);
+					removeJsxAttrs(node, ["source", "apiScope"]);
+					return;
+				}
+				const transformers = [];
+				if (node.name === "ApiExample" && vfsConfig.twoslashTransformer) transformers.push(vfsConfig.twoslashTransformer);
+				else if (node.name === "ApiMember" && vfsConfig.hideCutTransformer) transformers.push(vfsConfig.hideCutTransformer);
+				else if (node.name === "ApiSignature") {
+					if (vfsConfig.hideCutLinesTransformer) transformers.push(vfsConfig.hideCutLinesTransformer);
+				}
+				const isExample = node.name === "ApiExample" && !!vfsConfig.twoslashTransformer;
+				let hast = await generateShikiHast(source, vfsConfig.highlighter, transformers.length > 0 ? transformers : void 0, isExample, vfsConfig.theme);
+				if (hast && vfsConfig.crossLinker) hast = vfsConfig.crossLinker.transformHast(hast, apiScopeValue);
+				const hastBase64 = hast ? Buffer.from(JSON.stringify(hast), "utf-8").toString("base64") : "";
+				node.attributes.push({
+					type: "mdxJsxAttribute",
+					name: "hast",
+					value: createExpressionValue(hastBase64)
+				});
+				removeJsxAttrs(node, ["source", "apiScope"]);
+			})();
+			promises.push(promise);
+		});
+		await Promise.all(promises);
+	};
+};
+
+//#endregion
+export { remarkApiCodeblocks };

package/remark-with-api.js

@@ -0,0 +1,172 @@
+import { BuildMetrics } from "./layers/ObservabilityLive.js";
+import { formatCode } from "./prettier-formatter.js";
+import { stripTwoslashDirectives } from "./markdown/helpers.js";
+import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
+import { visit } from "./node_modules/.pnpm/unist-util-visit@5.1.0/node_modules/unist-util-visit/lib/index.js";
+import { Effect, Metric } from "effect";
+import { codeToHast, hastToHtml } from "shiki";
+
+//#region src/remark-with-api.ts
+/* v8 ignore start -- remark plugin, requires MDX compilation context */
+/**
+* Supported languages for with-api code blocks
+* Based on GitHub Linguist standard aliases:
+* - TypeScript: typescript, ts
+* - JavaScript: javascript, js, node
+* - TSX/JSX: tsx, jsx (Shiki-supported)
+*/
+const SUPPORTED_LANGUAGES = new Set([
+	"typescript",
+	"ts",
+	"javascript",
+	"js",
+	"node",
+	"tsx",
+	"jsx"
+]);
+/**
+* Infer API scope from file path
+* Path structure: docs/en/api-name/rest-of-path.mdx
+*/
+function inferApiScope(filePath) {
+	const match = filePath.replace(/\\/g, "/").match(/(?:^|\/)(docs\/en|website\/docs\/en)\/([^/]+)(?:\/|$)/);
+	if (!match) return;
+	return match[2];
+}
+/**
+* Remark plugin that transforms `with-api` code blocks into ApiExample components
+*
+* Usage in markdown:
+* ```typescript with-api
+* import { ClaudeBinaryPlugin } from "claude-binary-plugin";
+* // Full twoslash support: @noErrors, @errors, ^?, etc.
+* ```
+*
+* The plugin:
+* 1. Detects code blocks with `with-api` in the meta string
+* 2. Supports typescript, ts, tsx, javascript, js, jsx languages
+* 3. Processes with Twoslash for type information
+* 4. Applies API docs cross-linker for type reference links
+* 5. Renders to ApiExample component with pre-rendered Shiki HAST
+*/
+const remarkWithApi = (options) => {
+	const { shikiCrossLinker, getTransformer, theme } = options;
+	const resolvedTheme = theme ?? DEFAULT_SHIKI_THEMES;
+	return async function remarkTransformer(tree, file) {
+		const fileStart = performance.now();
+		const promises = [];
+		let blockCount = 0;
+		let needsApiExampleImport = false;
+		const isSsgMd = import.meta.env?.SSG_MD || process.env.RSBUILD_ENVIRONMENT === "node_md" || process.env.BUILD_TARGET === "node_md";
+		const currentFilePath = file.path;
+		if (currentFilePath) {
+			const apiScope = inferApiScope(currentFilePath);
+			if (apiScope) shikiCrossLinker.setApiScope(apiScope);
+		}
+		visit(tree, "code", (node, index, parent) => {
+			const hasWithApi = node.meta?.includes("with-api");
+			const lang = node.lang || "typescript";
+			const isSupported = SUPPORTED_LANGUAGES.has(lang);
+			if (!hasWithApi || !isSupported) return;
+			blockCount++;
+			const promise = (async () => {
+				const blockStart = performance.now();
+				const rawCode = node.value;
+				const code = (await formatCode(rawCode, lang)).code;
+				const twoslashTransformer = getTransformer();
+				const transformers = twoslashTransformer ? [twoslashTransformer] : [];
+				const shikiStart = performance.now();
+				let hast = await codeToHast(code, {
+					lang,
+					meta: { __raw: "twoslash" },
+					themes: {
+						light: resolvedTheme.light,
+						dark: resolvedTheme.dark
+					},
+					defaultColor: false,
+					cssVariablePrefix: "--api-shiki-",
+					transformers
+				});
+				const apiScope = currentFilePath ? inferApiScope(currentFilePath) : void 0;
+				if (apiScope) hast = shikiCrossLinker.transformHast(hast, apiScope);
+				const shikiTime = performance.now() - shikiStart;
+				const totalBlockTime = performance.now() - blockStart;
+				Effect.runSync(Metric.increment(BuildMetrics.codeblockTotal));
+				Effect.runSync(Metric.update(BuildMetrics.codeblockDuration, totalBlockTime));
+				if (shikiTime > 0) Effect.runSync(Metric.update(BuildMetrics.codeblockShikiDuration, shikiTime));
+				if (totalBlockTime > 100) Effect.runSync(Metric.increment(BuildMetrics.codeblockSlow));
+				if (parent && typeof index === "number") if (isSsgMd) {
+					const cleanCode = hastToHtml(hast).replace(/<[^>]*>/g, "").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").trim();
+					node.lang = "typescript";
+					node.meta = void 0;
+					node.value = cleanCode;
+				} else {
+					const displayCode = stripTwoslashDirectives(code);
+					const hastJson = JSON.stringify(hast);
+					const mdxNode = {
+						type: "mdxJsxFlowElement",
+						name: "ApiExample",
+						attributes: [{
+							type: "mdxJsxAttribute",
+							name: "code",
+							value: displayCode
+						}, {
+							type: "mdxJsxAttribute",
+							name: "hast",
+							value: hastJson
+						}],
+						children: []
+					};
+					parent.children[index] = mdxNode;
+					needsApiExampleImport = true;
+				}
+			})();
+			promises.push(promise);
+		});
+		await Promise.all(promises);
+		if (needsApiExampleImport) {
+			if (!tree.children.some((node) => {
+				const n = node;
+				return n.type === "mdxjsEsm" && typeof n.value === "string" && n.value.includes("ApiExample");
+			})) {
+				const importNode = {
+					type: "mdxjsEsm",
+					value: "import { ApiExample } from \"rspress-plugin-api-extractor/runtime\";",
+					data: { estree: {
+						type: "Program",
+						body: [{
+							type: "ImportDeclaration",
+							specifiers: [{
+								type: "ImportSpecifier",
+								imported: {
+									type: "Identifier",
+									name: "ApiExample"
+								},
+								local: {
+									type: "Identifier",
+									name: "ApiExample"
+								}
+							}],
+							source: {
+								type: "Literal",
+								value: "rspress-plugin-api-extractor/runtime"
+							}
+						}],
+						sourceType: "module"
+					} }
+				};
+				let insertIndex = 0;
+				for (let i = 0; i < tree.children.length; i++) if (tree.children[i].type === "yaml") {
+					insertIndex = i + 1;
+					break;
+				}
+				tree.children.splice(insertIndex, 0, importNode);
+			}
+		}
+		const fileTime = performance.now() - fileStart;
+		if (blockCount > 0) console.log(`⏱️  [remark-with-api] Processed ${blockCount} blocks in ${fileTime.toFixed(0)}ms (avg: ${(fileTime / blockCount).toFixed(0)}ms per block)`);
+	};
+};
+
+//#endregion
+export { remarkWithApi };

package/route-collisions.js

@@ -0,0 +1,52 @@
+//#region src/route-collisions.ts
+/**
+* Group candidates by their final route (`${folder}/${baseName}`) and return the
+* groups with more than one distinct item. The route key is the lowercased path
+* the file is written to, so detection matches generation (and what a
+* case-insensitive filesystem would merge). Companion pairs (same name, different
+* folders) land under different keys and are never collisions.
+*
+* Output is deterministic: collisions ordered by route, items within a collision
+* ordered by canonicalReference.
+*/
+function detectRouteCollisions(candidates) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const key = `${candidate.folder}/${candidate.baseName}`;
+		const group = byKey.get(key) ?? [];
+		group.push(candidate);
+		byKey.set(key, group);
+	}
+	const collisions = [];
+	for (const [route, group] of byKey) if (group.length > 1) {
+		const items = [...group].sort((a, b) => a.canonicalRef < b.canonicalRef ? -1 : a.canonicalRef > b.canonicalRef ? 1 : 0);
+		collisions.push({
+			route,
+			items
+		});
+	}
+	collisions.sort((a, b) => a.route < b.route ? -1 : a.route > b.route ? 1 : 0);
+	return collisions;
+}
+/** Build an actionable build-time error message for one or more route collisions. */
+function formatRouteCollisionError(collisions, baseRoute) {
+	const lines = [];
+	for (const collision of collisions) {
+		lines.push(`Route collision: ${collision.items.length} API items resolve to the same documentation path "${baseRoute}/${collision.route}":`);
+		for (const item of collision.items) lines.push(`  - ${item.displayName} (${item.kind})  [${item.canonicalRef}]`);
+	}
+	lines.push("");
+	lines.push("Item names must be unique per category folder. Paths are lowercased, so names differing only in case collide. Rename one of the items, or configure categories so they map to different folders.");
+	return `[rspress-plugin-api-extractor] ${lines.join("\n")}`;
+}
+/**
+* Throw a descriptive error if any distinct items resolve to the same route.
+* Called at build time before pages are generated, so collisions fail fast.
+*/
+function assertNoRouteCollisions(candidates, baseRoute) {
+	const collisions = detectRouteCollisions(candidates);
+	if (collisions.length > 0) throw new Error(formatRouteCollisionError(collisions, baseRoute));
+}
+
+//#endregion
+export { assertNoRouteCollisions };

package/runtime/components/ApiExample/index.js

@@ -1,29 +1,33 @@
-import { Fragment, jsx } from "react/jsx-runtime";
-import { createElement, useMemo } from "react";
 import { decodeHast } from "../../utils/decode-hast.js";
 import { ExampleBlock } from "../ExampleBlock/index.js";
+import { createElement, useMemo } from "react";
+import { Fragment, jsx } from "react/jsx-runtime";
+
+//#region src/runtime/components/ApiExample/index.tsx
+/**
+* Renders an example code block.
+*
+* Replaces ExampleBlockWrapper with a simpler component that takes a plain
+* code string (no base64, no HAST for code). The code should already have
+* Twoslash directives stripped.
+*
+* In SSG-MD mode, renders a plain code block with the example code.
+*/
 function ApiExample({ code, hast }) {
-    const parsedHast = useMemo(()=>decodeHast(hast, "ApiExample"), [
-        hast
-    ]);
-    if (import.meta.env.SSG_MD) {
-        const header = "```typescript\n";
-        const footer = "\n```\n";
-        return /*#__PURE__*/ jsx(Fragment, {
-            children: `${header}${code.trim()}${footer}`
-        });
-    }
-    if (parsedHast) return /*#__PURE__*/ createElement(ExampleBlock, {
-        hast: parsedHast,
-        code: code.trim()
-    });
-    return /*#__PURE__*/ jsx("pre", {
-        children: /*#__PURE__*/ jsx("code", {
-            className: "language-typescript",
-            children: code.trim()
-        })
-    });
+	const parsedHast = useMemo(() => decodeHast(hast, "ApiExample"), [hast]);
+	if (import.meta.env.SSG_MD) return /* @__PURE__ */ jsx(Fragment, { children: `\`\`\`typescript
+${code.trim()}
+\`\`\`
+` });
+	if (parsedHast) return createElement(ExampleBlock, {
+		hast: parsedHast,
+		code: code.trim()
+	});
+	return /* @__PURE__ */ jsx("pre", { children: /* @__PURE__ */ jsx("code", {
+		className: "language-typescript",
+		children: code.trim()
+	}) });
 }
-const components_ApiExample = ApiExample;
-export default components_ApiExample;
-export { ApiExample };
+
+//#endregion
+export { ApiExample, ApiExample as default };