rspress-plugin-api-extractor 0.14.0 → 0.15.0

package/twoslash-cache.js

@@ -1,174 +0,0 @@
-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

@@ -1,87 +0,0 @@
-//#region src/twoslash-patterns.ts
-/**
-* Twoslash directive detection patterns.
-*
-* These regexes mirror the upstream Twoslash source at:
-* https://github.com/twoslashes/twoslash/blob/main/packages/twoslash/src/regexp.ts
-*
-* All patterns allow an optional space after `//` (e.g., both `// @noErrors`
-* and `//@noErrors` are valid Twoslash syntax).
-*/
-/**
-* Config directives: boolean flags and key-value pairs.
-*
-* Upstream: `reConfigBoolean` + `reConfigValue` + `reFilenamesMakers`
-*
-* @example
-* ```
-* // @noErrors
-* //@strict
-* // @errors: 2304
-* // @target: ES2020
-* // @filename: example.ts
-* ```
-*/
-const RE_CONFIG = /^\/\/\s?@\w+/;
-/**
-* Annotation markers: query, completion, and highlight markers.
-*
-* Upstream: `reAnnonateMarkers` — `/^\s*\/\/\s*\^(\?|\||\^+)( .*)?$/gm`
-*
-* These are positioned under code lines with `^` characters for alignment.
-* After `line.trim()`, leading whitespace is removed but internal spaces
-* between `//` and `^` are preserved.
-*
-* @example
-* ```
-* // ^? — query (show type info)
-* //    ^? — query with alignment spaces
-* // ^| — completion (show autocomplete)
-* // ^^^ — highlight range
-* // ^^^^ description text
-* ```
-*/
-const RE_ANNOTATION = /^\/\/\s*\^[?|^]/;
-/**
-* Cut directives: control which code is visible in output.
-*
-* Upstream: `reCutBefore`, `reCutAfter`, `reCutStart`, `reCutEnd`
-*
-* @example
-* ```
-* // ---cut---
-* //---cut-before---
-* // ---cut-after---
-* // ---cut-start---
-* // ---cut-end---
-* ```
-*/
-const RE_CUT = /^\/\/\s?---cut/;
-/**
-* Test whether a trimmed line is any Twoslash directive.
-*
-* Covers all directive types: config flags, config values, filename markers,
-* annotation markers (query/completion/highlight), and cut directives.
-*
-* @param trimmedLine - The line with leading/trailing whitespace removed
-* @returns true if the line is a Twoslash directive
-*/
-function isTwoslashDirective(trimmedLine) {
-	return RE_CONFIG.test(trimmedLine) || RE_ANNOTATION.test(trimmedLine) || RE_CUT.test(trimmedLine);
-}
-/**
-* Classify a cut directive line.
-*
-* @param trimmedLine - The line with leading/trailing whitespace removed
-* @returns The cut type, or null if not a cut directive
-*/
-function classifyCutDirective(trimmedLine) {
-	if (/^\/\/\s?---cut(-before)?---$/.test(trimmedLine)) return "cut-before";
-	if (/^\/\/\s?---cut-after---$/.test(trimmedLine)) return "cut-after";
-	if (/^\/\/\s?---cut-start---$/.test(trimmedLine)) return "cut-start";
-	if (/^\/\/\s?---cut-end---$/.test(trimmedLine)) return "cut-end";
-	return null;
-}
-
-//#endregion
-export { classifyCutDirective, isTwoslashDirective };