vitepress-plugin-api-extractor 0.1.0

package/ApiExtractor.js

@@ -0,0 +1,96 @@
+import { PlatformLive, RegistryLive } from "./Registry.js";
+import { generate } from "./Generate.js";
+import { environmentHash, makeTwoslashTransformer } from "./Twoslash.js";
+import { TwoslashCacheStore } from "./TwoslashCache.js";
+import { Effect, Layer, ManagedRuntime } from "effect";
+
+//#region src/ApiExtractor.ts
+/**
+* The public helper a site's `.vitepress/config.mts` awaits at config-load
+* time: generates the pages, opens the Twoslash result cache and returns the
+* sidebar, the code transformer and the `buildEnd` hook that persists the
+* cache.
+*
+* @remarks
+* Generation happens HERE, at config load, because VitePress has no
+* pre-scan hook comparable to RSPress's `config()`: its config file is ESM
+* and may top-level await, and `buildEnd` / `postRender` run after the fact.
+* The result is merged into `defineConfig` by the site.
+*
+* @packageDocumentation
+*/
+const AppLive = Layer.mergeAll(PlatformLive, RegistryLive, TwoslashCacheStore.layer);
+/**
+* Generate the API pages and return what the site's config needs.
+*
+* @example
+* ```ts
+* // .vitepress/config.mts
+* import { defineConfig } from "vitepress";
+* import { apiExtractor } from "vitepress-plugin-api-extractor";
+*
+* const api = await apiExtractor({ dir: "./lib/models/kitchensink" });
+*
+* export default defineConfig({
+*   themeConfig: { sidebar: api.sidebar },
+*   markdown: { codeTransformers: [...api.codeTransformers] },
+*   buildEnd: async () => { await api.hooks.buildEnd(); },
+* });
+* ```
+*
+* @public
+*/
+async function apiExtractor(options) {
+	const runtime = ManagedRuntime.make(AppLive);
+	const cwd = options.cwd ?? process.cwd();
+	const log = options.log ?? true;
+	const generated = await runtime.runPromise(generate({
+		dir: options.dir,
+		cwd,
+		docsDir: options.docsDir ?? "docs",
+		baseRoute: options.baseRoute ?? "/api",
+		apiName: options.name,
+		siteOrigin: options.siteOrigin,
+		base: options.base,
+		categories: options.categories,
+		externalPackages: options.externalPackages,
+		suppressExampleErrors: options.suppressExampleErrors,
+		source: options.source
+	}));
+	const envHash = environmentHash(generated.vfs);
+	const typesCache = await runtime.runPromise(Effect.gen(function* () {
+		return yield* (yield* TwoslashCacheStore).open(envHash);
+	}));
+	const transformer = makeTwoslashTransformer({
+		vfs: generated.vfs,
+		compilerOptions: generated.compilerOptions,
+		typesCache
+	});
+	if (log) {
+		const external = generated.externalTypes.loaded.length > 0 ? `, ${generated.externalTypes.loaded.length} external package(s)` : "";
+		console.log(`[vitepress-plugin-api-extractor] ${generated.packageName}: ${generated.routes.length} pages under ${generated.baseRoute}, ${generated.vfs.size} declaration files${external}, twoslash cache ${typesCache.stats().entries} entries`);
+		if (generated.externalTypes.warning) console.warn(`[vitepress-plugin-api-extractor] external types degraded: ${generated.externalTypes.warning}`);
+		for (const name of generated.uncategorized) console.warn(`[vitepress-plugin-api-extractor] skipped ${name}: no category matched`);
+	}
+	let persisted;
+	const buildEnd = () => {
+		persisted ??= runtime.runPromise(Effect.gen(function* () {
+			const report = yield* (yield* TwoslashCacheStore).persist();
+			return report._tag === "Some" ? report.value : void 0;
+		})).then(async (report) => {
+			if (log && report) console.log(`[vitepress-plugin-api-extractor] twoslash cache: ${report.hits} hit(s), ${report.misses} miss(es), ${report.entries} entries${report.dirty ? " (saved)" : ""}${report.degraded ? " (degraded)" : ""}`);
+			await runtime.dispose();
+			return report;
+		});
+		return persisted;
+	};
+	return {
+		sidebar: generated.sidebar,
+		codeTransformers: [transformer],
+		hooks: { buildEnd },
+		generated
+	};
+}
+
+//#endregion
+export { apiExtractor };

package/Categories.js

@@ -0,0 +1,49 @@
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+
+//#region src/Categories.ts
+/**
+* The default category set: one group per API item kind, with the folder,
+* singular name and sidebar presentation each carries.
+*
+* @remarks
+* The same seven categories the RSPress plugin's `DEFAULT_CATEGORIES`
+* declares, so both adapters generate the same routes from the same bundle.
+* A shared home for the defaults is a Tier 2 candidate; until then keep the
+* two in step.
+*
+* @packageDocumentation
+*/
+const category = (displayName, singularName, folderName, kind) => ({
+	displayName,
+	singularName,
+	folderName,
+	itemKinds: [kind],
+	collapsible: true,
+	collapsed: true
+});
+/**
+* The default categories, in sidebar order.
+*
+* @public
+*/
+const DEFAULT_CATEGORIES = {
+	classes: category("Classes", "Class", "class", ApiItemKind.Class),
+	interfaces: category("Interfaces", "Interface", "interface", ApiItemKind.Interface),
+	functions: category("Functions", "Function", "function", ApiItemKind.Function),
+	types: category("Types", "Type", "type", ApiItemKind.TypeAlias),
+	enums: category("Enums", "Enum", "enum", ApiItemKind.Enum),
+	variables: category("Variables", "Variable", "variable", ApiItemKind.Variable),
+	namespaces: category("Namespaces", "Namespace", "namespace", ApiItemKind.Namespace)
+};
+/** The navigation-tree view of a category. */
+function navCategory(config) {
+	return {
+		displayName: config.displayName,
+		folderName: config.folderName,
+		...config.collapsible !== void 0 ? { collapsible: config.collapsible } : {},
+		...config.collapsed !== void 0 ? { collapsed: config.collapsed } : {}
+	};
+}
+
+//#endregion
+export { DEFAULT_CATEGORIES, navCategory };

package/Generate.js

@@ -0,0 +1,220 @@
+import { DEFAULT_CATEGORIES, navCategory } from "./Categories.js";
+import { emitFrontmatter } from "./emit/frontmatter.js";
+import { emitMarkdownBody } from "./emit/markdown.js";
+import { sidebarFor } from "./emit/sidebar.js";
+import { externalPackagesOf, loadExternalTypes } from "./Registry.js";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { PackageManifest } from "@effected/package-json";
+import { discoverBundle } from "@tsdoctor/bundle";
+import { ApiExtractedPackage, CrossLinker, Model, TypeReferenceExtractor } from "@tsdoctor/model";
+import { buildIndexPage, buildNav, buildPage, prepareWorkItems } from "@tsdoctor/pages";
+import { attributionFacts, deriveScriptBody, deriveSiteUrl, headTags, packageContext } from "@tsdoctor/seo";
+import { resolveTypeScriptConfig } from "@tsdoctor/vfs";
+
+//#region src/Generate.ts
+/**
+* The generation program: discover the bundle, load the model, build the
+* virtual file system and compiler options, lift every item into a
+* `@tsdoctor/pages` `Page`, emit it as VitePress markdown and write it under
+* the site's source directory.
+*
+* @remarks
+* This is the minimal path for the alpha. The RSPress plugin runs the same
+* sequence inside its `ConfigService` (`layers/config-resolution.ts`), which
+* is adapter-shaped — events, metrics, the multi-API and multi-version
+* cascades — so the neutral parts are re-spelled here rather than extracted;
+* the duplication (model → VFS → import prepending, dependency extraction,
+* compiler-option resolution) is the recorded Tier 2 item. Every file is
+* written unconditionally: snapshot-tracked incremental writes are not
+* wired for the alpha.
+*
+* @packageDocumentation
+*/
+/**
+* Prepend `import type` statements for external references to each entry
+* point's declaration file, in place.
+*/
+function prependImportsToVfs(vfs, apiPackage, packageName) {
+	const extractor = new TypeReferenceExtractor(apiPackage, packageName);
+	for (const entryPoint of apiPackage.entryPoints) {
+		const entry = entryPoint;
+		const statements = TypeReferenceExtractor.formatImports(extractor.extractImportsForEntryPoint(entry));
+		if (statements.length === 0) continue;
+		const file = `node_modules/${packageName}/${entry.displayName ? `${entry.displayName}.d.ts` : "index.d.ts"}`;
+		const existing = vfs.get(file);
+		if (existing) vfs.set(file, `${statements.join("\n")}\n\n${existing}`);
+	}
+}
+function resolveCategories(overrides) {
+	const result = { ...DEFAULT_CATEGORIES };
+	for (const [key, override] of Object.entries(overrides ?? {})) {
+		const base = result[key];
+		if (base) result[key] = {
+			...base,
+			...override
+		};
+		else if (override.displayName && override.singularName && override.folderName) result[key] = override;
+	}
+	return result;
+}
+/** The file a route is written to under `docsDir`. */
+const fileFor = (docsDir, route) => `${docsDir}${route}.md`;
+/**
+* Generate the API pages for one bundle.
+*
+* @remarks
+* Fails typed on what a user can fix — a missing bundle folder, an
+* unreadable model — and degrades on what is an enhancement (external types,
+* a manifest the SEO layer cannot decode, an example Prettier rejects). The
+* error channel is the union of `@tsdoctor/bundle`'s discovery errors,
+* `@tsdoctor/model`'s load errors and the platform's write errors.
+*
+* @public
+*/
+const generate = Effect.fn("Generate.generate")(function* (input) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const descriptor = yield* discoverBundle(input.dir, { cwd: input.cwd });
+	const apiPackage = yield* Model.load(descriptor.modelPath);
+	const packageName = descriptor.name;
+	const packageJson = descriptor.packageJsonPath === void 0 ? void 0 : yield* fs.readFileString(descriptor.packageJsonPath).pipe(Effect.map((text) => JSON.parse(text)), Effect.orElseSucceed(() => void 0));
+	const manifest = packageJson === void 0 ? void 0 : yield* decodeManifest(packageJson);
+	const vfs = ApiExtractedPackage.fromPackage(apiPackage, packageName).toVfs();
+	prependImportsToVfs(vfs, apiPackage, packageName);
+	const externalTypes = yield* loadExternalTypes(vfs, input.externalPackages ?? externalPackagesOf(packageJson), /* @__PURE__ */ new Set([packageName]));
+	const compilerOptions = yield* Effect.promise(() => resolveTypeScriptConfig(descriptor.dir, void 0, descriptor.tsconfigPath === void 0 ? void 0 : { tsconfig: descriptor.tsconfigPath }));
+	const categories = resolveCategories(input.categories);
+	const prepared = prepareWorkItems({
+		apiPackage,
+		categories,
+		baseRoute: input.baseRoute
+	});
+	if (prepared.collisions.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`route collisions under ${input.baseRoute}: ${prepared.collisions.map((c) => `${c.route} <- ${c.items.map((i) => i.displayName).join(", ")}`).join("; ")}`));
+	const linker = CrossLinker.fromRoutes(prepared.crossLinkData.routes);
+	const siteUrl = deriveSiteUrl(input.siteOrigin, input.base);
+	const structuredDataPkg = manifest === void 0 ? void 0 : packageContext({
+		siteUrl,
+		baseRoute: input.baseRoute,
+		packageName,
+		...manifest.version != null ? { version: manifest.version.toString() } : {},
+		...manifest.description != null ? { description: manifest.description } : {},
+		attribution: attributionFacts(manifest)
+	});
+	const buildTime = (/* @__PURE__ */ new Date()).toISOString();
+	const docsDir = path.resolve(input.cwd, input.docsDir);
+	const entries = [];
+	const routes = [];
+	const formatFailures = [];
+	for (const workItem of prepared.workItems) {
+		const written = yield* writePage(workItem, {
+			input,
+			packageName,
+			linker,
+			siteUrl,
+			structuredDataPkg,
+			buildTime,
+			docsDir,
+			onFormatFailure: (route) => formatFailures.push(route)
+		});
+		if (Option.isSome(written)) {
+			entries.push(written.value.nav);
+			routes.push(written.value.route);
+		}
+	}
+	const nav = buildNav({
+		baseRoute: input.baseRoute,
+		categories: Object.fromEntries(Object.entries(categories).map(([key, config]) => [key, navCategory(config)])),
+		entries
+	});
+	const index = buildIndexPage({
+		packageName,
+		baseRoute: input.baseRoute
+	});
+	const indexBody = [
+		`# ${index.title}`,
+		"",
+		index.description,
+		"",
+		...nav.groups.flatMap((group) => [
+			`## ${group.category.displayName}`,
+			"",
+			...group.pages.map((page) => `- [${page.label}](${page.route})`),
+			""
+		])
+	].join("\n");
+	yield* writeFile(fs, path, fileFor(docsDir, `${input.baseRoute}/index`), emitFrontmatter(index) + indexBody);
+	return {
+		packageName,
+		baseRoute: input.baseRoute,
+		sidebar: sidebarFor(nav),
+		vfs,
+		compilerOptions,
+		routes,
+		crossLinkData: prepared.crossLinkData,
+		externalTypes,
+		uncategorized: prepared.uncategorized.map((item) => item.displayName),
+		formatFailures
+	};
+});
+const writePage = Effect.fn("Generate.writePage")(function* (workItem, ctx) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const { item, categoryConfig } = workItem;
+	const built = yield* buildPage({
+		item,
+		categoryKey: workItem.categoryKey,
+		singularName: categoryConfig.singularName,
+		folderName: categoryConfig.folderName,
+		baseRoute: ctx.input.baseRoute,
+		packageName: ctx.packageName,
+		apiName: ctx.input.apiName,
+		namespaceMember: workItem.namespaceMember,
+		availableFrom: workItem.availableFrom,
+		syntheticBase: workItem.syntheticBase,
+		memberAnchors: workItem.memberAnchors,
+		source: ctx.input.source,
+		suppressExampleErrors: ctx.input.suppressExampleErrors,
+		linker: ctx.linker,
+		onExampleFormatError: () => Effect.sync(() => ctx.onFormatFailure(item.displayName))
+	});
+	if (Option.isNone(built)) return Option.none();
+	const page = built.value;
+	const structuredData = ctx.structuredDataPkg === void 0 ? void 0 : deriveScriptBody(ctx.structuredDataPkg, {
+		pageRoute: page.route,
+		symbolName: item.displayName,
+		description: page.description,
+		section: categoryConfig.displayName,
+		publishedTime: ctx.buildTime,
+		modifiedTime: ctx.buildTime
+	});
+	const tags = headTags({
+		siteUrl: ctx.siteUrl,
+		pageRoute: page.route,
+		description: page.description,
+		publishedTime: ctx.buildTime,
+		modifiedTime: ctx.buildTime,
+		section: categoryConfig.displayName,
+		packageName: ctx.packageName,
+		...structuredData !== void 0 && structuredData._tag === "Success" ? { structuredData: structuredData.success } : {}
+	});
+	const body = yield* Effect.fromResult(emitMarkdownBody(page)).pipe(Effect.orDie);
+	const content = emitFrontmatter({
+		title: page.title,
+		description: page.description,
+		headTags: tags
+	}) + body;
+	yield* writeFile(fs, path, fileFor(ctx.docsDir, page.route), content);
+	return Option.some({
+		route: page.route,
+		nav: page.nav
+	});
+});
+function writeFile(fs, path, file, content) {
+	return fs.makeDirectory(path.dirname(file), { recursive: true }).pipe(Effect.andThen(fs.writeFileString(file, content)));
+}
+function decodeManifest(packageJson) {
+	return PackageManifest.decode(packageJson).pipe(Effect.map((manifest) => manifest), Effect.orElseSucceed(() => void 0));
+}
+
+//#endregion
+export { generate };

package/Registry.js

@@ -0,0 +1,117 @@
+import { Effect, Layer, Path } from "effect";
+import { NodeFileSystem, NodeHttpClient } from "@effect/platform-node";
+import { Cache } from "@effected/store";
+import { AppDirs, Xdg } from "@effected/xdg";
+import { PackageFetcher, PackageSpec, RegistryObserver, TypeCache, TypeRegistry } from "@tsdoctor/registry";
+
+//#region src/Registry.ts
+/**
+* External type loading: the `@tsdoctor/registry` stack over the same XDG
+* cache the RSPress plugin uses, and the degrading merge of a documented
+* package's dependencies into the build's virtual file system.
+*
+* @remarks
+* External types are an enhancement — without them code blocks type-check
+* without their dependencies' declarations, which is a worse page rather
+* than a broken build — so every failure here degrades to "no external
+* types" and is reported as a warning the caller may print.
+*
+* @packageDocumentation
+*/
+/**
+* The XDG namespace every tsdoctor cache lives under — shared with the
+* RSPress plugin so both adapters read one type cache and one Twoslash
+* result cache.
+*
+* @public
+*/
+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)));
+/** 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)), Cache.degrading);
+/** The registry emits no logs of its own; this adapter listens to nothing yet. */
+const RegistryObserverLive = Layer.succeed(RegistryObserver, { emit: () => Effect.void });
+/**
+* The full registry runtime: `TypeRegistry` over an XDG-rooted `TypeCache`
+* and the jsDelivr `PackageFetcher`. Bound to a const so the stack builds
+* once per runtime.
+*
+* @public
+*/
+const RegistryLive = TypeRegistry.layer.pipe(Layer.provideMerge(Layer.mergeAll(TypeCache.layerXdg(), PackageFetcher.layer)), Layer.provideMerge(RegistryObserverLive), Layer.provide(Layer.mergeAll(MetadataCacheLive, AppDirsLive, PlatformLive, NodeHttpClient.layerUndici)), Layer.orDie);
+/**
+* The dependency-field names `package.json` declares packages under.
+*/
+const DEPENDENCY_FIELDS = ["dependencies", "peerDependencies"];
+/**
+* The external packages a documented package's manifest declares, in the
+* `dependencies` and `peerDependencies` fields.
+*
+* @public
+*/
+function externalPackagesOf(packageJson) {
+	if (packageJson === void 0) return [];
+	const packages = [];
+	for (const field of DEPENDENCY_FIELDS) {
+		const entries = packageJson[field];
+		if (entries === null || typeof entries !== "object") continue;
+		for (const [name, version] of Object.entries(entries)) if (typeof version === "string" && !version.startsWith("workspace:") && !version.startsWith("catalog:")) packages.push({
+			name,
+			version
+		});
+	}
+	return packages;
+}
+/**
+* Resolve each package to an exact published version and merge its
+* declarations into `vfs`, in place. First-party packages (the ones being
+* documented) are excluded: their api.json-derived declarations are
+* authoritative and a published copy would clobber them.
+*
+* @remarks
+* Degrades, never fails: an unresolvable package is skipped, and an
+* infrastructure failure (no HOME for XDG, an unreachable CDN) leaves the
+* VFS as it was with a `warning` in the report.
+*
+* @public
+*/
+const loadExternalTypes = Effect.fn("Registry.loadExternalTypes")(function* (vfs, packages, documented) {
+	const candidates = packages.filter((pkg) => !documented.has(pkg.name));
+	if (candidates.length === 0) return {
+		loaded: [],
+		skipped: []
+	};
+	const registry = yield* TypeRegistry;
+	const resolved = yield* Effect.forEach(candidates, (pkg) => registry.resolveVersion(pkg.name, pkg.version).pipe(Effect.map((version) => new PackageSpec({
+		name: pkg.name,
+		version
+	})), Effect.catch(() => Effect.succeed(null))), { concurrency: 5 });
+	const specs = resolved.filter((spec) => spec !== null);
+	const skipped = candidates.filter((_, index) => resolved[index] === null).map((pkg) => pkg.name);
+	if (specs.length === 0) return {
+		loaded: [],
+		skipped
+	};
+	const result = yield* Effect.result(registry.getVfs(specs, { autoFetch: true }));
+	if (result._tag === "Failure") return {
+		loaded: [],
+		skipped: [...skipped, ...specs.map((spec) => spec.name)],
+		warning: result.failure.message
+	};
+	for (const [file, content] of result.success.entries()) vfs.set(file, content);
+	return {
+		loaded: specs.map((spec) => spec.name),
+		skipped
+	};
+});
+
+//#endregion
+export { AppDirsLive, PlatformLive, RegistryLive, TSDOCTOR_NAMESPACE, externalPackagesOf, loadExternalTypes };

package/Twoslash.js

@@ -0,0 +1,43 @@
+import { DEFAULT_COMPILER_OPTIONS, toProgrammaticCompilerOptions, twoslashEnvHash } from "@tsdoctor/vfs";
+import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
+import ts from "typescript";
+
+//#region src/Twoslash.ts
+/**
+* Fingerprint the type environment: the declarations plus the compiler that
+* interprets them, so a generation cached by one TypeScript is never served
+* by another.
+*
+* @public
+*/
+function environmentHash(vfs) {
+	return twoslashEnvHash(vfs, `typescript@${ts.version}`);
+}
+/**
+* Build the Shiki transformer for VitePress's `markdown.codeTransformers`.
+*
+* @remarks
+* Errors never throw: `noErrorValidation` lets a diagnostic render as an
+* annotation, and `throws: false` keeps `@shikijs/vitepress-twoslash` from
+* failing the build on one (it would, by default, on CI). Examples are
+* documentation, not a test suite.
+*
+* @public
+*/
+function makeTwoslashTransformer(options) {
+	const extraFiles = {};
+	for (const [path, content] of options.vfs.entries()) extraFiles[path] = content;
+	const compilerOptions = toProgrammaticCompilerOptions(options.compilerOptions ?? DEFAULT_COMPILER_OPTIONS);
+	return transformerTwoslash({
+		...options.typesCache != null ? { typesCache: options.typesCache } : {},
+		twoslashOptions: {
+			extraFiles,
+			compilerOptions,
+			handbookOptions: { noErrorValidation: true }
+		},
+		throws: false
+	});
+}
+
+//#endregion
+export { environmentHash, makeTwoslashTransformer };

package/TwoslashCache.js

@@ -0,0 +1,102 @@
+import { AppDirsLive, PlatformLive } from "./Registry.js";
+import { Context, Effect, Layer, Option, Path } from "effect";
+import { decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey } from "@tsdoctor/vfs";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
+
+//#region src/TwoslashCache.ts
+/**
+* Persistence for the Twoslash result cache: one gzipped generation per type
+* environment in a sqlite-backed `@effected/store` Cache under the XDG cache
+* dir — the same `twoslash.sqlite` and the same blob keys the RSPress plugin
+* writes, so a site built by either adapter warms the other.
+*
+* @remarks
+* `TwoslashTypesCache.read`/`write` are synchronous (Shiki calls them inside
+* its `preprocess` hook), so persistence is load-once before generation and
+* save-once after the site build; every lookup in between is an in-memory
+* map hit. Both operations degrade: a cache that cannot be read is a cache
+* miss, and one that cannot be written loses nothing but the next warm start.
+*
+* @packageDocumentation
+*/
+/**
+* A sqlite-backed Cache in the XDG cache dir, separate from the registry's
+* `metadata.sqlite`. Degrading: an unusable cache directory yields a cache
+* that always misses rather than a failed build.
+*/
+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)), Cache.degrading);
+/**
+* The Twoslash generation store.
+*
+* @public
+*/
+var TwoslashCacheStore = class extends Context.Service()("vitepress-plugin-api-extractor/TwoslashCacheStore") {
+	/**
+	* The live store over the XDG sqlite cache.
+	*
+	* @remarks
+	* `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(() => StoreLive);
+	/** An always-cold in-memory store, for tests. */
+	static layerTest = Layer.sync(this, () => {
+		let open = null;
+		return {
+			open: (envHash) => Effect.sync(() => {
+				const cache = makeTwoslashCache();
+				open = {
+					cache,
+					envHash
+				};
+				return cache;
+			}),
+			persist: () => Effect.sync(() => open === null ? Option.none() : Option.some({
+				...open.cache.stats(),
+				envHash: open.envHash,
+				degraded: false
+			}))
+		};
+	});
+};
+const StoreLive = Layer.effect(TwoslashCacheStore, Effect.gen(function* () {
+	const store = yield* Cache;
+	let open = null;
+	return {
+		open: (envHash) => store.get(twoslashBlobKey(envHash)).pipe(Effect.map((entry) => Option.isSome(entry) ? decodeTwoslashCache(entry.value.value) : /* @__PURE__ */ new Map()), Effect.catch(() => Effect.succeed(/* @__PURE__ */ new Map())), 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,
+				degraded: store.degraded
+			});
+			if (!stats.dirty) return Effect.succeed(report);
+			return store.set({
+				key: twoslashBlobKey(envHash),
+				value: encodeTwoslashCache(cache.entries()),
+				tags: ["twoslash"]
+			}).pipe(Effect.catch(() => Effect.void), Effect.as(report));
+		})
+	};
+})).pipe(Layer.provide(CacheLive));
+
+//#endregion
+export { TwoslashCacheStore };

package/emit/frontmatter.js

@@ -0,0 +1,58 @@
+import { emitFrontmatterBlock } from "@tsdoctor/model";
+
+//#region src/emit/frontmatter.ts
+/**
+* Frontmatter assembly for generated pages: the page title and description
+* plus the neutral `@tsdoctor/seo` head tags rendered into VitePress's
+* `HeadConfig` shape.
+*
+* @remarks
+* Adapter-side on purpose — the IR carries facts and a `HeadTag[]`, not a
+* block. VitePress spells a `meta`/`link` tag as a `[tag, attrs]` pair and a
+* script body as the `[tag, attrs, innerHTML]` TRIPLE; RSPress spells the
+* same body as a `children` attribute. That one difference is why assembly
+* is not shared.
+*
+* @packageDocumentation
+*/
+/**
+* Collapse newlines and runs of whitespace to single spaces, and trim.
+*
+* @remarks
+* Whitespace normalization, not quoting — `@effected/yaml` owns quoting.
+*/
+function cleanValue(value) {
+	return value.replace(/[\r\n]+/g, " ").replace(/\s+/g, " ").trim();
+}
+/**
+* Render a neutral head tag into VitePress's `HeadConfig` entry.
+*
+* @public
+*/
+function headConfig(tag) {
+	const attrs = {};
+	for (const [key, value] of Object.entries(tag.attrs)) attrs[key] = cleanValue(value);
+	return tag.body != null ? [
+		tag.tag,
+		attrs,
+		cleanValue(tag.body)
+	] : [tag.tag, attrs];
+}
+/**
+* Emit the frontmatter block for a page: `title`, `description` and, when
+* the page carries any, `head` in VitePress's `HeadConfig[]` shape.
+*
+* @public
+*/
+function emitFrontmatter(input) {
+	const data = {
+		title: cleanValue(input.title),
+		description: cleanValue(input.description)
+	};
+	const head = (input.headTags ?? []).map(headConfig);
+	if (head.length > 0) data.head = head;
+	return emitFrontmatterBlock(data);
+}
+
+//#endregion
+export { emitFrontmatter, headConfig };