rspress-plugin-api-extractor 0.11.0 → 0.12.0

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

@@ -1,32 +1,28 @@
 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 { deriveSiteUrl } from "../og-resolver.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 { hashContent } from "@tsdoctor/snapshot";
-import { Effect, Layer, Metric } from "effect";
-import ts from "typescript";
 
-//#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).
@@ -129,8 +125,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 +146,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 +183,28 @@ 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;
+				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;
@@ -202,14 +223,14 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 						...resolvedSource != null ? { source: resolvedSource } : {},
 						...packageJson != null ? { packageJson } : {},
 						...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 +259,30 @@ 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);
+							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;
@@ -268,41 +303,18 @@ const ConfigServiceLive = Layer.effect(ConfigService, Effect.gen(function* () {
 									...resolvedSource != null ? { source: resolvedSource } : {},
 									...packageJson != null ? { packageJson } : {},
 									...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 +329,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 +356,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 +377,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 +404,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

package/markdown/shiki-utils.js

@@ -60,7 +60,7 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 * Accepts a single theme name applied to both modes, an explicit pair, or a
 * raw theme object. Lives beside {@link DEFAULT_SHIKI_THEMES} because it falls
 * back to it; it was previously duplicated byte-for-byte in `plugin.ts` and
-* `ConfigServiceLive.ts`.
+* `ConfigService.layer.ts`.
 */
 function normalizeThemeConfig(theme) {
 	if (!theme) return { ...DEFAULT_SHIKI_THEMES };

package/model-loader.js

@@ -1,5 +1,5 @@
 import { isLoadedModel, isVersionConfig } from "./config-utils.js";
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 import { Effect } from "effect";
 import { Model } from "@tsdoctor/model";
@@ -10,8 +10,8 @@ import { Model } from "@tsdoctor/model";
 */
 async function loadPackageJsonFromPath(pkgPath) {
 	const resolvedPath = path.resolve(pkgPath.toString());
-	if (!fs.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
-	const content = fs.readFileSync(resolvedPath, "utf-8");
+	if (!fsSync.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
+	const content = fsSync.readFileSync(resolvedPath, "utf-8");
 	try {
 		return JSON.parse(content);
 	} catch (error) {

package/observability/EventBus.js

@@ -23,9 +23,9 @@ function makeEventBusLayer(sinks) {
 * @remarks
 * Fills `ctx.buildId` from the {@link BuildId} Reference when the caller left
 * it empty, which is why no emit site passes one. Before this, 24 sites wrote
-* `ctx: { buildId: "" }` — 22 in `ConfigServiceLive`, where the real value sat
+* `ctx: { buildId: "" }` — 22 in `ConfigService.layer`, where the real value sat
 * three scopes up and was simply not reached, and every site in
-* `TypeRegistryServiceLive`, where the layer is module-level and there is no
+* `TypeRegistryService.layer`, where the layer is module-level and there is no
 * build to name. The second group is why a Reference is the fix and a
 * find-and-replace is not: a Reference reaches code that no parameter can.
 *

package/observability/heartbeat.js

@@ -1,6 +1,6 @@
+import { BuildMetrics } from "../layers/build-metrics.js";
 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

package/observability/sinks/metrics-sink.js

@@ -18,7 +18,7 @@ import { Metric } from "effect";
 * 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
+* remain inline increments in `ConfigService.layer`. `externalPackagesTotal` counts
 * CONFIGURED packages via `incrementBy(length)`; the only candidate event,
 * `TypeRegistryEvent{BatchComplete}`, carries an unstructured `detail` string and
 * a `loaded` (SUCCEEDED) count — different semantics, so deriving it here would