rspress-plugin-api-extractor 0.10.0 → 0.12.0

package/services/OgService.js

@@ -0,0 +1,190 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { imageMimeType, ogAltText, resolveOgUrl } from "../og-resolver.js";
+import { Context, Data, Effect, FileSystem, Layer, Option, Path } from "effect";
+import { imageSize } from "image-size";
+
+//#region src/services/OgService.ts
+/**
+* Resolving an API's configured Open Graph image into page metadata.
+*
+* @remarks
+* Replaces the `OpenGraphResolver` class, which did synchronous `node:fs` from
+* inside `Effect.promise`, carried its own sync-island event emitter, and
+* returned `undefined` for all three of its failure modes — indistinguishable
+* from "no image was configured".
+*
+* This is also where phase 4's SEO work lands, which is why the contract is
+* wider than today's single caller needs: it names its failures instead of
+* erasing them.
+*
+* @packageDocumentation
+*/
+const OgImageErrorBase = Data.TaggedError("OgImageError");
+/**
+* A configured OG image that could not be resolved.
+*
+* @remarks
+* `cause` carries the original failure (an `image-size` parse error, a
+* filesystem error) rather than a stringified copy of it.
+*/
+var OgImageError = class extends OgImageErrorBase {
+	get message() {
+		if (this.code === "invalid-url") return `Invalid Open Graph image URL in '${this.field}': ${this.value} — expected an absolute http(s) URL or a path starting with '/'`;
+		if (this.code === "invalid-secure-url") return `Invalid Open Graph secure URL in '${this.field}': ${this.value} — secureUrl must be an absolute https URL`;
+		const cause = this.cause instanceof Error ? this.cause.message : String(this.cause);
+		return `Could not read Open Graph image '${this.value}': ${cause}`;
+	}
+};
+var OgService = class OgService extends Context.Service()("rspress-plugin-api-extractor/OgService") {
+	/**
+	* Resolve OG images through the core `FileSystem`, with one read per file per
+	* build.
+	*
+	* @remarks
+	* The `node:fs` `existsSync` + `imageSizeFromFile` pair this replaces ran once
+	* per PAGE, so a 400-page API re-read the same image 400 times. The memo below
+	* keys on the absolute path and removes that entirely.
+	*
+	* The memo is per build, not persisted. A cross-build cache in the shared XDG
+	* store was considered and deliberately deferred: it would need mtime/size
+	* invalidation to stay sound, and a stale image dimension is a silent wrong
+	* answer. There is nothing expensive enough here to justify that yet — when
+	* phase 4 starts GENERATING images, which are expensive and content-addressed,
+	* the XDG cache is the right home for them.
+	*
+	* `imageSize` over the read bytes replaces `imageSizeFromFile`, which took a
+	* path and therefore required real `node:fs`. Same parser, same output.
+	*
+	* `Effect.suspend(() => make())` rather than a bare `make`: a static
+	* initializer runs while the module body is still evaluating, so naming a
+	* `const` declared further down throws at import time with a clean typecheck.
+	*/
+	static layer = Layer.effect(this, Effect.suspend(() => make()));
+	/**
+	* An in-memory double whose unstubbed member dies naming itself.
+	*
+	* @remarks
+	* **There is deliberately no default `resolveImage`.** A default returning
+	* `Option.none` would be indistinguishable from "this API declares no
+	* image", which is precisely the ambiguity {@link OgImageError} exists to
+	* remove — and a test asserting that a page rendered without an `og:image`
+	* would then pass whether or not the service was ever consulted.
+	*
+	* Where the wiring is what matters, prefer the real layer over a platform
+	* filesystem instead of this double; see `__test__/utils/layers.ts`.
+	*/
+	static makeTest = (overrides = {}) => ({ resolveImage: overrides.resolveImage ?? (() => unstubbed("resolveImage")) });
+	/** {@link OgService.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(OgService, OgService.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`OgService.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const make = () => Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	/** Absolute path → facts, or `null` for "looked, could not use it". */
+	const factsByPath = /* @__PURE__ */ new Map();
+	/** Locate a root-relative image under the docs `public/` directory. */
+	const findLocalImage = (imagePath, docsRoot) => {
+		if (docsRoot == null || !imagePath.startsWith("/")) return Effect.succeed(Option.none());
+		const candidate = path.join(docsRoot, "public", imagePath);
+		return fileSystem.exists(candidate).pipe(Effect.orElseSucceed(() => false), Effect.map((found) => found ? Option.some(candidate) : Option.none()));
+	};
+	/**
+	* Read dimensions and MIME type. A file that cannot be parsed warns and
+	* yields nothing — the page still gets its `og:image`, just without
+	* dimensions, which is what the class this replaced did.
+	*/
+	const readImageFacts = (filePath) => Effect.gen(function* () {
+		const memoed = factsByPath.get(filePath);
+		if (memoed !== void 0) return memoed;
+		const result = yield* Effect.result(fileSystem.readFile(filePath).pipe(Effect.flatMap((bytes) => Effect.try(() => imageSize(bytes)))));
+		if (result._tag === "Failure") {
+			const error = new OgImageError({
+				code: "unreadable-image",
+				field: "ogImage",
+				value: filePath,
+				cause: result.failure
+			});
+			yield* emit(PluginEvent.ConfigValidationWarning({
+				ctx: {},
+				field: "ogImage",
+				value: filePath,
+				reason: error.message,
+				level: "warn"
+			}));
+			factsByPath.set(filePath, null);
+			return null;
+		}
+		const size = result.success;
+		const mimeType = imageMimeType(size.type);
+		const facts = {
+			...size.width != null ? { width: size.width } : {},
+			...size.height != null ? { height: size.height } : {},
+			...mimeType != null ? { type: mimeType } : {}
+		};
+		factsByPath.set(filePath, facts);
+		return facts;
+	});
+	const resolveFromString = (imageUrl, request) => Effect.gen(function* () {
+		const resolvedUrl = resolveOgUrl(request.siteUrl, imageUrl);
+		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
+			code: "invalid-url",
+			field: "ogImage",
+			value: imageUrl
+		}));
+		const localPath = yield* findLocalImage(imageUrl, request.docsRoot);
+		const facts = Option.isSome(localPath) ? yield* readImageFacts(localPath.value) : null;
+		return Option.some({
+			url: resolvedUrl,
+			type: facts?.type,
+			width: facts?.width,
+			height: facts?.height,
+			alt: ogAltText(request.packageName, request.apiName)
+		});
+	});
+	const resolveFromMetadata = (metadata, request) => Effect.gen(function* () {
+		const { url, secureUrl, type, width, height, alt } = metadata;
+		const resolvedUrl = resolveOgUrl(request.siteUrl, url);
+		if (resolvedUrl == null) return yield* Effect.fail(new OgImageError({
+			code: "invalid-url",
+			field: "ogImage.url",
+			value: url
+		}));
+		let resolvedSecureUrl;
+		if (secureUrl != null) {
+			if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
+			else {
+				const error = new OgImageError({
+					code: "invalid-secure-url",
+					field: "ogImage.secureUrl",
+					value: secureUrl
+				});
+				yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {},
+					field: "ogImage.secureUrl",
+					value: secureUrl,
+					reason: error.message,
+					level: "warn"
+				}));
+			}
+		}
+		return Option.some({
+			url: resolvedUrl,
+			secureUrl: resolvedSecureUrl,
+			type,
+			width,
+			height,
+			alt: alt ?? ogAltText(request.packageName, request.apiName)
+		});
+	});
+	return { resolveImage: (request) => {
+		if (request.config == null) return Effect.succeed(Option.none());
+		return typeof request.config === "object" ? resolveFromMetadata(request.config, request) : resolveFromString(request.config, request);
+	} };
+});
+
+//#endregion
+export { OgImageError, OgService };

package/services/PluginConfig.js

@@ -0,0 +1,26 @@
+import { Context } from "effect";
+
+//#region src/services/PluginConfig.ts
+/**
+* The decoded plugin options, as a service.
+*
+* @remarks
+* `ConfigService.layer` used to be a factory taking these as an argument, which
+* made it a layer-returning function — the shape the house rules warn about,
+* since layers memoize by reference and a second call mints a second layer.
+* It was only ever called once, but "only ever called once" is a property of
+* the current call sites, not of the design.
+*
+* A `Context.Service` rather than a `Context.Reference`, deliberately, and for
+* the same reason the Shiki themes are a layer argument: a Reference carries a
+* default, so a wiring mistake would silently resolve to empty options and the
+* build would document nothing while reporting success. There is no sensible
+* default for "which APIs is this site documenting", so forgetting to provide
+* it should be a loud "service not provided", which is what this gives.
+*
+* @packageDocumentation
+*/
+var PluginConfig = class extends Context.Service()("rspress-plugin-api-extractor/PluginConfig") {};
+
+//#endregion
+export { PluginConfig };

package/services/TwoslashCacheService.js

@@ -1,4 +1,8 @@
-import { Context } from "effect";
+import { AppDirsLive, PlatformLive } from "../layers/xdg.js";
+import { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey } from "../twoslash-cache.js";
+import { Context, Effect, Layer, Option, Path } from "effect";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
 
 //#region src/services/TwoslashCacheService.ts
 /**
@@ -9,7 +13,129 @@ import { Context } from "effect";
 * hook and cannot await: the service loads once before the render phase and
 * saves once after it, while every lookup in between is a synchronous map hit.
 */
-var TwoslashCacheService = class extends Context.Service()("rspress-plugin-api-extractor/TwoslashCacheService") {};
+var TwoslashCacheService = class TwoslashCacheService extends Context.Service()("rspress-plugin-api-extractor/TwoslashCacheService") {
+	/**
+	* Live Twoslash cache persistence.
+	*
+	* @remarks
+	* Failure is absorbed at TWO levels, and both are load-bearing. Inside the
+	* service, a failed read or write degrades that one operation. Around the
+	* layer, a failed CONSTRUCTION — no HOME for XDG, an unwritable cache
+	* directory, a corrupt database — degrades to {@link DegradedLive}.
+	*
+	* The second is why `Layer.catchCause` wraps this at all. While the sqlite
+	* layer was provided inside each method, a construction failure surfaced as
+	* that method's failure and the in-method handler swallowed it. Hoisting
+	* acquisition to layer construction moved the failure to `ManagedRuntime`
+	* build time, where it would abort the entire build — breaking the contract
+	* this service documents, that an unreachable cache must never fail a build
+	* that would otherwise succeed. `catchCause` rather than a failure-only catch
+	* because a defect thrown by the sqlite driver must degrade too.
+	*
+	* `Layer.suspend` because the composition below is declared after this class:
+	* a static initializer runs while the module body is still evaluating, so
+	* naming those consts directly throws at import time with a clean typecheck.
+	*/
+	static layer = Layer.suspend(() => CacheBackedLive.pipe(Layer.catchCause(() => DegradedLive)));
+	/**
+	* An always-cold in-memory double.
+	*
+	* @remarks
+	* Tests that resolve config must not touch the user's real XDG cache, and
+	* must not have their results depend on whether a previous run warmed it.
+	*
+	* `open` returns a REAL in-memory generation rather than a stub, and that is
+	* not an accident: `registerEnvironment` hands this object to the Twoslash
+	* transformers, so a cache that could not be read or written would change
+	* the render path's SHAPE rather than merely dropping its persistence.
+	*/
+	static makeTest = (overrides = {}) => ({
+		load: overrides.load ?? (() => Effect.succeed(/* @__PURE__ */ new Map())),
+		save: overrides.save ?? (() => Effect.void),
+		open: overrides.open ?? (() => Effect.succeed(makeTwoslashCache())),
+		persist: overrides.persist ?? (() => Effect.succeed(Option.none()))
+	});
+	/** {@link TwoslashCacheService.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(TwoslashCacheService, TwoslashCacheService.makeTest(overrides));
+};
+/**
+* A sqlite-backed `@effected/store` Cache in the XDG cache dir, separate from
+* the registry's `metadata.sqlite`.
+*
+* XDG rather than the repo: these are regenerable results derived from content
+* hashes, so they belong with the user's other caches — shared across worktrees
+* and checkouts of the same project, and untouched by cleaning `dist/`. Nothing
+* here needs to be committed for a build to be correct.
+*/
+const CacheLive = Layer.unwrap(Effect.gen(function* () {
+	const appDirs = yield* AppDirs;
+	const path = yield* Path.Path;
+	const cacheDir = yield* appDirs.ensureCache;
+	return Cache.layerSqlite({ filename: path.join(cacheDir, "twoslash.sqlite") });
+})).pipe(Layer.provide(Layer.mergeAll(AppDirsLive, PlatformLive)));
+/**
+* Live Twoslash cache persistence.
+*
+* Both operations swallow every failure by design — see the service docs. A
+* missing HOME, an unwritable cache dir or a corrupt database degrades the
+* build to "type-check everything", which is exactly the behaviour before this
+* cache existed.
+*/
+/**
+* Add the build-generation half of the service on top of a load/save pair.
+*
+* @remarks
+* Shared by the real and degraded layers so the two cannot drift: a degraded
+* build must still hand out a working in-memory cache, otherwise the
+* transformers have nothing to read or write and the render pass changes
+* shape rather than merely losing persistence.
+*/
+function withGeneration(base) {
+	let open = null;
+	return {
+		...base,
+		open: (envHash) => base.load(envHash).pipe(Effect.map((restored) => {
+			const cache = makeTwoslashCache(restored);
+			open = {
+				cache,
+				envHash
+			};
+			return cache;
+		})),
+		persist: () => Effect.suspend(() => {
+			if (open === null) return Effect.succeed(Option.none());
+			const { cache, envHash } = open;
+			const stats = cache.stats();
+			const report = Option.some({
+				...stats,
+				envHash
+			});
+			return stats.dirty ? base.save(envHash, cache.entries()).pipe(Effect.as(report)) : Effect.succeed(report);
+		})
+	};
+}
+const CacheBackedLive = Layer.effect(TwoslashCacheService, Effect.gen(function* () {
+	const cache = yield* Cache;
+	return withGeneration({
+		load: (envHash) => cache.get(twoslashBlobKey(envHash)).pipe(Effect.map((entry) => Option.isSome(entry) ? decodeTwoslashCache(entry.value.value) : /* @__PURE__ */ new Map()), Effect.catch(() => Effect.succeed(/* @__PURE__ */ new Map()))),
+		save: (envHash, entries) => cache.set({
+			key: twoslashBlobKey(envHash),
+			value: encodeTwoslashCache(entries),
+			tags: ["twoslash"]
+		}).pipe(Effect.catch(() => Effect.void))
+	});
+})).pipe(Layer.provide(CacheLive));
+/**
+* A cache that holds nothing, for when the real one cannot be opened.
+*
+* @remarks
+* `load` returns empty and `save` discards, which is precisely the behaviour
+* before this cache existed: type-check everything, persist nothing.
+*/
+const DegradedLive = Layer.succeed(TwoslashCacheService, withGeneration({
+	load: () => Effect.succeed(/* @__PURE__ */ new Map()),
+	save: () => Effect.void
+}));
 
 //#endregion
 export { TwoslashCacheService };

package/services/TwoslashEnvironments.js

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

package/services/TypeRegistryService.js

@@ -1,7 +1,183 @@
-import { Context } from "effect";
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { resolveExternalPackageVersions } from "../config-utils.js";
+import { TypeRegistryError } from "../errors.js";
+import { AppDirsLive, PlatformLive } from "../layers/xdg.js";
+import { Context, Duration, Effect, Layer, Path } from "effect";
+import { NodeHttpClient } from "@effect/platform-node";
+import { PackageFetcher, PackageSpec, RegistryObserver, TypeCache, TypeRegistry } from "@tsdoctor/registry";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
 
 //#region src/services/TypeRegistryService.ts
-var TypeRegistryService = class extends Context.Service()("rspress-plugin-api-extractor/TypeRegistryService") {};
+var TypeRegistryService = class TypeRegistryService extends Context.Service()("rspress-plugin-api-extractor/TypeRegistryService") {
+	/**
+	* The `@tsdoctor/registry` stack, acquired once.
+	*
+	* @remarks
+	* `Layer.catchCause` keeps a broken environment — no HOME for XDG, an
+	* unwritable cache directory — from aborting the build at `ManagedRuntime`
+	* construction. External type loading is an enhancement: without it code
+	* blocks render without Twoslash enrichment, which is a degradation, not a
+	* failure. That was true while the stack was provided per method and the
+	* in-method handlers absorbed it; hoisting acquisition made it something the
+	* layer has to say for itself.
+	*
+	* `Layer.suspend` because the composition below is declared after this class: a
+	* static initializer runs while the module body is still evaluating, so naming
+	* those consts directly throws at import time with a clean typecheck.
+	*/
+	static layer = Layer.suspend(() => RegistryBackedLive.pipe(Layer.catchCause(() => DegradedLive)));
+	/**
+	* An in-memory double: no network, no XDG cache, no sqlite.
+	*
+	* @remarks
+	* Defaults resolve every spec unchanged and load an empty VFS — the shape a
+	* build takes when nothing external is configured. Override a member to
+	* exercise a specific path; an override for one member leaves the other at
+	* its default rather than forcing the test to restate it, which is the whole
+	* difference from the hand-written `Layer.succeed` doubles this replaces.
+	*/
+	static makeTest = (overrides = {}) => ({
+		resolveVersions: overrides.resolveVersions ?? ((packages) => Effect.succeed([...packages])),
+		loadPackages: overrides.loadPackages ?? (() => Effect.succeed({ vfs: /* @__PURE__ */ new Map() }))
+	});
+	/** {@link TypeRegistryService.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(TypeRegistryService, TypeRegistryService.makeTest(overrides));
+};
+/**
+* Forward @tsdoctor/registry's typed `RegistryEvent`s to the plugin's Effect
+* logger. Since v1 the library emits no logs of its own — observers are the only
+* diagnostic surface — so this restores the build output and routes it through
+* the plugin's configured log level/format (a single source, no duplication).
+*
+* The summary (`BatchComplete`) and failures are surfaced at info/warning;
+* per-package detail stays at debug so a normal build is quiet.
+*/
+const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) => {
+	switch (event._tag) {
+		case "VersionResolved": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: { packageName: event.package },
+			level: "debug",
+			kind: "VersionResolved",
+			detail: `${event.requested} -> ${event.resolved}`
+		}));
+		case "VersionResolveFailed": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: { packageName: event.package },
+			level: "debug",
+			kind: "VersionResolveFailed",
+			detail: `${event.requested}: ${event.kind}`
+		}));
+		case "CacheHit":
+		case "CacheMiss":
+		case "FetchStart": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {
+				packageName: event.package,
+				version: event.version
+			},
+			level: "debug",
+			kind: event._tag,
+			detail: ""
+		}));
+		case "CacheStale": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {
+				packageName: event.package,
+				version: event.version
+			},
+			level: "debug",
+			kind: "CacheStale",
+			detail: ""
+		}));
+		case "FetchFailed": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {},
+			level: "debug",
+			kind: "FetchFailed",
+			detail: `HTTP ${event.status}: ${event.url}${event.bodySnippet ? ` — ${event.bodySnippet}` : ""}`
+		}));
+		case "PackageLoaded": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {
+				packageName: event.package,
+				version: event.version
+			},
+			level: "debug",
+			kind: "PackageLoaded",
+			detail: `${event.files} files, ${event.source}`
+		}));
+		case "PackageLoadFailed": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {
+				packageName: event.package,
+				version: event.version
+			},
+			level: "warn",
+			kind: "PackageLoadFailed",
+			detail: `[${event.kind}] ${event.error instanceof Error ? event.error.message : String(event.error)}`
+		}));
+		case "BatchStart": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {},
+			level: "debug",
+			kind: "BatchStart",
+			detail: `${event.total} package(s)`
+		}));
+		case "BatchComplete": return emit(PluginEvent.TypeRegistryEvent({
+			ctx: {},
+			level: "info",
+			kind: "BatchComplete",
+			detail: `${event.loaded}/${event.total} packages, ${event.totalFiles} files, ${Math.round(Duration.toMillis(event.duration))}ms`
+		}));
+	}
+} });
+/** Metadata plane: a sqlite-backed `@effected/store` Cache rooted in the XDG cache dir. */
+const MetadataCacheLive = Layer.unwrap(Effect.gen(function* () {
+	const appDirs = yield* AppDirs;
+	const path = yield* Path.Path;
+	const cacheDir = yield* appDirs.ensureCache;
+	return Cache.layerSqlite({ filename: path.join(cacheDir, "metadata.sqlite") });
+})).pipe(Layer.provide(Layer.mergeAll(AppDirsLive, PlatformLive)));
+/**
+* The full registry runtime: TypeRegistry over an XDG-rooted TypeCache and the
+* jsDelivr PackageFetcher, with the observer that forwards registry events to
+* the plugin's EventBus (found ambiently via serviceOption at emit time).
+*/
+const RegistryLayer = TypeRegistry.layer.pipe(Layer.provideMerge(Layer.mergeAll(TypeCache.layerXdg(), PackageFetcher.layer)), Layer.provideMerge(RegistryObserverLayer), Layer.provide(Layer.mergeAll(MetadataCacheLive, AppDirsLive, PlatformLive, NodeHttpClient.layerUndici)));
+/**
+* TypeRegistryService.layer: uses @tsdoctor/registry Effect programs directly.
+*/
+const RegistryBackedLive = Layer.effect(TypeRegistryService, Effect.gen(function* () {
+	const registry = yield* TypeRegistry;
+	return {
+		resolveVersions: (packages) => resolveExternalPackageVersions(packages, (pkg) => registry.resolveVersion(pkg.name, pkg.version)).pipe(Effect.catch(() => Effect.succeed([...packages]))),
+		loadPackages: (packages) => packages.length === 0 ? Effect.succeed({ vfs: /* @__PURE__ */ new Map() }) : Effect.gen(function* () {
+			const specs = packages.map((pkg) => new PackageSpec({
+				name: pkg.name,
+				version: pkg.version
+			}));
+			return { vfs: yield* registry.getVfs(specs, { autoFetch: true }) };
+		}).pipe(Effect.catch((error) => Effect.fail(new TypeRegistryError({
+			packageName: packages.map((p) => p.name).join(", "),
+			version: packages.map((p) => p.version).join(", "),
+			reason: error instanceof Error ? error.message ?? String(error) : String(error)
+		}))))
+	};
+})).pipe(Layer.provide(RegistryLayer));
+/**
+* The service when the registry stack cannot be built at all.
+*
+* @remarks
+* Preserves exactly the split the working service documents: `resolveVersions`
+* passes its specs through unresolved rather than swallowing the problem, so
+* the failure surfaces from `loadPackages` as a {@link PluginTypeRegistryError}
+* with a message, which `ConfigService.layer` turns into a build-continues
+* warning. Before acquisition moved to layer construction this fell out of the
+* per-method handlers; it has to be stated explicitly now.
+*/
+const DegradedLive = Layer.succeed(TypeRegistryService, {
+	resolveVersions: (packages) => Effect.succeed([...packages]),
+	loadPackages: (packages) => Effect.fail(new TypeRegistryError({
+		packageName: packages.map((p) => p.name).join(", "),
+		version: packages.map((p) => p.version).join(", "),
+		reason: "type registry unavailable: its cache directory or metadata database could not be opened"
+	}))
+});
 
 //#endregion
 export { TypeRegistryService };