rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/observability/sinks/metrics-sink.js

@@ -1,17 +1,22 @@
 import { BuildMetrics } from "../../layers/build-metrics.js";
-import { Effect, Metric } from "effect";
+import { 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
+* histogram update against the build's metric registry. 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.
 *
+* Events whose breakdown is worth querying are recorded twice — undimensioned
+* for the build-wide totals, and tagged for `metric-report.ts`. The attributes
+* are deliberately bounded (scope, status, phase, TS code); anything unbounded,
+* 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
 * CONFIGURED packages via `incrementBy(length)`; the only candidate event,
@@ -19,46 +24,84 @@ import { Effect, Metric } from "effect";
 * a `loaded` (SUCCEEDED) count — different semantics, so deriving it here would
 * change what the metric means. `apiVersionsLoaded` has no corresponding event.
 */
-function makeMetricsSink() {
+function makeMetricsSink(context) {
+	const update = (metric, input) => metric.updateUnsafe(input, context);
+	/** Record `metric` twice: undimensioned, and tagged for breakdown queries. */
+	const both = (metric, input, attributes) => {
+		update(metric, input);
+		update(Metric.withAttributes(metric, attributes), input);
+	};
+	const scopeOf = (event) => event.ctx.apiScope ?? "(unscoped)";
 	return {
 		minLevel: "trace",
 		handle(event) {
 			switch (event._tag) {
 				case "FileDecision":
-					Effect.runSync(Metric.update(BuildMetrics.filesTotal, 1));
-					if (event.status === "new") Effect.runSync(Metric.update(BuildMetrics.filesNew, 1));
-					else if (event.status === "modified") Effect.runSync(Metric.update(BuildMetrics.filesModified, 1));
-					else Effect.runSync(Metric.update(BuildMetrics.filesUnchanged, 1));
+					both(BuildMetrics.filesTotal, 1, {
+						scope: scopeOf(event),
+						status: event.status
+					});
+					if (event.status === "new") update(BuildMetrics.filesNew, 1);
+					else if (event.status === "modified") update(BuildMetrics.filesModified, 1);
+					else update(BuildMetrics.filesUnchanged, 1);
 					break;
 				case "PageGenerated":
-					Effect.runSync(Metric.update(BuildMetrics.pagesGenerated, 1));
+					update(BuildMetrics.pagesGenerated, 1);
 					break;
 				case "ApiDocsCompleted":
-					Effect.runSync(Metric.update(BuildMetrics.apisCompleted, 1));
+					update(BuildMetrics.apisCompleted, 1);
 					break;
 				case "TwoslashDiagnostic":
-					Effect.runSync(Metric.update(BuildMetrics.twoslashDiagnostics, 1));
-					Effect.runSync(Metric.update(BuildMetrics.twoslashErrors, 1));
+					both(BuildMetrics.twoslashDiagnostics, 1, {
+						code: `TS${event.code}`,
+						scope: scopeOf(event)
+					});
+					update(BuildMetrics.twoslashErrors, 1);
 					break;
 				case "PrettierError":
-					Effect.runSync(Metric.update(BuildMetrics.prettierErrors, 1));
+					both(BuildMetrics.prettierErrors, 1, { scope: scopeOf(event) });
+					break;
+				case "ShikiError":
+					both(BuildMetrics.shikiErrors, 1, { scope: scopeOf(event) });
 					break;
-				case "CodeBlockProcessed":
-					Effect.runSync(Metric.update(BuildMetrics.codeblockTotal, 1));
-					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.update(BuildMetrics.codeblockSlow, 1));
+				case "CodeBlockProcessed": {
+					const attrs = {
+						scope: event.ctx.apiScope ?? "(unscoped)",
+						component: event.component,
+						twoslash: String(event.twoslash)
+					};
+					const tagged = (metric) => Metric.withAttributes(metric, attrs);
+					update(BuildMetrics.codeblockTotal, 1);
+					update(tagged(BuildMetrics.codeblockTotal), 1);
+					update(BuildMetrics.codeblockDuration, event.totalMs);
+					update(BuildMetrics.codeblockTimeMs, event.totalMs);
+					update(tagged(BuildMetrics.codeblockTimeMs), event.totalMs);
+					update(BuildMetrics.codeblockTwoslashMs, event.twoslashMs);
+					update(tagged(BuildMetrics.codeblockTwoslashMs), event.twoslashMs);
+					update(BuildMetrics.codeblockShikiMs, event.shikiMs);
+					update(tagged(BuildMetrics.codeblockShikiMs), event.shikiMs);
+					if (event.twoslash) {
+						update(BuildMetrics.codeblockTwoslashTotal, 1);
+						update(tagged(BuildMetrics.codeblockTwoslashTotal), 1);
+					}
+					if (event.shikiMs > 0) update(BuildMetrics.codeblockShikiDuration, event.shikiMs);
+					if (event.slow) {
+						update(BuildMetrics.codeblockSlow, 1);
+						update(tagged(BuildMetrics.codeblockSlow), 1);
+					}
 					break;
+				}
 				case "VfsGenerated":
-					Effect.runSync(Metric.update(BuildMetrics.vfsFiles, 1));
+					update(BuildMetrics.vfsFiles, 1);
 					break;
 				case "ImportsPrepended":
-					Effect.runSync(Metric.update(BuildMetrics.importsPrepended, 1));
+					update(BuildMetrics.importsPrepended, 1);
 					break;
 				case "PhaseCompleted":
-					Effect.runSync(Metric.update(BuildMetrics.phaseDuration, event.durationMs));
+					update(BuildMetrics.phaseDuration, event.durationMs);
+					both(BuildMetrics.phaseTimeMs, event.durationMs, { phase: event.phase });
 					break;
-				case "DefaultApplied": Effect.runSync(Metric.update(BuildMetrics.configDefaultsApplied, 1));
+				case "DefaultApplied": update(BuildMetrics.configDefaultsApplied, 1);
 			}
 		}
 	};

package/observability/sinks/render-sink.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { Effect, FileSystem } from "effect";
+
+//#region src/observability/sinks/render-sink.ts
+const UNSCOPED = "(unscoped)";
+/** How many of the slowest blocks the artifact retains. */
+const SLOWEST_LIMIT = 25;
+function makeRenderSink() {
+	let firstAt = 0;
+	let lastAt = 0;
+	const byFile = /* @__PURE__ */ new Map();
+	const slowest = [];
+	return {
+		minLevel: "trace",
+		handle(event) {
+			if (event._tag !== "CodeBlockProcessed") return;
+			const now = performance.now();
+			if (firstAt === 0) firstAt = now;
+			lastAt = now;
+			const sample = {
+				apiScope: event.ctx.apiScope ?? UNSCOPED,
+				file: event.ctx.file ?? "unknown",
+				component: event.component,
+				totalMs: event.totalMs,
+				twoslashMs: event.twoslashMs,
+				shikiMs: event.shikiMs
+			};
+			const current = byFile.get(sample.file) ?? {
+				blocks: 0,
+				twoslashBlocks: 0,
+				totalMs: 0,
+				twoslashMs: 0
+			};
+			byFile.set(sample.file, {
+				blocks: current.blocks + 1,
+				twoslashBlocks: current.twoslashBlocks + (event.twoslash ? 1 : 0),
+				totalMs: current.totalMs + sample.totalMs,
+				twoslashMs: current.twoslashMs + sample.twoslashMs
+			});
+			if (slowest.length < SLOWEST_LIMIT || sample.totalMs > (slowest.at(-1)?.totalMs ?? 0)) {
+				const at = slowest.findIndex((s) => s.totalMs < sample.totalMs);
+				slowest.splice(at === -1 ? slowest.length : at, 0, sample);
+				if (slowest.length > SLOWEST_LIMIT) slowest.length = SLOWEST_LIMIT;
+			}
+		},
+		snapshot() {
+			return {
+				wallMs: firstAt === 0 ? 0 : lastAt - firstAt,
+				byFile: Object.fromEntries(byFile),
+				slowest: [...slowest]
+			};
+		}
+	};
+}
+/**
+* Write the render-phase attribution artifact to
+* `<cwd>/.api-docs/build/render-phase.json`, combining the metric-derived
+* rollups with the sample-shaped per-file and slowest-block data.
+*
+* Writes nothing when no code block was processed, so a build that never
+* reached the render phase does not leave an empty artifact behind.
+*/
+function writeRenderPhaseJson(report, samples, opts) {
+	return Effect.gen(function* () {
+		if (report.overall.blocks === 0) return;
+		const fs = yield* FileSystem.FileSystem;
+		const dir = path.join(opts.cwd, ".api-docs", "build");
+		yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.ignore);
+		const doc = {
+			generatedAt: opts.generatedAt,
+			package: opts.packageName,
+			target: "prod",
+			overall: report.overall,
+			wallMs: samples.wallMs,
+			byScope: report.byScope,
+			byComponent: report.byComponent,
+			series: report.series,
+			byFile: samples.byFile,
+			slowest: samples.slowest
+		};
+		yield* fs.writeFileString(path.join(dir, "render-phase.json"), `${JSON.stringify(doc, null, 2)}\n`).pipe(Effect.ignore);
+	});
+}
+
+//#endregion
+export { makeRenderSink, writeRenderPhaseJson };

package/observability/sinks/trace-sink.js

@@ -7,30 +7,23 @@ function openTracePath(p) {
 	fs.writeFileSync(p, "");
 }
 /**
-* Create a JSONL trace sink.
+* Create a JSONL trace sink, opening the file eagerly at construction.
 *
-* 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.
+* The path is always known up front: `resolveObservability` derives it from
+* `cwd`, which (unlike the RSPress `outDir`) is available at plugin-factory
+* time. The sink previously supported a deferred mode — construct with no path,
+* bind one later via `setPath` — for the era when the path depended on
+* `outDir`; nothing has called it since, so it is gone.
 */
-function makeTraceSink(initialPath) {
-	let currentPath = initialPath ?? null;
-	if (currentPath) openTracePath(currentPath);
+function makeTraceSink(tracePath) {
+	openTracePath(tracePath);
 	return {
 		minLevel: "trace",
 		capturesPayload: true,
 		handle: (event) => {
-			if (!currentPath) return;
-			fs.appendFileSync(currentPath, `${JSON.stringify(event)}\n`);
+			fs.appendFileSync(tracePath, `${JSON.stringify(event)}\n`);
 		},
-		flush: () => {},
-		setPath: (p) => {
-			currentPath = p;
-			openTracePath(p);
-		}
+		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",
@@ -54,4 +56,4 @@ function withPhase(phase, ctx, effect, thresholds) {
 }
 
 //#endregion
-export { PHASE_THRESHOLD_KEY, withPhase };
+export { withPhase };

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 };