rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/layers/HighlighterServiceLive.js

@@ -0,0 +1,52 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { HighlighterService } from "../services/HighlighterService.js";
+import { SHIKI_LANGS } from "../markdown/shiki-utils.js";
+import { Effect, Layer } from "effect";
+import { createHighlighter } from "shiki";
+
+//#region src/layers/HighlighterServiceLive.ts
+/**
+* Acquire the build's highlighter, and release it when the runtime is
+* disposed.
+*
+* @remarks
+* `Layer.effect` over `Effect.acquireRelease` is the v4 scoped-constructor
+* idiom (`Layer.scoped` is gone; `Layer.effect` strips `Scope` from `R`).
+* Because the layer sits in the `ManagedRuntime`'s stack, the highlighter is
+* created on the runtime's first use and `dispose()`d by
+* `effectRuntime.dispose()` — which `plugin.ts` calls on production builds
+* only, so a dev HMR session keeps one highlighter across rebuilds instead of
+* leaking one per rebuild.
+*
+* **Bind the result to a `const`.** This is a layer FACTORY: each call mints a
+* fresh layer reference, and layers memoize by reference, so calling it twice
+* in one graph acquires two highlighters — the exact leak this layer exists to
+* fix.
+*
+* The themes are passed in rather than read from a resolved build context
+* because the layer builds before `ConfigService.resolve()` runs. Passing them
+* as an argument rather than through a `Context.Reference` is deliberate: a
+* Reference carries a default, so forgetting to wire it would silently load
+* only the default themes and render every custom-themed block wrong. A
+* missing argument is a type error.
+*/
+function HighlighterServiceLive(themes) {
+	return Layer.effect(HighlighterService, Effect.gen(function* () {
+		const startedMs = performance.now();
+		const highlighter = yield* Effect.acquireRelease(Effect.promise(() => createHighlighter({
+			themes: [...themes],
+			langs: [...SHIKI_LANGS]
+		})), (instance) => Effect.sync(() => instance.dispose()));
+		yield* emit(PluginEvent.PhaseCompleted({
+			ctx: {},
+			level: "debug",
+			phase: "shikiInit",
+			durationMs: Math.round(performance.now() - startedMs)
+		}));
+		return { highlighter };
+	}));
+}
+
+//#endregion
+export { HighlighterServiceLive };

package/layers/ObservabilityLive.js

@@ -1,8 +1,10 @@
 import { makeEventBusLayer } from "../observability/EventBus.js";
-import { BuildMetrics } from "./build-metrics.js";
+import { formatCodeBlockReport, seriesFor } from "../observability/metric-report.js";
+import { BuildMetrics, makeMetricStore } 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 { makeRenderSink } from "../observability/sinks/render-sink.js";
 import { makeTraceSink } from "../observability/sinks/trace-sink.js";
 import { Effect, Layer, Logger, Metric, References } from "effect";
 
@@ -29,7 +31,8 @@ function makeSummaryLoggerLayer(logLevel) {
 	return Layer.mergeAll(Logger.layer([pluginLogger]), Layer.succeed(References.MinimumLogLevel, effectLevel));
 }
 /**
-* Compose the console + metrics + issues (+ optional trace) sinks into an EventBus layer.
+* Compose the console + metrics + issues + render (+ optional trace) sinks into
+* an EventBus layer.
 *
 * `cwd` is known at plugin-factory time (unlike the RSPress `outDir`), so the
 * trace path is resolved eagerly by `resolveObservability` and the trace sink
@@ -37,17 +40,22 @@ function makeSummaryLoggerLayer(logLevel) {
 */
 function buildEventBus(obs) {
 	const issues = makeIssuesSink();
+	const render = makeRenderSink();
+	const metrics = makeMetricStore();
 	const sinks = [
 		makeConsoleSink(obs.logLevel, { json: obs.json }),
-		makeMetricsSink(),
-		issues
+		makeMetricsSink(metrics.context),
+		issues,
+		render
 	];
 	const trace = obs.tracePath ? makeTraceSink(obs.tracePath) : null;
 	if (trace) sinks.push(trace);
 	return {
 		layer: makeEventBusLayer(sinks),
 		trace,
-		issues
+		issues,
+		render,
+		metrics
 	};
 }
 /**
@@ -55,8 +63,12 @@ function buildEventBus(obs) {
 * 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.
+*
+* When a code-block report is supplied, the per-scope attribution lines are
+* appended after the aggregate code-block line. The report is optional so
+* existing callers and tests keep working unchanged.
 */
-const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
+const logBuildSummary = (slowCodeBlockMs, renderPhase) => Effect.gen(function* () {
 	const filesTotal = yield* Metric.value(BuildMetrics.filesTotal);
 	const filesNew = yield* Metric.value(BuildMetrics.filesNew);
 	const filesModified = yield* Metric.value(BuildMetrics.filesModified);
@@ -68,6 +80,7 @@ const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
 	const pagesGenerated = yield* Metric.value(BuildMetrics.pagesGenerated);
 	const externalPackages = yield* Metric.value(BuildMetrics.externalPackagesTotal);
 	const phaseDurationSnapshot = yield* Metric.value(BuildMetrics.phaseDuration);
+	const snapshots = yield* Metric.snapshot;
 	const total = filesTotal.count;
 	const newCount = filesNew.count;
 	const modified = filesModified.count;
@@ -86,14 +99,20 @@ const logBuildSummary = (slowCodeBlockMs) => Effect.gen(function* () {
 		yield* Effect.log(`📝 ${total} files (${parts.join(", ")})`);
 	}
 	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 (phaseDurationSnapshot.count > 0) {
+		const named = seriesFor(snapshots, "phase.time.ms").map((p) => `${p.attributes.phase ?? "?"} ${(p.value / 1e3).toFixed(1)}s`).slice(0, 6).join(", ");
+		yield* Effect.log(named.length > 0 ? `⏱ ${phaseDurationSnapshot.count} phase(s): ${named}` : `⏱ ${phaseDurationSnapshot.count} phase(s) timed`);
+	}
 	if (blocks > 0 && slowBlocks > 0) yield* Effect.logWarning(`Code block performance: ${slowBlocks} of ${blocks} blocks were slow (>${slowCodeBlockMs}ms)`);
+	if (renderPhase) for (const line of formatCodeBlockReport(renderPhase)) yield* Effect.log(line);
 	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(", ")})`);
+		const byCode = seriesFor(snapshots, "twoslash.diagnostics");
+		for (const series of byCode.slice(0, 5)) yield* Effect.logWarning(`  ${series.attributes.code ?? "TS?"} x${series.value} in ${series.attributes.scope ?? "(unscoped)"}`);
 	}
 });
 

package/layers/OgServiceLive.js

@@ -0,0 +1,134 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { imageMimeType, ogAltText, resolveOgUrl } from "../og-resolver.js";
+import { OgImageError, OgService } from "../services/OgService.js";
+import { Effect, FileSystem, Layer, Option, Path } from "effect";
+import { imageSize } from "image-size";
+
+//#region src/layers/OgServiceLive.ts
+/**
+* Resolve OG images through the core `FileSystem`, with one read per file per
+* build.
+*
+* @remarks
+* The `node:fs` `existsSync` + `imageSizeFromFile` pair this replaces ran once
+* per PAGE, so a 400-page API re-read the same image 400 times. The memo below
+* keys on the absolute path and removes that entirely.
+*
+* The memo is per build, not persisted. A cross-build cache in the shared XDG
+* store was considered and deliberately deferred: it would need mtime/size
+* invalidation to stay sound, and a stale image dimension is a silent wrong
+* answer. There is nothing expensive enough here to justify that yet — when
+* phase 4 starts GENERATING images, which are expensive and content-addressed,
+* the XDG cache is the right home for them.
+*
+* `imageSize` over the read bytes replaces `imageSizeFromFile`, which took a
+* path and therefore required real `node:fs`. Same parser, same output.
+*/
+const OgServiceLive = Layer.effect(OgService, Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	/** Absolute path → facts, or `null` for "looked, could not use it". */
+	const factsByPath = /* @__PURE__ */ new Map();
+	/** Locate a root-relative image under the docs `public/` directory. */
+	const findLocalImage = (imagePath, docsRoot) => {
+		if (docsRoot == null || !imagePath.startsWith("/")) return Effect.succeed(Option.none());
+		const candidate = path.join(docsRoot, "public", imagePath);
+		return fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false), Effect.map((found) => found ? Option.some(candidate) : Option.none()));
+	};
+	/**
+	* Read dimensions and MIME type. A file that cannot be parsed warns and
+	* yields nothing — the page still gets its `og:image`, just without
+	* dimensions, which is what the class this replaced did.
+	*/
+	const readImageFacts = (filePath) => Effect.gen(function* () {
+		const memoed = factsByPath.get(filePath);
+		if (memoed !== void 0) return memoed;
+		const result = yield* Effect.result(fileSystem.readFile(filePath).pipe(Effect.flatMap((bytes) => Effect.try(() => imageSize(bytes)))));
+		if (result._tag === "Failure") {
+			const error = new OgImageError({
+				code: "unreadable-image",
+				field: "ogImage",
+				value: filePath,
+				cause: result.failure
+			});
+			yield* emit(PluginEvent.ConfigValidationWarning({
+				ctx: {},
+				field: "ogImage",
+				value: filePath,
+				reason: error.message,
+				level: "warn"
+			}));
+			factsByPath.set(filePath, null);
+			return null;
+		}
+		const size = result.success;
+		const mimeType = imageMimeType(size.type);
+		const facts = {
+			...size.width != null ? { width: size.width } : {},
+			...size.height != null ? { height: size.height } : {},
+			...mimeType != null ? { type: mimeType } : {}
+		};
+		factsByPath.set(filePath, facts);
+		return facts;
+	});
+	const resolveFromString = (imageUrl, request) => Effect.gen(function* () {
+		const resolvedUrl = resolveOgUrl(request.siteUrl, imageUrl);
+		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
+			code: "invalid-url",
+			field: "ogImage",
+			value: imageUrl
+		}));
+		const localPath = yield* findLocalImage(imageUrl, request.docsRoot);
+		const facts = Option.isSome(localPath) ? yield* readImageFacts(localPath.value) : null;
+		return Option.some({
+			url: resolvedUrl,
+			type: facts?.type,
+			width: facts?.width,
+			height: facts?.height,
+			alt: ogAltText(request.packageName, request.apiName)
+		});
+	});
+	const resolveFromMetadata = (metadata, request) => Effect.gen(function* () {
+		const { url, secureUrl, type, width, height, alt } = metadata;
+		const resolvedUrl = resolveOgUrl(request.siteUrl, url);
+		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
+			code: "invalid-url",
+			field: "ogImage.url",
+			value: url
+		}));
+		let resolvedSecureUrl;
+		if (secureUrl != null) {
+			if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
+			else {
+				const error = new OgImageError({
+					code: "invalid-secure-url",
+					field: "ogImage.secureUrl",
+					value: secureUrl
+				});
+				yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {},
+					field: "ogImage.secureUrl",
+					value: secureUrl,
+					reason: error.message,
+					level: "warn"
+				}));
+			}
+		}
+		return Option.some({
+			url: resolvedUrl,
+			secureUrl: resolvedSecureUrl,
+			type,
+			width,
+			height,
+			alt: alt ?? ogAltText(request.packageName, request.apiName)
+		});
+	});
+	return { resolveImage: (request) => {
+		if (request.config == null) return Effect.succeed(Option.none());
+		return typeof request.config === "object" ? resolveFromMetadata(request.config, request) : resolveFromString(request.config, request);
+	} };
+}));
+
+//#endregion
+export { OgServiceLive };

package/layers/TwoslashCacheServiceLive.js

@@ -0,0 +1,108 @@
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
+import { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey } from "../twoslash-cache.js";
+import { AppDirsLive, PlatformLive } from "./xdg.js";
+import { Effect, Layer, Option, Path } from "effect";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
+
+//#region src/layers/TwoslashCacheServiceLive.ts
+/**
+* A sqlite-backed `@effected/store` Cache in the XDG cache dir, separate from
+* the registry's `metadata.sqlite`.
+*
+* XDG rather than the repo: these are regenerable results derived from content
+* hashes, so they belong with the user's other caches — shared across worktrees
+* and checkouts of the same project, and untouched by cleaning `dist/`. Nothing
+* here needs to be committed for a build to be correct.
+*/
+const CacheLive = Layer.unwrap(Effect.gen(function* () {
+	const appDirs = yield* AppDirs;
+	const path = yield* Path.Path;
+	const cacheDir = yield* appDirs.ensureCache;
+	return Cache.layerSqlite({ filename: path.join(cacheDir, "twoslash.sqlite") });
+})).pipe(Layer.provide(Layer.mergeAll(AppDirsLive, PlatformLive)));
+/**
+* Live Twoslash cache persistence.
+*
+* Both operations swallow every failure by design — see the service docs. A
+* missing HOME, an unwritable cache dir or a corrupt database degrades the
+* build to "type-check everything", which is exactly the behaviour before this
+* cache existed.
+*/
+/**
+* Add the build-generation half of the service on top of a load/save pair.
+*
+* @remarks
+* Shared by the real and degraded layers so the two cannot drift: a degraded
+* build must still hand out a working in-memory cache, otherwise the
+* transformers have nothing to read or write and the render pass changes
+* shape rather than merely losing persistence.
+*/
+function withGeneration(base) {
+	let open = null;
+	return {
+		...base,
+		open: (envHash) => base.load(envHash).pipe(Effect.map((restored) => {
+			const cache = makeTwoslashCache(restored);
+			open = {
+				cache,
+				envHash
+			};
+			return cache;
+		})),
+		persist: () => Effect.suspend(() => {
+			if (open === null) return Effect.succeed(Option.none());
+			const { cache, envHash } = open;
+			const stats = cache.stats();
+			const report = Option.some({
+				...stats,
+				envHash
+			});
+			return stats.dirty ? base.save(envHash, cache.entries()).pipe(Effect.as(report)) : Effect.succeed(report);
+		})
+	};
+}
+const CacheBackedLive = Layer.effect(TwoslashCacheService, Effect.gen(function* () {
+	const cache = yield* Cache;
+	return withGeneration({
+		load: (envHash) => cache.get(twoslashBlobKey(envHash)).pipe(Effect.map((entry) => Option.isSome(entry) ? decodeTwoslashCache(entry.value.value) : /* @__PURE__ */ new Map()), Effect.catch(() => Effect.succeed(/* @__PURE__ */ new Map()))),
+		save: (envHash, entries) => cache.set({
+			key: twoslashBlobKey(envHash),
+			value: encodeTwoslashCache(entries),
+			tags: ["twoslash"]
+		}).pipe(Effect.catch(() => Effect.void))
+	});
+})).pipe(Layer.provide(CacheLive));
+/**
+* A cache that holds nothing, for when the real one cannot be opened.
+*
+* @remarks
+* `load` returns empty and `save` discards, which is precisely the behaviour
+* before this cache existed: type-check everything, persist nothing.
+*/
+const DegradedLive = Layer.succeed(TwoslashCacheService, withGeneration({
+	load: () => Effect.succeed(/* @__PURE__ */ new Map()),
+	save: () => Effect.void
+}));
+/**
+* Live Twoslash cache persistence.
+*
+* @remarks
+* Failure is absorbed at TWO levels, and both are load-bearing. Inside the
+* service, a failed read or write degrades that one operation. Around the
+* layer, a failed CONSTRUCTION — no HOME for XDG, an unwritable cache
+* directory, a corrupt database — degrades to {@link DegradedLive}.
+*
+* The second is why `Layer.catchCause` wraps this at all. While the sqlite
+* layer was provided inside each method, a construction failure surfaced as
+* that method's failure and the in-method handler swallowed it. Hoisting
+* acquisition to layer construction moved the failure to `ManagedRuntime`
+* build time, where it would abort the entire build — breaking the contract
+* this service documents, that an unreachable cache must never fail a build
+* that would otherwise succeed. `catchCause` rather than a failure-only catch
+* because a defect thrown by the sqlite driver must degrade too.
+*/
+const TwoslashCacheServiceLive = CacheBackedLive.pipe(Layer.catchCause(() => DegradedLive));
+
+//#endregion
+export { TwoslashCacheServiceLive };

package/layers/TwoslashEnvironmentsLive.js

@@ -0,0 +1,33 @@
+import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
+import { TwoslashEnvironmentRegistry } from "../twoslash-transformer.js";
+import { Layer } from "effect";
+
+//#region src/layers/TwoslashEnvironmentsLive.ts
+/**
+* One environment registry per runtime.
+*
+* @remarks
+* `Layer.sync` rather than `Layer.succeed`: the registry is mutable, and a
+* `Layer.succeed` would capture a single instance shared by every layer graph
+* that referenced this const — including, in a test run, every test file in
+* the process. Building it when the layer builds is what makes substitution
+* work: a test that wants an isolated registry provides its own layer, which
+* is what the old static `TwoslashManager.reset()` was standing in for.
+*
+* Deliberately NOT `Layer.effect` with a finalizer. The registry holds Shiki
+* transformers, which the render pass uses AFTER `config()` returns — the same
+* lifetime constraint the highlighter has, and for the same reason.
+*/
+const TwoslashEnvironmentsLive = Layer.sync(TwoslashEnvironments, () => {
+	const registry = new TwoslashEnvironmentRegistry();
+	return {
+		registerEnvironment: (options) => registry.registerEnvironment(options),
+		registerScope: (apiScope, compilerOptions) => registry.registerScope(apiScope, compilerOptions),
+		transformerFor: (apiScope) => registry.transformerFor(apiScope),
+		setCurrentFile: (path) => registry.setCurrentFile(path),
+		reportErrorForTest: (error, code, file) => registry.reportErrorForTest(error, code, file)
+	};
+});
+
+//#endregion
+export { TwoslashEnvironmentsLive };

package/layers/TypeRegistryServiceLive.js

@@ -3,11 +3,12 @@ import { emit } from "../observability/EventBus.js";
 import { resolveExternalPackageVersions } from "../config-utils.js";
 import { TypeRegistryError } from "../errors.js";
 import { TypeRegistryService } from "../services/TypeRegistryService.js";
-import { NodeFileSystem, NodeHttpClient } from "@effect/platform-node";
+import { AppDirsLive, PlatformLive } from "./xdg.js";
+import { NodeHttpClient } from "@effect/platform-node";
 import { Duration, Effect, Layer, Path } from "effect";
 import { PackageFetcher, PackageSpec, RegistryObserver, TypeCache, TypeRegistry } from "@tsdoctor/registry";
 import { Cache } from "@effected/store";
-import { AppDirs, Xdg } from "@effected/xdg";
+import { AppDirs } from "@effected/xdg";
 
 //#region src/layers/TypeRegistryServiceLive.ts
 /**
@@ -22,19 +23,13 @@ import { AppDirs, Xdg } from "@effected/xdg";
 const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) => {
 	switch (event._tag) {
 		case "VersionResolved": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: {
-				buildId: "",
-				packageName: event.package
-			},
+			ctx: { packageName: event.package },
 			level: "debug",
 			kind: "VersionResolved",
 			detail: `${event.requested} -> ${event.resolved}`
 		}));
 		case "VersionResolveFailed": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: {
-				buildId: "",
-				packageName: event.package
-			},
+			ctx: { packageName: event.package },
 			level: "debug",
 			kind: "VersionResolveFailed",
 			detail: `${event.requested}: ${event.kind}`
@@ -43,7 +38,6 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 		case "CacheMiss":
 		case "FetchStart": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -53,7 +47,6 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 		}));
 		case "CacheStale": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -62,14 +55,13 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 			detail: ""
 		}));
 		case "FetchFailed": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: { buildId: "" },
+			ctx: {},
 			level: "debug",
 			kind: "FetchFailed",
 			detail: `HTTP ${event.status}: ${event.url}${event.bodySnippet ? ` — ${event.bodySnippet}` : ""}`
 		}));
 		case "PackageLoaded": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -79,7 +71,6 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 		}));
 		case "PackageLoadFailed": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -88,35 +79,19 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 			detail: `[${event.kind}] ${event.error instanceof Error ? event.error.message : String(event.error)}`
 		}));
 		case "BatchStart": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: { buildId: "" },
+			ctx: {},
 			level: "debug",
 			kind: "BatchStart",
 			detail: `${event.total} package(s)`
 		}));
 		case "BatchComplete": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: { buildId: "" },
+			ctx: {},
 			level: "info",
 			kind: "BatchComplete",
 			detail: `${event.loaded}/${event.total} packages, ${event.totalFiles} files, ${Math.round(Duration.toMillis(event.duration))}ms`
 		}));
 	}
 } });
-/**
-* @tsdoctor/registry composes at the edge: the library ships no platform
-* layer of its own, so the plugin wires FileSystem/Path, the XDG directories,
-* the sqlite metadata Cache and the HTTP client here.
-*
-* All layers are bound to module-level consts (never rebuilt per call) per the
-* v4 layer memoization discipline.
-*/
-const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
-/**
-* XDG app directories under the tsdoctor-wide namespace. Renamed from the
-* legacy "type-registry-effect" namespace in phase 2 per the resolved identity
-* decision (see tsdoctor-package-architecture.md) — a deliberate one-time
-* on-disk cache invalidation: existing caches go cold and refetch.
-*/
-const AppDirsLive = AppDirs.layer({ namespace: "tsdoctor" }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
 /** Metadata plane: a sqlite-backed `@effected/store` Cache rooted in the XDG cache dir. */
 const MetadataCacheLive = Layer.unwrap(Effect.gen(function* () {
 	const appDirs = yield* AppDirs;
@@ -133,23 +108,55 @@ const RegistryLayer = TypeRegistry.layer.pipe(Layer.provideMerge(Layer.mergeAll(
 /**
 * TypeRegistryServiceLive: uses @tsdoctor/registry Effect programs directly.
 */
-const TypeRegistryServiceLive = Layer.succeed(TypeRegistryService, {
-	resolveVersions: (packages) => Effect.gen(function* () {
-		const registry = yield* TypeRegistry;
-		return yield* resolveExternalPackageVersions(packages, (pkg) => registry.resolveVersion(pkg.name, pkg.version));
-	}).pipe(Effect.provide(RegistryLayer), Effect.catch(() => Effect.succeed([...packages]))),
-	loadPackages: (packages) => packages.length === 0 ? Effect.succeed({ vfs: /* @__PURE__ */ new Map() }) : Effect.gen(function* () {
-		const specs = packages.map((pkg) => new PackageSpec({
-			name: pkg.name,
-			version: pkg.version
-		}));
-		return { vfs: yield* (yield* TypeRegistry).getVfs(specs, { autoFetch: true }) };
-	}).pipe(Effect.provide(RegistryLayer), Effect.catch((error) => Effect.fail(new TypeRegistryError({
+const RegistryBackedLive = Layer.effect(TypeRegistryService, Effect.gen(function* () {
+	const registry = yield* TypeRegistry;
+	return {
+		resolveVersions: (packages) => resolveExternalPackageVersions(packages, (pkg) => registry.resolveVersion(pkg.name, pkg.version)).pipe(Effect.catch(() => Effect.succeed([...packages]))),
+		loadPackages: (packages) => packages.length === 0 ? Effect.succeed({ vfs: /* @__PURE__ */ new Map() }) : Effect.gen(function* () {
+			const specs = packages.map((pkg) => new PackageSpec({
+				name: pkg.name,
+				version: pkg.version
+			}));
+			return { vfs: yield* registry.getVfs(specs, { autoFetch: true }) };
+		}).pipe(Effect.catch((error) => Effect.fail(new TypeRegistryError({
+			packageName: packages.map((p) => p.name).join(", "),
+			version: packages.map((p) => p.version).join(", "),
+			reason: error instanceof Error ? error.message ?? String(error) : String(error)
+		}))))
+	};
+})).pipe(Layer.provide(RegistryLayer));
+/**
+* The service when the registry stack cannot be built at all.
+*
+* @remarks
+* Preserves exactly the split the working service documents: `resolveVersions`
+* passes its specs through unresolved rather than swallowing the problem, so
+* the failure surfaces from `loadPackages` as a {@link PluginTypeRegistryError}
+* with a message, which `ConfigServiceLive` turns into a build-continues
+* warning. Before acquisition moved to layer construction this fell out of the
+* per-method handlers; it has to be stated explicitly now.
+*/
+const DegradedLive = Layer.succeed(TypeRegistryService, {
+	resolveVersions: (packages) => Effect.succeed([...packages]),
+	loadPackages: (packages) => Effect.fail(new TypeRegistryError({
 		packageName: packages.map((p) => p.name).join(", "),
 		version: packages.map((p) => p.version).join(", "),
-		reason: error instanceof Error ? error.message ?? String(error) : String(error)
-	}))))
+		reason: "type registry unavailable: its cache directory or metadata database could not be opened"
+	}))
 });
+/**
+* TypeRegistryServiceLive: the `@tsdoctor/registry` stack, acquired once.
+*
+* @remarks
+* `Layer.catchCause` keeps a broken environment — no HOME for XDG, an
+* unwritable cache directory — from aborting the build at `ManagedRuntime`
+* construction. External type loading is an enhancement: without it code
+* blocks render without Twoslash enrichment, which is a degradation, not a
+* failure. That was true while the stack was provided per method and the
+* in-method handlers absorbed it; hoisting acquisition made it something the
+* layer has to say for itself.
+*/
+const TypeRegistryServiceLive = RegistryBackedLive.pipe(Layer.catchCause(() => DegradedLive));
 
 //#endregion
 export { TypeRegistryServiceLive };

package/layers/build-metrics.js

@@ -1,12 +1,21 @@
-import { Metric } from "effect";
+import { Context, Layer, Metric } from "effect";
 
 //#region src/layers/build-metrics.ts
+/** Create an isolated metric store for a single build. */
+function makeMetricStore() {
+	const registry = /* @__PURE__ */ new Map();
+	return {
+		registry,
+		context: Context.make(Metric.MetricRegistry, registry),
+		layer: Layer.succeed(Metric.MetricRegistry, registry)
+	};
+}
 /**
 * 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.
+* Metric state lives in the `Metric.MetricRegistry` of the surrounding context,
+* not in these constants, so these may be shared module-level values while each
+* build still gets its own counters — see {@link MetricRegistryLive}.
 *
 * Extracted into its own module so that `metrics-sink.ts` can import it
 * without creating a circular dependency through `ObservabilityLive.ts`
@@ -36,8 +45,20 @@ const BuildMetrics = {
 	] }),
 	codeblockTotal: Metric.counter("codeblock.total"),
 	codeblockSlow: Metric.counter("codeblock.slow"),
+	/**
+	* Summed milliseconds per dimension. Counters rather than histograms because
+	* the question these answer is "where did the time go", which needs a total;
+	* the histograms above still carry the distribution.
+	*/
+	codeblockTimeMs: Metric.counter("codeblock.time.ms"),
+	codeblockTwoslashMs: Metric.counter("codeblock.twoslash.ms"),
+	codeblockShikiMs: Metric.counter("codeblock.shiki.ms"),
+	/** Blocks the Twoslash transformer actually ran on. */
+	codeblockTwoslashTotal: Metric.counter("codeblock.twoslash.total"),
 	twoslashErrors: Metric.counter("twoslash.errors"),
 	prettierErrors: Metric.counter("prettier.errors"),
+	/** Shiki render failures. Previously unmapped, so they never reached a metric. */
+	shikiErrors: Metric.counter("shiki.errors"),
 	pagesGenerated: Metric.counter("pages.generated"),
 	apisCompleted: Metric.counter("apis.completed"),
 	apiVersionsLoaded: Metric.counter("api.versions.loaded"),
@@ -52,6 +73,12 @@ const BuildMetrics = {
 		5e3,
 		1e4
 	] }),
+	/**
+	* Summed phase milliseconds. Tagged by phase name, which the histogram alone
+	* cannot express — every phase previously collapsed into one distribution, so
+	* resolve could not be told apart from generate or write.
+	*/
+	phaseTimeMs: Metric.counter("phase.time.ms"),
 	vfsFiles: Metric.counter("vfs.files"),
 	importsPrepended: Metric.counter("imports.prepended"),
 	twoslashDiagnostics: Metric.counter("twoslash.diagnostics"),
@@ -59,4 +86,4 @@ const BuildMetrics = {
 };
 
 //#endregion
-export { BuildMetrics };
+export { BuildMetrics, makeMetricStore };