rspress-plugin-api-extractor 0.9.2 → 0.10.0

package/twoslash-cache.js

@@ -0,0 +1,174 @@
+import { createHash } from "node:crypto";
+import { gunzipSync, gzipSync } from "node:zlib";
+
+//#region src/twoslash-cache.ts
+/**
+* Persisted Twoslash result cache.
+*
+* Type-checking code blocks is by far the dominant cost of the render phase —
+* measured at ~97% of it, concentrated in the minority of blocks that carry an
+* `@example` (see `render-phase-instrumentation.md`). `@shikijs/twoslash`
+* exposes a first-class `typesCache` seam for exactly this, so the work here is
+* a keying scheme and a store rather than a new interception point.
+*
+* ## Soundness
+*
+* A Twoslash result depends on the code, the compiler options, the declarations
+* it is checked against, and the compiler doing the checking. The keys cover
+* all four: the per-entry key carries the code, its language and the compiler
+* options; {@link twoslashEnvHash} carries the declarations and the TypeScript
+* version.
+*
+* The TypeScript version is load-bearing and easy to overlook — `lib.d.ts`
+* ships with the compiler and inference changes between releases, so an upgrade
+* against unchanged declarations yields different hovers. Omitting it would let
+* a warm cache serve results from the previous compiler and stay wrong until
+* the API's own declarations happened to change.
+*
+* NOT covered, and covered instead by {@link TWOSLASH_CACHE_FORMAT}: the
+* `@shikijs/twoslash` / `twoslash` renderer version, which determines the shape
+* of the stored `nodes`. Bump the format constant when upgrading those, since
+* nothing derives it automatically.
+*
+* ## Invalidation granularity
+*
+* The consequence of that soundness is coarse invalidation: any VFS change
+* discards the whole generation, because a declaration change anywhere can
+* legitimately change any block's inferred types. So this cache makes repeat
+* builds over an UNCHANGED API nearly free — CI re-runs, prose-only edits,
+* theme and config changes, rebuilding a site without touching the library —
+* and does nothing for the build right after an API item changes.
+*
+* Sharpening that would need per-scope type environments, so one package's
+* change stops invalidating every other package's blocks. That is fix (b) in
+* `render-phase-instrumentation.md`, tracked as a correctness fix; it would
+* make this cache substantially more effective on a multi-API site as a side
+* effect.
+*
+* ## Synchronous by necessity
+*
+* `TwoslashTypesCache.read`/`write` are synchronous — they are called from
+* inside Shiki's `preprocess` hook. Persistence is therefore load-once at
+* startup and save-once at the end, against an in-memory map; there is no
+* per-entry I/O. See `TwoslashCacheService`.
+*/
+/**
+* Bumped when the stored shape changes, so an older blob is treated as absent
+* rather than deserialized into the wrong shape.
+*
+* Also the manual lever for renderer changes: bump this when upgrading
+* `@shikijs/twoslash` or `twoslash`, whose versions determine the shape of the
+* stored `nodes` and are not derived into any key.
+*/
+const TWOSLASH_CACHE_FORMAT = 1;
+function sha256(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/**
+* Fingerprint the type environment a generation is checked against.
+*
+* Covers the declarations (`vfs`) and the compiler that interprets them
+* (`toolchain`). The VFS is hashed over sorted `path\0content` pairs so the
+* digest is stable against map iteration order.
+*
+* `toolchain` must carry the TypeScript version. The declarations alone do not
+* determine the answer: `lib.d.ts` ships with the compiler and inference
+* behaviour changes between releases, so upgrading TypeScript against unchanged
+* declarations produces different hovers. Without the version in the key the
+* warm cache would serve results computed by the previous compiler, and stay
+* wrong until the API's own declarations happened to change.
+*
+* Compiler OPTIONS are deliberately not folded in here — they belong on the
+* per-entry key, so one generation can hold results from the several
+* configurations a multi-API site may declare.
+*/
+function twoslashEnvHash(vfs, toolchain) {
+	const hash = createHash("sha256");
+	hash.update(`format:${1}\0toolchain:${toolchain}\0`);
+	for (const key of [...vfs.keys()].sort()) hash.update(`${key}\0${vfs.get(key) ?? ""}\0`);
+	return hash.digest("hex");
+}
+/** JSON with object keys sorted, so equivalent options hash identically. */
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+/**
+* Per-entry key: the code, its language, and the compiler configuration it is
+* checked under.
+*
+* The configuration matters because two APIs on one site may be documented
+* under different `tsconfig`s — the same source checked under different options
+* can produce different types, so it must not share a cache entry.
+*/
+function twoslashEntryKey(code, lang, compilerOptions) {
+	return sha256(`${lang ?? "ts"}\0${stableStringify(compilerOptions ?? {})}\0${code}`);
+}
+/**
+* The cache key a whole generation is stored under. One blob per environment,
+* so a changed environment reads as a miss rather than serving stale results.
+*/
+function twoslashBlobKey(envHash) {
+	return `twoslash/v${1}/${envHash}`;
+}
+/**
+* Build a synchronous Twoslash cache over an in-memory map, optionally seeded
+* with entries loaded from a previous build.
+*/
+function makeTwoslashCache(initial) {
+	const map = new Map(initial);
+	let hits = 0;
+	let misses = 0;
+	let dirty = false;
+	return {
+		read: (code, lang, options) => {
+			const found = map.get(twoslashEntryKey(code, lang, options?.compilerOptions));
+			if (found === void 0) {
+				misses += 1;
+				return null;
+			}
+			hits += 1;
+			return found;
+		},
+		write: (code, data, lang, options) => {
+			const value = {
+				nodes: data.nodes,
+				code: data.code,
+				...data.meta?.extension != null ? { meta: { extension: data.meta.extension } } : {}
+			};
+			map.set(twoslashEntryKey(code, lang, options?.compilerOptions), value);
+			dirty = true;
+		},
+		stats: () => ({
+			hits,
+			misses,
+			entries: map.size,
+			dirty
+		}),
+		entries: () => map
+	};
+}
+/** Serialize a generation for storage. Gzipped JSON — hover text compresses well. */
+function encodeTwoslashCache(entries) {
+	return gzipSync(Buffer.from(JSON.stringify(Object.fromEntries(entries)), "utf-8"));
+}
+/**
+* Deserialize a stored generation.
+*
+* Returns an empty map for anything unreadable — a truncated blob, a format
+* change, a corrupted file. A cache that cannot be read is a cache miss, never
+* a build failure.
+*/
+function decodeTwoslashCache(blob) {
+	try {
+		const parsed = JSON.parse(gunzipSync(blob).toString("utf-8"));
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return /* @__PURE__ */ new Map();
+		return new Map(Object.entries(parsed));
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+
+//#endregion
+export { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey, twoslashEntryKey, twoslashEnvHash };

package/twoslash-patterns.js

@@ -84,4 +84,4 @@ function classifyCutDirective(trimmedLine) {
 }
 
 //#endregion
-export { RE_ANNOTATION, RE_CONFIG, RE_CUT, classifyCutDirective, isTwoslashDirective };
+export { classifyCutDirective, isTwoslashDirective };

package/twoslash-timing-wrapper.js

@@ -0,0 +1,23 @@
+//#region src/twoslash-timing-wrapper.ts
+/**
+* Wraps a Twoslash transformer to measure execution time
+*/
+function createTwoslashTimingWrapper(twoslashTransformer, onTiming) {
+	const wrapper = {
+		...twoslashTransformer,
+		name: `${twoslashTransformer.name}-timing-wrapper`
+	};
+	if (twoslashTransformer.preprocess) {
+		const originalPreprocess = twoslashTransformer.preprocess;
+		wrapper.preprocess = function(code, options) {
+			const start = performance.now();
+			const result = originalPreprocess.call(this, code, options);
+			onTiming(performance.now() - start);
+			return result ?? void 0;
+		};
+	}
+	return wrapper;
+}
+
+//#endregion
+export { createTwoslashTimingWrapper };

package/twoslash-transformer.js

@@ -5,7 +5,6 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { toHast } from "mdast-util-to-hast";
 
 //#region src/twoslash-transformer.ts
-/* v8 ignore start -- Shiki/Twoslash integration, requires full highlighter setup for testing */
 /**
 * Module-level emitter seam. Default is a no-op; wire in `setEventEmitter(emitSync)`
 * from plugin.ts right after the runtime emitter is created so that Twoslash error
@@ -228,12 +227,35 @@ function renderMarkdownInline(markdown, context) {
 *
 * @see {@link TypeRegistryService} for VFS generation
 */
+/**
+* Fingerprint a compiler configuration so environments can be deduped and code
+* blocks routed to the right one. Keys are sorted, so two configurations that
+* differ only in property order share an environment.
+*/
+function twoslashConfigKey(options) {
+	const entries = Object.entries(options).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	return JSON.stringify(entries);
+}
 var TwoslashManager = class TwoslashManager {
 	static instance = null;
 	/**
-	* Twoslash transformer instance
+	* Transformers keyed by compiler-config fingerprint.
+	*
+	* One environment per DISTINCT configuration, not per API: two packages
+	* documented under the same compiler options share an environment, and with
+	* it the TypeScript language services Twoslash builds per block. A build
+	* where every API agrees on its config therefore costs exactly what the
+	* single shared environment used to.
+	*/
+	environments = /* @__PURE__ */ new Map();
+	/** API scope to config fingerprint, for `getTransformer(scope)`. */
+	scopeConfigs = /* @__PURE__ */ new Map();
+	/**
+	* Fingerprint of the first environment initialized, used for code blocks
+	* that carry no scope — a `with-api` fence in a page outside any documented
+	* package's route.
 	*/
-	transformer = null;
+	defaultConfigKey = null;
 	/**
 	* VFS keys snapshot captured at initialize() time.
 	* Returned by vfsKeysSnapshot() for TwoslashCheckFailed events.
@@ -272,13 +294,16 @@ var TwoslashManager = class TwoslashManager {
 	* @param tsEnvCache - TypeScript virtual environment cache for reusing language services
 	* @param compilerOptions - TypeScript compiler options for Twoslash (defaults to DEFAULT_COMPILER_OPTIONS)
 	*/
-	initialize(vfs, _reserved, _reserved2, tsEnvCache, compilerOptions) {
+	initialize(vfs, _reserved, _reserved2, tsEnvCache, compilerOptions, typesCache) {
 		const extraFiles = {};
 		for (const [path, content] of vfs.entries()) extraFiles[path] = content;
 		this._vfsKeys = Array.from(vfs.keys());
 		const resolvedOptions = compilerOptions ?? DEFAULT_COMPILER_OPTIONS;
 		this._resolvedCompilerOptions = resolvedOptions;
-		this.transformer = transformerTwoslash({
+		const configKey = twoslashConfigKey(resolvedOptions);
+		if (this.defaultConfigKey === null) this.defaultConfigKey = configKey;
+		if (this.environments.has(configKey)) return;
+		const transformer = transformerTwoslash({
 			renderer: rendererRich({
 				processHoverInfo: (info) => {
 					return info.replace(/^\(([\w-]+)\)\s+/gm, "").replace(/\nimport .*$/gm, "").trim();
@@ -288,6 +313,7 @@ var TwoslashManager = class TwoslashManager {
 				renderMarkdownInline
 			}),
 			...tsEnvCache != null ? { cache: tsEnvCache } : {},
+			...typesCache != null ? { typesCache } : {},
 			twoslashOptions: {
 				extraFiles,
 				compilerOptions: resolvedOptions,
@@ -299,13 +325,26 @@ var TwoslashManager = class TwoslashManager {
 				this.handleTwoslashError(error, code, this.currentFilePath);
 			}
 		});
+		this.environments.set(configKey, transformer);
 	}
 	/**
-	* Get the initialized Twoslash transformer.
-	* Returns null if not initialized.
+	* Associate an API scope with the compiler configuration it is documented
+	* under, so its code blocks are type-checked with that configuration.
+	*/
+	registerScope(apiScope, compilerOptions) {
+		this.scopeConfigs.set(apiScope, twoslashConfigKey(compilerOptions));
+	}
+	/**
+	* Get the Twoslash transformer for an API scope.
+	*
+	* An unknown or absent scope falls back to the first environment built: a
+	* `with-api` fence can appear on a page outside any documented package's
+	* route, and type-checking it under some configuration beats not checking it.
+	* Returns null before any environment is initialized.
 	*/
-	getTransformer() {
-		return this.transformer;
+	getTransformer(apiScope) {
+		const key = (apiScope != null ? this.scopeConfigs.get(apiScope) : void 0) ?? this.defaultConfigKey;
+		return key != null ? this.environments.get(key) ?? null : null;
 	}
 	/**
 	* Set the source file path used to attribute subsequent Twoslash error events.
@@ -320,7 +359,9 @@ var TwoslashManager = class TwoslashManager {
 	* Clear the Twoslash transformer (useful for testing or reinitializing)
 	*/
 	clear() {
-		this.transformer = null;
+		this.environments.clear();
+		this.scopeConfigs.clear();
+		this.defaultConfigKey = null;
 	}
 	/**
 	* Reset the singleton instance (useful for testing)

package/runtime/components/MarkdownText/index.js

@@ -1,34 +0,0 @@
-import { Fragment, jsx } from "react/jsx-runtime";
-
-//#region src/runtime/components/MarkdownText/index.tsx
-/**
-* Renders plain text with markdown links as React elements.
-* Only supports basic markdown links: [text](url)
-*/
-function MarkdownText({ children }) {
-	const parts = parseMarkdownLinks(children);
-	return /* @__PURE__ */ jsx(Fragment, { children: parts });
-}
-/**
-* Parse markdown links and return array of React nodes
-*/
-function parseMarkdownLinks(text) {
-	const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
-	const parts = [];
-	let lastIndex = 0;
-	let key = 0;
-	for (const match of text.matchAll(linkRegex)) {
-		if (match.index !== void 0 && match.index > lastIndex) parts.push(text.slice(lastIndex, match.index));
-		const [fullMatch, linkText, url] = match;
-		parts.push(/* @__PURE__ */ jsx("a", {
-			href: url,
-			children: linkText
-		}, key++));
-		lastIndex = (match.index ?? 0) + fullMatch.length;
-	}
-	if (lastIndex < text.length) parts.push(text.slice(lastIndex));
-	return parts;
-}
-
-//#endregion
-export { MarkdownText, MarkdownText as default };