rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/layers/ConfigServiceLive.js

@@ -0,0 +1,377 @@
+import { BuildMetrics } from "./ObservabilityLive.js";
+import { TypeReferenceExtractor } from "../type-reference-extractor.js";
+import { OpenGraphResolver } from "../og-resolver.js";
+import { resolveTypeScriptConfig } from "../typescript-config.js";
+import { TwoslashManager } from "../twoslash-transformer.js";
+import { 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 { HideCutLinesTransformer, MemberFormatTransformer } from "../hide-cut-transformer.js";
+import { DEFAULT_SHIKI_THEMES } from "../markdown/shiki-utils.js";
+import { ApiModelLoader } from "../model-loader.js";
+import { DEFAULT_CATEGORIES } from "../schemas/config.js";
+import "../schemas/index.js";
+import { ConfigService } from "../services/ConfigService.js";
+import { PathDerivationService } from "../services/PathDerivationService.js";
+import { TypeRegistryService } from "../services/TypeRegistryService.js";
+import path from "node:path";
+import { Effect, Layer, Metric } from "effect";
+import os from "node:os";
+import { createHighlighter } from "shiki";
+
+//#region src/layers/ConfigServiceLive.ts
+/**
+* Normalize theme configuration from user input to a consistent format.
+*/
+function normalizeThemeConfig(theme) {
+	if (!theme) return { ...DEFAULT_SHIKI_THEMES };
+	if (typeof theme === "string") return {
+		light: theme,
+		dark: theme
+	};
+	if ("light" in theme && "dark" in theme && typeof theme.light === "string" && typeof theme.dark === "string") return {
+		light: theme.light,
+		dark: theme.dark
+	};
+	return {
+		light: theme,
+		dark: theme
+	};
+}
+/**
+* Prepend import statements for external type references to the VFS declaration files.
+*/
+function prependImportsToVfs(vfs, apiPackage, packageName) {
+	const extractor = new TypeReferenceExtractor(apiPackage, packageName);
+	for (const entryPoint of apiPackage.entryPoints) {
+		const imports = extractor.extractImportsForEntryPoint(entryPoint);
+		const importStatements = TypeReferenceExtractor.formatImports(imports);
+		if (importStatements.length === 0) continue;
+		const entryName = entryPoint.displayName || "";
+		const key = `node_modules/${packageName}/${entryName ? `${entryName}.d.ts` : "index.d.ts"}`;
+		const existing = vfs.get(key);
+		if (existing) vfs.set(key, `${importStatements.join("\n")}\n\n${existing}`);
+	}
+}
+/**
+* Validate plugin options and return an Effect that fails with ConfigValidationError.
+*/
+function validateOptions(options, rspressConfig) {
+	return Effect.gen(function* () {
+		const { api, apis } = options;
+		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) return yield* new ConfigValidationError({
+			field: "api/apis",
+			reason: "Must provide either 'api' or 'apis'."
+		});
+		if (apis) {
+			if (apis.length === 0) return yield* new ConfigValidationError({
+				field: "apis",
+				reason: "'apis' must contain at least one API configuration."
+			});
+			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* Effect.logWarning("api.versions is provided but RSPress multiVersion is not configured. Versions will be ignored.");
+			if (!api.model) return yield* new ConfigValidationError({
+				field: "api.model",
+				reason: "'model' is required when multiVersion is not active."
+			});
+		}
+	});
+}
+/**
+* Create ConfigServiceLive from plugin options.
+* Resolves plugin options + RSPress config into a fully prepared build context
+* with loaded models, type system, and resources.
+*/
+function ConfigServiceLive(options, shikiCrossLinker) {
+	return Layer.effect(ConfigService, Effect.gen(function* () {
+		const typeRegistry = yield* TypeRegistryService;
+		const pathService = yield* PathDerivationService;
+		return { resolve: (rspressConfig) => Effect.gen(function* () {
+			const loadStart = performance.now();
+			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 categoryResolver = new CategoryResolver();
+			const pluginDefaults = categoryResolver.mergeCategories(DEFAULT_CATEGORIES, options.defaultCategories);
+			const apiConfigs = [];
+			const combinedVfs = /* @__PURE__ */ new Map();
+			const allExternalPackages = [];
+			let firstApiTsconfig;
+			let firstApiCompilerOptions;
+			/**
+			* Helper to process a single API model (shared by single and multi modes).
+			*/
+			const processSimpleApi = (api, model, outputDir, fullRoute) => Effect.promise(async () => {
+				const { apiPackage, source: loaderSource } = await ApiModelLoader.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 ? await ApiModelLoader.loadPackageJson(api.packageJson) : void 0;
+				validateExternalPackages(api.externalPackages, packageJson);
+				const externalPackages = api.externalPackages || extractAutoDetectedPackages(packageJson, api.autoDetectDependencies);
+				if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.incrementBy(BuildMetrics.externalPackagesTotal, externalPackages.length));
+				const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
+				prependImportsToVfs(vfs, apiPackage, api.packageName);
+				const resolvedOgImage = api.ogImage ?? options.ogImage;
+				const resolvedTheme = normalizeThemeConfig(api.theme);
+				return {
+					vfs,
+					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 } : {},
+						...options.siteUrl != null ? { siteUrl: options.siteUrl } : {},
+						...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
+						docsDir: path.dirname(outputDir),
+						...docsRoot != null ? { docsRoot } : {},
+						...resolvedTheme != null ? { theme: resolvedTheme } : {}
+					}
+				};
+			});
+			if (options.api) {
+				const api = options.api;
+				const baseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? "/");
+				firstApiTsconfig = api.tsconfig;
+				firstApiCompilerOptions = api.compilerOptions;
+				if (rspressMultiVersion && api.versions) {
+					const versionResults = yield* Effect.forEach(Object.entries(api.versions), ([version, versionValue]) => Effect.gen(function* () {
+						const versionDp = (yield* pathService.derivePaths({
+							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(),
+							externalPackages: [],
+							config: null
+						};
+						return yield* Effect.promise(async () => {
+							const versionConfig = isVersionConfig(versionValue) ? versionValue : { model: versionValue };
+							const { apiPackage, packageJson: versionPackageJson, categories: versionCategories, source: versionSource, externalPackages: versionExternalPackages, autoDetectDependencies: versionAutoDetectDependencies, llmsPlugin: versionLlms, ogImage: versionOgImage } = await ApiModelLoader.loadVersionModel(versionConfig);
+							Effect.runSync(Metric.increment(BuildMetrics.apiVersionsLoaded));
+							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 ApiModelLoader.loadPackageJson(api.packageJson) : void 0);
+							validateExternalPackages(versionExternalPackages || api.externalPackages, packageJson);
+							const autoDetectOptions = versionAutoDetectDependencies || api.autoDetectDependencies;
+							const externalPackages = versionExternalPackages || api.externalPackages || extractAutoDetectedPackages(packageJson, autoDetectOptions);
+							if (externalPackages && externalPackages.length > 0) Effect.runSync(Metric.incrementBy(BuildMetrics.externalPackagesTotal, externalPackages.length));
+							const vfs = ApiExtractedPackage.fromPackage(apiPackage, api.packageName).generateVfs();
+							prependImportsToVfs(vfs, apiPackage, api.packageName);
+							const resolvedOgImage = versionOgImage ?? api.ogImage ?? options.ogImage;
+							const resolvedTheme = normalizeThemeConfig(api.theme);
+							const outputDir = versionDp.outputDir;
+							const fullRoute = versionDp.routeBase;
+							return {
+								vfs,
+								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 } : {},
+									...options.siteUrl != null ? { siteUrl: options.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);
+					}
+				} else if (api.model) {
+					const dp = (yield* pathService.derivePaths({
+						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);
+						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);
+					}
+				}
+			} else if (options.apis) {
+				const apisWithTsconfig = options.apis.filter((a) => a.tsconfig);
+				if (apisWithTsconfig.length > 0) {
+					firstApiTsconfig = apisWithTsconfig[0].tsconfig;
+					const uniqueTsconfigs = new Set(apisWithTsconfig.map((a) => String(a.tsconfig)));
+					if (uniqueTsconfigs.size > 1) yield* Effect.logWarning(`Multiple APIs specify different tsconfig values: ${[...uniqueTsconfigs].join(", ")}. Using '${String(firstApiTsconfig)}' for TypeScript resolution. Per-API tsconfig resolution will be supported in a future release.`);
+				}
+				const apisWithCompilerOptions = options.apis.filter((a) => a.compilerOptions);
+				if (apisWithCompilerOptions.length > 0) firstApiCompilerOptions = apisWithCompilerOptions[0].compilerOptions;
+				const multiResults = yield* Effect.forEach(options.apis, (api) => Effect.gen(function* () {
+					const apiBaseRoute = yield* pathService.normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`);
+					const dp = (yield* pathService.derivePaths({
+						mode: "multi",
+						docsRoot: rspressRoot,
+						baseRoute: apiBaseRoute,
+						apiFolder: api.apiFolder ?? "api",
+						locales: rspressLocales,
+						defaultLang: rspressLang,
+						versions: [],
+						defaultVersion: void 0
+					}))[0];
+					if (!dp) return [];
+					return [yield* processSimpleApi(api, api.model, dp.outputDir, dp.routeBase)];
+				}), { 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);
+				}
+			}
+			const loadMs = performance.now() - loadStart;
+			yield* Effect.logDebug(`Loading API models: ${loadMs.toFixed(0)}ms`);
+			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* Effect.promise(() => resolveTypeScriptConfig(projectRoot, globalTsConfig));
+			yield* Effect.logDebug(`Resolved TypeScript config: target=${resolvedCompilerOptions.target}, module=${resolvedCompilerOptions.module}, lib=[${resolvedCompilerOptions.lib?.join(", ")}]`);
+			let tsEnvCache = /* @__PURE__ */ new Map();
+			const typeLoadResult = yield* Effect.either(Effect.gen(function* () {
+				if (allExternalPackages.length > 0) {
+					const typesStart = performance.now();
+					const result = yield* typeRegistry.loadPackages(allExternalPackages);
+					const cache = yield* typeRegistry.createTypeScriptCache(allExternalPackages, resolvedCompilerOptions);
+					for (const [filePath, content] of result.vfs.entries()) combinedVfs.set(filePath, content);
+					yield* Effect.logDebug(`Loading external package types: ${(performance.now() - typesStart).toFixed(0)}ms`);
+					return cache;
+				}
+				return yield* typeRegistry.createTypeScriptCache([], resolvedCompilerOptions);
+			}));
+			if (typeLoadResult._tag === "Right") tsEnvCache = typeLoadResult.right;
+			else {
+				yield* Effect.logWarning(`Failed to load external types: ${typeLoadResult.left.message}. Continuing with empty VFS.`);
+				const fallbackCache = yield* Effect.either(typeRegistry.createTypeScriptCache([], resolvedCompilerOptions));
+				if (fallbackCache._tag === "Right") tsEnvCache = fallbackCache.right;
+			}
+			const twoslashStartMs = performance.now();
+			TwoslashManager.getInstance().initialize(combinedVfs, void 0, void 0, tsEnvCache, resolvedCompilerOptions);
+			yield* Effect.logDebug(`Initializing Twoslash: ${(performance.now() - twoslashStartMs).toFixed(0)}ms`);
+			const shikiStartMs = performance.now();
+			const themeSet = /* @__PURE__ */ new Set();
+			const customThemes = [];
+			for (const config of apiConfigs) {
+				const theme = config.theme ?? {
+					light: DEFAULT_SHIKI_THEMES.light,
+					dark: DEFAULT_SHIKI_THEMES.dark
+				};
+				if (typeof theme.light === "string") themeSet.add(theme.light);
+				else if (typeof theme.light === "object") customThemes.push(theme.light);
+				if (typeof theme.dark === "string") themeSet.add(theme.dark);
+				else if (typeof theme.dark === "object") customThemes.push(theme.dark);
+			}
+			if (typeof DEFAULT_SHIKI_THEMES.light === "string") themeSet.add(DEFAULT_SHIKI_THEMES.light);
+			if (typeof DEFAULT_SHIKI_THEMES.dark === "string") themeSet.add(DEFAULT_SHIKI_THEMES.dark);
+			const themes = [...themeSet, ...customThemes];
+			const langs = [
+				"typescript",
+				"javascript",
+				"json",
+				"bash",
+				"sh"
+			];
+			const highlighter = yield* Effect.promise(() => createHighlighter({
+				themes,
+				langs
+			}));
+			yield* Effect.logDebug(`Initializing Shiki highlighter: ${(performance.now() - shikiStartMs).toFixed(0)}ms`);
+			const ogResolver = options.siteUrl ? new OpenGraphResolver({
+				siteUrl: options.siteUrl,
+				...docsRoot != null ? { docsRoot } : {}
+			}) : null;
+			const hideCutTransformer = MemberFormatTransformer;
+			const hideCutLinesTransformer = HideCutLinesTransformer;
+			const twoslashTransformer = TwoslashManager.getInstance().getTransformer() ?? void 0;
+			const logLevel = options.logLevel ?? "info";
+			const suppressExampleErrors = options.errors?.example !== "show";
+			return {
+				apiConfigs,
+				combinedVfs,
+				highlighter,
+				tsEnvCache,
+				resolvedCompilerOptions,
+				ogResolver,
+				shikiCrossLinker,
+				hideCutTransformer,
+				hideCutLinesTransformer,
+				twoslashTransformer,
+				pageConcurrency: os.cpus().length,
+				logLevel: logLevel === "none" ? "info" : logLevel,
+				suppressExampleErrors
+			};
+		}) };
+	}));
+}
+/**
+* Strip npm scope from a package name.
+*/
+function unscopedName(packageName) {
+	return packageName.startsWith("@") ? packageName.split("/")[1] ?? packageName : packageName;
+}
+
+//#endregion
+export { ConfigServiceLive };

package/layers/ObservabilityLive.js

@@ -0,0 +1,136 @@
+import { Effect, Layer, LogLevel, Logger, Metric, MetricBoundaries } from "effect";
+
+//#region src/layers/ObservabilityLive.ts
+/**
+* All build metrics as named counters/histograms.
+*
+* Note: Effect Metrics use a process-wide registry. In tests, counters
+* accumulate across test cases within the same process. Test assertions
+* should use loose matching (toContain) rather than exact count checks.
+*/
+const BuildMetrics = {
+	filesTotal: Metric.counter("files.total"),
+	filesNew: Metric.counter("files.new"),
+	filesModified: Metric.counter("files.modified"),
+	filesUnchanged: Metric.counter("files.unchanged"),
+	codeblockDuration: Metric.histogram("codeblock.duration", MetricBoundaries.fromIterable([
+		10,
+		25,
+		50,
+		100,
+		200,
+		500,
+		1e3
+	])),
+	codeblockShikiDuration: Metric.histogram("codeblock.shiki.duration", MetricBoundaries.fromIterable([
+		5,
+		10,
+		25,
+		50,
+		100,
+		250
+	])),
+	codeblockTotal: Metric.counter("codeblock.total"),
+	codeblockSlow: Metric.counter("codeblock.slow"),
+	twoslashErrors: Metric.counter("twoslash.errors"),
+	prettierErrors: Metric.counter("prettier.errors"),
+	pagesGenerated: Metric.counter("pages.generated"),
+	apiVersionsLoaded: Metric.counter("api.versions.loaded"),
+	externalPackagesTotal: Metric.counter("external.packages.total")
+};
+/**
+* Format a Date as HH:MM:SS for console output.
+*/
+function formatTime(date) {
+	return date.toTimeString().slice(0, 8);
+}
+/**
+* Extract annotations from HashMap to a plain object.
+*/
+function annotationsToObject(annotations) {
+	const obj = {};
+	for (const [key, value] of annotations) obj[key] = value;
+	return obj;
+}
+/**
+* Create a custom plugin logger for the given mode.
+* Uses a closure to capture debugMode — no mutable module state.
+*/
+function makePluginLogger(debugMode) {
+	return Logger.make(({ logLevel, message, date, annotations }) => {
+		if (debugMode) {
+			const entry = {
+				timestamp: date.getTime(),
+				level: logLevel.label.toLowerCase(),
+				message: typeof message === "string" ? message : String(message),
+				...annotationsToObject(annotations)
+			};
+			console.log(JSON.stringify(entry));
+		} else {
+			const time = formatTime(date);
+			const msg = typeof message === "string" ? message : String(message);
+			const prefix = logLevel._tag === "Warning" ? "⚠️  " : logLevel._tag === "Error" ? "🔴 " : "";
+			console.log(`[${time}] ${prefix}${msg}`);
+		}
+	});
+}
+/**
+* Create the complete observability layer for the plugin.
+* Replaces the default Effect logger with a custom one and sets minimum log level.
+*
+* @param logLevel - Plugin log level from options
+*/
+function PluginLoggerLayer(logLevel = "info") {
+	const pluginLogger = makePluginLogger(logLevel === "debug");
+	const effectLogLevel = {
+		debug: LogLevel.Debug,
+		verbose: LogLevel.Debug,
+		info: LogLevel.Info,
+		warn: LogLevel.Warning,
+		error: LogLevel.Error,
+		none: LogLevel.None
+	}[logLevel];
+	return Layer.mergeAll(Logger.replace(Logger.defaultLogger, pluginLogger), Logger.minimumLogLevel(effectLogLevel));
+}
+/**
+* Log a build summary by reading all metric snapshots.
+* Replaces the 4 separate logSummary() calls in afterBuild.
+*/
+const logBuildSummary = Effect.gen(function* () {
+	const filesTotal = yield* Metric.value(BuildMetrics.filesTotal);
+	const filesNew = yield* Metric.value(BuildMetrics.filesNew);
+	const filesModified = yield* Metric.value(BuildMetrics.filesModified);
+	const filesUnchanged = yield* Metric.value(BuildMetrics.filesUnchanged);
+	const twoslashErrors = yield* Metric.value(BuildMetrics.twoslashErrors);
+	const prettierErrors = yield* Metric.value(BuildMetrics.prettierErrors);
+	const codeblockTotal = yield* Metric.value(BuildMetrics.codeblockTotal);
+	const codeblockSlow = yield* Metric.value(BuildMetrics.codeblockSlow);
+	const total = filesTotal.count;
+	const newCount = filesNew.count;
+	const modified = filesModified.count;
+	const unchanged = filesUnchanged.count;
+	const tsErrors = twoslashErrors.count;
+	const prErrors = prettierErrors.count;
+	const blocks = codeblockTotal.count;
+	const slowBlocks = codeblockSlow.count;
+	if (total === 0) yield* Effect.log("📝 No files generated");
+	else if (newCount === 0 && modified === 0) yield* Effect.log(`📝 ${total} files (all unchanged)`);
+	else {
+		const parts = [];
+		if (newCount > 0) parts.push(`${newCount} new`);
+		if (modified > 0) parts.push(`${modified} modified`);
+		if (unchanged > 0) parts.push(`${unchanged} unchanged`);
+		yield* Effect.log(`📝 ${total} files (${parts.join(", ")})`);
+	}
+	if (blocks > 0 && slowBlocks > 0) yield* Effect.logWarning(`⚠️  Code block performance: ${slowBlocks} of ${blocks} blocks were slow (>100ms)`);
+	const totalErrors = tsErrors + prErrors;
+	if (totalErrors > 0) {
+		const errorParts = [];
+		if (tsErrors > 0) errorParts.push(`${tsErrors} Twoslash`);
+		if (prErrors > 0) errorParts.push(`${prErrors} Prettier`);
+		yield* Effect.logWarning(`🔴 ${totalErrors} error(s) in code blocks (${errorParts.join(", ")})`);
+	}
+});
+
+//#endregion
+export { BuildMetrics, PluginLoggerLayer, logBuildSummary };

package/layers/PathDerivationServiceLive.js

@@ -0,0 +1,16 @@
+import { deriveOutputPaths, normalizeBaseRoute } from "../path-derivation.js";
+import { PathDerivationService } from "../services/PathDerivationService.js";
+import { Effect, Layer } from "effect";
+
+//#region src/layers/PathDerivationServiceLive.ts
+const PathDerivationServiceLive = Layer.succeed(PathDerivationService, {
+	derivePaths: (input) => Effect.succeed(deriveOutputPaths({
+		...input,
+		locales: [...input.locales],
+		versions: [...input.versions]
+	})),
+	normalizeBaseRoute: (route) => Effect.succeed(normalizeBaseRoute(route))
+});
+
+//#endregion
+export { PathDerivationServiceLive };

package/layers/SnapshotServiceLive.js

@@ -0,0 +1,94 @@
+import { hashContent } from "../content-hash.js";
+import { SnapshotService } from "../services/SnapshotService.js";
+import { SnapshotDbError } from "../errors.js";
+import migration from "../migrations/001_create_snapshots.js";
+import { NodeContext } from "@effect/platform-node";
+import { Effect, Layer, Option } from "effect";
+import { Migrator } from "@effect/sql";
+import * as SqlClient from "@effect/sql/SqlClient";
+import { SqliteClient, SqliteMigrator } from "@effect/sql-sqlite-node";
+
+//#region src/layers/SnapshotServiceLive.ts
+function toFileSnapshot(row) {
+	return {
+		outputDir: row.output_dir,
+		filePath: row.file_path,
+		publishedTime: row.published_time,
+		modifiedTime: row.modified_time,
+		contentHash: row.content_hash,
+		frontmatterHash: row.frontmatter_hash,
+		buildTime: row.build_time
+	};
+}
+function toSnapshotDbError(error) {
+	return new SnapshotDbError({
+		operation: "query",
+		dbPath: "snapshot-db",
+		reason: error instanceof Error ? error.message : String(error)
+	});
+}
+const SnapshotServiceLive = (dbPath) => {
+	const SqlLive = SqliteClient.layer({ filename: dbPath });
+	const MigratorLive = SqliteMigrator.layer({ loader: Migrator.fromRecord({ "001_create_snapshots": migration }) }).pipe(Layer.provide(Layer.merge(SqlLive, NodeContext.layer)));
+	const ServiceImpl = Layer.scoped(SnapshotService, Effect.gen(function* () {
+		const sql = yield* SqlClient.SqlClient;
+		yield* Effect.addFinalizer(() => sql`PRAGMA wal_checkpoint(TRUNCATE)`.pipe(Effect.ignore));
+		return {
+			hashContent,
+			getSnapshot: (outputDir, filePath) => sql`SELECT * FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${filePath}`.pipe(Effect.map((rows) => rows.length > 0 ? Option.some(toFileSnapshot(rows[0])) : Option.none()), Effect.mapError(toSnapshotDbError)),
+			getAllForDirectory: (outputDir) => sql`SELECT * FROM file_snapshots WHERE output_dir = ${outputDir}`.pipe(Effect.map((rows) => rows.map(toFileSnapshot)), Effect.mapError(toSnapshotDbError)),
+			getFilePaths: (outputDir) => sql`SELECT file_path FROM file_snapshots WHERE output_dir = ${outputDir}`.pipe(Effect.map((rows) => rows.map((r) => r.file_path)), Effect.mapError(toSnapshotDbError)),
+			upsert: (snapshot) => sql`INSERT INTO file_snapshots
+						(output_dir, file_path, published_time, modified_time,
+						 content_hash, frontmatter_hash, build_time)
+						VALUES (${snapshot.outputDir}, ${snapshot.filePath},
+								${snapshot.publishedTime}, ${snapshot.modifiedTime},
+								${snapshot.contentHash}, ${snapshot.frontmatterHash},
+								${snapshot.buildTime})
+						ON CONFLICT(output_dir, file_path) DO UPDATE SET
+							published_time = ${snapshot.publishedTime},
+							modified_time = ${snapshot.modifiedTime},
+							content_hash = ${snapshot.contentHash},
+							frontmatter_hash = ${snapshot.frontmatterHash},
+							build_time = ${snapshot.buildTime}
+						WHERE published_time != ${snapshot.publishedTime}
+						   OR modified_time != ${snapshot.modifiedTime}
+						   OR content_hash != ${snapshot.contentHash}
+						   OR frontmatter_hash != ${snapshot.frontmatterHash}`.pipe(Effect.as(true), Effect.mapError(toSnapshotDbError)),
+			batchUpsert: (snapshots) => (snapshots.length === 0 ? Effect.succeed(0) : sql.withTransaction(Effect.forEach(snapshots, (s) => sql`INSERT INTO file_snapshots
+												(output_dir, file_path, published_time, modified_time,
+												 content_hash, frontmatter_hash, build_time)
+												VALUES (${s.outputDir}, ${s.filePath},
+														${s.publishedTime}, ${s.modifiedTime},
+														${s.contentHash}, ${s.frontmatterHash},
+														${s.buildTime})
+												ON CONFLICT(output_dir, file_path) DO UPDATE SET
+													published_time = ${s.publishedTime},
+													modified_time = ${s.modifiedTime},
+													content_hash = ${s.contentHash},
+													frontmatter_hash = ${s.frontmatterHash},
+													build_time = ${s.buildTime}
+												WHERE published_time != ${s.publishedTime}
+												   OR modified_time != ${s.modifiedTime}
+												   OR content_hash != ${s.contentHash}
+												   OR frontmatter_hash != ${s.frontmatterHash}`, { concurrency: 1 })).pipe(Effect.map(() => snapshots.length))).pipe(Effect.mapError(toSnapshotDbError)),
+			deleteSnapshot: (outputDir, filePath) => sql`DELETE FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${filePath}`.pipe(Effect.asVoid, Effect.mapError(toSnapshotDbError)),
+			cleanupStale: (outputDir, currentFiles) => Effect.gen(function* () {
+				const rows = yield* sql`SELECT file_path FROM file_snapshots WHERE output_dir = ${outputDir}`;
+				const staleFiles = [];
+				for (const row of rows) {
+					const fp = row.file_path;
+					if (!currentFiles.has(fp)) {
+						yield* sql`DELETE FROM file_snapshots WHERE output_dir = ${outputDir} AND file_path = ${fp}`;
+						staleFiles.push(fp);
+					}
+				}
+				return staleFiles;
+			}).pipe(Effect.mapError(toSnapshotDbError))
+		};
+	}));
+	return Layer.provide(ServiceImpl, Layer.merge(SqlLive, MigratorLive));
+};
+
+//#endregion
+export { SnapshotServiceLive };

package/layers/TypeRegistryServiceLive.js

@@ -0,0 +1,46 @@
+import { TypeRegistryError } from "../errors.js";
+import { TypeRegistryService } from "../services/TypeRegistryService.js";
+import { Effect, Layer } from "effect";
+import { PackageSpec, TypeRegistry } from "type-registry-effect";
+import { NodeLayer, createTypeScriptCache } from "type-registry-effect/node";
+
+//#region src/layers/TypeRegistryServiceLive.ts
+/**
+* TypeRegistryServiceLive: uses type-registry-effect Effect programs directly.
+*
+* The NodeLayer from type-registry-effect provides CacheService, PackageFetcher,
+* and TypeResolver with Node.js platform implementations (FileSystem, HttpClient).
+*
+* Built-in metrics (packagesLoaded, packagesFailed, cacheHits, etc.) are
+* automatically tracked by the upstream library.
+*/
+const TypeRegistryServiceLive = Layer.succeed(TypeRegistryService, {
+	loadPackages: (packages) => Effect.gen(function* () {
+		if (packages.length === 0) return { vfs: /* @__PURE__ */ new Map() };
+		const specs = packages.map((pkg) => new PackageSpec({
+			name: pkg.name,
+			version: pkg.version
+		}));
+		return { vfs: yield* TypeRegistry.getVFS(specs, { autoFetch: true }).pipe(Effect.catchAll((error) => Effect.fail(new TypeRegistryError({
+			packageName: packages.map((p) => p.name).join(", "),
+			version: packages.map((p) => p.version).join(", "),
+			reason: error.message ?? String(error)
+		})))) };
+	}).pipe(Effect.provide(NodeLayer)),
+	createTypeScriptCache: (packages, compilerOptions) => Effect.tryPromise({
+		try: () => {
+			return createTypeScriptCache(packages.map((pkg) => new PackageSpec({
+				name: pkg.name,
+				version: pkg.version
+			})), compilerOptions);
+		},
+		catch: (error) => new TypeRegistryError({
+			packageName: packages.map((p) => p.name).join(", "),
+			version: "",
+			reason: error instanceof Error ? error.message : String(error)
+		})
+	})
+});
+
+//#endregion
+export { TypeRegistryServiceLive };