rspress-plugin-api-extractor 0.2.2 → 0.3.1

package/remark-with-api.js

@@ -1,13 +1,21 @@
-import { BuildMetrics } from "./layers/ObservabilityLive.js";
+import { PluginEvent } from "./observability/events.js";
 import { formatCode } from "./prettier-formatter.js";
 import { stripTwoslashDirectives } from "./markdown/helpers.js";
+import { TwoslashManager } from "./twoslash-transformer.js";
 import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
-import { Effect, Metric } from "effect";
 import { codeToHast, hastToHtml } from "shiki";
 import { visit } from "unist-util-visit";
 
 //#region src/remark-with-api.ts
-/* v8 ignore start -- remark plugin, requires MDX compilation context */
+/** Module-level emitter injected by plugin.ts at startup. */
+let emitEvent = () => {};
+let currentBuildId = "";
+let currentSlowCodeBlockMs = 500;
+function setRemarkWithApiEventEmitter(fn, buildId = "", slowCodeBlockMs = 500) {
+	emitEvent = fn;
+	currentBuildId = buildId;
+	currentSlowCodeBlockMs = slowCodeBlockMs;
+}
 /**
 * Supported languages for with-api code blocks
 * Based on GitHub Linguist standard aliases:
@@ -15,7 +23,7 @@ import { visit } from "unist-util-visit";
 * - JavaScript: javascript, js, node
 * - TSX/JSX: tsx, jsx (Shiki-supported)
 */
-const SUPPORTED_LANGUAGES = new Set([
+const SUPPORTED_LANGUAGES = /* @__PURE__ */ new Set([
 	"typescript",
 	"ts",
 	"javascript",
@@ -53,22 +61,20 @@ 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);
+			TwoslashManager.getInstance().setCurrentFile(currentFilePath);
 		}
 		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;
@@ -91,10 +97,19 @@ const remarkWithApi = (options) => {
 				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));
+				const isSlow = totalBlockTime > currentSlowCodeBlockMs;
+				emitEvent(PluginEvent.CodeBlockProcessed({
+					ctx: {
+						buildId: currentBuildId,
+						...currentFilePath != null ? { file: currentFilePath } : {}
+					},
+					lang,
+					shikiMs: shikiTime,
+					twoslashMs: totalBlockTime - shikiTime,
+					totalMs: totalBlockTime,
+					slow: isSlow,
+					level: "debug"
+				}));
 				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";
@@ -163,10 +178,8 @@ const remarkWithApi = (options) => {
 				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 };
+export { remarkWithApi, setRemarkWithApiEventEmitter };

package/route-collisions.js

@@ -49,4 +49,4 @@ function assertNoRouteCollisions(candidates, baseRoute) {
 }
 
 //#endregion
-export { assertNoRouteCollisions };
+export { assertNoRouteCollisions, detectRouteCollisions, formatRouteCollisionError };

package/runtime/components/ApiExample/index.js

@@ -5,13 +5,13 @@ import { Fragment, jsx } from "react/jsx-runtime";
 
 //#region src/runtime/components/ApiExample/index.tsx
 /**
-* Renders an example code block.
+* Renders an example code block in generated API documentation pages.
 *
-* 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 browser mode renders a Shiki-highlighted code block with copy and wrap
+* controls. In SSG-MD mode renders a plain fenced code block.
 *
-* In SSG-MD mode, renders a plain code block with the example code.
+* @param props - {@link ApiExampleProps}
+* @public
 */
 function ApiExample({ code, hast }) {
 	const parsedHast = useMemo(() => decodeHast(hast, "ApiExample"), [hast]);

package/runtime/components/ApiMember/index.js

@@ -5,15 +5,13 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/runtime/components/ApiMember/index.tsx
 /**
-* Renders an individual class/interface member signature block.
+* Renders an individual class or interface member signature block.
 *
-* Replaces MemberSignatureWrapper with a simpler component that takes plain
-* string props. The `code` prop contains only the member signature (not
-* wrapped in a class skeleton), and `summary` is plain markdown-compatible
-* text (not HTML with anchor tags, not base64-encoded).
+* In browser mode renders an `h3` heading with a Shiki-highlighted signature.
+* In SSG-MD mode renders a heading, summary, and plain fenced code block.
 *
-* In SSG-MD mode, renders a heading with member name, summary text,
-* and a plain code block with the member signature.
+* @param props - {@link ApiMemberProps}
+* @public
 */
 function ApiMember({ code, memberName, summary, id, hast, hasParameters }) {
 	const parsedHast = useMemo(() => decodeHast(hast, "ApiMember"), [hast]);

package/runtime/components/ApiSignature/index.js

@@ -7,13 +7,11 @@ import { Fragment, jsx } from "react/jsx-runtime";
 /**
 * Renders a full API type signature block.
 *
-* Replaces SignatureBlockWrapper with a simpler component that takes plain
-* string props (no base64 encoding for code). Produces clean semantic HTML
-* that RSPress converts to LLM-readable markdown in SSG-MD mode, and renders
-* interactive Shiki-highlighted code in browser mode.
+* In browser mode renders an interactive Shiki-highlighted code block.
+* In SSG-MD mode renders a plain fenced code block for LLM consumption.
 *
-* In SSG-MD mode, renders a "Signature" heading followed by a plain
-* code block with the type signature.
+* @param props - {@link ApiSignatureProps}
+* @public
 */
 function ApiSignature({ code, heading: _heading = "Signature", id: _id = "signature", hast, hasParameters, hasMembers }) {
 	const parsedHast = useMemo(() => decodeHast(hast, "ApiSignature"), [hast]);

package/runtime/components/EnumMembersTable/index.js

@@ -3,6 +3,11 @@ import index_module_default from "./index.module.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/runtime/components/EnumMembersTable/index.tsx
+/**
+* Renders a table of enum members with their values and descriptions.
+*
+* @public
+*/
 const EnumMembersTable = ({ members }) => {
 	if (!members || members.length === 0) return null;
 	if (import.meta.env.SSG_MD) {

package/runtime/components/ExampleBlock/index.js

@@ -9,9 +9,11 @@ import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/runtime/components/ExampleBlock/index.tsx
 /**
-* Code block for examples - displays syntax-highlighted code without a heading
-* Similar to SignatureBlock but without the "Signature" header
-* Includes both copy and wrap buttons in the toolbar
+* Code block for examples — displays syntax-highlighted code without a heading.
+* Similar to {@link SignatureBlock} but without the "Signature" header.
+* Includes both copy and wrap buttons in the toolbar.
+*
+* @internal
 */
 function ExampleBlock({ hast, code }) {
 	const { wrapped, toggleWrap } = useWrapToggle();

package/runtime/components/MemberSignature/index.js

@@ -8,8 +8,10 @@ import clsx from "clsx";
 
 //#region src/runtime/components/MemberSignature/index.tsx
 /**
-* Interactive member signature block with h3 header and wrap button
-* Displays syntax-highlighted TypeScript member signatures with hover tooltips
+* Interactive member signature block with h3 header and wrap button.
+* Displays syntax-highlighted TypeScript member signatures with hover tooltips.
+*
+* @internal
 */
 function MemberSignature({ hast, memberName, id, summary, hasParameters = false }) {
 	const { wrapped, toggleWrap } = useWrapToggle();

package/runtime/components/ParametersTable/index.js

@@ -3,6 +3,11 @@ import index_module_default from "./index.module.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/runtime/components/ParametersTable/index.tsx
+/**
+* Renders a table of function or method parameters with their types and descriptions.
+*
+* @public
+*/
 const ParametersTable = ({ parameters }) => {
 	if (!parameters || parameters.length === 0) return null;
 	if (import.meta.env.SSG_MD) {

package/runtime/components/SignatureBlock/index.js

@@ -8,8 +8,10 @@ import clsx from "clsx";
 
 //#region src/runtime/components/SignatureBlock/index.tsx
 /**
-* Interactive signature block with wrap button
-* Displays syntax-highlighted TypeScript signatures with hover tooltips
+* Interactive signature block with wrap button.
+* Displays syntax-highlighted TypeScript signatures with hover tooltips.
+*
+* @internal
 */
 function SignatureBlock({ hast, heading = "Signature", id = "signature", hasParameters = false }) {
 	const { wrapped, toggleWrap } = useWrapToggle();

package/runtime/components/shared/variables.css

@@ -65,18 +65,3 @@ html.rp-dark {
   --api-color-link-hover: #79c0ff;
   --api-color-code-bg: #6e768166;
 }
-
-html.rp-dark .rp-social-links__item {
-  background-color: var(--api-color-bg-secondary);
-  border-color: var(--api-color-border);
-  color: var(--api-color-text);
-}
-
-html.rp-dark .rp-social-links__item:hover {
-  background-color: var(--api-color-hover-bg);
-  border-color: var(--api-color-border-hover);
-}
-
-html.rp-dark .rp-social-links__item:active {
-  background-color: var(--api-color-active-bg);
-}