rspress-plugin-api-extractor 0.6.4 → 0.7.0

package/build-stages.js

@@ -16,7 +16,7 @@ import { VariablePageGenerator } from "./markdown/page-generators/variable-page.
 import "./markdown/index.js";
 import { resolveEntryPoints } from "./multi-entry-resolver.js";
 import { OpenGraphResolver } from "./og-resolver.js";
-import { assertNoRouteCollisions } from "./route-collisions.js";
+import { detectRouteCollisions, formatRouteCollisionError } from "./route-collisions.js";
 import { SnapshotService } from "./services/SnapshotService.js";
 import { BASE_CLASS_ANCHOR, detectSyntheticBases } from "./synthetic-bases.js";
 import path from "node:path";
@@ -45,6 +45,24 @@ function crossLinkKindPriority(kind) {
 	return CROSS_LINK_KIND_PRIORITY[kind] ?? 100;
 }
 /**
+* Module-level emitter seam. `prepareWorkItems` runs synchronously outside any
+* Effect fiber, so a route collision cannot `yield* emit(...)` — it mirrors the
+* sync-island pattern used by `twoslash-transformer.ts` (`setEventEmitter`) and
+* `loader.ts` (`setLoaderEventEmitter`). Default is a no-op; wired in plugin.ts
+* via `setBuildStagesEventEmitter(emitSync, buildId)` right after the runtime
+* emitter is created.
+*/
+let emitEvent = () => {};
+let currentBuildId = "";
+/**
+* Inject the runtime-bound emitter into the build-stages module.
+* Call this right after `makeRuntimeEmitter` in plugin.ts.
+*/
+function setBuildStagesEventEmitter(fn, buildId = "") {
+	emitEvent = fn;
+	currentBuildId = buildId;
+}
+/**
 * Sanitize a display name to create a valid HTML ID.
 * Mirrors the logic in MarkdownCrossLinker.sanitizeId().
 */
@@ -98,7 +116,20 @@ function prepareWorkItems(input) {
 			canonicalRef: nsMember.item.canonicalReference?.toString() ?? nsMember.qualifiedName
 		});
 	}
-	assertNoRouteCollisions(candidates, baseRoute);
+	const collisions = detectRouteCollisions(candidates);
+	if (collisions.length > 0) {
+		try {
+			for (const collision of collisions) emitEvent(PluginEvent.RouteCollisionDetected({
+				ctx: {
+					buildId: currentBuildId,
+					route: collision.route
+				},
+				level: "error",
+				items: collision.items.map((item) => `${item.displayName} (${item.kind}) [${item.canonicalRef}]`)
+			}));
+		} catch {}
+		throw new Error(formatRouteCollisionError(collisions, baseRoute));
+	}
 	const routes = /* @__PURE__ */ new Map();
 	const kinds = /* @__PURE__ */ new Map();
 	const routeOwnerPriority = /* @__PURE__ */ new Map();
@@ -772,4 +803,4 @@ function buildPipelineForApi(input) {
 }
 
 //#endregion
-export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, normalizeMarkdownSpacing, prepareWorkItems, writeMetadata, writeSingleFile };
+export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, normalizeMarkdownSpacing, prepareWorkItems, setBuildStagesEventEmitter, writeMetadata, writeSingleFile };

package/index.d.ts

@@ -710,6 +710,7 @@ declare const PluginOptions: Schema.Struct<{
   readonly observability: Schema.optional<Schema.Struct<{
     readonly logLevel: Schema.optional<Schema.Literals<readonly ["none", "error", "warn", "info", "debug", "trace", "verbose"]>>;
     readonly trace: Schema.optional<Schema.Union<readonly [Schema.Boolean, Schema.String]>>;
+    readonly progressInterval: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.Boolean]>>;
     readonly thresholds: Schema.optional<Schema.Struct<{
       readonly slowCodeBlock: Schema.withDecodingDefault<Schema.Number, never>;
       readonly slowPageGeneration: Schema.withDecodingDefault<Schema.Number, never>;

package/layers/ObservabilityLive.js

@@ -1,6 +1,7 @@
 import { makeEventBusLayer } from "../observability/EventBus.js";
-import { makeConsoleSink } from "../observability/sinks/console-sink.js";
 import { BuildMetrics } from "./build-metrics.js";
+import { makeConsoleSink } from "../observability/sinks/console-sink.js";
+import { makeIssuesSink } from "../observability/sinks/issues-sink.js";
 import { makeMetricsSink } from "../observability/sinks/metrics-sink.js";
 import { makeTraceSink } from "../observability/sinks/trace-sink.js";
 import { Effect, Layer, Logger, Metric, References } from "effect";
@@ -28,24 +29,25 @@ function makeSummaryLoggerLayer(logLevel) {
 	return Layer.mergeAll(Logger.layer([pluginLogger]), Layer.succeed(References.MinimumLogLevel, effectLevel));
 }
 /**
-* 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.
+* Compose the console + metrics + issues (+ optional trace) sinks into an EventBus layer.
 *
-* When `traceIsDefault` is false the caller supplied an explicit path string,
-* so we open the file eagerly (existing behaviour).
+* `cwd` is known at plugin-factory time (unlike the RSPress `outDir`), so the
+* trace path is resolved eagerly by `resolveObservability` and the trace sink
+* opens its file immediately — no deferred re-binding is needed.
 */
-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;
+function buildEventBus(obs) {
+	const issues = makeIssuesSink();
+	const sinks = [
+		makeConsoleSink(obs.logLevel, { json: obs.json }),
+		makeMetricsSink(),
+		issues
+	];
+	const trace = obs.tracePath ? makeTraceSink(obs.tracePath) : null;
 	if (trace) sinks.push(trace);
 	return {
 		layer: makeEventBusLayer(sinks),
-		trace
+		trace,
+		issues
 	};
 }
 /**

package/layers/build-metrics.js

@@ -39,6 +39,7 @@ const BuildMetrics = {
 	twoslashErrors: Metric.counter("twoslash.errors"),
 	prettierErrors: Metric.counter("prettier.errors"),
 	pagesGenerated: Metric.counter("pages.generated"),
+	apisCompleted: Metric.counter("apis.completed"),
 	apiVersionsLoaded: Metric.counter("api.versions.loaded"),
 	externalPackagesTotal: Metric.counter("external.packages.total"),
 	phaseDuration: Metric.histogram("phase.duration", { boundaries: [

package/model-loader.js

@@ -1,3 +1,4 @@
+import { PluginEvent } from "./observability/events.js";
 import { isLoadedModel, isVersionConfig } from "./config-utils.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -5,6 +6,26 @@ import { loadApiModel } from "api-extractor-llms";
 
 //#region src/model-loader.ts
 /**
+* Module-level emitter seam. `loadFromPath` is called from inside an
+* `Effect.promise(async () => {...})` body in `ConfigServiceLive.ts`, so a
+* load failure cannot `yield* emit(...)` — it mirrors the sync-island pattern
+* used by `twoslash-transformer.ts` (`setEventEmitter`) and `loader.ts`
+* (`setLoaderEventEmitter`, a DIFFERENT module — the ApiParser/TSDoc statics,
+* not this one). Default is a no-op; wired in plugin.ts via
+* `setModelLoaderEventEmitter(emitSync, buildId)` right after the runtime
+* emitter is created.
+*/
+let emitEvent = () => {};
+let currentBuildId = "";
+/**
+* Inject the runtime-bound emitter into the model-loader module.
+* Call this right after `makeRuntimeEmitter` in plugin.ts.
+*/
+function setModelLoaderEventEmitter(fn, buildId = "") {
+	emitEvent = fn;
+	currentBuildId = buildId;
+}
+/**
 * Utility class for loading API models from various sources
 */
 var ApiModelLoader = class ApiModelLoader {
@@ -17,8 +38,20 @@ var ApiModelLoader = class ApiModelLoader {
 	*/
 	static async loadFromPath(modelPath) {
 		const resolvedPath = path.resolve(modelPath.toString());
-		if (!fs.existsSync(resolvedPath)) throw new Error(`API model file not found: ${resolvedPath}`);
-		return loadApiModel(resolvedPath);
+		try {
+			if (!fs.existsSync(resolvedPath)) throw new Error(`API model file not found: ${resolvedPath}`);
+			return await loadApiModel(resolvedPath);
+		} catch (error) {
+			try {
+				emitEvent(PluginEvent.ModelLoadFailed({
+					ctx: { buildId: currentBuildId },
+					level: "error",
+					modelPath: resolvedPath,
+					reason: error instanceof Error ? error.message : String(error)
+				}));
+			} catch {}
+			throw error;
+		}
 	}
 	/**
 	* Load package.json from a path (string, URL, or Buffer)
@@ -92,4 +125,4 @@ var ApiModelLoader = class ApiModelLoader {
 };
 
 //#endregion
-export { ApiModelLoader };
+export { ApiModelLoader, setModelLoaderEventEmitter };

package/observability/heartbeat.js

@@ -0,0 +1,73 @@
+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
+/** Build a `BuildProgress` event from the current + previous metric snapshot. */
+function makeProgressEvent(args) {
+	const { phase, curr, prev } = args;
+	const delta = phase === "resolve" ? curr.vfsFiles - prev.vfsFiles : curr.pages - prev.pages;
+	return PluginEvent.BuildProgress({
+		ctx: { buildId: args.buildId },
+		level: "info",
+		phase,
+		elapsedMs: args.elapsedMs,
+		vfsFiles: curr.vfsFiles,
+		externalPackages: curr.externalPackages,
+		apisCompleted: curr.apisCompleted,
+		apisTotal: args.apisTotal,
+		pages: curr.pages,
+		codeBlocks: curr.codeBlocks,
+		delta
+	});
+}
+/** One-line human-readable render of a `BuildProgress` event body (no timestamp prefix). */
+function formatProgress(e) {
+	const secs = `${Math.round(e.elapsedMs / 1e3)}s`;
+	if (e.phase === "resolve") return `API docs · resolving types · ${e.vfsFiles} files · ${e.externalPackages} pkgs · ${secs} (+${e.delta} files)`;
+	return `API docs · ${e.apisCompleted}/${e.apisTotal} APIs · ${e.pages} pages · ${e.codeBlocks} blocks · ${secs} (+${e.delta} pages)`;
+}
+/** Read the five progress counters into a snapshot. */
+const readCounts = Effect.gen(function* () {
+	return {
+		vfsFiles: (yield* Metric.value(BuildMetrics.vfsFiles)).count,
+		externalPackages: (yield* Metric.value(BuildMetrics.externalPackagesTotal)).count,
+		apisCompleted: (yield* Metric.value(BuildMetrics.apisCompleted)).count,
+		pages: (yield* Metric.value(BuildMetrics.pagesGenerated)).count,
+		codeBlocks: (yield* Metric.value(BuildMetrics.codeblockTotal)).count
+	};
+});
+/**
+* Sleep-first heartbeat loop: waits `intervalMs`, then reads the metric
+* snapshot and emits a `BuildProgress` event, repeating until the phase Ref
+* reads `"done"` or the fiber is interrupted (scope close). Sleeping first
+* means a build that finishes before the first interval emits nothing.
+*/
+function runHeartbeat(opts) {
+	const loop = (prev) => Effect.gen(function* () {
+		yield* Effect.sleep(Duration.millis(opts.intervalMs));
+		const phase = yield* Ref.get(opts.phaseRef);
+		if (phase === "done") return;
+		const curr = yield* readCounts;
+		yield* emit(makeProgressEvent({
+			phase,
+			buildId: opts.buildId,
+			elapsedMs: performance.now() - opts.startTime,
+			apisTotal: opts.apisTotal,
+			curr,
+			prev
+		}));
+		return yield* loop(curr);
+	});
+	return loop({
+		vfsFiles: 0,
+		externalPackages: 0,
+		apisCompleted: 0,
+		pages: 0,
+		codeBlocks: 0
+	});
+}
+
+//#endregion
+export { formatProgress, makeProgressEvent, readCounts, runHeartbeat };

package/observability/sinks/console-sink.js

@@ -1,4 +1,5 @@
 import { LEVEL_RANK, levelOf } from "../events.js";
+import { formatProgress } from "../heartbeat.js";
 
 //#region src/observability/sinks/console-sink.ts
 function formatTime(date) {
@@ -16,6 +17,7 @@ function render(event) {
 		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 "BuildProgress": return formatProgress(event);
 		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.ignored.length > 2 ? `${event.field}: using '${event.chosen}', ignoring ${event.ignored.length} alternatives (first configured value wins)` : `${event.field}: using '${event.chosen}', ignoring ${event.ignored.join(", ")}`;

package/observability/sinks/issues-sink.js

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { Effect, FileSystem } from "effect";
+
+//#region src/observability/sinks/issues-sink.ts
+function withApi(base, api) {
+	return api ? {
+		...base,
+		api
+	} : base;
+}
+/**
+* Map an issue-relevant event to a typed `Issue` and its bucket. Returns null
+* for events that are not build issues.
+*
+* `suppressed[]` is intentionally not produced here: no event in the current
+* stream distinguishes a diagnostic silenced by `suppressExampleErrors` /
+* `@noErrors` from one that surfaced, so the bucket is reserved (always emitted,
+* currently empty) for schema parity with the bundler artifact.
+*/
+function eventToIssue(event) {
+	switch (event._tag) {
+		case "TwoslashDiagnostic": return {
+			bucket: "warnings",
+			issue: withApi({
+				source: "twoslash",
+				level: "warn",
+				text: event.message,
+				code: `TS${event.code}`,
+				file: event.file,
+				line: event.line,
+				column: event.col
+			}, event.ctx.packageName)
+		};
+		case "TwoslashCheckFailed": return {
+			bucket: "warnings",
+			issue: withApi({
+				source: "twoslash",
+				level: "warn",
+				text: `Twoslash check failed (TS${event.code})`,
+				code: `TS${event.code}`,
+				file: event.file,
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		case "PrettierError": return {
+			bucket: "warnings",
+			issue: withApi({
+				source: "prettier",
+				level: "warn",
+				text: event.reason,
+				code: "prettier",
+				file: event.file,
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		case "ShikiError": return {
+			bucket: "warnings",
+			issue: withApi({
+				source: "shiki",
+				level: "warn",
+				text: event.reason,
+				code: "shiki",
+				file: event.file,
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		case "ConfigValidationWarning": return {
+			bucket: "warnings",
+			issue: withApi({
+				source: "config",
+				level: "warn",
+				text: `${event.field}: ${event.value}${event.reason ? ` — ${event.reason}` : ""}`,
+				code: "config-validation",
+				file: event.ctx.file ?? "",
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		case "RouteCollisionDetected": return {
+			bucket: "errors",
+			issue: withApi({
+				source: "routing",
+				level: "error",
+				text: `Route collision between: ${event.items.join(", ")}`,
+				code: "route-collision",
+				file: event.ctx.file ?? "",
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		case "ModelLoadFailed": return {
+			bucket: "errors",
+			issue: withApi({
+				source: "model",
+				level: "error",
+				text: event.reason,
+				code: "model-load-failed",
+				file: event.modelPath,
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		case "BuildFailed": return {
+			bucket: "errors",
+			issue: withApi({
+				source: "build",
+				level: "error",
+				text: event.error,
+				code: "build-failed",
+				file: "",
+				line: 0,
+				column: 0
+			}, event.ctx.packageName)
+		};
+		default: return null;
+	}
+}
+/**
+* Collector sink: accumulates issue events into in-memory buckets. Always-on
+* (collection is cheap); the write is gated by `isProd` in `afterBuild`.
+*/
+function makeIssuesSink() {
+	const warnings = [];
+	const errors = [];
+	const suppressed = [];
+	return {
+		minLevel: "trace",
+		handle(event) {
+			const mapped = eventToIssue(event);
+			if (!mapped) return;
+			if (mapped.bucket === "warnings") warnings.push(mapped.issue);
+			else errors.push(mapped.issue);
+		},
+		snapshot: () => ({
+			warnings: [...warnings],
+			errors: [...errors],
+			suppressed: [...suppressed]
+		}),
+		reset: () => {
+			warnings.length = 0;
+			errors.length = 0;
+			suppressed.length = 0;
+		}
+	};
+}
+/** Serialize an issues snapshot to `<cwd>/.api-docs/build/issues.json` (bundler schema). */
+function writeIssuesJson(snapshot, opts) {
+	return Effect.gen(function* () {
+		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",
+			warnings: snapshot.warnings,
+			errors: snapshot.errors,
+			suppressed: snapshot.suppressed
+		};
+		yield* fs.writeFileString(path.join(dir, "issues.json"), `${JSON.stringify(doc, null, 2)}\n`).pipe(Effect.ignore);
+	});
+}
+
+//#endregion
+export { eventToIssue, makeIssuesSink, writeIssuesJson };

package/observability/sinks/metrics-sink.js

@@ -33,6 +33,9 @@ function makeMetricsSink() {
 				case "PageGenerated":
 					Effect.runSync(Metric.update(BuildMetrics.pagesGenerated, 1));
 					break;
+				case "ApiDocsCompleted":
+					Effect.runSync(Metric.update(BuildMetrics.apisCompleted, 1));
+					break;
 				case "TwoslashDiagnostic":
 					Effect.runSync(Metric.update(BuildMetrics.twoslashDiagnostics, 1));
 					Effect.runSync(Metric.update(BuildMetrics.twoslashErrors, 1));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.6.4",
+	"version": "0.7.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [

package/plugin.js

@@ -1,9 +1,12 @@
 import { PluginEvent } from "./observability/events.js";
 import { emit, makeRuntimeEmitter } from "./observability/EventBus.js";
+import { runHeartbeat } from "./observability/heartbeat.js";
+import { writeIssuesJson } from "./observability/sinks/issues-sink.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 { setBuildStagesEventEmitter } from "./build-stages.js";
 import { TwoslashManager, setEventEmitter } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import { generateApiDocs } from "./build-program.js";
@@ -11,6 +14,7 @@ import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-deri
 import { fromDir, fromParentDir } from "./config-helpers.js";
 import { mergeLlmsPluginConfig } from "./config-utils.js";
 import { DEFAULT_SHIKI_THEMES, setShikiUtilsEventEmitter } from "./markdown/shiki-utils.js";
+import { setModelLoaderEventEmitter } from "./model-loader.js";
 import { resolveObservability } from "./schemas/observability.js";
 import { PluginOptions } from "./schemas/config.js";
 import "./schemas/index.js";
@@ -27,11 +31,26 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { NodeFileSystem } from "@effect/platform-node";
-import { Effect, Layer, ManagedRuntime, Schema } from "effect";
+import { Effect, FileSystem, Layer, ManagedRuntime, Ref, Schema } from "effect";
 
 //#region src/plugin.ts
 /* v8 ignore start -- RSPress plugin adapter, requires RSPress runtime */
 /**
+* Best-effort read of the consuming site's `package.json` `name`, used to tag
+* the `.api-docs/build/issues.json` artifact. Falls back to "unknown" when the file
+* is missing or unreadable — never fails.
+*/
+const readSitePackageName = Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const pkgJsonPath = path.resolve(process.cwd(), "package.json");
+	const content = yield* fileSystem.readFileString(pkgJsonPath).pipe(Effect.orElseSucceed(() => ""));
+	try {
+		const parsed = JSON.parse(content);
+		if (parsed && typeof parsed === "object" && "name" in parsed && typeof parsed.name === "string") return parsed.name;
+	} catch {}
+	return "unknown";
+});
+/**
 * Normalize theme configuration from user input to a consistent format.
 */
 function normalizeThemeConfig(theme) {
@@ -57,18 +76,17 @@ function ApiExtractorPluginImpl(rawOptions) {
 	const shikiCrossLinker = new ShikiCrossLinker();
 	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,
+		cwd: process.cwd(),
 		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 { layer: eventBusLayer, trace: traceSink, issues: issuesSink } = buildEventBus(obs);
+	const dbPath = path.resolve(process.cwd(), ".api-docs", "snapshot", "api-docs.db");
+	fs.mkdirSync(path.dirname(dbPath), { recursive: true });
 	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);
@@ -80,6 +98,8 @@ function ApiExtractorPluginImpl(rawOptions) {
 	setOgResolverEventEmitter(emitSync, buildId);
 	setRemarkWithApiEventEmitter(emitSync, buildId, obs.thresholds.slowCodeBlock);
 	setRemarkApiCodeblocksEventEmitter(emitSync, buildId);
+	setBuildStagesEventEmitter(emitSync, buildId);
+	setModelLoaderEventEmitter(emitSync, buildId);
 	const fileContextMap = /* @__PURE__ */ new Map();
 	let docsRoot;
 	let isFirstBuild = true;
@@ -94,6 +114,14 @@ function ApiExtractorPluginImpl(rawOptions) {
 		async afterBuild(_config, isProd) {
 			if (isFirstBuild) {
 				await effectRuntime.runPromise(logBuildSummary(obs.thresholds.slowCodeBlock));
+				if (isProd) await effectRuntime.runPromise(Effect.gen(function* () {
+					const packageName = yield* readSitePackageName;
+					yield* writeIssuesJson(issuesSink.snapshot(), {
+						cwd: process.cwd(),
+						packageName,
+						generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+					});
+				}));
 				if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled) {
 					const { processLlmsFiles } = await import("./llms-program.js");
 					await effectRuntime.runPromise(processLlmsFiles({
@@ -109,7 +137,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 			if (traceSink) traceSink.flush();
 			if (isProd) await effectRuntime.dispose();
 		},
-		async config(_config) {
+		async config(_config, _utils, isProd) {
 			const buildStartTime = performance.now();
 			if (_config.root) docsRoot = path.isAbsolute(_config.root) ? _config.root : path.resolve(process.cwd(), _config.root);
 			const rspressRoot = docsRoot || process.cwd();
@@ -118,10 +146,6 @@ 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 ?? "/");
@@ -152,6 +176,7 @@ function ApiExtractorPluginImpl(rawOptions) {
 			}
 			VfsRegistry.clear();
 			fileContextMap.clear();
+			issuesSink.reset();
 			for (const dep of deprecations) emitSync(PluginEvent.DeprecatedConfigUsed({
 				ctx: { buildId },
 				level: "warn",
@@ -173,15 +198,29 @@ function ApiExtractorPluginImpl(rawOptions) {
 						mode: "prod",
 						apiCount
 					}));
+					const phaseRef = yield* Ref.make("resolve");
+					if (isProd && obs.progressIntervalMs !== null) yield* Effect.forkScoped(runHeartbeat({
+						phaseRef,
+						intervalMs: obs.progressIntervalMs,
+						startTime: buildStartTime,
+						apisTotal: apiCount,
+						buildId
+					}));
 					const buildContext = yield* (yield* ConfigService).resolve(rspressConfigSubset);
 					buildResults.length = 0;
+					yield* Ref.set(phaseRef, "generate");
 					yield* Effect.forEach(buildContext.apiConfigs, (apiConfig) => generateApiDocs({
 						...apiConfig,
 						suppressExampleErrors: buildContext.suppressExampleErrors
 					}, buildContext, fileContextMap).pipe(Effect.tap((result) => {
 						buildResults.push(result);
-						return Effect.void;
+						return emit(PluginEvent.ApiDocsCompleted({
+							ctx: { buildId },
+							level: "debug",
+							packageName: result.packageName
+						}));
 					})), { concurrency: 2 });
+					yield* Ref.set(phaseRef, "done");
 					const totalMs = performance.now() - buildStartTime;
 					yield* emit(PluginEvent.BuildCompleted({
 						ctx: { buildId },
@@ -199,6 +238,16 @@ function ApiExtractorPluginImpl(rawOptions) {
 					error: message
 				}));
 				if (traceSink) traceSink.flush();
+				if (isProd) try {
+					await effectRuntime.runPromise(Effect.gen(function* () {
+						const packageName = yield* readSitePackageName;
+						yield* writeIssuesJson(issuesSink.snapshot(), {
+							cwd: process.cwd(),
+							packageName,
+							generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+						});
+					}));
+				} catch {}
 				throw error;
 			}
 			const updatedConfig = { ..._config };

package/route-collisions.js

@@ -39,14 +39,6 @@ function formatRouteCollisionError(collisions, baseRoute) {
 	lines.push("Item names must be unique per category folder. Paths are lowercased, so names differing only in case collide. Rename one of the items, or configure categories so they map to different folders.");
 	return `[rspress-plugin-api-extractor] ${lines.join("\n")}`;
 }
-/**
-* Throw a descriptive error if any distinct items resolve to the same route.
-* Called at build time before pages are generated, so collisions fail fast.
-*/
-function assertNoRouteCollisions(candidates, baseRoute) {
-	const collisions = detectRouteCollisions(candidates);
-	if (collisions.length > 0) throw new Error(formatRouteCollisionError(collisions, baseRoute));
-}
 
 //#endregion
-export { assertNoRouteCollisions, detectRouteCollisions, formatRouteCollisionError };
+export { detectRouteCollisions, formatRouteCollisionError };

package/schemas/observability.js

@@ -14,6 +14,7 @@ const EventLevelSchema = Schema.Literals([
 const ObservabilityConfig = Schema.Struct({
 	logLevel: Schema.optional(EventLevelSchema),
 	trace: Schema.optional(Schema.Union([Schema.Boolean, Schema.String])),
+	progressInterval: Schema.optional(Schema.Union([Schema.Number, Schema.Boolean])),
 	thresholds: Schema.optional(PerformanceThresholds)
 });
 const DEFAULT_THRESHOLDS = {
@@ -41,7 +42,7 @@ function resolveObservability(input) {
 	});
 	const level = normalizeLevel(input.envLogLevel) ?? normalizeLevel(input.observability?.logLevel) ?? normalizeLevel(input.logLevel) ?? "info";
 	const traceOpt = input.observability?.trace;
-	const tracePath = typeof traceOpt === "string" ? traceOpt : traceOpt === true ? `${input.outDir}/.api-extractor/trace-${input.buildId}.jsonl` : null;
+	const tracePath = typeof traceOpt === "string" ? traceOpt : traceOpt === true ? `${input.cwd}/.api-docs/build/trace-${input.buildId}.jsonl` : null;
 	const merged = {
 		...DEFAULT_THRESHOLDS,
 		...input.performance?.thresholds ?? {},
@@ -55,11 +56,15 @@ function resolveObservability(input) {
 		slowHttpRequest: merged.slowHttpRequest ?? DEFAULT_THRESHOLDS.slowHttpRequest,
 		slowDbOperation: merged.slowDbOperation ?? DEFAULT_THRESHOLDS.slowDbOperation
 	};
+	const pi = input.observability?.progressInterval;
+	const seconds = pi === false ? null : typeof pi === "number" ? pi : 10;
+	const progressIntervalMs = seconds !== null && Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : null;
 	return {
 		resolved: {
 			logLevel: level,
 			json: level === "debug",
 			tracePath,
+			progressIntervalMs,
 			thresholds
 		},
 		deprecations