rspress-plugin-api-extractor 0.10.0 → 0.11.0

package/layers/HighlighterServiceLive.js

@@ -0,0 +1,52 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { HighlighterService } from "../services/HighlighterService.js";
+import { SHIKI_LANGS } from "../markdown/shiki-utils.js";
+import { Effect, Layer } from "effect";
+import { createHighlighter } from "shiki";
+
+//#region src/layers/HighlighterServiceLive.ts
+/**
+* Acquire the build's highlighter, and release it when the runtime is
+* disposed.
+*
+* @remarks
+* `Layer.effect` over `Effect.acquireRelease` is the v4 scoped-constructor
+* idiom (`Layer.scoped` is gone; `Layer.effect` strips `Scope` from `R`).
+* Because the layer sits in the `ManagedRuntime`'s stack, the highlighter is
+* created on the runtime's first use and `dispose()`d by
+* `effectRuntime.dispose()` — which `plugin.ts` calls on production builds
+* only, so a dev HMR session keeps one highlighter across rebuilds instead of
+* leaking one per rebuild.
+*
+* **Bind the result to a `const`.** This is a layer FACTORY: each call mints a
+* fresh layer reference, and layers memoize by reference, so calling it twice
+* in one graph acquires two highlighters — the exact leak this layer exists to
+* fix.
+*
+* The themes are passed in rather than read from a resolved build context
+* because the layer builds before `ConfigService.resolve()` runs. Passing them
+* as an argument rather than through a `Context.Reference` is deliberate: a
+* Reference carries a default, so forgetting to wire it would silently load
+* only the default themes and render every custom-themed block wrong. A
+* missing argument is a type error.
+*/
+function HighlighterServiceLive(themes) {
+	return Layer.effect(HighlighterService, Effect.gen(function* () {
+		const startedMs = performance.now();
+		const highlighter = yield* Effect.acquireRelease(Effect.promise(() => createHighlighter({
+			themes: [...themes],
+			langs: [...SHIKI_LANGS]
+		})), (instance) => Effect.sync(() => instance.dispose()));
+		yield* emit(PluginEvent.PhaseCompleted({
+			ctx: {},
+			level: "debug",
+			phase: "shikiInit",
+			durationMs: Math.round(performance.now() - startedMs)
+		}));
+		return { highlighter };
+	}));
+}
+
+//#endregion
+export { HighlighterServiceLive };

package/layers/OgServiceLive.js

@@ -0,0 +1,134 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { imageMimeType, ogAltText, resolveOgUrl } from "../og-resolver.js";
+import { OgImageError, OgService } from "../services/OgService.js";
+import { Effect, FileSystem, Layer, Option, Path } from "effect";
+import { imageSize } from "image-size";
+
+//#region src/layers/OgServiceLive.ts
+/**
+* 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.
+*/
+const OgServiceLive = Layer.effect(OgService, 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 { OgServiceLive };

package/layers/TwoslashCacheServiceLive.js

@@ -1,17 +1,11 @@
 import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
-import { decodeTwoslashCache, encodeTwoslashCache, twoslashBlobKey } from "../twoslash-cache.js";
-import { NodeFileSystem } from "@effect/platform-node";
+import { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey } from "../twoslash-cache.js";
+import { AppDirsLive, PlatformLive } from "./xdg.js";
 import { Effect, Layer, Option, Path } from "effect";
 import { Cache } from "@effected/store";
-import { AppDirs, Xdg } from "@effected/xdg";
+import { AppDirs } from "@effected/xdg";
 
 //#region src/layers/TwoslashCacheServiceLive.ts
-const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
-/**
-* XDG app dirs under the same `tsdoctor` namespace the type registry uses, so
-* every derived-artifact cache this plugin keeps lives in one place.
-*/
-const AppDirsLive = AppDirs.layer({ namespace: "tsdoctor" }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
 /**
 * A sqlite-backed `@effected/store` Cache in the XDG cache dir, separate from
 * the registry's `metadata.sqlite`.
@@ -35,19 +29,80 @@ const CacheLive = Layer.unwrap(Effect.gen(function* () {
 * build to "type-check everything", which is exactly the behaviour before this
 * cache existed.
 */
-const TwoslashCacheServiceLive = Layer.succeed(TwoslashCacheService, {
-	load: (envHash) => Effect.gen(function* () {
-		const entry = yield* (yield* Cache).get(twoslashBlobKey(envHash));
-		return Option.isSome(entry) ? decodeTwoslashCache(entry.value.value) : /* @__PURE__ */ new Map();
-	}).pipe(Effect.provide(CacheLive), Effect.catchCause(() => Effect.succeed(/* @__PURE__ */ new Map()))),
-	save: (envHash, entries) => Effect.gen(function* () {
-		yield* (yield* Cache).set({
+/**
+* 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.provide(CacheLive), Effect.catchCause(() => Effect.void))
-});
+		}).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
+}));
+/**
+* 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.
+*/
+const TwoslashCacheServiceLive = CacheBackedLive.pipe(Layer.catchCause(() => DegradedLive));
 
 //#endregion
 export { TwoslashCacheServiceLive };

package/layers/TwoslashEnvironmentsLive.js

@@ -0,0 +1,33 @@
+import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
+import { TwoslashEnvironmentRegistry } from "../twoslash-transformer.js";
+import { Layer } from "effect";
+
+//#region src/layers/TwoslashEnvironmentsLive.ts
+/**
+* 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.
+*/
+const TwoslashEnvironmentsLive = Layer.sync(TwoslashEnvironments, () => {
+	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 { TwoslashEnvironmentsLive };

package/layers/TypeRegistryServiceLive.js

@@ -3,11 +3,12 @@ import { emit } from "../observability/EventBus.js";
 import { resolveExternalPackageVersions } from "../config-utils.js";
 import { TypeRegistryError } from "../errors.js";
 import { TypeRegistryService } from "../services/TypeRegistryService.js";
-import { NodeFileSystem, NodeHttpClient } from "@effect/platform-node";
+import { AppDirsLive, PlatformLive } from "./xdg.js";
+import { NodeHttpClient } from "@effect/platform-node";
 import { Duration, Effect, Layer, Path } from "effect";
 import { PackageFetcher, PackageSpec, RegistryObserver, TypeCache, TypeRegistry } from "@tsdoctor/registry";
 import { Cache } from "@effected/store";
-import { AppDirs, Xdg } from "@effected/xdg";
+import { AppDirs } from "@effected/xdg";
 
 //#region src/layers/TypeRegistryServiceLive.ts
 /**
@@ -22,19 +23,13 @@ import { AppDirs, Xdg } from "@effected/xdg";
 const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) => {
 	switch (event._tag) {
 		case "VersionResolved": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: {
-				buildId: "",
-				packageName: event.package
-			},
+			ctx: { packageName: event.package },
 			level: "debug",
 			kind: "VersionResolved",
 			detail: `${event.requested} -> ${event.resolved}`
 		}));
 		case "VersionResolveFailed": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: {
-				buildId: "",
-				packageName: event.package
-			},
+			ctx: { packageName: event.package },
 			level: "debug",
 			kind: "VersionResolveFailed",
 			detail: `${event.requested}: ${event.kind}`
@@ -43,7 +38,6 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 		case "CacheMiss":
 		case "FetchStart": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -53,7 +47,6 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 		}));
 		case "CacheStale": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -62,14 +55,13 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 			detail: ""
 		}));
 		case "FetchFailed": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: { buildId: "" },
+			ctx: {},
 			level: "debug",
 			kind: "FetchFailed",
 			detail: `HTTP ${event.status}: ${event.url}${event.bodySnippet ? ` — ${event.bodySnippet}` : ""}`
 		}));
 		case "PackageLoaded": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -79,7 +71,6 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 		}));
 		case "PackageLoadFailed": return emit(PluginEvent.TypeRegistryEvent({
 			ctx: {
-				buildId: "",
 				packageName: event.package,
 				version: event.version
 			},
@@ -88,35 +79,19 @@ const RegistryObserverLayer = Layer.succeed(RegistryObserver, { emit: (event) =>
 			detail: `[${event.kind}] ${event.error instanceof Error ? event.error.message : String(event.error)}`
 		}));
 		case "BatchStart": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: { buildId: "" },
+			ctx: {},
 			level: "debug",
 			kind: "BatchStart",
 			detail: `${event.total} package(s)`
 		}));
 		case "BatchComplete": return emit(PluginEvent.TypeRegistryEvent({
-			ctx: { buildId: "" },
+			ctx: {},
 			level: "info",
 			kind: "BatchComplete",
 			detail: `${event.loaded}/${event.total} packages, ${event.totalFiles} files, ${Math.round(Duration.toMillis(event.duration))}ms`
 		}));
 	}
 } });
-/**
-* @tsdoctor/registry composes at the edge: the library ships no platform
-* layer of its own, so the plugin wires FileSystem/Path, the XDG directories,
-* the sqlite metadata Cache and the HTTP client here.
-*
-* All layers are bound to module-level consts (never rebuilt per call) per the
-* v4 layer memoization discipline.
-*/
-const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
-/**
-* XDG app directories under the tsdoctor-wide namespace. Renamed from the
-* legacy "type-registry-effect" namespace in phase 2 per the resolved identity
-* decision (see tsdoctor-package-architecture.md) — a deliberate one-time
-* on-disk cache invalidation: existing caches go cold and refetch.
-*/
-const AppDirsLive = AppDirs.layer({ namespace: "tsdoctor" }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
 /** 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;
@@ -133,23 +108,55 @@ const RegistryLayer = TypeRegistry.layer.pipe(Layer.provideMerge(Layer.mergeAll(
 /**
 * TypeRegistryServiceLive: uses @tsdoctor/registry Effect programs directly.
 */
-const TypeRegistryServiceLive = Layer.succeed(TypeRegistryService, {
-	resolveVersions: (packages) => Effect.gen(function* () {
-		const registry = yield* TypeRegistry;
-		return yield* resolveExternalPackageVersions(packages, (pkg) => registry.resolveVersion(pkg.name, pkg.version));
-	}).pipe(Effect.provide(RegistryLayer), 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* (yield* TypeRegistry).getVfs(specs, { autoFetch: true }) };
-	}).pipe(Effect.provide(RegistryLayer), Effect.catch((error) => Effect.fail(new TypeRegistryError({
+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 `ConfigServiceLive` 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: error instanceof Error ? error.message ?? String(error) : String(error)
-	}))))
+		reason: "type registry unavailable: its cache directory or metadata database could not be opened"
+	}))
 });
+/**
+* TypeRegistryServiceLive: 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.
+*/
+const TypeRegistryServiceLive = RegistryBackedLive.pipe(Layer.catchCause(() => DegradedLive));
 
 //#endregion
 export { TypeRegistryServiceLive };

package/layers/xdg.js

@@ -0,0 +1,44 @@
+import { NodeFileSystem } from "@effect/platform-node";
+import { Layer, Path } from "effect";
+import { AppDirs, Xdg } from "@effected/xdg";
+
+//#region src/layers/xdg.ts
+/**
+* The plugin's shared platform and XDG layers.
+*
+* @remarks
+* Both cache-backed services — the type registry and the Twoslash result cache
+* — need a Node platform and an XDG app-directory root, and both used to
+* declare their own. Two consequences, both fixed by having one home:
+*
+* 1. **Two distinct layer references build twice.** Layer memoization is by
+*    reference, so a second `Layer.mergeAll(NodeFileSystem.layer, Path.layer)`
+*    is a different layer as far as the memo map is concerned, and the XDG
+*    resolution ran once per consumer.
+* 2. **The namespace literal was copy-pasted.** The house style bans exactly
+*    this: when two sibling layers must agree on an identity string, the
+*    agreement has to be structural rather than textual. A drift here is
+*    silent and permanent — the caches move to a different directory, every
+*    lookup misses, and a build that should hit a warm Twoslash cache goes
+*    cold forever with no error and nothing in the output to notice.
+*
+* @packageDocumentation
+*/
+/**
+* The XDG namespace every cache this plugin keeps lives under.
+*
+* @remarks
+* One definition, deliberately. Changing it invalidates every on-disk cache —
+* the type registry's `metadata.sqlite` and the Twoslash result cache's
+* `twoslash.sqlite` — which is a cold refetch and a full re-type-check, not an
+* error. That was accepted once, at the phase-2 rename from
+* `type-registry-effect`; do not do it casually.
+*/
+const TSDOCTOR_NAMESPACE = "tsdoctor";
+/** Node platform services: the filesystem and path implementations. */
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, Path.layer);
+/** XDG application directories rooted at {@link TSDOCTOR_NAMESPACE}. */
+const AppDirsLive = AppDirs.layer({ namespace: TSDOCTOR_NAMESPACE }).pipe(Layer.provide(Layer.mergeAll(Xdg.layer, PlatformLive)));
+
+//#endregion
+export { AppDirsLive, PlatformLive, TSDOCTOR_NAMESPACE };

package/markdown/helpers.js

@@ -4,7 +4,6 @@ import { formatCode } from "../prettier-formatter.js";
 import { TypeReferenceExtractor } from "../type-reference-extractor.js";
 
 //#region src/markdown/helpers.ts
-/* v8 ignore start -- markdown generation helpers, tested via page generator integration tests */
 /**
 * Helper utilities for generating markdown API documentation.
 *
@@ -50,63 +49,18 @@ function prepareExampleCode(example, apiItemName, packageName, suppressErrors =
 	};
 }
 /**
-* Sanitize a display name to create a URL-safe HTML ID.
-*
-* Converts a display name (e.g., method or property name) into a valid
-* HTML ID suitable for anchor links. Handles special characters, quotes,
-* and optionally adds a prefix for disambiguation.
-*
-* @param displayName - The original display name
-* @param prefix - Optional prefix to add (e.g., "static-property")
-* @returns URL-safe ID string
-*
-* @example
-* ```ts
-* sanitizeId("myMethod");        // "mymethod"
-* sanitizeId("get value");       // "get-value"
-* sanitizeId("run", "static");   // "static-run"
-* ```
-*/
-function sanitizeId(displayName, prefix = "") {
-	const baseName = displayName.replace(/["']/g, "").replace(/[^\w-]/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
-	return prefix ? `${prefix}-${baseName}` : baseName;
-}
-/**
-* Escape a YAML string value by handling special characters.
-*
-* Normalizes whitespace and wraps strings in double quotes if they contain
-* characters that could break YAML parsing (colons, quotes, hashes, pipes,
-* brackets, braces, Unicode characters, etc.).
-*
-* @param value - The string value to escape
-* @returns YAML-safe string
-*
-* @example
-* ```ts
-* escapeYamlString("Hello World");           // "Hello World"
-* escapeYamlString("Type: string");          // "\"Type: string\""
-* escapeYamlString("He said \"hello\"");     // "\"He said \\\"hello\\\"\""
-* escapeYamlString("@pkg/name。:");          // "\"@pkg/name。:\""
-* ```
-*/
-/**
-* Normalize a string for use as a YAML frontmatter value: collapse newlines
-* and repeated whitespace to single spaces and trim.
-*
-* This is the cleaning half of the former hand-rolled YAML escaping. It is
-* applied to every frontmatter value BEFORE serialization so the parsed data
-* (and therefore the snapshot frontmatter hash — see `@tsdoctor/snapshot`)
-* is byte-identical to what the previous emitter produced; the quoting half
-* is now owned by the real YAML emitter in `../frontmatter.ts`.
+* Collapse newlines and runs of whitespace to single spaces, and trim.
+*
+* @remarks
+* Applied to every frontmatter scalar before emission. This is NOT quoting —
+* `@effected/yaml` owns that — it is whitespace normalization, and it is
+* load-bearing: the snapshot system hashes the PARSED frontmatter, so a value
+* that folds differently between builds would churn the hash. Survives the
+* removal of `escapeYamlString`, which was its other caller.
 */
 function cleanYamlValue(value) {
 	return value.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
 }
-function escapeYamlString(value) {
-	const cleaned = cleanYamlValue(value);
-	if (/["':#|>&*!%@`[\]{},?-]/.test(cleaned) || /[\u0080-\uFFFF]/.test(cleaned) || /^(true|false|null|~|yes|no|on|off)$/i.test(cleaned) || /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(cleaned)) return `"${cleaned.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
-	return cleaned;
-}
 /**
 * Escape generic type parameters in MDX by wrapping them in backticks.
 *
@@ -334,4 +288,4 @@ async function formatExampleCode(code, language, _context) {
 }
 
 //#endregion
-export { escapeMdxGenerics, escapeYamlString, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, sanitizeId, stripTwoslashDirectives };
+export { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives };