rspress-plugin-api-extractor 0.10.0 → 0.12.0

package/layers/AppLayer.js

@@ -0,0 +1,67 @@
+import { BuildId, PageConcurrency, SuppressExampleErrors, Thresholds } from "../BuildEnv.js";
+import { OgService } from "../services/OgService.js";
+import { collectShikiThemes } from "../markdown/shiki-utils.js";
+import { HighlighterService } from "../services/HighlighterService.js";
+import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
+import { PluginConfig } from "../services/PluginConfig.js";
+import { PlatformLive } from "./xdg.js";
+import { TypeRegistryService } from "../services/TypeRegistryService.js";
+import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
+import { ConfigService } from "../services/ConfigService.js";
+import { makeSummaryLoggerLayer } from "./observability.js";
+import { Layer } from "effect";
+import { SnapshotService } from "@tsdoctor/snapshot";
+import { NodeFileSystem } from "@effect/platform-node";
+
+//#region src/layers/AppLayer.ts
+/**
+* The build's layer stack, tiered.
+*
+* @remarks
+* `plugin.ts` used to merge eleven layers side by side in one `Layer.mergeAll`
+* — `NodeFileSystem.layer` (platform) next to `TypeRegistryService.layer`
+* (domain) next to `makeSummaryLoggerLayer` (observability) — with one of them
+* carrying a local `Layer.provide` because a flat merge could not feed it its
+* dependencies. Reading that told you what the build contains but not what
+* depends on what.
+*
+* The tiers below are ordered by what they may reach: platform knows nothing
+* about this plugin, core services know the platform, and build-scoped services
+* know both.
+*
+* @packageDocumentation
+*/
+/**
+* Build both stacks for one build.
+*
+* @remarks
+* **A layer factory: call it once and bind the result to a `const`.** Layers
+* memoize by reference, so a second call mints a second stack — a second Shiki
+* highlighter, a second snapshot database, a second metric registry.
+*/
+function makeAppLayers(input) {
+	/**
+	* Per-build configuration, provided to BOTH stacks. Sharing these values is
+	* what lets a sync island and an Effect program agree on the build id and
+	* the slow-block threshold without either being handed them.
+	*/
+	const BuildEnvLayer = Layer.mergeAll(Layer.succeed(BuildId, input.buildId), Layer.succeed(Thresholds, input.obs.thresholds), Layer.succeed(PageConcurrency, input.pageConcurrency), Layer.succeed(SuppressExampleErrors, input.options.errors?.example !== "show"));
+	/**
+	* Sinks, metrics and the logger gate. Synchronously buildable, which is what
+	* lets the emitter stack below reuse it wholesale.
+	*/
+	const ObservabilityLayer = Layer.mergeAll(input.eventBus, input.metrics.layer, makeSummaryLoggerLayer(input.obs.logLevel));
+	/** Services that own a resource and need only the platform to build. */
+	const CoreLayer = Layer.mergeAll(TypeRegistryService.layer, TwoslashCacheService.layer, SnapshotService.layer(input.dbPath), Layer.provide(OgService.layer, PlatformLive));
+	/** Bound to a `const`: this is a factory, and a second call acquires a second highlighter. */
+	const HighlighterLive = HighlighterService.layer(collectShikiThemes(input.options.api ? [input.options.api] : input.options.apis ?? []));
+	/** Services scoped to this build's configuration. */
+	const BuildLayer = Layer.mergeAll(Layer.succeed(PluginConfig, input.options), HighlighterLive, TwoslashEnvironments.layer, BuildEnvLayer);
+	return {
+		app: Layer.provideMerge(ConfigService.layer, Layer.mergeAll(BuildLayer, CoreLayer, ObservabilityLayer, NodeFileSystem.layer)),
+		emitter: Layer.mergeAll(ObservabilityLayer, BuildEnvLayer)
+	};
+}
+
+//#endregion
+export { makeAppLayers };

package/layers/api-results.js

@@ -0,0 +1,83 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { Effect } from "effect";
+
+//#region src/layers/api-results.ts
+/**
+* Accumulating one API's resolution result into the build-wide totals.
+*
+* @remarks
+* `ConfigService.layer` resolves APIs down three paths — versioned, single
+* non-versioned, and multi-API — and each one ended with a near-identical
+* ~35-line block that merged the same three accumulators and then emitted the
+* same two events per VFS entry. Three copies of one algorithm is three places
+* for it to drift, and the third copy had ALREADY drifted: it emits its events
+* inside the per-API effect and merges afterwards, rather than doing both in
+* one pass.
+*
+* Splitting the block in two is what makes all three paths expressible. The
+* merge is pure and the emission is effectful, and the multi-API path needs
+* them at different moments; a single combined helper would have fitted two
+* paths and forced the third to keep its own copy.
+*
+* @packageDocumentation
+*/
+/**
+* Merge one result into the build-wide accumulators.
+*
+* @remarks
+* Mutates `acc` rather than returning a new one. The accumulators are three
+* `const` collections in a long generator that appends to them from several
+* branches, and threading a replacement through every branch would be a larger
+* change than this task is buying.
+*
+* **The VFS is a single flat namespace shared by every documented API.** A
+* later entry silently overwrites an earlier one at the same path, which is
+* load-bearing rather than accidental: cross-package type references resolve
+* only because every package's declarations live in one environment (see
+* `type-loading-vfs.md`).
+*/
+function mergeApiResult(acc, result) {
+	for (const [filepath, content] of result.vfs.entries()) acc.combinedVfs.set(filepath, content);
+	if (result.externalPackages.length > 0) acc.allExternalPackages.push(...result.externalPackages);
+	if (result.config) acc.apiConfigs.push(result.config);
+}
+/**
+* Emit the per-entry VFS events for one API's payloads.
+*
+* @remarks
+* `ImportsPrepended` fires only when imports were actually prepended, so an
+* entry that needed none produces one event rather than two.
+*
+* `wantTrace` gates the two heavy fields — the full declaration text and the
+* resolved import refs. Both are only ever read by the JSONL trace sink, and
+* carrying them unconditionally would put every generated declaration file
+* through the event bus on every build.
+*/
+function emitVfsPayloadEvents(packageName, payloads, wantTrace) {
+	return Effect.gen(function* () {
+		for (const payload of payloads) {
+			const ctx = {
+				packageName,
+				...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+			};
+			yield* emit(PluginEvent.VfsGenerated({
+				ctx,
+				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,
+				level: "debug",
+				file: payload.file,
+				imports: wantTrace ? payload.importRefs : []
+			}));
+		}
+	});
+}
+
+//#endregion
+export { emitVfsPayloadEvents, mergeApiResult };

package/layers/build-metrics.js

@@ -18,7 +18,7 @@ function makeMetricStore() {
 * 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`
+* without creating a circular dependency through `observability.ts`
 * (which itself imports `metrics-sink.ts`).
 */
 const BuildMetrics = {

package/layers/config-resolution.js

@@ -0,0 +1,407 @@
+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 { TypeReferenceExtractor } from "../type-reference-extractor.js";
+import { deriveSiteUrl } from "../og-resolver.js";
+import { withPhase } from "../observability/spans.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 { loadApiModel, loadPackageJson, loadVersionModel } from "../model-loader.js";
+import { DEFAULT_CATEGORIES } from "../schemas/config.js";
+import { PluginConfig } from "../services/PluginConfig.js";
+import { TypeRegistryService } from "../services/TypeRegistryService.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";
+
+//#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).
+*/
+function prependImportsToVfs(vfs, apiPackage, packageName, wantTrace) {
+	const extractor = new TypeReferenceExtractor(apiPackage, packageName);
+	const payloads = [];
+	for (const entryPoint of apiPackage.entryPoints) {
+		const entryEp = entryPoint;
+		const imports = extractor.extractImportsForEntryPoint(entryEp);
+		const importStatements = TypeReferenceExtractor.formatImports(imports);
+		const entryName = entryEp.displayName || "";
+		const file = `node_modules/${packageName}/${entryName ? `${entryName}.d.ts` : "index.d.ts"}`;
+		const hasImports = importStatements.length > 0;
+		if (hasImports) {
+			const existing = vfs.get(file);
+			if (existing) vfs.set(file, `${importStatements.join("\n")}\n\n${existing}`);
+		}
+		const content = vfs.get(file) ?? "";
+		const declCount = entryEp.members.length;
+		const contentHash = hashContent(content);
+		const importRefs = wantTrace && hasImports ? imports.map((i) => ({
+			from: i.packageName,
+			symbols: [...i.symbols]
+		})) : [];
+		payloads.push({
+			file,
+			entryPoint: entryName,
+			declCount,
+			contentHash,
+			content: wantTrace ? content : "",
+			hasImports,
+			importRefs
+		});
+	}
+	return payloads;
+}
+/**
+* Validate plugin options and return an Effect that fails with ConfigValidationError.
+*/
+function validateOptions(options, rspressConfig) {
+	return Effect.gen(function* () {
+		const api = options.api ?? void 0;
+		const apis = options.apis != null && options.apis.length > 0 ? options.apis : void 0;
+		const { multiVersion } = rspressConfig;
+		if (api && apis) return yield* new ConfigValidationError({
+			field: "api/apis",
+			reason: "Cannot provide both 'api' and 'apis'. Use 'api' for single-package sites or 'apis' for multi-package portals."
+		});
+		if (!api && !apis) {
+			if (classifyApiConfig(options) === "missing") return yield* new ConfigValidationError({
+				field: "api/apis",
+				reason: "Must provide either 'api' or 'apis'."
+			});
+			return;
+		}
+		if (apis) {
+			if (multiVersion) return yield* new ConfigValidationError({
+				field: "apis",
+				reason: "multiVersion is not supported with 'apis' (multi-API mode). Use 'api' (single-API mode) for versioned documentation."
+			});
+			return;
+		}
+		if (api) {
+			if (multiVersion) {
+				if (!api.versions) return yield* new ConfigValidationError({
+					field: "api.versions",
+					reason: "'versions' is required when multiVersion is active."
+				});
+				const pluginKeys = new Set(Object.keys(api.versions));
+				const rspressKeys = new Set(multiVersion.versions);
+				if (pluginKeys.size !== rspressKeys.size || ![...pluginKeys].every((k) => rspressKeys.has(k))) return yield* new ConfigValidationError({
+					field: "api.versions",
+					reason: `api.versions keys [${[...pluginKeys].join(", ")}] must exactly match multiVersion.versions [${[...rspressKeys].join(", ")}].`
+				});
+			} else {
+				if (api.versions) yield* emit(PluginEvent.ConfigCascadeWarning({
+					ctx: {},
+					level: "warn",
+					field: "versions",
+					chosen: "(none — multiVersion not configured)",
+					ignored: ["api.versions"]
+				}));
+				if (!api.model) return yield* new ConfigValidationError({
+					field: "api.model",
+					reason: "'model' is required when multiVersion is not active."
+				});
+			}
+		}
+	});
+}
+/**
+* Resolve plugin options + RSPress config into the API configs the pipeline
+* runs over.
+*
+* @remarks
+* A module-level `const`, not a factory. It took the plugin options as an
+* argument and was called inline at the merge site, which made it a
+* layer-returning function: layers memoize by reference, so a second call
+* 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 makeConfigService = Effect.gen(function* () {
+	const typeRegistry = yield* TypeRegistryService;
+	const options = yield* PluginConfig;
+	return { resolve: (rspressConfig) => Effect.gen(function* () {
+		const buildId = yield* BuildId;
+		const loadStart = performance.now();
+		const wantTrace = yield* wantsLevel("trace");
+		yield* validateOptions(options, { ...rspressConfig.multiVersion ? { multiVersion: {
+			default: rspressConfig.multiVersion.default,
+			versions: [...rspressConfig.multiVersion.versions]
+		} } : {} });
+		const rspressMultiVersion = rspressConfig.multiVersion;
+		const rspressLocales = rspressConfig.locales?.map((l) => l.lang) ?? [];
+		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;
+		/**
+		* Raw TypeScript config per API scope. Each documented package is
+		* type-checked under its OWN configuration; the build no longer picks
+		* one and applies it to everything.
+		*/
+		const scopeTsConfigs = /* @__PURE__ */ new Map();
+		/**
+		* Emit a typed ModelLoadFailed event for a failed model load, then
+		* convert the typed failure to a defect — a missing or unparsable
+		* model remains fatal to the build, exactly as before, but the
+		* event now rides the error channel instead of a sync-island seam.
+		*/
+		const withModelLoadEvents = (self) => self.pipe(Effect.tapError((error) => emit(PluginEvent.ModelLoadFailed({
+			ctx: { buildId },
+			level: "error",
+			modelPath: "modelPath" in error ? error.modelPath : "<loader function>",
+			reason: error.message
+		}))), Effect.orDie);
+		/**
+		* Helper to process a single API model (shared by single and multi modes).
+		*/
+		const processSimpleApi = (api, model, outputDir, fullRoute, wantTrace) => Effect.gen(function* () {
+			const { apiPackage, source: loaderSource } = yield* withModelLoadEvents(loadApiModel(model));
+			{
+				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 ? 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) 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;
+				const resolvedTheme = normalizeThemeConfig(api.theme);
+				return {
+					vfs,
+					vfsPayloads,
+					externalPackages: externalPackages || [],
+					config: {
+						apiPackage,
+						packageName: api.packageName,
+						...api.name != null ? { apiName: api.name } : {},
+						outputDir,
+						baseRoute: fullRoute,
+						categories: resolvedCategories,
+						...resolvedSource != null ? { source: resolvedSource } : {},
+						...packageJson != null ? { packageJson } : {},
+						...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
+						...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) {
+				const api = options.api;
+				const baseRoute = normalizeBaseRoute(api.baseRoute ?? "/");
+				firstApiTsconfig = api.tsconfig;
+				firstApiCompilerOptions = api.compilerOptions;
+				scopeTsConfigs.set(apiScopeOf(baseRoute, api.packageName), rawTsConfig(api));
+				if (rspressMultiVersion && api.versions) {
+					const versionResults = yield* Effect.forEach(Object.entries(api.versions), ([version, versionValue]) => Effect.gen(function* () {
+						const versionDp = deriveOutputPaths({
+							mode: "single",
+							docsRoot: rspressRoot,
+							baseRoute,
+							apiFolder: api.apiFolder ?? "api",
+							locales: rspressLocales,
+							defaultLang: rspressLang,
+							versions: [version],
+							defaultVersion: rspressMultiVersion?.default
+						})[0];
+						if (!versionDp) return {
+							vfs: /* @__PURE__ */ new Map(),
+							vfsPayloads: [],
+							externalPackages: [],
+							config: null
+						};
+						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));
+						{
+							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 ? 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) 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;
+							const resolvedTheme = normalizeThemeConfig(api.theme);
+							const outputDir = versionDp.outputDir;
+							const fullRoute = versionDp.routeBase;
+							return {
+								vfs,
+								vfsPayloads,
+								externalPackages: externalPackages || [],
+								config: {
+									apiPackage,
+									packageName: `${api.packageName} (${version})`,
+									...api.name != null ? { apiName: api.name } : {},
+									outputDir,
+									baseRoute: fullRoute,
+									categories: resolvedCategories,
+									...resolvedSource != null ? { source: resolvedSource } : {},
+									...packageJson != null ? { packageJson } : {},
+									...resolvedLlms != null ? { llmsPlugin: resolvedLlms } : {},
+									...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) {
+						mergeApiResult(acc, result);
+						yield* emitVfsPayloadEvents(api.packageName, result.vfsPayloads, wantTrace);
+					}
+				} else if (api.model) {
+					const dp = deriveOutputPaths({
+						mode: "single",
+						docsRoot: rspressRoot,
+						baseRoute,
+						apiFolder: api.apiFolder ?? "api",
+						locales: rspressLocales,
+						defaultLang: rspressLang,
+						versions: [],
+						defaultVersion: void 0
+					})[0];
+					if (dp) {
+						const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase, wantTrace);
+						mergeApiResult(acc, result);
+						yield* emitVfsPayloadEvents(api.packageName, result.vfsPayloads, wantTrace);
+					}
+				}
+			} else if (options.apis) {
+				const apisWithTsconfig = options.apis.filter((a) => a.tsconfig);
+				if (apisWithTsconfig.length > 0) firstApiTsconfig = apisWithTsconfig[0].tsconfig;
+				const apisWithCompilerOptions = options.apis.filter((a) => a.compilerOptions);
+				if (apisWithCompilerOptions.length > 0) firstApiCompilerOptions = apisWithCompilerOptions[0].compilerOptions;
+				for (const a of options.apis) {
+					const scopeRoute = normalizeBaseRoute(a.baseRoute ?? `/${unscopedName(a.packageName)}`);
+					scopeTsConfigs.set(apiScopeOf(scopeRoute, a.packageName), rawTsConfig(a));
+				}
+				const multiResults = yield* Effect.forEach(options.apis, (api) => Effect.gen(function* () {
+					const apiBaseRoute = normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
+					const dp = deriveOutputPaths({
+						mode: "multi",
+						docsRoot: rspressRoot,
+						baseRoute: apiBaseRoute,
+						apiFolder: api.apiFolder ?? "api",
+						locales: rspressLocales,
+						defaultLang: rspressLang,
+						versions: [],
+						defaultVersion: void 0
+					})[0];
+					if (!dp) return [];
+					const result = yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase, wantTrace);
+					yield* emitVfsPayloadEvents(api.packageName, result.vfsPayloads, wantTrace);
+					return [result];
+				}), { concurrency: "unbounded" });
+				for (const results of multiResults) for (const result of results) mergeApiResult(acc, result);
+			}
+		}));
+		const loadMs = performance.now() - loadStart;
+		yield* emit(PluginEvent.ModelLoaded({
+			ctx: {},
+			level: "debug",
+			entryPoints: apiConfigs.length,
+			itemCount: apiConfigs.reduce((sum, cfg) => sum + cfg.apiPackage.entryPoints.reduce((s, ep) => s + ep.members.length, 0), 0),
+			durationMs: Math.round(loadMs)
+		}));
+		const projectRoot = process.cwd();
+		let globalTsConfig;
+		if (firstApiTsconfig || firstApiCompilerOptions) {
+			globalTsConfig = {};
+			if (firstApiTsconfig != null) globalTsConfig.tsconfig = firstApiTsconfig;
+			if (firstApiCompilerOptions != null) globalTsConfig.compilerOptions = firstApiCompilerOptions;
+		}
+		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
+		}));
+		yield* mergeExternalTypes(typeRegistry, combinedVfs, apiConfigs, allExternalPackages);
+		yield* registerTypeEnvironments({
+			combinedVfs,
+			resolvedCompilerOptions,
+			scopeTsConfigs,
+			projectRoot
+		});
+		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;
+	const cfg = {};
+	if (api.tsconfig != null) cfg.tsconfig = api.tsconfig;
+	if (api.compilerOptions != null) cfg.compilerOptions = api.compilerOptions;
+	return cfg;
+}
+
+//#endregion
+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 };