rspress-plugin-api-extractor 0.2.2 → 0.3.0

package/layers/ObservabilityLive.js

@@ -1,102 +1,61 @@
-import { Effect, Layer, LogLevel, Logger, Metric, MetricBoundaries } from "effect";
+import { makeEventBusLayer } from "../observability/EventBus.js";
+import { makeConsoleSink } from "../observability/sinks/console-sink.js";
+import { BuildMetrics } from "./build-metrics.js";
+import { makeMetricsSink } from "../observability/sinks/metrics-sink.js";
+import { makeTraceSink } from "../observability/sinks/trace-sink.js";
+import { Effect, Layer, LogLevel, Logger, Metric } from "effect";
 
 //#region src/layers/ObservabilityLive.ts
-/**
-* All build metrics as named counters/histograms.
-*
-* Note: Effect Metrics use a process-wide registry. In tests, counters
-* accumulate across test cases within the same process. Test assertions
-* should use loose matching (toContain) rather than exact count checks.
-*/
-const BuildMetrics = {
-	filesTotal: Metric.counter("files.total"),
-	filesNew: Metric.counter("files.new"),
-	filesModified: Metric.counter("files.modified"),
-	filesUnchanged: Metric.counter("files.unchanged"),
-	codeblockDuration: Metric.histogram("codeblock.duration", MetricBoundaries.fromIterable([
-		10,
-		25,
-		50,
-		100,
-		200,
-		500,
-		1e3
-	])),
-	codeblockShikiDuration: Metric.histogram("codeblock.shiki.duration", MetricBoundaries.fromIterable([
-		5,
-		10,
-		25,
-		50,
-		100,
-		250
-	])),
-	codeblockTotal: Metric.counter("codeblock.total"),
-	codeblockSlow: Metric.counter("codeblock.slow"),
-	twoslashErrors: Metric.counter("twoslash.errors"),
-	prettierErrors: Metric.counter("prettier.errors"),
-	pagesGenerated: Metric.counter("pages.generated"),
-	apiVersionsLoaded: Metric.counter("api.versions.loaded"),
-	externalPackagesTotal: Metric.counter("external.packages.total")
-};
-/**
-* Format a Date as HH:MM:SS for console output.
-*/
 function formatTime(date) {
 	return date.toTimeString().slice(0, 8);
 }
 /**
-* Extract annotations from HashMap to a plain object.
-*/
-function annotationsToObject(annotations) {
-	const obj = {};
-	for (const [key, value] of annotations) obj[key] = value;
-	return obj;
-}
-/**
-* Create a custom plugin logger for the given mode.
-* Uses a closure to capture debugMode — no mutable module state.
+* A slim Effect Logger layer that gates the residual `Effect.log*` calls in
+* `build-program.ts` and `logBuildSummary` at the configured level.
+*
+* Level mapping: none→None, error→Error, warn→Warning, info→Info,
+* debug/trace→Debug.  Format: `[HH:MM:SS] <prefix><message>` with
+* `⚠️  ` / `🔴 ` prefixes for Warning / Error to match the EventBus
+* console-sink style.
 */
-function makePluginLogger(debugMode) {
-	return Logger.make(({ logLevel, message, date, annotations }) => {
-		if (debugMode) {
-			const entry = {
-				timestamp: date.getTime(),
-				level: logLevel.label.toLowerCase(),
-				message: typeof message === "string" ? message : String(message),
-				...annotationsToObject(annotations)
-			};
-			console.log(JSON.stringify(entry));
-		} else {
-			const time = formatTime(date);
-			const msg = typeof message === "string" ? message : String(message);
-			const prefix = logLevel._tag === "Warning" ? "⚠️  " : logLevel._tag === "Error" ? "🔴 " : "";
-			console.log(`[${time}] ${prefix}${msg}`);
-		}
+function makeSummaryLoggerLayer(logLevel) {
+	const effectLevel = logLevel === "none" ? LogLevel.None : logLevel === "error" ? LogLevel.Error : logLevel === "warn" ? LogLevel.Warning : logLevel === "info" ? LogLevel.Info : LogLevel.Debug;
+	const pluginLogger = Logger.make(({ logLevel: lvl, message, date }) => {
+		const time = formatTime(date);
+		const msg = typeof message === "string" ? message : String(message);
+		const prefix = lvl._tag === "Warning" ? "⚠️  " : lvl._tag === "Error" ? "🔴 " : "";
+		console.log(`[${time}] ${prefix}${msg}`);
 	});
+	return Layer.mergeAll(Logger.replace(Logger.defaultLogger, pluginLogger), Logger.minimumLogLevel(effectLevel));
 }
 /**
-* Create the complete observability layer for the plugin.
-* Replaces the default Effect logger with a custom one and sets minimum log level.
+* Compose the console + metrics (+ optional trace) sinks into an EventBus layer.
+*
+* When `traceIsDefault` is true the trace path was derived from the guessed
+* outDir at factory time.  In that case we create the sink in deferred mode
+* (no `initialPath`) so no stray empty file is written to the guessed path;
+* `plugin.ts` must call `trace.setPath(realPath)` in the `config()` hook once
+* the real RSPress `outDir` is known.
 *
-* @param logLevel - Plugin log level from options
+* When `traceIsDefault` is false the caller supplied an explicit path string,
+* so we open the file eagerly (existing behaviour).
 */
-function PluginLoggerLayer(logLevel = "info") {
-	const pluginLogger = makePluginLogger(logLevel === "debug");
-	const effectLogLevel = {
-		debug: LogLevel.Debug,
-		verbose: LogLevel.Debug,
-		info: LogLevel.Info,
-		warn: LogLevel.Warning,
-		error: LogLevel.Error,
-		none: LogLevel.None
-	}[logLevel];
-	return Layer.mergeAll(Logger.replace(Logger.defaultLogger, pluginLogger), Logger.minimumLogLevel(effectLogLevel));
+function buildEventBus(obs, traceIsDefault = false) {
+	const sinks = [makeConsoleSink(obs.logLevel, { json: obs.json }), makeMetricsSink()];
+	const trace = obs.tracePath ? makeTraceSink(traceIsDefault ? void 0 : obs.tracePath) : null;
+	if (trace) sinks.push(trace);
+	return {
+		layer: makeEventBusLayer(sinks),
+		trace
+	};
 }
 /**
 * Log a build summary by reading all metric snapshots.
+* Accepts the configured slow-codeblock threshold so the warning message
+* interpolates the actual threshold rather than a hard-coded 100ms.
 * Replaces the 4 separate logSummary() calls in afterBuild.
 */
-const logBuildSummary = Effect.gen(function* () {
+const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
 	const filesTotal = yield* Metric.value(BuildMetrics.filesTotal);
 	const filesNew = yield* Metric.value(BuildMetrics.filesNew);
 	const filesModified = yield* Metric.value(BuildMetrics.filesModified);
@@ -105,6 +64,9 @@ const logBuildSummary = Effect.gen(function* () {
 	const prettierErrors = yield* Metric.value(BuildMetrics.prettierErrors);
 	const codeblockTotal = yield* Metric.value(BuildMetrics.codeblockTotal);
 	const codeblockSlow = yield* Metric.value(BuildMetrics.codeblockSlow);
+	const pagesGenerated = yield* Metric.value(BuildMetrics.pagesGenerated);
+	const externalPackages = yield* Metric.value(BuildMetrics.externalPackagesTotal);
+	const phaseDurationSnapshot = yield* Metric.value(BuildMetrics.phaseDuration);
 	const total = filesTotal.count;
 	const newCount = filesNew.count;
 	const modified = filesModified.count;
@@ -122,15 +84,17 @@ const logBuildSummary = Effect.gen(function* () {
 		if (unchanged > 0) parts.push(`${unchanged} unchanged`);
 		yield* Effect.log(`📝 ${total} files (${parts.join(", ")})`);
 	}
-	if (blocks > 0 && slowBlocks > 0) yield* Effect.logWarning(`⚠️  Code block performance: ${slowBlocks} of ${blocks} blocks were slow (>100ms)`);
+	if (pagesGenerated.count > 0) yield* Effect.log(`🧩 ${pagesGenerated.count} pages, ${externalPackages.count} external package(s)`);
+	if (phaseDurationSnapshot.count > 0) yield* Effect.log(`⏱ ${phaseDurationSnapshot.count} phase(s) timed`);
+	if (blocks > 0 && slowBlocks > 0) yield* Effect.logWarning(`Code block performance: ${slowBlocks} of ${blocks} blocks were slow (>${slowCodeBlockMs}ms)`);
 	const totalErrors = tsErrors + prErrors;
 	if (totalErrors > 0) {
 		const errorParts = [];
 		if (tsErrors > 0) errorParts.push(`${tsErrors} Twoslash`);
 		if (prErrors > 0) errorParts.push(`${prErrors} Prettier`);
-		yield* Effect.logWarning(`🔴 ${totalErrors} error(s) in code blocks (${errorParts.join(", ")})`);
+		yield* Effect.logWarning(`${totalErrors} error(s) in code blocks (${errorParts.join(", ")})`);
 	}
 });
 
 //#endregion
-export { BuildMetrics, PluginLoggerLayer, logBuildSummary };
+export { buildEventBus, logBuildSummary, makeSummaryLoggerLayer };

package/layers/TypeRegistryServiceLive.js

@@ -1,20 +1,134 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { resolveExternalPackageVersions } from "../config-utils.js";
 import { TypeRegistryError } from "../errors.js";
 import { TypeRegistryService } from "../services/TypeRegistryService.js";
 import { Effect, Layer } from "effect";
-import { PackageSpec, TypeRegistry } from "type-registry-effect";
-import { NodeLayer, createTypeScriptCache } from "type-registry-effect/node";
+import { PackageSpec, RegistryEvent, TypeRegistry, TypeRegistryObserver } from "type-registry-effect";
+import { NodeLayer } from "type-registry-effect/node";
 
 //#region src/layers/TypeRegistryServiceLive.ts
 /**
-* TypeRegistryServiceLive: uses type-registry-effect Effect programs directly.
+* Forward type-registry-effect's typed `RegistryEvent`s to the plugin's Effect
+* logger. Since v1 the library emits no logs of its own — observers are the only
+* diagnostic surface — so this restores the build output and routes it through
+* the plugin's configured log level/format (a single source, no duplication).
 *
-* The NodeLayer from type-registry-effect provides CacheService, PackageFetcher,
-* and TypeResolver with Node.js platform implementations (FileSystem, HttpClient).
+* The summary (`BatchComplete`) and failures are surfaced at info/warning;
+* per-package detail stays at debug so a normal build is quiet.
+*/
+const RegistryObserverLayer = Layer.succeed(TypeRegistryObserver, { emit: (event) => RegistryEvent.$match(event, {
+	VersionResolved: ({ package: pkg, requested, resolved }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg
+		},
+		level: "debug",
+		kind: "VersionResolved",
+		detail: `${requested} -> ${resolved}`
+	})),
+	VersionResolveFailed: ({ package: pkg, requested, reason }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg
+		},
+		level: "debug",
+		kind: "VersionResolveFailed",
+		detail: `${requested}: ${reason}`
+	})),
+	CacheHit: ({ package: pkg, version }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg,
+			version
+		},
+		level: "debug",
+		kind: "CacheHit",
+		detail: ""
+	})),
+	CacheStale: ({ package: pkg, version }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg,
+			version
+		},
+		level: "debug",
+		kind: "CacheStale",
+		detail: ""
+	})),
+	CacheMiss: ({ package: pkg, version }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg,
+			version
+		},
+		level: "debug",
+		kind: "CacheMiss",
+		detail: ""
+	})),
+	FetchStart: ({ package: pkg, version }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg,
+			version
+		},
+		level: "debug",
+		kind: "FetchStart",
+		detail: ""
+	})),
+	FetchFailed: ({ url, status, bodySnippet }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: { buildId: "" },
+		level: "debug",
+		kind: "FetchFailed",
+		detail: `HTTP ${status}: ${url}${bodySnippet ? ` — ${bodySnippet}` : ""}`
+	})),
+	PackageLoaded: ({ package: pkg, version, files, source }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg,
+			version
+		},
+		level: "debug",
+		kind: "PackageLoaded",
+		detail: `${files} files, ${source}`
+	})),
+	PackageLoadFailed: ({ package: pkg, version, kind, message }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: {
+			buildId: "",
+			packageName: pkg,
+			version
+		},
+		level: "warn",
+		kind: "PackageLoadFailed",
+		detail: `[${kind}] ${message}`
+	})),
+	BatchStart: ({ total }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: { buildId: "" },
+		level: "debug",
+		kind: "BatchStart",
+		detail: `${total} package(s)`
+	})),
+	BatchComplete: ({ loaded, total, totalFiles, durationMs }) => emit(PluginEvent.TypeRegistryEvent({
+		ctx: { buildId: "" },
+		level: "info",
+		kind: "BatchComplete",
+		detail: `${loaded}/${total} packages, ${totalFiles} files, ${durationMs}ms`
+	}))
+}) });
+/**
+* type-registry-effect runtime: the Node platform layer plus the observer that
+* forwards registry events to the plugin logger.
 *
-* Built-in metrics (packagesLoaded, packagesFailed, cacheHits, etc.) are
-* automatically tracked by the upstream library.
+* `NodeLayer` provides CacheService, PackageFetcher, and TypeResolver with
+* Node.js platform implementations (FileSystem, HttpClient). Built-in metrics
+* (packagesLoaded, packagesFailed, cacheHits, etc.) are tracked by the library.
+*/
+const RegistryLayer = Layer.merge(NodeLayer, RegistryObserverLayer);
+/**
+* TypeRegistryServiceLive: uses type-registry-effect Effect programs directly.
 */
 const TypeRegistryServiceLive = Layer.succeed(TypeRegistryService, {
+	resolveVersions: (packages) => resolveExternalPackageVersions(packages, (pkg) => TypeRegistry.resolveVersion(pkg.name, pkg.version)).pipe(Effect.provide(RegistryLayer)),
 	loadPackages: (packages) => Effect.gen(function* () {
 		if (packages.length === 0) return { vfs: /* @__PURE__ */ new Map() };
 		const specs = packages.map((pkg) => new PackageSpec({
@@ -26,20 +140,7 @@ const TypeRegistryServiceLive = Layer.succeed(TypeRegistryService, {
 			version: packages.map((p) => p.version).join(", "),
 			reason: error.message ?? String(error)
 		})))) };
-	}).pipe(Effect.provide(NodeLayer)),
-	createTypeScriptCache: (packages, compilerOptions) => Effect.tryPromise({
-		try: () => {
-			return createTypeScriptCache(packages.map((pkg) => new PackageSpec({
-				name: pkg.name,
-				version: pkg.version
-			})), compilerOptions);
-		},
-		catch: (error) => new TypeRegistryError({
-			packageName: packages.map((p) => p.name).join(", "),
-			version: "",
-			reason: error instanceof Error ? error.message : String(error)
-		})
-	})
+	}).pipe(Effect.provide(RegistryLayer))
 });
 
 //#endregion

package/layers/build-metrics.js

@@ -0,0 +1,61 @@
+import { Metric, MetricBoundaries } from "effect";
+
+//#region src/layers/build-metrics.ts
+/**
+* All build metrics as named counters/histograms.
+*
+* Note: Effect Metrics use a process-wide registry. In tests, counters
+* accumulate across test cases within the same process. Test assertions
+* should use loose matching (toContain) rather than exact count checks.
+*
+* Extracted into its own module so that `metrics-sink.ts` can import it
+* without creating a circular dependency through `ObservabilityLive.ts`
+* (which itself imports `metrics-sink.ts`).
+*/
+const BuildMetrics = {
+	filesTotal: Metric.counter("files.total"),
+	filesNew: Metric.counter("files.new"),
+	filesModified: Metric.counter("files.modified"),
+	filesUnchanged: Metric.counter("files.unchanged"),
+	codeblockDuration: Metric.histogram("codeblock.duration", MetricBoundaries.fromIterable([
+		10,
+		25,
+		50,
+		100,
+		200,
+		500,
+		1e3
+	])),
+	codeblockShikiDuration: Metric.histogram("codeblock.shiki.duration", MetricBoundaries.fromIterable([
+		5,
+		10,
+		25,
+		50,
+		100,
+		250
+	])),
+	codeblockTotal: Metric.counter("codeblock.total"),
+	codeblockSlow: Metric.counter("codeblock.slow"),
+	twoslashErrors: Metric.counter("twoslash.errors"),
+	prettierErrors: Metric.counter("prettier.errors"),
+	pagesGenerated: Metric.counter("pages.generated"),
+	apiVersionsLoaded: Metric.counter("api.versions.loaded"),
+	externalPackagesTotal: Metric.counter("external.packages.total"),
+	phaseDuration: Metric.histogram("phase.duration", MetricBoundaries.fromIterable([
+		50,
+		100,
+		250,
+		500,
+		1e3,
+		2500,
+		5e3,
+		1e4
+	])),
+	vfsFiles: Metric.counter("vfs.files"),
+	importsPrepended: Metric.counter("imports.prepended"),
+	twoslashDiagnostics: Metric.counter("twoslash.diagnostics"),
+	configDefaultsApplied: Metric.counter("config.defaults.applied")
+};
+
+//#endregion
+export { BuildMetrics };

package/llms-program.js

@@ -1,3 +1,5 @@
+import { PluginEvent } from "./observability/events.js";
+import { emit } from "./observability/EventBus.js";
 import { filterLlmsFullTxt, filterLlmsTxt, generatePackageLlmsFullTxt, generatePackageLlmsTxt, generateStructuredLlmsTxt, parseLlmsTxtLine } from "./llms-processing.js";
 import path from "node:path";
 import { Effect } from "effect";
@@ -173,19 +175,24 @@ function collectApiPageContent(globalLlmsFullContent, result) {
 function processLlmsFiles(input) {
 	return Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
-		const { outDir, buildResults, llmsPlugin, packageRoutes } = input;
+		const { outDir, buildResults, llmsPlugin, packageRoutes, buildId } = input;
+		const ctx = { buildId };
 		if (buildResults.length === 0) return;
 		const apiRoutes = buildApiRoutes(buildResults);
-		yield* Effect.logDebug(`Built ${apiRoutes.size} API routes for LLMs filtering`);
+		yield* emit(PluginEvent.LlmsRoutesBuilt({
+			ctx,
+			level: "debug",
+			count: apiRoutes.size
+		}));
 		if (apiRoutes.size === 0) return;
 		const prefixes = discoverPrefixes(buildResults);
-		yield* Effect.forEach([...prefixes], (prefix) => processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin, packageRoutes), { concurrency: "unbounded" });
+		yield* Effect.forEach([...prefixes], (prefix) => processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin, packageRoutes, ctx), { concurrency: "unbounded" });
 	});
 }
 /**
 * Process global and per-package LLMs files for a single prefix.
 */
-function processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin, packageRoutes) {
+function processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin, packageRoutes, ctx) {
 	return Effect.gen(function* () {
 		const prefixDir = prefix ? path.join(outDir, prefix) : outDir;
 		const llmsTxtPath = path.join(prefixDir, "llms.txt");
@@ -216,19 +223,25 @@ function processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin,
 		}
 		if (llmsPlugin.scopes) {
 			const prefixResults = prefix === "" ? [...buildResults] : buildResults.filter((r) => r.baseRoute.startsWith(`/${prefix}/`));
-			yield* Effect.forEach(prefixResults, (result) => generatePerPackageFiles(fs, outDir, result, llmsTxtContent, llmsFullTxtContent, apiRoutes, llmsPlugin, packageRoutes.get(result.packageName) ?? result.baseRoute), { concurrency: "unbounded" });
+			yield* Effect.forEach(prefixResults, (result) => generatePerPackageFiles(fs, outDir, result, llmsTxtContent, llmsFullTxtContent, apiRoutes, llmsPlugin, packageRoutes.get(result.packageName) ?? result.baseRoute, ctx), { concurrency: "unbounded" });
 		}
+		yield* emit(PluginEvent.LlmsPrefixProcessed({
+			ctx,
+			level: "debug",
+			prefix
+		}));
 	});
 }
 /**
 * Generate per-package LLMs files (llms.txt, llms-full.txt, llms-docs.txt, llms-api.txt).
 */
-function generatePerPackageFiles(fs, outDir, result, globalLlmsTxtContent, globalLlmsFullContent, apiRoutes, llmsPlugin, packageRoute) {
+function generatePerPackageFiles(fs, outDir, result, globalLlmsTxtContent, globalLlmsFullContent, apiRoutes, llmsPlugin, packageRoute, ctx) {
 	return Effect.gen(function* () {
 		const pkgRouteSegment = packageRoute.replace(/^\//, "");
 		const packageLlmsDir = pkgRouteSegment ? path.join(outDir, pkgRouteSegment) : outDir;
 		yield* fs.makeDirectory(packageLlmsDir, { recursive: true }).pipe(Effect.orDie);
 		const displayName = result.apiName ?? result.packageName;
+		const writtenFiles = [];
 		const apiEntries = collectApiEntries(globalLlmsTxtContent, result);
 		const guideEntries = collectGuideEntries(globalLlmsTxtContent, apiRoutes, packageRoute);
 		const packageLlmsTxt = generatePackageLlmsTxt({
@@ -238,6 +251,7 @@ function generatePerPackageFiles(fs, outDir, result, globalLlmsTxtContent, globa
 			apiPages: apiEntries
 		});
 		yield* fs.writeFileString(path.join(packageLlmsDir, "llms.txt"), packageLlmsTxt).pipe(Effect.orDie);
+		writtenFiles.push("llms.txt");
 		const apiPageContent = collectApiPageContent(globalLlmsFullContent, result);
 		const guideRouteUrls = new Set(guideEntries.map((e) => e.url));
 		const guidePageContent = globalLlmsFullContent ? extractSections(globalLlmsFullContent, (url) => guideRouteUrls.has(url)) : [];
@@ -245,16 +259,24 @@ function generatePerPackageFiles(fs, outDir, result, globalLlmsTxtContent, globa
 		if (fullPageContent.length > 0) {
 			const packageLlmsFullTxt = generatePackageLlmsFullTxt(fullPageContent);
 			yield* fs.writeFileString(path.join(packageLlmsDir, "llms-full.txt"), packageLlmsFullTxt).pipe(Effect.orDie);
+			writtenFiles.push("llms-full.txt");
 		}
 		if (llmsPlugin.apiTxt && apiPageContent.length > 0) {
 			const apiTxtContent = generatePackageLlmsFullTxt(apiPageContent);
 			yield* fs.writeFileString(path.join(packageLlmsDir, "llms-api.txt"), apiTxtContent).pipe(Effect.orDie);
+			writtenFiles.push("llms-api.txt");
 		}
 		if (guidePageContent.length > 0) {
 			const docsTxtContent = generatePackageLlmsFullTxt(guidePageContent);
 			yield* fs.writeFileString(path.join(packageLlmsDir, "llms-docs.txt"), docsTxtContent).pipe(Effect.orDie);
+			writtenFiles.push("llms-docs.txt");
 		}
-		yield* Effect.logDebug(`Generated LLMs files for ${displayName} in ${packageLlmsDir}`);
+		yield* emit(PluginEvent.LlmsPackageFilesGenerated({
+			ctx,
+			level: "debug",
+			dir: packageLlmsDir,
+			files: writtenFiles
+		}));
 	});
 }
 

package/loader.js

@@ -1,7 +1,15 @@
+import { PluginEvent } from "./observability/events.js";
 import { ApiDocumentedItem, ApiItemKind } from "@microsoft/api-extractor-model";
 import { extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag } from "api-extractor-llms";
 
 //#region src/loader.ts
+/** Module-level emitter injected by plugin.ts at startup. */
+let emitEvent = () => {};
+let currentBuildId = "";
+function setLoaderEventEmitter(fn, buildId = "") {
+	emitEvent = fn;
+	currentBuildId = buildId;
+}
 /**
 * Parser for extracting and analyzing information from API Extractor models and TSDoc comments
 */
@@ -53,7 +61,13 @@ var ApiParser = class ApiParser {
 					break;
 				}
 			}
-			if (!categorized && typeof process !== "undefined" && !process.env.VITEST) console.warn(`⚠️  API item "${member.displayName}" (kind: ${member.kind}) not categorized`);
+			if (!categorized && typeof process !== "undefined" && !process.env.VITEST) emitEvent(PluginEvent.ItemSkipped({
+				ctx: { buildId: currentBuildId },
+				item: member.displayName,
+				kind: String(member.kind),
+				reason: "uncategorized",
+				level: "warn"
+			}));
 		}
 		return items;
 	}
@@ -183,4 +197,4 @@ var ApiParser = class ApiParser {
 };
 
 //#endregion
-export { ApiParser };
+export { ApiParser, setLoaderEventEmitter };

package/markdown/shiki-utils.js

@@ -1,4 +1,13 @@
+import { PluginEvent } from "../observability/events.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
 */
@@ -39,10 +48,15 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 		if (enableTwoslash) options.meta = { __raw: "twoslash" };
 		return await highlighter.codeToHast(code, options);
 	} catch (error) {
-		console.error("Failed to generate Shiki HAST:", error);
+		emitEvent(PluginEvent.ShikiError({
+			ctx: { buildId: currentBuildId },
+			file: "unknown",
+			reason: String(error),
+			level: "warn"
+		}));
 		return null;
 	}
 }
 
 //#endregion
-export { DEFAULT_SHIKI_THEMES, generateShikiHast };
+export { DEFAULT_SHIKI_THEMES, generateShikiHast, setShikiUtilsEventEmitter };

package/observability/EventBus.js

@@ -0,0 +1,38 @@
+import { LEVEL_RANK, levelOf } from "./events.js";
+import { Context, Effect, Layer, Option } from "effect";
+
+//#region src/observability/EventBus.ts
+var EventBus = class extends Context.Tag("rspress-plugin-api-extractor/EventBus")() {};
+function makeShape(sinks) {
+	const maxAdmitted = sinks.filter((s) => s.capturesPayload === true).reduce((max, s) => Math.max(max, LEVEL_RANK[s.minLevel]), -1);
+	return {
+		emit: (event) => Effect.sync(() => {
+			const rank = LEVEL_RANK[levelOf(event)];
+			for (const sink of sinks) if (rank <= LEVEL_RANK[sink.minLevel]) sink.handle(event);
+		}),
+		wantsLevel: (level) => Effect.succeed(LEVEL_RANK[level] <= maxAdmitted)
+	};
+}
+function makeEventBusLayer(sinks) {
+	return Layer.succeed(EventBus, makeShape(sinks));
+}
+/** No sinks: every emit is a no-op, wantsLevel always false. */
+const EventBusNoop = makeEventBusLayer([]);
+/** Emit when a bus is in context; silently no-op otherwise. */
+function emit(event) {
+	return Effect.serviceOption(EventBus).pipe(Effect.flatMap((maybe) => Option.isSome(maybe) ? maybe.value.emit(event) : Effect.void));
+}
+/**
+* Returns true when a bus is in context and has at least one sink admitted at
+* `level`; false otherwise. R = never, safe to use anywhere emit is used.
+*/
+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 { emit, makeEventBusLayer, makeRuntimeEmitter, wantsLevel };

package/observability/events.js

@@ -0,0 +1,17 @@
+import { Data } from "effect";
+
+//#region src/observability/events.ts
+const LEVEL_RANK = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	debug: 3,
+	trace: 4
+};
+const PluginEvent = Data.taggedEnum();
+function levelOf(event) {
+	return event.level;
+}
+
+//#endregion
+export { LEVEL_RANK, PluginEvent, levelOf };