rspress-plugin-api-extractor 0.2.2 → 0.3.0

package/observability/sinks/console-sink.js

@@ -0,0 +1,63 @@
+import { LEVEL_RANK, levelOf } from "../events.js";
+
+//#region src/observability/sinks/console-sink.ts
+function formatTime(date) {
+	return date.toTimeString().slice(0, 8);
+}
+/**
+* One-line human-readable summary of an event. Uses a switch on `_tag` (not
+* `PluginEvent.$match`, whose Effect signature requires EXHAUSTIVE cases with
+* no `_` wildcard). TypeScript narrows `event` to the variant in each case.
+* Extend per _tag as needed; the `default` arm renders the bare tag.
+*/
+function render(event) {
+	switch (event._tag) {
+		case "BuildStarted": return `Generating API documentation (${event.apiCount} API${event.apiCount === 1 ? "" : "s"})…`;
+		case "PhaseStarted": return `→ ${event.phase}`;
+		case "PhaseCompleted": return `✓ ${event.phase} (${event.durationMs}ms)`;
+		case "BuildCompleted": return `API documentation complete (${(event.durationMs / 1e3).toFixed(2)}s)`;
+		case "BuildFailed": return `Error in ${event.phase}: ${event.error}`;
+		case "SlowOperation": return `slow ${event.operation}: ${event.durationMs}ms (>${event.threshold}ms)`;
+		case "ConfigCascadeWarning": return `${event.field}: using '${event.chosen}', ignoring ${event.ignored.join(", ")}`;
+		case "ConfigValidationWarning": return `${event.field}: rejected '${event.value}'${event.reason ? ` — ${event.reason}` : ""}`;
+		case "DeprecatedConfigUsed": return `option '${event.key}' is deprecated; use ${event.replacement}`;
+		case "ModelLoaded": return `loaded model: ${event.itemCount} items, ${event.entryPoints} entry point(s) (${event.durationMs}ms)`;
+		case "ConfigResolved": return `resolved ${event.baseRoute}: ${event.categoryCount} categories, ${event.externalCount} external`;
+		case "TwoslashDiagnostic": return `Twoslash TS${event.code} in ${event.file}:${event.line}:${event.col}: ${event.message}`;
+		case "TwoslashCheckFailed": return `Twoslash check failed (TS${event.code}) in ${event.file}; ${event.fsMapKeys.length} VFS files`;
+		case "PageGenerated": return `page ${event.category}/${event.item} (${event.durationMs}ms)`;
+		case "FileDecision": return `${event.status}: ${event.file}`;
+		case "ItemSkipped": return `skipped ${event.kind} "${event.item}": ${event.reason}`;
+		case "ShikiError": return `Shiki error in ${event.file}: ${event.reason}`;
+		case "PrettierError": return `Prettier error in ${event.file}: ${event.reason}`;
+		case "LlmsPackageFilesGenerated": return `llms files: ${event.dir} (${event.files.length})`;
+		case "TypeRegistryEvent": return event.kind === "BatchComplete" ? event.detail : `${event.kind} ${event.ctx.packageName ?? ""} ${event.detail}`.trim();
+		default: return event._tag;
+	}
+}
+function makeConsoleSink(logLevel, opts = {}) {
+	const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+	const json = opts.json ?? false;
+	const minLevel = logLevel === "none" ? "error" : logLevel;
+	const threshold = logLevel === "none" ? -1 : LEVEL_RANK[minLevel];
+	return {
+		minLevel,
+		capturesPayload: json,
+		handle: (event) => {
+			if (LEVEL_RANK[levelOf(event)] > threshold) return;
+			if (json) {
+				console.log(JSON.stringify({
+					timestamp: now().getTime(),
+					...event
+				}));
+				return;
+			}
+			const level = levelOf(event);
+			const prefix = level === "error" ? "🔴 " : level === "warn" ? "⚠️  " : "";
+			console.log(`[${formatTime(now())}] ${prefix}${render(event)}`);
+		}
+	};
+}
+
+//#endregion
+export { makeConsoleSink };

package/observability/sinks/metrics-sink.js

@@ -0,0 +1,68 @@
+import { BuildMetrics } from "../../layers/build-metrics.js";
+import { Effect, Metric } from "effect";
+
+//#region src/observability/sinks/metrics-sink.ts
+/**
+* Event-driven metrics sink.
+*
+* Translates each `PluginEvent` to the corresponding `BuildMetrics` counter or
+* histogram update via `Effect.runSync`. The fan-out from `EventBus.emit` is
+* synchronous, so by the time the emitting fiber resumes the metrics are already
+* recorded — counts are exact when `logBuildSummary` reads them in `afterBuild`.
+*
+* Unmapped event tags hit the `default` branch and are silently ignored.
+*
+* Intentionally NOT derived here: `externalPackagesTotal` and `apiVersionsLoaded`
+* remain inline increments in `ConfigServiceLive`. `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
+* change what the metric means. `apiVersionsLoaded` has no corresponding event.
+*/
+function makeMetricsSink() {
+	return {
+		minLevel: "trace",
+		handle(event) {
+			switch (event._tag) {
+				case "FileDecision":
+					Effect.runSync(Metric.increment(BuildMetrics.filesTotal));
+					if (event.status === "new") Effect.runSync(Metric.increment(BuildMetrics.filesNew));
+					else if (event.status === "modified") Effect.runSync(Metric.increment(BuildMetrics.filesModified));
+					else Effect.runSync(Metric.increment(BuildMetrics.filesUnchanged));
+					break;
+				case "PageGenerated":
+					Effect.runSync(Metric.increment(BuildMetrics.pagesGenerated));
+					break;
+				case "TwoslashDiagnostic":
+					Effect.runSync(Metric.increment(BuildMetrics.twoslashDiagnostics));
+					Effect.runSync(Metric.increment(BuildMetrics.twoslashErrors));
+					break;
+				case "PrettierError":
+					Effect.runSync(Metric.increment(BuildMetrics.prettierErrors));
+					break;
+				case "CodeBlockProcessed":
+					Effect.runSync(Metric.increment(BuildMetrics.codeblockTotal));
+					Effect.runSync(Metric.update(BuildMetrics.codeblockDuration, event.totalMs));
+					if (event.shikiMs > 0) Effect.runSync(Metric.update(BuildMetrics.codeblockShikiDuration, event.shikiMs));
+					if (event.slow) Effect.runSync(Metric.increment(BuildMetrics.codeblockSlow));
+					break;
+				case "VfsGenerated":
+					Effect.runSync(Metric.increment(BuildMetrics.vfsFiles));
+					break;
+				case "ImportsPrepended":
+					Effect.runSync(Metric.increment(BuildMetrics.importsPrepended));
+					break;
+				case "PhaseCompleted":
+					Effect.runSync(Metric.update(BuildMetrics.phaseDuration, event.durationMs));
+					break;
+				case "DefaultApplied":
+					Effect.runSync(Metric.increment(BuildMetrics.configDefaultsApplied));
+					break;
+				default: break;
+			}
+		}
+	};
+}
+
+//#endregion
+export { makeMetricsSink };

package/observability/sinks/trace-sink.js

@@ -0,0 +1,38 @@
+import fs 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, "");
+}
+/**
+* Create a JSONL trace sink.
+*
+* When `initialPath` is provided the file is opened eagerly at construction
+* (existing behaviour for an explicit `trace: "/some/path"` config).
+* When omitted the sink starts in deferred mode — events are silently dropped
+* until `setPath` is called.  This lets `plugin.ts` create the sink before
+* the RSPress `outDir` is known and then bind the real path in the `config()`
+* hook once `_config.outDir` is available.
+*/
+function makeTraceSink(initialPath) {
+	let currentPath = initialPath ?? null;
+	if (currentPath) openTracePath(currentPath);
+	return {
+		minLevel: "trace",
+		capturesPayload: true,
+		handle: (event) => {
+			if (!currentPath) return;
+			fs.appendFileSync(currentPath, `${JSON.stringify(event)}\n`);
+		},
+		flush: () => {},
+		setPath: (p) => {
+			currentPath = p;
+			openTracePath(p);
+		}
+	};
+}
+
+//#endregion
+export { makeTraceSink };

package/observability/spans.js

@@ -0,0 +1,57 @@
+import { PluginEvent } from "./events.js";
+import { emit } from "./EventBus.js";
+import { Effect } from "effect";
+
+//#region src/observability/spans.ts
+/**
+* Maps phase names to threshold keys in ResolvedObservability["thresholds"].
+* Used by withPhase to determine the breach threshold for a given phase.
+*/
+const PHASE_THRESHOLD_KEY = {
+	modelLoad: "slowApiLoad",
+	resolve: "slowApiLoad",
+	generate: "slowPageGeneration",
+	write: "slowFileOperation",
+	cleanup: "slowDbOperation"
+};
+/**
+* Wrap an Effect in a phase span.
+*
+* Emits PhaseStarted before the effect runs, measures wall-clock duration,
+* emits PhaseCompleted after, and emits SlowOperation when the duration
+* exceeds the threshold mapped for this phase (defaulting to slowApiLoad).
+*
+* 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) {
+	return Effect.gen(function* () {
+		yield* emit(PluginEvent.PhaseStarted({
+			ctx,
+			level: "debug",
+			phase
+		}));
+		const start = performance.now();
+		const result = yield* Effect.withSpan(`phase.${phase}`)(effect);
+		const elapsed = performance.now() - start;
+		const durationMs = Math.round(elapsed);
+		yield* emit(PluginEvent.PhaseCompleted({
+			ctx,
+			level: "debug",
+			phase,
+			durationMs
+		}));
+		const threshold = thresholds[PHASE_THRESHOLD_KEY[phase] ?? "slowApiLoad"];
+		if (elapsed >= threshold) yield* emit(PluginEvent.SlowOperation({
+			ctx,
+			level: "warn",
+			operation: `phase.${phase}`,
+			durationMs,
+			threshold
+		}));
+		return result;
+	});
+}
+
+//#endregion
+export { withPhase };

package/og-resolver.js

@@ -1,8 +1,16 @@
+import { PluginEvent } from "./observability/events.js";
 import fs from "node:fs";
 import path from "node:path";
 import { imageSizeFromFile } from "image-size/fromFile";
 
 //#region src/og-resolver.ts
+/** Module-level emitter injected by plugin.ts at startup. */
+let emitEvent = () => {};
+let currentBuildId = "";
+function setOgResolverEventEmitter(fn, buildId = "") {
+	emitEvent = fn;
+	currentBuildId = buildId;
+}
 /**
 * MIME type mappings for common image formats.
 * Used to determine the `og:image:type` meta tag value.
@@ -122,12 +130,24 @@ var OpenGraphResolver = class {
 		const { url, secureUrl, type, width, height, alt } = metadata;
 		const resolvedUrl = this.resolveUrl(url);
 		if (!resolvedUrl) {
-			console.warn(`[og-resolver] Invalid ogImage URL format: "${url}"`);
+			emitEvent(PluginEvent.ConfigValidationWarning({
+				ctx: { buildId: currentBuildId },
+				field: "ogImage.url",
+				value: url,
+				reason: "invalid URL format",
+				level: "warn"
+			}));
 			return;
 		}
 		let resolvedSecureUrl;
 		if (secureUrl) if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
-		else console.warn(`[og-resolver] ogImage secureUrl must be an absolute HTTPS URL: "${secureUrl}"`);
+		else emitEvent(PluginEvent.ConfigValidationWarning({
+			ctx: { buildId: currentBuildId },
+			field: "ogImage.secureUrl",
+			value: secureUrl,
+			reason: "secureUrl must be absolute HTTPS",
+			level: "warn"
+		}));
 		return {
 			url: resolvedUrl,
 			secureUrl: resolvedSecureUrl,
@@ -154,7 +174,13 @@ var OpenGraphResolver = class {
 	async resolveFromString(imageUrl, packageName, apiName) {
 		const resolvedUrl = this.resolveUrl(imageUrl);
 		if (!resolvedUrl) {
-			console.warn(`[og-resolver] Invalid ogImage format: "${imageUrl}" (must be absolute URL or path starting with /)`);
+			emitEvent(PluginEvent.ConfigValidationWarning({
+				ctx: { buildId: currentBuildId },
+				field: "ogImage",
+				value: imageUrl,
+				reason: "invalid URL format",
+				level: "warn"
+			}));
 			return;
 		}
 		const localPath = this.findLocalImage(imageUrl);
@@ -207,7 +233,13 @@ var OpenGraphResolver = class {
 				...mimeType != null ? { type: mimeType } : {}
 			};
 		} catch (error) {
-			console.warn(`[og-resolver] Failed to read image dimensions from ${filePath}:`, error.message);
+			emitEvent(PluginEvent.ConfigValidationWarning({
+				ctx: { buildId: currentBuildId },
+				field: "ogImage",
+				value: filePath,
+				reason: error.message ?? String(error),
+				level: "warn"
+			}));
 			return;
 		}
 	}
@@ -268,4 +300,4 @@ var OpenGraphResolver = class {
 };
 
 //#endregion
-export { OpenGraphResolver };
+export { OpenGraphResolver, setOgResolverEventEmitter };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -32,7 +32,7 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effect/platform": "^0.96.1",
+		"@effect/platform": "^0.96.2",
 		"@effect/platform-node": "^0.107.0",
 		"@effect/sql": "^0.51.1",
 		"@effect/sql-sqlite-node": "^0.52.0",
@@ -40,7 +40,7 @@
 		"@shikijs/twoslash": "^4.2.0",
 		"api-extractor-llms": "0.1.0",
 		"clsx": "^2.1.1",
-		"effect": "^3.21.3",
+		"effect": "^3.21.4",
 		"gray-matter": "^4.0.3",
 		"hast-util-to-jsx-runtime": "^2.3.6",
 		"image-size": "^2.0.2",
@@ -51,7 +51,7 @@
 		"react-markdown": "^10.1.0",
 		"semver-effect": "^0.2.1",
 		"shiki": "^4.2.0",
-		"type-registry-effect": "^0.2.3",
+		"type-registry-effect": "^1.0.0",
 		"typescript": "^6.0.3",
 		"unist-util-visit": "^5.1.0"
 	},

package/plugin.js

@@ -1,11 +1,17 @@
-import { PluginLoggerLayer, logBuildSummary } from "./layers/ObservabilityLive.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
+import { PluginEvent } from "./observability/events.js";
+import { emit, makeRuntimeEmitter } from "./observability/EventBus.js";
+import { buildEventBus, logBuildSummary, makeSummaryLoggerLayer } from "./layers/ObservabilityLive.js";
+import { setLoaderEventEmitter } from "./loader.js";
+import { setPrettierEventEmitter } from "./prettier-formatter.js";
+import { setOgResolverEventEmitter } from "./og-resolver.js";
+import { TwoslashManager, setEventEmitter } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateApiDocs } from "./build-program.js";
 import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-derivation.js";
 import { fromDir, fromParentDir } from "./config-helpers.js";
 import { mergeLlmsPluginConfig } from "./config-utils.js";
-import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
+import { DEFAULT_SHIKI_THEMES, setShikiUtilsEventEmitter } from "./markdown/shiki-utils.js";
+import { resolveObservability } from "./schemas/observability.js";
 import { PluginOptions } from "./schemas/config.js";
 import "./schemas/index.js";
 import { ConfigService } from "./services/ConfigService.js";
@@ -13,8 +19,8 @@ import { ConfigServiceLive } from "./layers/ConfigServiceLive.js";
 import { PathDerivationServiceLive } from "./layers/PathDerivationServiceLive.js";
 import { SnapshotServiceLive } from "./layers/SnapshotServiceLive.js";
 import { TypeRegistryServiceLive } from "./layers/TypeRegistryServiceLive.js";
-import { remarkApiCodeblocks } from "./remark-api-codeblocks.js";
-import { remarkWithApi } from "./remark-with-api.js";
+import { remarkApiCodeblocks, setRemarkApiCodeblocksEventEmitter } from "./remark-api-codeblocks.js";
+import { remarkWithApi, setRemarkWithApiEventEmitter } from "./remark-with-api.js";
 import { ShikiCrossLinker } from "./shiki-transformer.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
@@ -49,13 +55,32 @@ function normalizeThemeConfig(theme) {
 function ApiExtractorPluginImpl(rawOptions) {
 	const options = Schema.decodeUnknownSync(PluginOptions)(rawOptions);
 	const shikiCrossLinker = new ShikiCrossLinker();
-	const logLevel = process.env.LOG_LEVEL?.toLowerCase() || options.logLevel || "info";
+	const envLogLevel = process.env.LOG_LEVEL?.toLowerCase();
+	const buildId = `${process.pid}-${performance.now().toString(36)}`;
+	const rspressOutDirGuess = path.resolve(process.cwd(), "dist");
+	const { resolved: obs, deprecations } = resolveObservability({
+		...options.observability ? { observability: options.observability } : {},
+		...options.logLevel ? { logLevel: options.logLevel } : {},
+		...options.performance ? { performance: { ...options.performance.thresholds !== void 0 ? { thresholds: options.performance.thresholds } : {} } } : {},
+		...envLogLevel ? { envLogLevel } : {},
+		outDir: rspressOutDirGuess,
+		buildId
+	});
+	const traceIsDefault = options.observability?.trace === true;
+	const { layer: eventBusLayer, trace: traceSink } = buildEventBus(obs, traceIsDefault);
 	const dbPath = path.resolve(process.cwd(), "api-docs-snapshot.db");
-	const BaseLayer = Layer.mergeAll(PathDerivationServiceLive, PluginLoggerLayer(logLevel), TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath));
-	const EffectAppLayer = Layer.provideMerge(ConfigServiceLive(options, shikiCrossLinker), BaseLayer);
+	const BaseLayer = Layer.mergeAll(PathDerivationServiceLive, eventBusLayer, TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath), makeSummaryLoggerLayer(obs.logLevel));
+	const EffectAppLayer = Layer.provideMerge(ConfigServiceLive(options, shikiCrossLinker, buildId, obs.thresholds), BaseLayer);
 	const effectRuntime = ManagedRuntime.make(EffectAppLayer);
+	const emitSync = makeRuntimeEmitter(effectRuntime);
+	setEventEmitter(emitSync, buildId);
+	setLoaderEventEmitter(emitSync, buildId);
+	setShikiUtilsEventEmitter(emitSync, buildId);
+	setPrettierEventEmitter(emitSync, buildId);
+	setOgResolverEventEmitter(emitSync, buildId);
+	setRemarkWithApiEventEmitter(emitSync, buildId, obs.thresholds.slowCodeBlock);
+	setRemarkApiCodeblocksEventEmitter(emitSync, buildId);
 	const fileContextMap = /* @__PURE__ */ new Map();
-	const isVerbose = logLevel === "verbose" || logLevel === "debug";
 	let docsRoot;
 	let isFirstBuild = true;
 	let rspressLlmsEnabled = false;
@@ -68,18 +93,20 @@ function ApiExtractorPluginImpl(rawOptions) {
 		async beforeBuild(_config, _isProd) {},
 		async afterBuild(_config, isProd) {
 			if (isFirstBuild) {
-				await effectRuntime.runPromise(logBuildSummary);
+				await effectRuntime.runPromise(logBuildSummary(obs.thresholds.slowCodeBlock));
 				if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled) {
 					const { processLlmsFiles } = await import("./llms-program.js");
 					await effectRuntime.runPromise(processLlmsFiles({
 						outDir: path.resolve(process.cwd(), rspressOutDir),
 						buildResults,
 						llmsPlugin: resolvedLlmsPlugin,
-						packageRoutes
+						packageRoutes,
+						buildId
 					}));
 				}
 				isFirstBuild = false;
 			}
+			if (traceSink) traceSink.flush();
 			if (isProd) await effectRuntime.dispose();
 		},
 		async config(_config) {
@@ -91,6 +118,10 @@ function ApiExtractorPluginImpl(rawOptions) {
 			const rspressMultiVersion = _config.multiVersion;
 			rspressLlmsEnabled = Boolean(_config.llms);
 			rspressOutDir = _config.outDir ?? "dist";
+			if (traceIsDefault && traceSink) {
+				const realTracePath = path.resolve(process.cwd(), rspressOutDir, ".api-extractor", `trace-${buildId}.jsonl`);
+				traceSink.setPath(realTracePath);
+			}
 			if (options.api) {
 				const api = options.api;
 				const baseRoute = normalizeBaseRoute(api.baseRoute ?? "/");
@@ -121,7 +152,12 @@ function ApiExtractorPluginImpl(rawOptions) {
 			}
 			VfsRegistry.clear();
 			fileContextMap.clear();
-			if (isVerbose) console.log("🚀 RSPress API Extractor Plugin");
+			for (const dep of deprecations) emitSync(PluginEvent.DeprecatedConfigUsed({
+				ctx: { buildId },
+				level: "warn",
+				key: dep.key,
+				replacement: dep.replacement
+			}));
 			try {
 				const rspressConfigSubset = {
 					...rspressMultiVersion != null ? { multiVersion: rspressMultiVersion } : {},
@@ -130,8 +166,14 @@ function ApiExtractorPluginImpl(rawOptions) {
 					...docsRoot != null ? { root: docsRoot } : {}
 				};
 				await effectRuntime.runPromise(Effect.gen(function* () {
+					const apiCount = options.api ? 1 : options.apis?.length ?? 0;
+					yield* emit(PluginEvent.BuildStarted({
+						ctx: { buildId },
+						level: "info",
+						mode: "prod",
+						apiCount
+					}));
 					const buildContext = yield* (yield* ConfigService).resolve(rspressConfigSubset);
-					yield* Effect.logInfo("Generating API documentation...");
 					buildResults.length = 0;
 					yield* Effect.forEach(buildContext.apiConfigs, (apiConfig) => generateApiDocs({
 						...apiConfig,
@@ -139,14 +181,24 @@ function ApiExtractorPluginImpl(rawOptions) {
 					}, buildContext, fileContextMap).pipe(Effect.tap((result) => {
 						buildResults.push(result);
 						return Effect.void;
-					}), Effect.tap(() => isVerbose ? Effect.logDebug(`Generating docs for ${apiConfig.packageName}`) : Effect.void)), { concurrency: 2 });
+					})), { concurrency: 2 });
+					const totalMs = performance.now() - buildStartTime;
+					yield* emit(PluginEvent.BuildCompleted({
+						ctx: { buildId },
+						level: "info",
+						durationMs: totalMs,
+						totals: {}
+					}));
 				}).pipe(Effect.scoped));
-				if (logLevel !== "none") {
-					const totalTime = ((performance.now() - buildStartTime) / 1e3).toFixed(2);
-					console.log(`✅ API documentation complete (${totalTime}s)`);
-				}
 			} catch (error) {
-				console.error(`❌ Error generating API documentation: ${error instanceof Error ? error.message : String(error)}`);
+				const message = error instanceof Error ? error.message : String(error);
+				emitSync(PluginEvent.BuildFailed({
+					ctx: { buildId },
+					level: "error",
+					phase: "generate",
+					error: message
+				}));
+				if (traceSink) traceSink.flush();
 				throw error;
 			}
 			const updatedConfig = { ..._config };
@@ -208,6 +260,8 @@ function ApiExtractorPluginImpl(rawOptions) {
 * files. Config helpers are available under `ApiExtractorPlugin.api` (single
 * package → one config for the `api:` option) and `ApiExtractorPlugin.apis`
 * (parent directory → array for the `apis:` option).
+*
+* @public
 */
 const ApiExtractorPlugin = Object.assign(ApiExtractorPluginImpl, {
 	api: { fromDir },

package/prettier-formatter.js

@@ -1,10 +1,16 @@
-import { BuildMetrics } from "./layers/ObservabilityLive.js";
+import { PluginEvent } from "./observability/events.js";
 import { addLogicalBlankLines } from "./code-post-processor.js";
-import { Effect, Metric } from "effect";
 import { format } from "prettier";
 
 //#region src/prettier-formatter.ts
 /* v8 ignore start -- Prettier integration wrapper, tested via page generator integration tests */
+/** Module-level emitter injected by plugin.ts at startup. */
+let emitEvent = () => {};
+let currentBuildId = "";
+function setPrettierEventEmitter(fn, buildId = "") {
+	emitEvent = fn;
+	currentBuildId = buildId;
+}
 /**
 * Map code fence languages to Prettier parsers
 */
@@ -59,7 +65,12 @@ async function formatCode(code, language) {
 	} catch (error) {
 		const formatTime = performance.now() - start;
 		const errorMsg = error instanceof Error ? error.message : String(error);
-		Effect.runSync(Metric.increment(BuildMetrics.prettierErrors));
+		emitEvent(PluginEvent.PrettierError({
+			ctx: { buildId: currentBuildId },
+			file: "unknown",
+			reason: errorMsg,
+			level: "warn"
+		}));
 		return {
 			code,
 			success: false,
@@ -70,4 +81,4 @@ async function formatCode(code, language) {
 }
 
 //#endregion
-export { formatCode };
+export { formatCode, setPrettierEventEmitter };

package/remark-api-codeblocks.js

@@ -1,8 +1,17 @@
+import { PluginEvent } from "./observability/events.js";
+import { TwoslashManager } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateShikiHast } from "./markdown/shiki-utils.js";
 import { visit } from "unist-util-visit";
 
 //#region src/remark-api-codeblocks.ts
+/** Module-level emitter injected by plugin.ts at startup. */
+let emitEvent = () => {};
+let currentBuildId = "";
+function setRemarkApiCodeblocksEventEmitter(fn, buildId = "") {
+	emitEvent = fn;
+	currentBuildId = buildId;
+}
 /**
 * Create an MDX JSX attribute value expression with proper estree AST.
 * This ensures the value is properly serialized as a JavaScript string literal.
@@ -82,7 +91,8 @@ const remarkApiCodeblocks = () => {
 		const promises = [];
 		const isSsgMd = import.meta.env?.SSG_MD || process.env.RSBUILD_ENVIRONMENT === "node_md" || process.env.BUILD_TARGET === "node_md";
 		const currentFilePath = file.path || "unknown";
-		const jsxComponentNames = new Set([
+		if (file.path) TwoslashManager.getInstance().setCurrentFile(file.path);
+		const jsxComponentNames = /* @__PURE__ */ new Set([
 			"ApiSignature",
 			"ApiMember",
 			"ApiExample"
@@ -99,7 +109,16 @@ const remarkApiCodeblocks = () => {
 				}
 				const vfsConfig = VfsRegistry.get(apiScopeValue);
 				if (!vfsConfig) {
-					console.warn(`[remark-api-codeblocks] No VFS config found for scope "${apiScopeValue}" in ${currentFilePath}`);
+					emitEvent(PluginEvent.ConfigCascadeWarning({
+						ctx: {
+							buildId: currentBuildId,
+							file: currentFilePath
+						},
+						field: "vfs",
+						chosen: apiScopeValue,
+						ignored: [],
+						level: "warn"
+					}));
 					removeJsxAttrs(node, ["source", "apiScope"]);
 					return;
 				}
@@ -127,4 +146,4 @@ const remarkApiCodeblocks = () => {
 };
 
 //#endregion
-export { remarkApiCodeblocks };
+export { remarkApiCodeblocks, setRemarkApiCodeblocksEventEmitter };