rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/remark-api-codeblocks.js

@@ -1,17 +1,12 @@
 import { PluginEvent } from "./observability/events.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
+import { emitSync, syncBuildId, syncSlowCodeBlockMs } from "./observability/sync-emitter.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateShikiHast } from "./markdown/shiki-utils.js";
+import { setTwoslashFile } from "./twoslash-access.js";
+import { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { visit } from "unist-util-visit";
 
 //#region src/remark-api-codeblocks.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-function setRemarkApiCodeblocksEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
 /**
 * Create an MDX JSX attribute value expression with proper estree AST.
 * This ensures the value is properly serialized as a JavaScript string literal.
@@ -91,7 +86,7 @@ const remarkApiCodeblocks = () => {
 		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";
-		if (file.path) TwoslashManager.getInstance().setCurrentFile(file.path);
+		if (file.path) setTwoslashFile(file.path);
 		const jsxComponentNames = /* @__PURE__ */ new Set([
 			"ApiSignature",
 			"ApiMember",
@@ -109,9 +104,9 @@ const remarkApiCodeblocks = () => {
 				}
 				const vfsConfig = VfsRegistry.get(apiScopeValue);
 				if (!vfsConfig) {
-					emitEvent(PluginEvent.ConfigCascadeWarning({
+					emitSync(PluginEvent.ConfigCascadeWarning({
 						ctx: {
-							buildId: currentBuildId,
+							buildId: syncBuildId(),
 							file: currentFilePath
 						},
 						field: "vfs",
@@ -123,14 +118,37 @@ const remarkApiCodeblocks = () => {
 					return;
 				}
 				const transformers = [];
-				if (node.name === "ApiExample" && vfsConfig.twoslashTransformer) transformers.push(vfsConfig.twoslashTransformer);
+				let twoslashMs = 0;
+				if (node.name === "ApiExample" && vfsConfig.twoslashTransformer) transformers.push(createTwoslashTimingWrapper(vfsConfig.twoslashTransformer, (duration) => {
+					twoslashMs += duration;
+				}));
 				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 shikiStart = performance.now();
+				const hastPromise = generateShikiHast(source, vfsConfig.highlighter, transformers.length > 0 ? transformers : void 0, isExample, vfsConfig.theme);
+				const renderMs = performance.now() - shikiStart;
+				let hast = await hastPromise;
+				const postStart = performance.now();
+				if (hast && vfsConfig.crossLinker) hast = vfsConfig.crossLinker.transformHast(hast);
+				const totalBlockTime = renderMs + (performance.now() - postStart);
+				emitSync(PluginEvent.CodeBlockProcessed({
+					ctx: {
+						buildId: syncBuildId(),
+						apiScope: apiScopeValue,
+						file: currentFilePath
+					},
+					lang: "typescript",
+					component: node.name,
+					twoslash: isExample,
+					twoslashMs,
+					shikiMs: Math.max(0, renderMs - twoslashMs),
+					totalMs: totalBlockTime,
+					slow: totalBlockTime > syncSlowCodeBlockMs(),
+					level: "debug"
+				}));
 				const hastBase64 = hast ? Buffer.from(JSON.stringify(hast), "utf-8").toString("base64") : "";
 				node.attributes.push({
 					type: "mdxJsxAttribute",
@@ -146,4 +164,4 @@ const remarkApiCodeblocks = () => {
 };
 
 //#endregion
-export { remarkApiCodeblocks, setRemarkApiCodeblocksEventEmitter };
+export { remarkApiCodeblocks };

package/remark-with-api.js

@@ -1,21 +1,15 @@
 import { PluginEvent } from "./observability/events.js";
+import { emitSync, syncBuildId, syncSlowCodeBlockMs } from "./observability/sync-emitter.js";
 import { formatCode } from "./prettier-formatter.js";
 import { stripTwoslashDirectives } from "./markdown/helpers.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
+import { VfsRegistry } from "./vfs-registry.js";
 import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
+import { setTwoslashFile } from "./twoslash-access.js";
+import { createTwoslashTimingWrapper } from "./twoslash-timing-wrapper.js";
 import { codeToHast, hastToHtml } from "shiki";
 import { visit } from "unist-util-visit";
 
 //#region src/remark-with-api.ts
-/** 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:
@@ -58,18 +52,14 @@ function inferApiScope(filePath) {
 * 5. Renders to ApiExample component with pre-rendered Shiki HAST
 */
 const remarkWithApi = (options) => {
-	const { shikiCrossLinker, getTransformer, theme } = options;
+	const { getTransformer, theme } = options;
 	const resolvedTheme = theme ?? DEFAULT_SHIKI_THEMES;
 	return async function remarkTransformer(tree, file) {
 		const promises = [];
 		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);
-		}
+		if (currentFilePath) setTwoslashFile(currentFilePath);
 		visit(tree, "code", (node, index, parent) => {
 			const hasWithApi = node.meta?.includes("with-api");
 			const lang = node.lang || "typescript";
@@ -78,9 +68,13 @@ const remarkWithApi = (options) => {
 			const promise = (async () => {
 				const blockStart = performance.now();
 				const rawCode = node.value;
+				const apiScope = currentFilePath ? inferApiScope(currentFilePath) : void 0;
 				const code = (await formatCode(rawCode, lang)).code;
-				const twoslashTransformer = getTransformer();
-				const transformers = twoslashTransformer ? [twoslashTransformer] : [];
+				let twoslashMs = 0;
+				const twoslashTransformer = getTransformer(apiScope);
+				const transformers = twoslashTransformer ? [createTwoslashTimingWrapper(twoslashTransformer, (duration) => {
+					twoslashMs += duration;
+				})] : [];
 				const shikiStart = performance.now();
 				let hast = await codeToHast(code, {
 					lang,
@@ -93,19 +87,22 @@ const remarkWithApi = (options) => {
 					cssVariablePrefix: "--api-shiki-",
 					transformers
 				});
-				const apiScope = currentFilePath ? inferApiScope(currentFilePath) : void 0;
-				if (apiScope) hast = shikiCrossLinker.transformHast(hast, apiScope);
-				const shikiTime = performance.now() - shikiStart;
+				const renderMs = performance.now() - shikiStart;
+				const scopeLinker = apiScope ? VfsRegistry.get(apiScope)?.crossLinker : void 0;
+				if (scopeLinker) hast = scopeLinker.transformHast(hast);
 				const totalBlockTime = performance.now() - blockStart;
-				const isSlow = totalBlockTime > currentSlowCodeBlockMs;
-				emitEvent(PluginEvent.CodeBlockProcessed({
+				const isSlow = totalBlockTime > syncSlowCodeBlockMs();
+				emitSync(PluginEvent.CodeBlockProcessed({
 					ctx: {
-						buildId: currentBuildId,
+						buildId: syncBuildId(),
+						...apiScope != null ? { apiScope } : {},
 						...currentFilePath != null ? { file: currentFilePath } : {}
 					},
 					lang,
-					shikiMs: shikiTime,
-					twoslashMs: totalBlockTime - shikiTime,
+					component: "with-api",
+					twoslash: twoslashTransformer != null,
+					twoslashMs,
+					shikiMs: Math.max(0, renderMs - twoslashMs),
 					totalMs: totalBlockTime,
 					slow: isSlow,
 					level: "debug"
@@ -184,4 +181,4 @@ const remarkWithApi = (options) => {
 };
 
 //#endregion
-export { remarkWithApi, setRemarkWithApiEventEmitter };
+export { remarkWithApi };

package/schemas/config.js

@@ -273,15 +273,19 @@ const MultiApiConfig = Schema.Struct({
 	* Path to a `tsconfig.json` for Twoslash.
 	*
 	* @remarks
-	* Twoslash runs against a single shared TypeScript environment for the
-	* whole build, so per-API tsconfigs are not honored in multi-API mode:
-	* the first API that provides one wins and the rest are ignored (a
-	* `ConfigCascadeWarning` is emitted when they differ). Ensure the
-	* configured tsconfigs are equivalent, or set the intended one on the
-	* first API only.
+	* This API's code blocks are type-checked under this config. APIs that
+	* declare the same config share one TypeScript environment; the file set
+	* is shared across all documented APIs either way, so a type owned by
+	* another documented package still resolves.
 	*/
 	tsconfig: Schema.optional(ModelInput),
-	/** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
+	/**
+	* TypeScript compiler options for Twoslash, applying to this API only.
+	*
+	* @remarks
+	* Merged on top of the defaults and of this API's `tsconfig`, so declaring
+	* a single option overrides just that one.
+	*/
 	compilerOptions: Schema.optional(Schema.Unknown)
 });
 /**

package/services/HighlighterService.js

@@ -0,0 +1,30 @@
+import { Context } from "effect";
+
+//#region src/services/HighlighterService.ts
+/**
+* The build's single Shiki highlighter.
+*
+* @remarks
+* A highlighter owns a WASM oniguruma instance and every loaded grammar and
+* theme, and it has a `dispose()` nobody was calling: `ConfigServiceLive`
+* created one per `resolve()`, so a dev-mode HMR session leaked one per
+* rebuild. The test run reported it as
+* `[Shiki] 10 instances have been created` — a console leak, not a failure.
+*
+* The fix is NOT to scope it to `resolve()`. `VfsRegistry` hands this
+* highlighter to the remark plugins, which RSPress invokes during its render
+* pass — after `config()` has returned and after any `resolve()`-scoped scope
+* would have closed. The lifetime that matches is the `ManagedRuntime`'s:
+* acquired when the layer builds, released by `effectRuntime.dispose()` in
+* `afterBuild` on production builds, and deliberately kept alive in dev so HMR
+* rebuilds reuse it.
+*
+* Getting that wrong is silent — a disposed highlighter does not throw, the
+* code blocks just render as unhighlighted `<pre>`.
+*
+* @packageDocumentation
+*/
+var HighlighterService = class extends Context.Service()("rspress-plugin-api-extractor/HighlighterService") {};
+
+//#endregion
+export { HighlighterService };

package/services/OgService.js

@@ -0,0 +1,23 @@
+import { Context, Data } from "effect";
+
+//#region src/services/OgService.ts
+const OgImageErrorBase = Data.TaggedError("OgImageError");
+/**
+* A configured OG image that could not be resolved.
+*
+* @remarks
+* `cause` carries the original failure (an `image-size` parse error, a
+* filesystem error) rather than a stringified copy of it.
+*/
+var OgImageError = class extends OgImageErrorBase {
+	get message() {
+		if (this.code === "invalid-url") return `Invalid Open Graph image URL in '${this.field}': ${this.value} — expected an absolute http(s) URL or a path starting with '/'`;
+		if (this.code === "invalid-secure-url") return `Invalid Open Graph secure URL in '${this.field}': ${this.value} — secureUrl must be an absolute https URL`;
+		const cause = this.cause instanceof Error ? this.cause.message : String(this.cause);
+		return `Could not read Open Graph image '${this.value}': ${cause}`;
+	}
+};
+var OgService = class extends Context.Service()("rspress-plugin-api-extractor/OgService") {};
+
+//#endregion
+export { OgImageError, OgService };

package/services/PluginConfig.js

@@ -0,0 +1,26 @@
+import { Context } from "effect";
+
+//#region src/services/PluginConfig.ts
+/**
+* The decoded plugin options, as a service.
+*
+* @remarks
+* `ConfigServiceLive` used to be a factory taking these as an argument, which
+* made it a layer-returning function — the shape the house rules warn about,
+* since layers memoize by reference and a second call mints a second layer.
+* It was only ever called once, but "only ever called once" is a property of
+* the current call sites, not of the design.
+*
+* A `Context.Service` rather than a `Context.Reference`, deliberately, and for
+* the same reason the Shiki themes are a layer argument: a Reference carries a
+* default, so a wiring mistake would silently resolve to empty options and the
+* build would document nothing while reporting success. There is no sensible
+* default for "which APIs is this site documenting", so forgetting to provide
+* it should be a loud "service not provided", which is what this gives.
+*
+* @packageDocumentation
+*/
+var PluginConfig = class extends Context.Service()("rspress-plugin-api-extractor/PluginConfig") {};
+
+//#endregion
+export { PluginConfig };

package/services/TwoslashCacheService.js

@@ -0,0 +1,15 @@
+import { Context } from "effect";
+
+//#region src/services/TwoslashCacheService.ts
+/**
+* Persistence for the Twoslash result cache.
+*
+* Split from the synchronous cache object (`twoslash-cache.ts`) because
+* `TwoslashTypesCache.read`/`write` are called from inside Shiki's `preprocess`
+* hook and cannot await: the service loads once before the render phase and
+* saves once after it, while every lookup in between is a synchronous map hit.
+*/
+var TwoslashCacheService = class extends Context.Service()("rspress-plugin-api-extractor/TwoslashCacheService") {};
+
+//#endregion
+export { TwoslashCacheService };

package/services/TwoslashEnvironments.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+//#region src/services/TwoslashEnvironments.ts
+var TwoslashEnvironments = class extends Context.Service()("rspress-plugin-api-extractor/TwoslashEnvironments") {};
+
+//#endregion
+export { TwoslashEnvironments };