rspress-plugin-api-extractor 0.10.0 → 0.12.0

package/layers/type-environment.js

@@ -0,0 +1,109 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { resolveTypeScriptConfig } from "../typescript-config.js";
+import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
+import { ConfigValidationError } from "../errors.js";
+import { twoslashEnvHash } from "../twoslash-cache.js";
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
+import { Effect } from "effect";
+import ts from "typescript";
+
+//#region src/layers/type-environment.ts
+/**
+* Building the build's Twoslash type-checking environments.
+*
+* @remarks
+* The last phase of config resolution, and the only one that has to run after
+* every API has contributed to the VFS: the result cache is keyed on the type
+* environment, so it can only be opened once the VFS is final, and no code
+* block may be rendered before it is.
+*
+* @packageDocumentation
+*/
+/**
+* Resolve a TypeScript configuration, failing typed on a malformed one.
+*
+* @remarks
+* `resolveTypeScriptConfig` throws a `TsConfigParseError` for a missing file, a
+* syntax error or a semantically invalid config. Both call sites used to run it
+* inside `Effect.promise`, so all three became untyped defects: the build died
+* with an unhandled rejection naming a file the user could fix, and wrote no
+* `issues.json` entry for it.
+*
+* A malformed tsconfig is a user misconfiguration, so it is fatal and TYPED —
+* not degraded. Falling back to default compiler options would type-check every
+* example against a configuration the user did not ask for and silently render
+* wrong hovers, which is the failure shape this subsystem suffers from most
+* (see the `lib`-spelling defect in `type-loading-vfs.md`).
+*/
+const resolveTsConfigTyped = (projectRoot, config) => Effect.tryPromise({
+	try: () => resolveTypeScriptConfig(projectRoot, config),
+	catch: (cause) => new ConfigValidationError({
+		field: "tsconfig",
+		reason: cause instanceof Error ? cause.message : String(cause),
+		cause
+	})
+});
+/**
+* Open the Twoslash result cache and register one environment per distinct
+* compiler configuration.
+*
+* @remarks
+* **The build-wide options are registered FIRST, deliberately.** An unknown
+* scope falls back to the first environment registered, and a `with-api` fence
+* can appear on a page outside any documented package's route — checking it
+* under the build-wide configuration beats not checking it at all.
+*
+* Resolution is memoised twice over. This function memoises by RAW config, so
+* N APIs sharing a tsconfig read it from disk once; `registerEnvironment` then
+* dedupes by a fingerprint of the ENCODED options, so APIs that spell the same
+* configuration differently still share one TypeScript environment. The second
+* of those is load-bearing: when the two fingerprints drifted apart once, every
+* scope lookup missed, per-scope type-checking silently degraded to build-wide,
+* and a 994-test suite stayed green through it.
+*/
+const registerTypeEnvironments = (input) => Effect.gen(function* () {
+	const twoslashEnv = twoslashEnvHash(input.combinedVfs, `typescript@${ts.version}`);
+	const twoslashCache = yield* (yield* TwoslashCacheService).open(twoslashEnv);
+	yield* emit(PluginEvent.TwoslashCacheLoaded({
+		ctx: {},
+		level: "debug",
+		envHash: twoslashEnv,
+		entries: twoslashCache.entries().size
+	}));
+	const twoslashStartMs = performance.now();
+	const environments = yield* TwoslashEnvironments;
+	environments.registerEnvironment({
+		vfs: input.combinedVfs,
+		compilerOptions: input.resolvedCompilerOptions,
+		typesCache: twoslashCache
+	});
+	const resolvedByRawConfig = /* @__PURE__ */ new Map();
+	for (const [apiScope, rawConfig] of input.scopeTsConfigs) {
+		if (rawConfig === void 0) {
+			environments.registerScope(apiScope, input.resolvedCompilerOptions);
+			continue;
+		}
+		const rawKey = JSON.stringify([String(rawConfig.tsconfig ?? ""), rawConfig.compilerOptions ?? null]);
+		let scopeOptions = resolvedByRawConfig.get(rawKey);
+		if (scopeOptions === void 0) {
+			scopeOptions = yield* resolveTsConfigTyped(input.projectRoot, rawConfig);
+			resolvedByRawConfig.set(rawKey, scopeOptions);
+		}
+		environments.registerEnvironment({
+			vfs: input.combinedVfs,
+			compilerOptions: scopeOptions,
+			typesCache: twoslashCache
+		});
+		environments.registerScope(apiScope, scopeOptions);
+	}
+	yield* emit(PluginEvent.TwoslashInitialized({
+		ctx: {},
+		level: "debug",
+		durationMs: Math.round(performance.now() - twoslashStartMs),
+		vfsFileCount: input.combinedVfs.size
+	}));
+});
+
+//#endregion
+export { registerTypeEnvironments, resolveTsConfigTyped };

package/layers/xdg.js

@@ -0,0 +1,44 @@
+import { Layer, Path } from "effect";
+import { NodeFileSystem } from "@effect/platform-node";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/layers/xdg.ts
+/**
+* The plugin's shared platform and XDG layers.
+*
+* @remarks
+* Both cache-backed services — the type registry and the Twoslash result cache
+* — need a Node platform and an XDG app-directory root, and both used to
+* declare their own. Two consequences, both fixed by having one home:
+*
+* 1. **Two distinct layer references build twice.** Layer memoization is by
+*    reference, so a second `Layer.mergeAll(NodeFileSystem.layer, Path.layer)`
+*    is a different layer as far as the memo map is concerned, and the XDG
+*    resolution ran once per consumer.
+* 2. **The namespace literal was copy-pasted.** The house style bans exactly
+*    this: when two sibling layers must agree on an identity string, the
+*    agreement has to be structural rather than textual. A drift here is
+*    silent and permanent — the caches move to a different directory, every
+*    lookup misses, and a build that should hit a warm Twoslash cache goes
+*    cold forever with no error and nothing in the output to notice.
+*
+* @packageDocumentation
+*/
+/**
+* The XDG namespace every cache this plugin keeps lives under.
+*
+* @remarks
+* One definition, deliberately. Changing it invalidates every on-disk cache —
+* the type registry's `metadata.sqlite` and the Twoslash result cache's
+* `twoslash.sqlite` — which is a cold refetch and a full re-type-check, not an
+* error. That was accepted once, at the phase-2 rename from
+* `type-registry-effect`; do not do it casually.
+*/
+const TSDOCTOR_NAMESPACE = "tsdoctor";
+/** Node platform services: the filesystem and path implementations. */
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
+/** XDG application directories rooted at {@link TSDOCTOR_NAMESPACE}. */
+const AppDirsLive = AppDirs.layer({ namespace: TSDOCTOR_NAMESPACE }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
+
+//#endregion
+export { AppDirsLive, PlatformLive, TSDOCTOR_NAMESPACE };

package/markdown/helpers.js

@@ -4,7 +4,6 @@ import { formatCode } from "../prettier-formatter.js";
 import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 
 //#region src/markdown/helpers.ts
-/* v8 ignore start -- markdown generation helpers, tested via page generator integration tests */
 /**
 * Helper utilities for generating markdown API documentation.
 *
@@ -50,63 +49,18 @@ function prepareExampleCode(example, apiItemName, packageName, suppressErrors =
 	};
 }
 /**
-* Sanitize a display name to create a URL-safe HTML ID.
-*
-* Converts a display name (e.g., method or property name) into a valid
-* HTML ID suitable for anchor links. Handles special characters, quotes,
-* and optionally adds a prefix for disambiguation.
-*
-* @param displayName - The original display name
-* @param prefix - Optional prefix to add (e.g., "static-property")
-* @returns URL-safe ID string
-*
-* @example
-* ```ts
-* sanitizeId("myMethod");        // "mymethod"
-* sanitizeId("get value");       // "get-value"
-* sanitizeId("run", "static");   // "static-run"
-* ```
-*/
-function sanitizeId(displayName, prefix = "") {
-	const baseName = displayName.replace(/["']/g, "").replace(/[^\w-]/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
-	return prefix ? `${prefix}-${baseName}` : baseName;
-}
-/**
-* Escape a YAML string value by handling special characters.
-*
-* Normalizes whitespace and wraps strings in double quotes if they contain
-* characters that could break YAML parsing (colons, quotes, hashes, pipes,
-* brackets, braces, Unicode characters, etc.).
-*
-* @param value - The string value to escape
-* @returns YAML-safe string
-*
-* @example
-* ```ts
-* escapeYamlString("Hello World");           // "Hello World"
-* escapeYamlString("Type: string");          // "\"Type: string\""
-* escapeYamlString("He said \"hello\"");     // "\"He said \\\"hello\\\"\""
-* escapeYamlString("@pkg/name。:");          // "\"@pkg/name。:\""
-* ```
-*/
-/**
-* Normalize a string for use as a YAML frontmatter value: collapse newlines
-* and repeated whitespace to single spaces and trim.
-*
-* This is the cleaning half of the former hand-rolled YAML escaping. It is
-* applied to every frontmatter value BEFORE serialization so the parsed data
-* (and therefore the snapshot frontmatter hash — see `@tsdoctor/snapshot`)
-* is byte-identical to what the previous emitter produced; the quoting half
-* is now owned by the real YAML emitter in `../frontmatter.ts`.
+* Collapse newlines and runs of whitespace to single spaces, and trim.
+*
+* @remarks
+* Applied to every frontmatter scalar before emission. This is NOT quoting —
+* `@effected/yaml` owns that — it is whitespace normalization, and it is
+* load-bearing: the snapshot system hashes the PARSED frontmatter, so a value
+* that folds differently between builds would churn the hash. Survives the
+* removal of `escapeYamlString`, which was its other caller.
 */
 function cleanYamlValue(value) {
 	return value.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
 }
-function escapeYamlString(value) {
-	const cleaned = cleanYamlValue(value);
-	if (/["':#|>&*!%@`[\]{},?-]/.test(cleaned) || /[\u0080-\uFFFF]/.test(cleaned) || /^(true|false|null|~|yes|no|on|off)$/i.test(cleaned) || /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(cleaned)) return `"${cleaned.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
-	return cleaned;
-}
 /**
 * Escape generic type parameters in MDX by wrapping them in backticks.
 *
@@ -334,4 +288,4 @@ async function formatExampleCode(code, language, _context) {
 }
 
 //#endregion
-export { escapeMdxGenerics, escapeYamlString, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives };
+export { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives };

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
+* `ConfigService.layer.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/model-loader.js

@@ -1,5 +1,5 @@
 import { isLoadedModel, isVersionConfig } from "./config-utils.js";
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 import { Effect } from "effect";
 import { Model } from "@tsdoctor/model";
@@ -10,8 +10,8 @@ import { Model } from "@tsdoctor/model";
 */
 async function loadPackageJsonFromPath(pkgPath) {
 	const resolvedPath = path.resolve(pkgPath.toString());
-	if (!fs.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
-	const content = fs.readFileSync(resolvedPath, "utf-8");
+	if (!fsSync.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
+	const content = fsSync.readFileSync(resolvedPath, "utf-8");
 	try {
 		return JSON.parse(content);
 	} catch (error) {

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 `ConfigService.layer`, where the real value sat
+* three scopes up and was simply not reached, and every site in
+* `TypeRegistryService.layer`, 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/heartbeat.js

@@ -1,6 +1,6 @@
+import { BuildMetrics } from "../layers/build-metrics.js";
 import { PluginEvent } from "./events.js";
 import { emit } from "./EventBus.js";
-import { BuildMetrics } from "../layers/build-metrics.js";
 import { Duration, Effect, Metric, Ref } from "effect";
 
 //#region src/observability/heartbeat.ts

package/observability/sinks/metrics-sink.js

@@ -18,7 +18,7 @@ import { Metric } from "effect";
 * such as a file path, belongs in a sample-shaped sink instead.
 *
 * Intentionally NOT derived here: `externalPackagesTotal` and `apiVersionsLoaded`
-* remain inline increments in `ConfigServiceLive`. `externalPackagesTotal` counts
+* remain inline increments in `ConfigService.layer`. `externalPackagesTotal` counts
 * CONFIGURED packages via `incrementBy(length)`; the only candidate event,
 * `TypeRegistryEvent{BatchComplete}`, carries an unstructured `detail` string and
 * a `loaded` (SUCCEEDED) count — different semantics, so deriving it here would

package/observability/sinks/trace-sink.js

@@ -1,10 +1,10 @@
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 
 //#region src/observability/sinks/trace-sink.ts
 function openTracePath(p) {
-	fs.mkdirSync(path.dirname(p), { recursive: true });
-	fs.writeFileSync(p, "");
+	fsSync.mkdirSync(path.dirname(p), { recursive: true });
+	fsSync.writeFileSync(p, "");
 }
 /**
 * Create a JSONL trace sink, opening the file eagerly at construction.
@@ -21,7 +21,7 @@ function makeTraceSink(tracePath) {
 		minLevel: "trace",
 		capturesPayload: true,
 		handle: (event) => {
-			fs.appendFileSync(tracePath, `${JSON.stringify(event)}\n`);
+			fsSync.appendFileSync(tracePath, `${JSON.stringify(event)}\n`);
 		},
 		flush: () => {}
 	};

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",