rspress-plugin-api-extractor 0.10.0 → 0.11.0

package/markdown/page-generators/class-page.js

@@ -1,7 +1,7 @@
 import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives } from "../helpers.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
 import { linkProse } from "../prose-linker.js";
-import { ApiItems, Signature, Tsdoc } from "@tsdoctor/model";
+import { ApiItems, Routes, Signature, Tsdoc } from "@tsdoctor/model";
 
 //#region src/markdown/page-generators/class-page.ts
 /**
@@ -60,7 +60,7 @@ var ClassPageGenerator = class {
 	*
 	* @param apiScope - API scope identifier for VFS lookup
 	*/
-	async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom, syntheticBase) {
+	async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom, syntheticBase, memberAnchors) {
 		const shouldSuppressErrors = suppressExampleErrors ?? true;
 		const name = apiClass.displayName;
 		const summary = Tsdoc.summary(apiClass) || "No description available.";
@@ -99,7 +99,7 @@ var ClassPageGenerator = class {
 			content += `## Constructors\n\n`;
 			for (const ctor of constructors) {
 				const ctorSummary = Tsdoc.summary(ctor);
-				const ctorId = sanitizeId("constructor");
+				const ctorId = Routes.memberAnchor("constructor");
 				const ctorItem = ctor;
 				const params = Tsdoc.params(ctor);
 				const hasParameters = params.length > 0;
@@ -131,15 +131,14 @@ var ClassPageGenerator = class {
 			const isGetter = m.displayName.startsWith("get ") || m.displayName.startsWith("set ");
 			return !isStatic && !isGetter;
 		});
-		const prefixMap = this.detectMemberConflicts(staticProperties, grouped.staticMethods, instanceProperties, grouped.instanceMethods, grouped.getters);
+		const anchors = memberAnchors ?? ApiItems.memberAnchors(apiClass);
+		const anchorFor = (member) => anchors.get(member.canonicalReference?.toString() ?? member.displayName) ?? Routes.memberAnchor(member.displayName);
 		const renderProperties = async (title, propList) => {
 			if (propList.length === 0) return;
 			content += `## ${title}\n\n`;
 			for (const prop of propList) {
 				const propSummary = Tsdoc.summary(prop);
-				const baseName = sanitizeId(prop.displayName);
-				const prefix = prefixMap.get(baseName) || "";
-				const propId = sanitizeId(prop.displayName, prefix);
+				const propId = anchorFor(prop);
 				const propItem = prop;
 				if (propItem.excerpt?.text) {
 					const memberSignature = Signature.format(propItem.excerpt).trim();
@@ -154,9 +153,7 @@ var ClassPageGenerator = class {
 			content += `## ${title}\n\n`;
 			for (const method of methodList) {
 				const methodSummary = Tsdoc.summary(method);
-				const baseName = sanitizeId(method.displayName);
-				const prefix = prefixMap.get(baseName) || "";
-				const methodId = sanitizeId(method.displayName, prefix);
+				const methodId = anchorFor(method);
 				const methodItem = method;
 				const params = Tsdoc.params(method);
 				const hasParameters = params.length > 0;
@@ -258,26 +255,6 @@ var ClassPageGenerator = class {
 		};
 	}
 	/**
-	* Detect naming conflicts between class members and return prefixes to apply.
-	* Returns a Map of sanitized name to prefix (empty string if no conflict).
-	*/
-	detectMemberConflicts(staticProps, staticMethods, instanceProps, instanceMethods, getters) {
-		const prefixMap = /* @__PURE__ */ new Map();
-		const staticPropNames = new Set(staticProps.map((p) => sanitizeId(p.displayName)));
-		const staticMethodNames = new Set(staticMethods.map((m) => sanitizeId(m.displayName)));
-		const instancePropNames = new Set(instanceProps.map((p) => sanitizeId(p.displayName)));
-		const instanceMethodNames = new Set(instanceMethods.map((m) => sanitizeId(m.displayName)));
-		const getterNames = new Set(getters.map((g) => sanitizeId(g.displayName)));
-		for (const name of staticPropNames) if (staticMethodNames.has(name) || instancePropNames.has(name) || instanceMethodNames.has(name) || getterNames.has(name)) prefixMap.set(name, "static-property");
-		for (const name of staticMethodNames) if (instanceMethodNames.has(name) || instancePropNames.has(name) || getterNames.has(name)) prefixMap.set(name, "static");
-		else if (staticPropNames.has(name)) prefixMap.set(name, "");
-		for (const name of instancePropNames) if (instanceMethodNames.has(name) || getterNames.has(name)) prefixMap.set(name, "property");
-		else if (staticMethodNames.has(name)) prefixMap.set(name, "");
-		for (const name of instanceMethodNames) if (!prefixMap.has(name)) prefixMap.set(name, "");
-		for (const name of getterNames) if (!prefixMap.has(name)) prefixMap.set(name, "");
-		return prefixMap;
-	}
-	/**
 	* Generate a class member signature with full class context
 	* Includes hidden imports with cut directive for external type resolution
 	* Uses the simplified approach: 3 lines (class opening, member, closing)

package/markdown/page-generators/index-pages.js

@@ -1,4 +1,4 @@
-import { escapeYamlString } from "../helpers.js";
+import { emitFrontmatterBlock } from "../../frontmatter.js";
 
 //#region src/markdown/page-generators/index-pages.ts
 /**
@@ -9,13 +9,11 @@ var MainIndexPageGenerator = class {
 	* Generate the main API index page
 	*/
 	generate(packageName, baseRoute, _categoryCounts) {
-		const content = `---
-title: API Reference
-description: Auto-generated API documentation for ${escapeYamlString(packageName)}
-overview: true
----
-
-`;
+		const content = emitFrontmatterBlock({
+			title: "API Reference",
+			description: `Auto-generated API documentation for ${packageName}`,
+			overview: true
+		});
 		return {
 			routePath: `${baseRoute}/index`,
 			content

package/markdown/page-generators/interface-page.js

@@ -1,7 +1,7 @@
 import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
-import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives } from "../helpers.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
 import { linkProse } from "../prose-linker.js";
-import { ApiItems, Signature, Tsdoc } from "@tsdoctor/model";
+import { ApiItems, Routes, Signature, Tsdoc } from "@tsdoctor/model";
 
 //#region src/markdown/page-generators/interface-page.ts
 /**
@@ -98,7 +98,7 @@ var InterfacePageGenerator = class {
 			content += `## Call Signatures\n\n`;
 			for (const callSig of callSignatures) {
 				const callSigSummary = Tsdoc.summary(callSig);
-				const callSigId = sanitizeId("call-signature");
+				const callSigId = Routes.memberAnchor("call-signature");
 				const callSigItem = callSig;
 				if (callSigItem.excerpt?.text) {
 					const memberSignature = Signature.format(callSigItem.excerpt).trim();
@@ -113,7 +113,7 @@ var InterfacePageGenerator = class {
 			content += `## Construct Signatures\n\n`;
 			for (const constructSig of constructSignatures) {
 				const constructSigSummary = Tsdoc.summary(constructSig);
-				const constructSigId = sanitizeId("construct-signature");
+				const constructSigId = Routes.memberAnchor("construct-signature");
 				const constructSigItem = constructSig;
 				if (constructSigItem.excerpt?.text) {
 					const memberSignature = Signature.format(constructSigItem.excerpt).trim();
@@ -128,7 +128,7 @@ var InterfacePageGenerator = class {
 			content += `## Index Signature\n\n`;
 			for (const indexSig of indexSignatures) {
 				const indexSigSummary = Tsdoc.summary(indexSig);
-				const indexSigId = sanitizeId("index-signature");
+				const indexSigId = Routes.memberAnchor("index-signature");
 				const indexSigItem = indexSig;
 				if (indexSigItem.excerpt?.text) {
 					const memberSignature = Signature.format(indexSigItem.excerpt).trim();
@@ -143,7 +143,7 @@ var InterfacePageGenerator = class {
 			content += `## Properties\n\n`;
 			for (const prop of properties) {
 				const propSummary = Tsdoc.summary(prop);
-				const propId = sanitizeId(prop.displayName);
+				const propId = Routes.memberAnchor(prop.displayName);
 				const propItem = prop;
 				if (propItem.excerpt?.text) {
 					const memberSignature = Signature.format(propItem.excerpt).trim();
@@ -158,7 +158,7 @@ var InterfacePageGenerator = class {
 			content += `## Methods\n\n`;
 			for (const method of methods) {
 				const methodSummary = Tsdoc.summary(method);
-				const methodId = sanitizeId(method.displayName);
+				const methodId = Routes.memberAnchor(method.displayName);
 				const methodItem = method;
 				if (methodItem.excerpt?.text) {
 					const memberSignature = Signature.format(methodItem.excerpt).trim();

package/markdown/shiki-utils.js

@@ -1,13 +1,7 @@
 import { PluginEvent } from "../observability/events.js";
+import { emitSync, syncBuildId } from "../observability/sync-emitter.js";
 
 //#region src/markdown/shiki-utils.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-function setShikiUtilsEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
 /**
 * Default Shiki theme configuration
 */
@@ -48,8 +42,8 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 		if (enableTwoslash) options.meta = { __raw: "twoslash" };
 		return await highlighter.codeToHast(code, options);
 	} catch (error) {
-		emitEvent(PluginEvent.ShikiError({
-			ctx: { buildId: currentBuildId },
+		emitSync(PluginEvent.ShikiError({
+			ctx: { buildId: syncBuildId() },
 			file: "unknown",
 			reason: String(error),
 			level: "warn"
@@ -57,6 +51,67 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 		return null;
 	}
 }
+/* v8 ignore stop -- everything below is pure and covered by __test__/markdown/shiki-themes.test.ts */
+/**
+* Normalize a theme option into the `{ light, dark }` pair the highlighter and
+* the remark plugins both expect.
+*
+* @remarks
+* Accepts a single theme name applied to both modes, an explicit pair, or a
+* raw theme object. Lives beside {@link DEFAULT_SHIKI_THEMES} because it falls
+* back to it; it was previously duplicated byte-for-byte in `plugin.ts` and
+* `ConfigServiceLive.ts`.
+*/
+function normalizeThemeConfig(theme) {
+	if (!theme) return { ...DEFAULT_SHIKI_THEMES };
+	if (typeof theme === "string") return {
+		light: theme,
+		dark: theme
+	};
+	if ("light" in theme && "dark" in theme && typeof theme.light === "string" && typeof theme.dark === "string") return {
+		light: theme.light,
+		dark: theme.dark
+	};
+	return {
+		light: theme,
+		dark: theme
+	};
+}
+/**
+* Every theme the build's single highlighter must load: one normalized pair
+* per documented API, plus the two defaults.
+*
+* @remarks
+* Takes the RAW option configs rather than resolved ones, because the
+* highlighter is now acquired when its layer builds — before `resolve()` has
+* run. That is sound: a resolved config's `theme` is exactly
+* `normalizeThemeConfig(api.theme)` and no version-level override exists, so
+* the two inputs cannot disagree.
+*
+* Named theme strings are deduplicated; object themes are not (they have no
+* identity to compare), which matches the previous behaviour and is harmless —
+* Shiki keys a loaded theme by its `name`.
+*/
+function collectShikiThemes(apis) {
+	const named = /* @__PURE__ */ new Set();
+	const objects = [];
+	for (const api of apis) {
+		const theme = normalizeThemeConfig(api.theme);
+		for (const input of [theme.light, theme.dark]) if (typeof input === "string") named.add(input);
+		else objects.push(input);
+	}
+	if (typeof DEFAULT_SHIKI_THEMES.light === "string") named.add(DEFAULT_SHIKI_THEMES.light);
+	if (typeof DEFAULT_SHIKI_THEMES.dark === "string") named.add(DEFAULT_SHIKI_THEMES.dark);
+	return [...named, ...objects];
+}
+/** Languages the highlighter loads. Every code block the plugin renders is one of these. */
+const SHIKI_LANGS = [
+	"typescript",
+	"javascript",
+	"json",
+	"bash",
+	"sh"
+];
 
 //#endregion
-export { DEFAULT_SHIKI_THEMES, generateShikiHast, setShikiUtilsEventEmitter };
+export { DEFAULT_SHIKI_THEMES, SHIKI_LANGS, collectShikiThemes, generateShikiHast, normalizeThemeConfig };

package/observability/EventBus.js

@@ -1,3 +1,4 @@
+import { BuildId } from "../BuildEnv.js";
 import { LEVEL_RANK, levelOf } from "./events.js";
 import { Context, Effect, Layer, Option } from "effect";
 
@@ -16,9 +17,34 @@ function makeShape(sinks) {
 function makeEventBusLayer(sinks) {
 	return Layer.succeed(EventBus, makeShape(sinks));
 }
-/** Emit when a bus is in context; silently no-op otherwise. */
+/**
+* Emit when a bus is in context; silently no-op otherwise.
+*
+* @remarks
+* Fills `ctx.buildId` from the {@link BuildId} Reference when the caller left
+* it empty, which is why no emit site passes one. Before this, 24 sites wrote
+* `ctx: { buildId: "" }` — 22 in `ConfigServiceLive`, where the real value sat
+* three scopes up and was simply not reached, and every site in
+* `TypeRegistryServiceLive`, where the layer is module-level and there is no
+* build to name. The second group is why a Reference is the fix and a
+* find-and-replace is not: a Reference reaches code that no parameter can.
+*
+* A caller that sets a non-empty `buildId` keeps it, so a test can still emit
+* with an explicit id.
+*/
 function emit(event) {
-	return Effect.serviceOption(EventBus).pipe(Effect.flatMap((maybe) => Option.isSome(maybe) ? maybe.value.emit(event) : Effect.void));
+	return Effect.gen(function* () {
+		const maybe = yield* Effect.serviceOption(EventBus);
+		if (Option.isNone(maybe)) return;
+		const filled = (event.ctx.buildId ?? "") === "" ? {
+			...event,
+			ctx: {
+				...event.ctx,
+				buildId: yield* BuildId
+			}
+		} : event;
+		yield* maybe.value.emit(filled);
+	});
 }
 /**
 * Returns true when a bus is in context and has at least one sink admitted at
@@ -27,10 +53,6 @@ function emit(event) {
 function wantsLevel(level) {
 	return Effect.serviceOption(EventBus).pipe(Effect.flatMap((maybe) => Option.isSome(maybe) ? maybe.value.wantsLevel(level) : Effect.succeed(false)));
 }
-/** Bind a runtime so non-Effect (sync island) callbacks can emit. */
-function makeRuntimeEmitter(runtime) {
-	return (event) => runtime.runSync(emit(event));
-}
 
 //#endregion
-export { EventBus, emit, makeEventBusLayer, makeRuntimeEmitter, wantsLevel };
+export { EventBus, emit, makeEventBusLayer, wantsLevel };

package/observability/spans.js

@@ -1,3 +1,4 @@
+import { Thresholds } from "../BuildEnv.js";
 import { PluginEvent } from "./events.js";
 import { emit } from "./EventBus.js";
 import { Effect } from "effect";
@@ -24,8 +25,9 @@ const PHASE_THRESHOLD_KEY = {
 * R type is unchanged: emit() is serviceOption-based (R = never), so adding
 * the span/events adds zero requirements to the caller.
 */
-function withPhase(phase, ctx, effect, thresholds) {
+function withPhase(phase, ctx, effect) {
 	return Effect.gen(function* () {
+		const thresholds = yield* Thresholds;
 		yield* emit(PluginEvent.PhaseStarted({
 			ctx,
 			level: "debug",

package/observability/sync-emitter.js

@@ -0,0 +1,78 @@
+import { BuildId, Thresholds } from "../BuildEnv.js";
+import { emit } from "./EventBus.js";
+import { Effect } from "effect";
+
+//#region src/observability/sync-emitter.ts
+/**
+* The one bridge from synchronous, fiber-less code to the EventBus.
+*
+* @remarks
+* Seven modules run outside any Effect fiber — remark visitors, Shiki's
+* `preprocess` hook, Prettier callbacks, the page-generation stages — and each
+* carried its own byte-identical copy of this seam: a module-level
+* `emitEvent`, a module-level `currentBuildId`, and a `setXEventEmitter(fn,
+* buildId)` for `plugin.ts` to call. Two of them had already grown a third
+* parameter for `slowCodeBlockMs`, which is how a duplicated seam decays: the
+* copies stop being identical one caller at a time.
+*
+* The seam itself is forced. The duplication was not, and neither was the
+* threading: every value those setters carried is now a `Context.Reference`
+* read from the runtime, so the signature is one runtime and nothing else.
+*
+* **The runtime handed here must be synchronously buildable.** `runSync`
+* builds the runtime's layer before running anything, so a runtime whose layer
+* opens a database fails with `AsyncFiberError` at the first emit — from a
+* remark plugin, during RSPress's render pass, invisible to every unit test.
+* `plugin.ts` builds a small observability-only runtime for exactly this
+* reason.
+*
+* @packageDocumentation
+*/
+const NOOP = {
+	emit: () => {},
+	buildId: "",
+	slowCodeBlockMs: Number.POSITIVE_INFINITY
+};
+let current = NOOP;
+/**
+* Bind the sync islands to a runtime.
+*
+* @remarks
+* Call once, immediately after constructing the observability runtime. The
+* References are read here rather than per emit: an emit happens per code
+* block on a large site, and these values are fixed for the build.
+*/
+function installSyncEmitter(runtime) {
+	const env = runtime.runSync(Effect.gen(function* () {
+		return {
+			buildId: yield* BuildId,
+			slowCodeBlockMs: (yield* Thresholds).slowCodeBlock
+		};
+	}));
+	current = {
+		emit: (event) => runtime.runSync(emit(event)),
+		buildId: env.buildId,
+		slowCodeBlockMs: env.slowCodeBlockMs
+	};
+}
+/** Emit an event from synchronous code. A no-op when nothing is installed. */
+function emitSync(event) {
+	current.emit(event);
+}
+/** The current build's id, for a sync site assembling an `EventContext`. */
+function syncBuildId() {
+	return current.buildId;
+}
+/**
+* The slow-code-block threshold, for the two remark plugins that time blocks.
+*
+* @remarks
+* The only piece of configuration a sync island needs beyond the build id, and
+* the reason the old seams had begun growing divergent signatures.
+*/
+function syncSlowCodeBlockMs() {
+	return current.slowCodeBlockMs;
+}
+
+//#endregion
+export { emitSync, installSyncEmitter, syncBuildId, syncSlowCodeBlockMs };