rspress-plugin-api-extractor 0.11.0 → 0.13.0

package/layers/{ConfigServiceLive.js → config-resolution.js}

@@ -1,32 +1,29 @@
 import { BuildId } from "../BuildEnv.js";
+import { BuildMetrics } from "./build-metrics.js";
 import { PluginEvent } from "../observability/events.js";
 import { emit, wantsLevel } from "../observability/EventBus.js";
-import { BuildMetrics } from "./build-metrics.js";
-import "./ObservabilityLive.js";
 import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 import { withPhase } from "../observability/spans.js";
-import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
-import { resolveTypeScriptConfig } from "../typescript-config.js";
+import { normalizeThemeConfig } from "../markdown/shiki-utils.js";
 import { apiScopeOf, deriveOutputPaths, normalizeBaseRoute, unscopedName } from "../path-derivation.js";
 import { classifyApiConfig, extractAutoDetectedPackages, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages } from "../config-utils.js";
 import { ApiExtractedPackage } from "../api-extracted-package.js";
 import { CategoryResolver } from "../category-resolver.js";
 import { ConfigValidationError } from "../errors.js";
-import { normalizeThemeConfig } from "../markdown/shiki-utils.js";
 import { loadApiModel, loadPackageJson, loadVersionModel } from "../model-loader.js";
 import { DEFAULT_CATEGORIES } from "../schemas/config.js";
-import "../schemas/index.js";
-import { ConfigService } from "../services/ConfigService.js";
 import { PluginConfig } from "../services/PluginConfig.js";
-import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
 import { TypeRegistryService } from "../services/TypeRegistryService.js";
-import { twoslashEnvHash } from "../twoslash-cache.js";
+import { emitVfsPayloadEvents, mergeApiResult } from "./api-results.js";
+import { mergeExternalTypes } from "./external-types.js";
+import { registerTypeEnvironments, resolveTsConfigTyped } from "./type-environment.js";
 import path from "node:path";
+import { Effect, Metric } from "effect";
+import { deriveSiteUrl } from "@tsdoctor/seo";
 import { hashContent } from "@tsdoctor/snapshot";
-import { Effect, Layer, Metric } from "effect";
-import ts from "typescript";
+import { PackageManifest } from "@effected/package-json";
 
-//#region src/layers/ConfigServiceLive.ts
+//#region src/layers/config-resolution.ts
 /**
 * Prepend import statements for external type references to the VFS declaration files.
 * Returns per-entry payloads for event emission (heavy content/importRefs gated on wantTrace).
@@ -65,6 +62,40 @@ function prependImportsToVfs(vfs, apiPackage, packageName, wantTrace) {
 	return payloads;
 }
 /**
+* Decode a loaded package.json into a typed {@link PackageManifest}, degrading
+* to `undefined` when it does not satisfy the codec.
+*
+* @remarks
+* `PackageManifest` is presence-lenient but shape-strict — the private
+* workspace-root shape decodes fine, but one malformed field (a `version` of
+* `"1.0"`, an `author` that is neither a string nor an object) fails the whole
+* decode. That is the right strictness for the SEO layer, which needs real
+* `Person` / `Repository` values rather than the discovery tier's raw unions,
+* but it must never fail a docs build: the failure is surfaced as a
+* `ConfigValidationWarning` (which reaches `issues.json`) and the manifest is
+* simply absent. The same posture as the OG image path in `build-stages.ts`.
+*/
+function decodeManifest(packageJson, buildId, packageName) {
+	return Effect.gen(function* () {
+		if (packageJson == null) return void 0;
+		const decoded = yield* Effect.result(PackageManifest.decode(packageJson));
+		if (decoded._tag === "Failure") {
+			yield* emit(PluginEvent.ConfigValidationWarning({
+				ctx: {
+					buildId,
+					packageName
+				},
+				field: "packageJson",
+				value: packageName,
+				reason: decoded.failure.message,
+				level: "warn"
+			}));
+			return;
+		}
+		return decoded.success;
+	});
+}
+/**
 * Validate plugin options and return an Effect that fails with ConfigValidationError.
 */
 function validateOptions(options, rspressConfig) {
@@ -129,8 +160,12 @@ function validateOptions(options, rspressConfig) {
 * would build a second `ConfigService` with its own captured `TypeRegistry`.
 * The options come from {@link PluginConfig} now, so there is nothing to pass
 * and nothing to call twice.
+*
+* The `Layer` around this lives on the service, as `ConfigService.layer`. The
+* implementation stays here rather than in the service module because it is
+* the bulk of config resolution; the service module declares the contract.
 */
-const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
+const makeConfigService = Effect.gen(function* () {
 	const typeRegistry = yield* TypeRegistryService;
 	const options = yield* PluginConfig;
 	return { resolve: (rspressConfig) => Effect.gen(function* () {
@@ -146,11 +181,18 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 		const rspressLang = rspressConfig.lang;
 		const docsRoot = rspressConfig.root;
 		const rspressRoot = docsRoot || process.cwd();
+		const siteUrl = deriveSiteUrl(rspressConfig.siteOrigin, rspressConfig.base);
 		const categoryResolver = new CategoryResolver();
 		const pluginDefaults = categoryResolver.mergeCategories(DEFAULT_CATEGORIES, options.defaultCategories);
 		const apiConfigs = [];
 		const combinedVfs = /* @__PURE__ */ new Map();
 		const allExternalPackages = [];
+		/** The three above, as one value the merge helper can take. */
+		const acc = {
+			apiConfigs,
+			combinedVfs,
+			allExternalPackages
+		};
 		let firstApiTsconfig;
 		let firstApiCompilerOptions;
 		/**
@@ -176,14 +218,29 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 		*/
 		const processSimpleApi = (api, model, outputDir, fullRoute, wantTrace) => Effect.gen(function* () {
 			const { apiPackage, source: loaderSource } = yield* withModelLoadEvents(loadApiModel(model));
-			return yield* Effect.promise(async () => {
+			{
 				const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories);
 				const resolvedSource = categoryResolver.resolveSourceConfig(api.source, loaderSource);
 				const resolvedLlms = mergeLlmsPluginConfig(options.llmsPlugin, api.llmsPlugin);
-				const packageJson = api.packageJson ? await loadPackageJson(api.packageJson) : void 0;
-				validateExternalPackages(api.externalPackages, packageJson);
+				const packageJson = api.packageJson ? yield* Effect.tryPromise({
+					try: () => loadPackageJson(api.packageJson),
+					catch: (cause) => new ConfigValidationError({
+						field: "packageJson",
+						reason: cause instanceof Error ? cause.message : String(cause),
+						cause
+					})
+				}) : void 0;
+				const manifest = yield* decodeManifest(packageJson, buildId, api.packageName);
+				yield* Effect.try({
+					try: () => validateExternalPackages(api.externalPackages, packageJson),
+					catch: (cause) => new ConfigValidationError({
+						field: "externalPackages",
+						reason: cause instanceof Error ? cause.message : String(cause),
+						cause
+					})
+				});
 				const externalPackages = api.externalPackages || extractAutoDetectedPackages(packageJson, api.autoDetectDependencies);
-				if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.update(BuildMetrics.externalPackagesTotal, externalPackages.length));
+				if (externalPackages && externalPackages.length > 0) yield* Metric.update(BuildMetrics.externalPackagesTotal, externalPackages.length);
 				const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
 				const vfsPayloads = prependImportsToVfs(vfs, apiPackage, api.packageName, wantTrace);
 				const resolvedOgImage = api.ogImage ?? options.ogImage;
@@ -201,15 +258,16 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 						categories: resolvedCategories,
 						...resolvedSource != null ? { source: resolvedSource } : {},
 						...packageJson != null ? { packageJson } : {},
+						...manifest != null ? { manifest } : {},
 						...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
-						...options.siteUrl != null ? { siteUrl: options.siteUrl } : {},
+						...siteUrl != null ? { siteUrl } : {},
 						...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
 						docsDir: path.dirname(outputDir),
 						...docsRoot != null ? { docsRoot } : {},
 						...resolvedTheme != null ? { theme: resolvedTheme } : {}
 					}
 				};
-			});
+			}
 		});
 		yield* withPhase("modelLoad", { buildId }, Effect.gen(function* () {
 			if (options.api) {
@@ -238,16 +296,31 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 						};
 						const versionConfig = isVersionConfig(versionValue) ? versionValue : { model: versionValue };
 						const { apiPackage, packageJson: versionPackageJson, categories: versionCategories, source: versionSource, externalPackages: versionExternalPackages, autoDetectDependencies: versionAutoDetectDependencies, llmsPlugin: versionLlms, ogImage: versionOgImage } = yield* withModelLoadEvents(loadVersionModel(versionConfig));
-						return yield* Effect.promise(async () => {
-							Effect.runSync(Metric.update(BuildMetrics.apiVersionsLoaded, 1));
+						{
+							yield* Metric.update(BuildMetrics.apiVersionsLoaded, 1);
 							const resolvedCategories = categoryResolver.resolveCategoryConfig(pluginDefaults, api.categories, versionCategories);
 							const resolvedSource = categoryResolver.resolveSourceConfig(api.source, versionSource);
 							const resolvedLlms = mergeLlmsPluginConfig(options.llmsPlugin, api.llmsPlugin, versionLlms);
-							const packageJson = versionPackageJson || (api.packageJson ? await loadPackageJson(api.packageJson) : void 0);
-							validateExternalPackages(versionExternalPackages || api.externalPackages, packageJson);
+							const packageJson = versionPackageJson || (api.packageJson ? yield* Effect.tryPromise({
+								try: () => loadPackageJson(api.packageJson),
+								catch: (cause) => new ConfigValidationError({
+									field: "packageJson",
+									reason: cause instanceof Error ? cause.message : String(cause),
+									cause
+								})
+							}) : void 0);
+							const manifest = yield* decodeManifest(packageJson, buildId, api.packageName);
+							yield* Effect.try({
+								try: () => validateExternalPackages(versionExternalPackages || api.externalPackages, packageJson),
+								catch: (cause) => new ConfigValidationError({
+									field: "externalPackages",
+									reason: cause instanceof Error ? cause.message : String(cause),
+									cause
+								})
+							});
 							const autoDetectOptions = versionAutoDetectDependencies || api.autoDetectDependencies;
 							const externalPackages = versionExternalPackages || api.externalPackages || extractAutoDetectedPackages(packageJson, autoDetectOptions);
-							if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.update(BuildMetrics.externalPackagesTotal, externalPackages.length));
+							if (externalPackages && externalPackages.length > 0) yield* Metric.update(BuildMetrics.externalPackagesTotal, externalPackages.length);
 							const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
 							const vfsPayloads = prependImportsToVfs(vfs, apiPackage, api.packageName, wantTrace);
 							const resolvedOgImage = versionOgImage ?? api.ogImage ?? options.ogImage;
@@ -267,42 +340,20 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 									categories: resolvedCategories,
 									...resolvedSource != null ? { source: resolvedSource } : {},
 									...packageJson != null ? { packageJson } : {},
+									...manifest != null ? { manifest } : {},
 									...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
-									...options.siteUrl != null ? { siteUrl: options.siteUrl } : {},
+									...siteUrl != null ? { siteUrl } : {},
 									...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
 									docsDir: path.dirname(outputDir),
 									...docsRoot != null ? { docsRoot } : {},
 									...resolvedTheme != null ? { theme: resolvedTheme } : {}
 								}
 							};
-						});
+						}
 					}), { concurrency: "unbounded" });
 					for (const result of versionResults) {
-						for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
-						if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
-						if (result.config) apiConfigs.push(result.config);
-						for (const payload of result.vfsPayloads) {
-							yield* emit(PluginEvent.VfsGenerated({
-								ctx: {
-									packageName: api.packageName,
-									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
-								},
-								level: "debug",
-								file: payload.file,
-								declCount: payload.declCount,
-								contentHash: payload.contentHash,
-								...wantTrace && payload.content ? { content: payload.content } : {}
-							}));
-							if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
-								ctx: {
-									packageName: api.packageName,
-									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
-								},
-								level: "debug",
-								file: payload.file,
-								imports: wantTrace ? payload.importRefs : []
-							}));
-						}
+						mergeApiResult(acc, result);
+						yield* emitVfsPayloadEvents(api.packageName, result.vfsPayloads, wantTrace);
 					}
 				} else if (api.model) {
 					const dp = deriveOutputPaths({
@@ -317,31 +368,8 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 					})[0];
 					if (dp) {
 						const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase, wantTrace);
-						for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
-						if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
-						apiConfigs.push(result.config);
-						for (const payload of result.vfsPayloads) {
-							yield* emit(PluginEvent.VfsGenerated({
-								ctx: {
-									packageName: api.packageName,
-									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
-								},
-								level: "debug",
-								file: payload.file,
-								declCount: payload.declCount,
-								contentHash: payload.contentHash,
-								...wantTrace && payload.content ? { content: payload.content } : {}
-							}));
-							if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
-								ctx: {
-									packageName: api.packageName,
-									...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
-								},
-								level: "debug",
-								file: payload.file,
-								imports: wantTrace ? payload.importRefs : []
-							}));
-						}
+						mergeApiResult(acc, result);
+						yield* emitVfsPayloadEvents(api.packageName, result.vfsPayloads, wantTrace);
 					}
 				}
 			} else if (options.apis) {
@@ -367,35 +395,10 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 					})[0];
 					if (!dp) return [];
 					const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase, wantTrace);
-					for (const payload of result.vfsPayloads) {
-						yield* emit(PluginEvent.VfsGenerated({
-							ctx: {
-								packageName: api.packageName,
-								...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
-							},
-							level: "debug",
-							file: payload.file,
-							declCount: payload.declCount,
-							contentHash: payload.contentHash,
-							...wantTrace && payload.content ? { content: payload.content } : {}
-						}));
-						if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
-							ctx: {
-								packageName: api.packageName,
-								...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
-							},
-							level: "debug",
-							file: payload.file,
-							imports: wantTrace ? payload.importRefs : []
-						}));
-					}
+					yield* emitVfsPayloadEvents(api.packageName, result.vfsPayloads, wantTrace);
 					return [result];
 				}), { concurrency: "unbounded" });
-				for (const results of multiResults) for (const result of results) {
-					for (const [filepath, content] of result.vfs.entries()) combinedVfs.set(filepath, content);
-					if (result.externalPackages.length > 0) allExternalPackages.push(...result.externalPackages);
-					apiConfigs.push(result.config);
-				}
+				for (const results of multiResults) for (const result of results) mergeApiResult(acc, result);
 			}
 		}));
 		const loadMs = performance.now() - loadStart;
@@ -413,86 +416,23 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 			if (firstApiTsconfig != null) globalTsConfig.tsconfig = firstApiTsconfig;
 			if (firstApiCompilerOptions != null) globalTsConfig.compilerOptions = firstApiCompilerOptions;
 		}
-		const resolvedCompilerOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, globalTsConfig));
+		const resolvedCompilerOptions = yield* resolveTsConfigTyped(projectRoot, globalTsConfig);
 		yield* emit(PluginEvent.TsCacheCreated({
 			ctx: {},
 			level: "debug",
 			compilerOptions: `target=${resolvedCompilerOptions.target}, module=${resolvedCompilerOptions.module}, lib=[${resolvedCompilerOptions.lib?.join(", ") ?? ""}]`,
 			durationMs: 0
 		}));
-		const documentedPackageNames = new Set(apiConfigs.map((config) => config.packageName));
-		const externalPackagesToLoad = allExternalPackages.filter((pkg) => !documentedPackageNames.has(pkg.name));
-		const typeLoadResult = yield* Effect.result(Effect.gen(function* () {
-			if (externalPackagesToLoad.length > 0) {
-				const resolvedPackages = yield* typeRegistry.resolveVersions(externalPackagesToLoad);
-				const droppedCount = externalPackagesToLoad.length - resolvedPackages.length;
-				if (droppedCount > 0) yield* emit(PluginEvent.ExternalPackageSkipped({
-					ctx: {},
-					level: "debug",
-					reason: `${droppedCount} unresolvable package(s) (unpublished or workspace-only)`
-				}));
-				if (resolvedPackages.length > 0) {
-					const result = yield* typeRegistry.loadPackages(resolvedPackages);
-					for (const [filePath, content] of result.vfs.entries()) combinedVfs.set(filePath, content);
-					yield* emit(PluginEvent.VfsMerged({
-						ctx: {},
-						level: "debug",
-						totalFiles: result.vfs.size,
-						packages: resolvedPackages.map((p) => p.name)
-					}));
-				}
-			}
-		}));
-		if (typeLoadResult._tag === "Failure") yield* emit(PluginEvent.ConfigCascadeWarning({
-			ctx: {},
-			level: "warn",
-			field: "externalTypes",
-			chosen: "empty VFS",
-			ignored: [typeLoadResult.failure.message ?? String(typeLoadResult.failure)]
-		}));
-		const twoslashEnv = twoslashEnvHash(combinedVfs, `typescript@${ts.version}`);
-		const twoslashCache = yield* (yield* TwoslashCacheService).open(twoslashEnv);
-		yield* emit(PluginEvent.TwoslashCacheLoaded({
-			ctx: {},
-			level: "debug",
-			envHash: twoslashEnv,
-			entries: twoslashCache.entries().size
-		}));
-		const twoslashStartMs = performance.now();
-		const environments = yield* TwoslashEnvironments;
-		environments.registerEnvironment({
-			vfs: combinedVfs,
-			compilerOptions: resolvedCompilerOptions,
-			typesCache: twoslashCache
+		yield* mergeExternalTypes(typeRegistry, combinedVfs, apiConfigs, allExternalPackages);
+		yield* registerTypeEnvironments({
+			combinedVfs,
+			resolvedCompilerOptions,
+			scopeTsConfigs,
+			projectRoot
 		});
-		const resolvedByRawConfig = /* @__PURE__ */ new Map();
-		for (const [apiScope, rawConfig] of scopeTsConfigs) {
-			if (rawConfig === void 0) {
-				environments.registerScope(apiScope, resolvedCompilerOptions);
-				continue;
-			}
-			const rawKey = JSON.stringify([String(rawConfig.tsconfig ?? ""), rawConfig.compilerOptions ?? null]);
-			let scopeOptions = resolvedByRawConfig.get(rawKey);
-			if (scopeOptions === void 0) {
-				scopeOptions = yield* Effect.promise(() => resolveTypeScriptConfig(projectRoot, rawConfig));
-				resolvedByRawConfig.set(rawKey, scopeOptions);
-			}
-			environments.registerEnvironment({
-				vfs: combinedVfs,
-				compilerOptions: scopeOptions,
-				typesCache: twoslashCache
-			});
-			environments.registerScope(apiScope, scopeOptions);
-		}
-		yield* emit(PluginEvent.TwoslashInitialized({
-			ctx: {},
-			level: "debug",
-			durationMs: Math.round(performance.now() - twoslashStartMs),
-			vfsFileCount: combinedVfs.size
-		}));
 		return apiConfigs;
 	}) };
-}));
+});
 /** The raw TypeScript config an API declares, or undefined when it declares none. */
 function rawTsConfig(api) {
 	if (api.tsconfig == null && api.compilerOptions == null) return void 0;
@@ -503,4 +443,4 @@ function rawTsConfig(api) {
 }
 
 //#endregion
-export { ConfigServiceLive };
+export { makeConfigService };

package/layers/external-types.js

@@ -0,0 +1,74 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { Effect } from "effect";
+
+//#region src/layers/external-types.ts
+/**
+* Merging external package declarations into the build's VFS.
+*
+* @remarks
+* The one phase of config resolution that **degrades rather than fails**.
+* External types are an enhancement: without them, code blocks render without
+* Twoslash enrichment, which is a worse page rather than a broken build. The
+* caller therefore never sees this fail — the failure is reported as a warning
+* and the VFS is left as it was.
+*
+* @packageDocumentation
+*/
+/**
+* Fetch external package declarations and merge them into `combinedVfs`.
+*
+* @remarks
+* **First-party packages are excluded, and that exclusion is load-bearing.**
+* The packages being documented are already served from their api.json-derived
+* virtual VFS, which is authoritative. Their published version may not exist
+* yet (an optimistic next version), and if it did, fetching it would clobber
+* the generated declarations with the previous release's — silently
+* documenting the wrong API.
+*
+* Versions are resolved to exact published ones first: the CDN behind
+* `loadPackages` 404s on a range or an unpublished package, so a spec that
+* cannot be resolved is dropped with a debug event rather than failing the
+* batch it is in.
+*
+* Mutates `combinedVfs` in place, matching the other resolution phases.
+*
+* The registry arrives as an argument rather than being pulled from context.
+* `ConfigService.layer` resolves it ONCE at layer construction, and yielding
+* the tag here instead would move it into `resolve`'s per-call requirement
+* channel — a different resolution point, and a widened public signature, for
+* a dependency that does not vary per call.
+*/
+const mergeExternalTypes = (typeRegistry, combinedVfs, apiConfigs, allExternalPackages) => Effect.gen(function* () {
+	const documentedPackageNames = new Set(apiConfigs.map((config) => config.packageName));
+	const externalPackagesToLoad = allExternalPackages.filter((pkg) => !documentedPackageNames.has(pkg.name));
+	const typeLoadResult = yield* Effect.result(Effect.gen(function* () {
+		if (externalPackagesToLoad.length === 0) return;
+		const resolvedPackages = yield* typeRegistry.resolveVersions(externalPackagesToLoad);
+		const droppedCount = externalPackagesToLoad.length - resolvedPackages.length;
+		if (droppedCount > 0) yield* emit(PluginEvent.ExternalPackageSkipped({
+			ctx: {},
+			level: "debug",
+			reason: `${droppedCount} unresolvable package(s) (unpublished or workspace-only)`
+		}));
+		if (resolvedPackages.length === 0) return;
+		const result = yield* typeRegistry.loadPackages(resolvedPackages);
+		for (const [filePath, content] of result.vfs.entries()) combinedVfs.set(filePath, content);
+		yield* emit(PluginEvent.VfsMerged({
+			ctx: {},
+			level: "debug",
+			totalFiles: result.vfs.size,
+			packages: resolvedPackages.map((p) => p.name)
+		}));
+	}));
+	if (typeLoadResult._tag === "Failure") yield* emit(PluginEvent.ConfigCascadeWarning({
+		ctx: {},
+		level: "warn",
+		field: "externalTypes",
+		chosen: "empty VFS",
+		ignored: [typeLoadResult.failure.message ?? String(typeLoadResult.failure)]
+	}));
+});
+
+//#endregion
+export { mergeExternalTypes };

package/layers/{ObservabilityLive.js → observability.js}

@@ -1,6 +1,6 @@
+import { BuildMetrics, makeMetricStore } from "./build-metrics.js";
 import { makeEventBusLayer } from "../observability/EventBus.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";
@@ -8,7 +8,7 @@ import { makeRenderSink } from "../observability/sinks/render-sink.js";
 import { makeTraceSink } from "../observability/sinks/trace-sink.js";
 import { Effect, Layer, Logger, Metric, References } from "effect";
 
-//#region src/layers/ObservabilityLive.ts
+//#region src/layers/observability.ts
 function formatTime(date) {
 	return date.toTimeString().slice(0, 8);
 }
@@ -117,4 +117,4 @@ const logBuildSummary = (slowCodeBlockMs, renderPhase) => Effect.gen(function* (
 });
 
 //#endregion
-export { BuildMetrics, buildEventBus, logBuildSummary, makeSummaryLoggerLayer };
+export { buildEventBus, logBuildSummary, makeSummaryLoggerLayer };

package/layers/type-environment.js

@@ -0,0 +1,109 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { resolveTypeScriptConfig } from "../typescript-config.js";
+import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
+import { ConfigValidationError } from "../errors.js";
+import { twoslashEnvHash } from "../twoslash-cache.js";
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
+import { Effect } from "effect";
+import ts from "typescript";
+
+//#region src/layers/type-environment.ts
+/**
+* Building the build's Twoslash type-checking environments.
+*
+* @remarks
+* The last phase of config resolution, and the only one that has to run after
+* every API has contributed to the VFS: the result cache is keyed on the type
+* environment, so it can only be opened once the VFS is final, and no code
+* block may be rendered before it is.
+*
+* @packageDocumentation
+*/
+/**
+* Resolve a TypeScript configuration, failing typed on a malformed one.
+*
+* @remarks
+* `resolveTypeScriptConfig` throws a `TsConfigParseError` for a missing file, a
+* syntax error or a semantically invalid config. Both call sites used to run it
+* inside `Effect.promise`, so all three became untyped defects: the build died
+* with an unhandled rejection naming a file the user could fix, and wrote no
+* `issues.json` entry for it.
+*
+* A malformed tsconfig is a user misconfiguration, so it is fatal and TYPED —
+* not degraded. Falling back to default compiler options would type-check every
+* example against a configuration the user did not ask for and silently render
+* wrong hovers, which is the failure shape this subsystem suffers from most
+* (see the `lib`-spelling defect in `type-loading-vfs.md`).
+*/
+const resolveTsConfigTyped = (projectRoot, config) => Effect.tryPromise({
+	try: () => resolveTypeScriptConfig(projectRoot, config),
+	catch: (cause) => new ConfigValidationError({
+		field: "tsconfig",
+		reason: cause instanceof Error ? cause.message : String(cause),
+		cause
+	})
+});
+/**
+* Open the Twoslash result cache and register one environment per distinct
+* compiler configuration.
+*
+* @remarks
+* **The build-wide options are registered FIRST, deliberately.** An unknown
+* scope falls back to the first environment registered, and a `with-api` fence
+* can appear on a page outside any documented package's route — checking it
+* under the build-wide configuration beats not checking it at all.
+*
+* Resolution is memoised twice over. This function memoises by RAW config, so
+* N APIs sharing a tsconfig read it from disk once; `registerEnvironment` then
+* dedupes by a fingerprint of the ENCODED options, so APIs that spell the same
+* configuration differently still share one TypeScript environment. The second
+* of those is load-bearing: when the two fingerprints drifted apart once, every
+* scope lookup missed, per-scope type-checking silently degraded to build-wide,
+* and a 994-test suite stayed green through it.
+*/
+const registerTypeEnvironments = (input) => Effect.gen(function* () {
+	const twoslashEnv = twoslashEnvHash(input.combinedVfs, `typescript@${ts.version}`);
+	const twoslashCache = yield* (yield* TwoslashCacheService).open(twoslashEnv);
+	yield* emit(PluginEvent.TwoslashCacheLoaded({
+		ctx: {},
+		level: "debug",
+		envHash: twoslashEnv,
+		entries: twoslashCache.entries().size
+	}));
+	const twoslashStartMs = performance.now();
+	const environments = yield* TwoslashEnvironments;
+	environments.registerEnvironment({
+		vfs: input.combinedVfs,
+		compilerOptions: input.resolvedCompilerOptions,
+		typesCache: twoslashCache
+	});
+	const resolvedByRawConfig = /* @__PURE__ */ new Map();
+	for (const [apiScope, rawConfig] of input.scopeTsConfigs) {
+		if (rawConfig === void 0) {
+			environments.registerScope(apiScope, input.resolvedCompilerOptions);
+			continue;
+		}
+		const rawKey = JSON.stringify([String(rawConfig.tsconfig ?? ""), rawConfig.compilerOptions ?? null]);
+		let scopeOptions = resolvedByRawConfig.get(rawKey);
+		if (scopeOptions === void 0) {
+			scopeOptions = yield* resolveTsConfigTyped(input.projectRoot, rawConfig);
+			resolvedByRawConfig.set(rawKey, scopeOptions);
+		}
+		environments.registerEnvironment({
+			vfs: input.combinedVfs,
+			compilerOptions: scopeOptions,
+			typesCache: twoslashCache
+		});
+		environments.registerScope(apiScope, scopeOptions);
+	}
+	yield* emit(PluginEvent.TwoslashInitialized({
+		ctx: {},
+		level: "debug",
+		durationMs: Math.round(performance.now() - twoslashStartMs),
+		vfsFileCount: input.combinedVfs.size
+	}));
+});
+
+//#endregion
+export { registerTypeEnvironments, resolveTsConfigTyped };

package/layers/xdg.js

@@ -1,5 +1,5 @@
-import { NodeFileSystem } from "@effect/platform-node";
 import { Layer, Path } from "effect";
+import { NodeFileSystem } from "@effect/platform-node";
 import { AppDirs, Xdg } from "@effected/xdg";
 
 //#region src/layers/xdg.ts