rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/build-stages.js

@@ -0,0 +1,664 @@
+import { hashContent, hashFrontmatter } from "./content-hash.js";
+import { BuildMetrics } from "./layers/ObservabilityLive.js";
+import { ApiParser } from "./loader.js";
+import { generateFrontmatter } from "./markdown/helpers.js";
+import { ClassPageGenerator } from "./markdown/page-generators/class-page.js";
+import { EnumPageGenerator } from "./markdown/page-generators/enum-page.js";
+import { FunctionPageGenerator } from "./markdown/page-generators/function-page.js";
+import { MainIndexPageGenerator } from "./markdown/page-generators/index-pages.js";
+import { InterfacePageGenerator } from "./markdown/page-generators/interface-page.js";
+import { NamespacePageGenerator } from "./markdown/page-generators/namespace-page.js";
+import { TypeAliasPageGenerator } from "./markdown/page-generators/type-alias-page.js";
+import { VariablePageGenerator } from "./markdown/page-generators/variable-page.js";
+import "./markdown/index.js";
+import { resolveEntryPoints } from "./multi-entry-resolver.js";
+import { OpenGraphResolver } from "./og-resolver.js";
+import { assertNoRouteCollisions } from "./route-collisions.js";
+import { SnapshotService } from "./services/SnapshotService.js";
+import path from "node:path";
+import { Effect, Metric, Stream } from "effect";
+import { FileSystem } from "@effect/platform";
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+import matter from "gray-matter";
+
+//#region src/build-stages.ts
+/**
+* Cross-link priority by API item kind (lower = higher priority). When a bare
+* name maps to multiple pages (the const+type companion pattern), the bare
+* cross-link resolves to the higher-priority kind — value declarations win over
+* type-only declarations, so `Foo` links to the importable schema, not the type.
+*/
+const CROSS_LINK_KIND_PRIORITY = {
+	Class: 0,
+	Function: 1,
+	Variable: 2,
+	Enum: 3,
+	Interface: 4,
+	TypeAlias: 5,
+	Namespace: 6
+};
+/** Lower number = higher priority for which page a bare cross-link name resolves to. */
+function crossLinkKindPriority(kind) {
+	return CROSS_LINK_KIND_PRIORITY[kind] ?? 100;
+}
+/**
+* Sanitize a display name to create a valid HTML ID.
+* Mirrors the logic in MarkdownCrossLinker.sanitizeId().
+*/
+function sanitizeId(displayName) {
+	return displayName.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/^-+|-+$/g, "");
+}
+/**
+* Prepare the flat list of WorkItems to process and the cross-link data maps.
+*
+* This function:
+* 1. Categorizes API items from the model
+* 2. Builds cross-link routes and kinds maps (replicating MarkdownCrossLinker.initialize())
+* 3. Extracts namespace members and adds their routes (with collision detection)
+* 4. Flattens all items into a single WorkItem[]
+*
+* NOTE: This function does NOT call the markdownCrossLinker singleton. The caller
+* is responsible for passing the returned crossLinkData to the cross-linker and
+* Shiki cross-linker as needed.
+*/
+function prepareWorkItems(input) {
+	const { apiPackage, categories, baseRoute } = input;
+	const resolvedItems = resolveEntryPoints(apiPackage);
+	const resolvedLookup = /* @__PURE__ */ new Map();
+	for (const resolved of resolvedItems) {
+		const key = `${resolved.item.displayName}::${resolved.item.kind}`;
+		resolvedLookup.set(key, resolved);
+	}
+	const items = ApiParser.categorizeApiItems(resolvedItems, categories);
+	const namespaceMembers = ApiParser.extractNamespaceMembers(resolvedItems);
+	const candidates = [];
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) candidates.push({
+		id: `${item.displayName}::${item.kind}`,
+		displayName: item.displayName,
+		folder: categoryConfig.folderName,
+		baseName: item.displayName.toLowerCase(),
+		kind: String(item.kind),
+		canonicalRef: item.canonicalReference?.toString() ?? item.displayName
+	});
+	for (const nsMember of namespaceMembers) {
+		const nsCategoryEntry = Object.entries(categories).find(([, config]) => config.itemKinds?.includes(nsMember.item.kind));
+		if (!nsCategoryEntry) continue;
+		const [, nsCategoryConfig] = nsCategoryEntry;
+		candidates.push({
+			id: nsMember.qualifiedName,
+			displayName: nsMember.qualifiedName,
+			folder: nsCategoryConfig.folderName,
+			baseName: nsMember.qualifiedName.toLowerCase(),
+			kind: String(nsMember.item.kind),
+			canonicalRef: nsMember.item.canonicalReference?.toString() ?? nsMember.qualifiedName
+		});
+	}
+	assertNoRouteCollisions(candidates, baseRoute);
+	const routes = /* @__PURE__ */ new Map();
+	const kinds = /* @__PURE__ */ new Map();
+	const routeOwnerPriority = /* @__PURE__ */ new Map();
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) {
+		const categoryItems = items[categoryKey] || [];
+		for (const item of categoryItems) {
+			const itemRoute = `${baseRoute}/${categoryConfig.folderName}/${item.displayName.toLowerCase()}`;
+			const priority = crossLinkKindPriority(String(item.kind));
+			const existingPriority = routeOwnerPriority.get(item.displayName);
+			if (existingPriority === void 0 || priority < existingPriority) {
+				routes.set(item.displayName, itemRoute);
+				kinds.set(item.displayName, item.kind);
+				routeOwnerPriority.set(item.displayName, priority);
+			}
+			if (item.kind === "Class" || item.kind === "Interface") {
+				const itemWithMembers = item;
+				for (const member of itemWithMembers.members) {
+					const memberName = member.displayName;
+					const memberId = sanitizeId(memberName);
+					const fullMemberName = `${item.displayName}.${memberName}`;
+					const memberRoute = `${itemRoute}#${memberId}`;
+					routes.set(fullMemberName, memberRoute);
+					kinds.set(fullMemberName, member.kind);
+				}
+			}
+		}
+	}
+	const unqualifiedNameCounts = /* @__PURE__ */ new Map();
+	for (const nsMember of namespaceMembers) {
+		const name = nsMember.item.displayName;
+		unqualifiedNameCounts.set(name, (unqualifiedNameCounts.get(name) || 0) + 1);
+	}
+	for (const nsMember of namespaceMembers) {
+		const categoryEntry = Object.entries(categories).find(([, config]) => config.itemKinds?.includes(nsMember.item.kind));
+		if (!categoryEntry) continue;
+		const [, categoryConfig] = categoryEntry;
+		const qualifiedRoute = `${baseRoute}/${categoryConfig.folderName}/${nsMember.qualifiedName.toLowerCase()}`;
+		routes.set(nsMember.qualifiedName, qualifiedRoute);
+		kinds.set(nsMember.qualifiedName, nsMember.item.kind);
+		const displayName = nsMember.item.displayName;
+		if (/^[A-Z]/.test(displayName) && (unqualifiedNameCounts.get(displayName) || 0) <= 1 && !routes.has(displayName)) {
+			routes.set(displayName, qualifiedRoute);
+			kinds.set(displayName, nsMember.item.kind);
+		}
+	}
+	const workItems = [];
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) {
+		const categoryItems = items[categoryKey] || [];
+		for (const item of categoryItems) {
+			const lookupKey = `${item.displayName}::${item.kind}`;
+			const resolved = resolvedLookup.get(lookupKey);
+			workItems.push({
+				item,
+				categoryKey,
+				categoryConfig,
+				...resolved?.availableFrom != null ? { availableFrom: resolved.availableFrom } : {}
+			});
+		}
+	}
+	for (const nsMember of namespaceMembers) {
+		const categoryEntry = Object.entries(categories).find(([, config]) => config.itemKinds?.includes(nsMember.item.kind));
+		if (categoryEntry) {
+			const [categoryKey, categoryConfig] = categoryEntry;
+			workItems.push({
+				item: nsMember.item,
+				categoryKey,
+				categoryConfig,
+				namespaceMember: nsMember
+			});
+		}
+	}
+	return {
+		workItems,
+		crossLinkData: {
+			routes,
+			kinds
+		}
+	};
+}
+/**
+* Normalize markdown spacing by removing excessive blank lines.
+* - Remove extra blank lines between headings and code blocks
+* - Ensure single blank line between sections
+*/
+function normalizeMarkdownSpacing(content) {
+	return content.replace(/\n\n\n+/g, "\n\n").replace(/^(#{1,6}\s+.+?)\n+(?=````)/gm, "$1\n").replace(/^(#{2}\s+.+?)\n\n+/gm, "$1\n\n");
+}
+/**
+* Generate a single page from a work item. Returns null for unsupported kinds.
+*/
+function generateSinglePage(workItem, ctx) {
+	return Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem;
+		const { existingSnapshots, baseRoute, packageName, apiScope, apiName, source, buildTime, resolvedOutputDir, suppressExampleErrors, llmsPlugin } = ctx;
+		const { item, categoryConfig, namespaceMember } = workItem;
+		let page = null;
+		switch (item.kind) {
+			case ApiItemKind.Class: {
+				const generator = new ClassPageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/class/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			case ApiItemKind.Interface: {
+				const generator = new InterfacePageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/interface/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			case ApiItemKind.Function: {
+				const generator = new FunctionPageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/function/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			case ApiItemKind.TypeAlias: {
+				const generator = new TypeAliasPageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/type/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			case ApiItemKind.Enum: {
+				const generator = new EnumPageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/enum/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			case ApiItemKind.Variable: {
+				const generator = new VariablePageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/variable/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			case ApiItemKind.Namespace: {
+				const generator = new NamespacePageGenerator();
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom));
+				page = {
+					routePath: page.routePath.replace("/namespace/", `/${categoryConfig.folderName}/`),
+					content: page.content
+				};
+				break;
+			}
+			default:
+				yield* Effect.logDebug(`Skipping item "${item.displayName}" with unsupported kind: ${item.kind} (${ApiItemKind[item.kind] || "unknown"}) in category "${categoryConfig.displayName}"`);
+				return null;
+		}
+		if (!page) return null;
+		if (namespaceMember) {
+			const simpleName = item.displayName.toLowerCase();
+			const qualifiedNameLower = namespaceMember.qualifiedName.toLowerCase();
+			page = {
+				routePath: page.routePath.replace(`/${simpleName}`, `/${qualifiedNameLower}`),
+				content: page.content
+			};
+		}
+		yield* Metric.increment(BuildMetrics.pagesGenerated);
+		const parsed = matter(page.content);
+		const bodyContent = normalizeMarkdownSpacing(parsed.content);
+		const frontmatterData = parsed.data;
+		const relativePathWithExt = `${page.routePath.replace(baseRoute, "").replace(/^\//, "")}.mdx`;
+		const contentHash = hashContent(bodyContent);
+		const frontmatterHash = hashFrontmatter(frontmatterData);
+		let publishedTime;
+		let modifiedTime;
+		let isUnchanged = false;
+		const oldSnapshot = existingSnapshots.get(relativePathWithExt);
+		if (!oldSnapshot) {
+			const absolutePath = path.join(resolvedOutputDir, relativePathWithExt);
+			if (yield* fileSystem.exists(absolutePath).pipe(Effect.orElseSucceed(() => false))) {
+				const existingContent = yield* fileSystem.readFileString(absolutePath).pipe(Effect.orElseSucceed(() => null));
+				if (existingContent !== null) {
+					const { data: existingFrontmatter, content: existingBody } = matter(existingContent);
+					const existingContentHash = hashContent(normalizeMarkdownSpacing(existingBody));
+					const existingFrontmatterHash = hashFrontmatter(existingFrontmatter);
+					if (existingContentHash === contentHash && existingFrontmatterHash === frontmatterHash) {
+						publishedTime = existingFrontmatter["article:published_time"] || buildTime;
+						modifiedTime = existingFrontmatter["article:modified_time"] || buildTime;
+						isUnchanged = true;
+					} else {
+						publishedTime = existingFrontmatter["article:published_time"] || buildTime;
+						modifiedTime = buildTime;
+					}
+				} else {
+					publishedTime = buildTime;
+					modifiedTime = buildTime;
+				}
+			} else {
+				publishedTime = buildTime;
+				modifiedTime = buildTime;
+			}
+		} else if (oldSnapshot.contentHash === contentHash && oldSnapshot.frontmatterHash === frontmatterHash) {
+			publishedTime = oldSnapshot.publishedTime;
+			modifiedTime = oldSnapshot.modifiedTime;
+			isUnchanged = true;
+		} else {
+			publishedTime = oldSnapshot.publishedTime;
+			modifiedTime = buildTime;
+		}
+		return {
+			workItem,
+			content: page.content,
+			bodyContent,
+			frontmatter: frontmatterData,
+			contentHash,
+			frontmatterHash,
+			routePath: page.routePath,
+			relativePathWithExt,
+			publishedTime,
+			modifiedTime,
+			isUnchanged
+		};
+	});
+}
+/**
+* Write a single generated page to disk. No-op for unchanged pages.
+*/
+function writeSingleFile(result, ctx) {
+	return Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem;
+		const { resolvedOutputDir, buildTime, ogResolver, siteUrl, ogImage, packageName, apiName } = ctx;
+		const { workItem, bodyContent, frontmatter, contentHash, frontmatterHash, publishedTime, modifiedTime, isUnchanged, routePath, relativePathWithExt } = result;
+		const { item, categoryKey, categoryConfig, namespaceMember } = workItem;
+		const absolutePath = path.join(resolvedOutputDir, relativePathWithExt);
+		const label = namespaceMember ? namespaceMember.qualifiedName : item.displayName;
+		const snapshot = {
+			outputDir: resolvedOutputDir,
+			filePath: relativePathWithExt,
+			publishedTime,
+			modifiedTime,
+			contentHash,
+			frontmatterHash,
+			buildTime
+		};
+		if (isUnchanged) {
+			yield* Metric.increment(BuildMetrics.filesTotal);
+			yield* Metric.increment(BuildMetrics.filesUnchanged);
+			return {
+				relativePathWithExt,
+				absolutePath,
+				status: "unchanged",
+				snapshot,
+				categoryKey,
+				label,
+				routePath
+			};
+		}
+		let finalContent = matter.stringify(bodyContent, frontmatter);
+		if (ogResolver && siteUrl && packageName) {
+			const ogImageMetadata = yield* Effect.promise(() => ogResolver.resolve(ogImage, packageName, apiName));
+			const ogMetadataOptions = {
+				siteUrl,
+				pageRoute: routePath,
+				description: frontmatter.description,
+				publishedTime,
+				modifiedTime,
+				section: categoryConfig.displayName,
+				packageName
+			};
+			if (ogImageMetadata) ogMetadataOptions.ogImage = ogImageMetadata;
+			const ogMetadata = OpenGraphResolver.createPageMetadata(ogMetadataOptions);
+			finalContent = generateFrontmatter(item.displayName, frontmatter.description, categoryConfig.singularName, apiName, ogMetadata) + bodyContent;
+		}
+		const fileExisted = yield* fileSystem.exists(absolutePath).pipe(Effect.orElseSucceed(() => false));
+		const dirPath = path.dirname(absolutePath);
+		yield* fileSystem.makeDirectory(dirPath, { recursive: true }).pipe(Effect.orDie);
+		yield* fileSystem.writeFileString(absolutePath, finalContent).pipe(Effect.orDie);
+		const status = fileExisted ? "modified" : "new";
+		yield* Metric.increment(BuildMetrics.filesTotal);
+		if (status === "new") yield* Metric.increment(BuildMetrics.filesNew);
+		else yield* Metric.increment(BuildMetrics.filesModified);
+		return {
+			relativePathWithExt,
+			absolutePath,
+			status,
+			snapshot,
+			categoryKey,
+			label,
+			routePath
+		};
+	});
+}
+/**
+* Write all metadata files (_meta.json and index.mdx) for the generated API docs.
+*
+* This function handles three groups of metadata:
+* 1. Root API _meta.json — category folder entries with collapsible/collapsed settings
+* 2. Main index page (index.mdx) — API landing page, skipped if already exists
+* 3. Category _meta.json files — sorted navigation entries per category folder
+*
+* All writes use snapshot tracking (hash comparison, disk fallback, timestamp
+* preservation) to avoid unnecessary disk writes.
+*
+* The `generatedFiles` Set is mutated — entries are added for each metadata file
+* written. This is required for stale file cleanup by the caller.
+*/
+function writeMetadata(input) {
+	return Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem;
+		const snapshotSvc = yield* SnapshotService;
+		const { fileResults, categories, resolvedOutputDir, existingSnapshots, buildTime, baseRoute, packageName, generatedFiles } = input;
+		const categoriesWithItems = /* @__PURE__ */ new Set();
+		for (const result of fileResults) categoriesWithItems.add(result.categoryKey);
+		const apiMetaEntries = [];
+		for (const [categoryKey, categoryConfig] of Object.entries(categories)) if (categoriesWithItems.has(categoryKey)) apiMetaEntries.push({
+			type: "dir",
+			name: categoryConfig.folderName,
+			label: categoryConfig.displayName,
+			collapsible: categoryConfig.collapsible ?? true,
+			collapsed: categoryConfig.collapsed ?? true,
+			overviewHeaders: categoryConfig.overviewHeaders ?? [2]
+		});
+		const apiMetaJsonPath = path.join(resolvedOutputDir, "_meta.json");
+		const apiMetaJsonRelPath = "_meta.json";
+		const apiMetaJsonContent = JSON.stringify(apiMetaEntries, null, "	");
+		const apiMetaContentHash = hashContent(apiMetaJsonContent);
+		const apiMetaOldSnapshot = existingSnapshots.get(apiMetaJsonRelPath);
+		let apiMetaUnchanged = false;
+		let apiMetaPublished;
+		let apiMetaModified;
+		if (!(yield* fileSystem.exists(apiMetaJsonPath).pipe(Effect.orElseSucceed(() => false)))) {
+			apiMetaPublished = apiMetaOldSnapshot?.publishedTime || buildTime;
+			apiMetaModified = buildTime;
+			apiMetaUnchanged = false;
+		} else if (!apiMetaOldSnapshot) {
+			const existingContent = yield* fileSystem.readFileString(apiMetaJsonPath).pipe(Effect.orElseSucceed(() => null));
+			const existingData = existingContent ? yield* Effect.try(() => JSON.parse(existingContent)).pipe(Effect.orElseSucceed(() => null)) : null;
+			if ((existingData ? JSON.stringify(existingData, null, "	") : null) === apiMetaJsonContent) {
+				apiMetaPublished = "2024-01-01T00:00:00.000Z";
+				apiMetaModified = "2024-01-01T00:00:00.000Z";
+				apiMetaUnchanged = true;
+			} else {
+				apiMetaPublished = "2024-01-01T00:00:00.000Z";
+				apiMetaModified = buildTime;
+			}
+		} else if (apiMetaOldSnapshot.contentHash === apiMetaContentHash) {
+			apiMetaPublished = apiMetaOldSnapshot.publishedTime;
+			apiMetaModified = apiMetaOldSnapshot.modifiedTime;
+			apiMetaUnchanged = true;
+		} else {
+			apiMetaPublished = apiMetaOldSnapshot.publishedTime;
+			apiMetaModified = buildTime;
+		}
+		if (!apiMetaUnchanged) {
+			yield* fileSystem.writeFileString(apiMetaJsonPath, apiMetaJsonContent).pipe(Effect.orDie);
+			yield* Metric.increment(BuildMetrics.filesTotal);
+			if (apiMetaOldSnapshot) yield* Metric.increment(BuildMetrics.filesModified);
+			else yield* Metric.increment(BuildMetrics.filesNew);
+		} else {
+			yield* Metric.increment(BuildMetrics.filesTotal);
+			yield* Metric.increment(BuildMetrics.filesUnchanged);
+		}
+		yield* snapshotSvc.upsert({
+			outputDir: resolvedOutputDir,
+			filePath: apiMetaJsonRelPath,
+			publishedTime: apiMetaPublished,
+			modifiedTime: apiMetaModified,
+			contentHash: apiMetaContentHash,
+			frontmatterHash: "",
+			buildTime
+		}).pipe(Effect.ignore);
+		generatedFiles.add(apiMetaJsonRelPath);
+		const categoryCounts = {};
+		for (const result of fileResults) categoryCounts[result.categoryKey] = (categoryCounts[result.categoryKey] || 0) + 1;
+		const mainIndex = new MainIndexPageGenerator().generate(packageName, baseRoute, categoryCounts);
+		const indexRelativePath = `${mainIndex.routePath.replace(baseRoute, "").replace(/^\//, "")}.mdx`;
+		const indexAbsolutePath = path.join(resolvedOutputDir, indexRelativePath);
+		if (!(yield* fileSystem.exists(indexAbsolutePath).pipe(Effect.orElseSucceed(() => false)))) {
+			const indexDirPath = path.dirname(indexAbsolutePath);
+			yield* fileSystem.makeDirectory(indexDirPath, { recursive: true }).pipe(Effect.orDie);
+			yield* fileSystem.writeFileString(indexAbsolutePath, mainIndex.content).pipe(Effect.orDie);
+			yield* Metric.increment(BuildMetrics.filesTotal);
+			yield* Metric.increment(BuildMetrics.filesNew);
+		} else {
+			yield* Metric.increment(BuildMetrics.filesTotal);
+			yield* Metric.increment(BuildMetrics.filesUnchanged);
+		}
+		generatedFiles.add("index.mdx");
+		const categoryMetaEntriesMap = /* @__PURE__ */ new Map();
+		for (const result of fileResults) {
+			const baseName = path.basename(result.relativePathWithExt, ".mdx");
+			const entries = categoryMetaEntriesMap.get(result.categoryKey) || [];
+			entries.push({
+				name: baseName,
+				label: result.label
+			});
+			categoryMetaEntriesMap.set(result.categoryKey, entries);
+		}
+		const metaSnapshotsToUpdate = (yield* Effect.forEach(Array.from(categoryMetaEntriesMap.entries()), ([categoryKey, entries]) => Effect.gen(function* () {
+			const categoryConfig = categories[categoryKey];
+			if (!categoryConfig || entries.length === 0) return null;
+			entries.sort((a, b) => a.label.localeCompare(b.label));
+			const categoryMeta = entries.map((entry) => ({
+				type: "file",
+				name: entry.name,
+				label: entry.label
+			}));
+			const categoryMetaPath = path.join(resolvedOutputDir, categoryConfig.folderName, "_meta.json");
+			const relPath = path.join(categoryConfig.folderName, "_meta.json");
+			const content = JSON.stringify(categoryMeta, null, "	");
+			const contentHash = hashContent(content);
+			const oldSnapshot = existingSnapshots.get(relPath);
+			let isUnchanged = false;
+			let publishedTime;
+			let modifiedTime;
+			if (!(yield* fileSystem.exists(categoryMetaPath).pipe(Effect.orElseSucceed(() => false)))) {
+				publishedTime = oldSnapshot?.publishedTime || buildTime;
+				modifiedTime = buildTime;
+				isUnchanged = false;
+			} else if (!oldSnapshot) {
+				const existingContent = yield* fileSystem.readFileString(categoryMetaPath).pipe(Effect.orElseSucceed(() => null));
+				const existingData = existingContent ? yield* Effect.try(() => JSON.parse(existingContent)).pipe(Effect.orElseSucceed(() => null)) : null;
+				if ((existingData ? JSON.stringify(existingData, null, "	") : null) === content) {
+					publishedTime = "2024-01-01T00:00:00.000Z";
+					modifiedTime = "2024-01-01T00:00:00.000Z";
+					isUnchanged = true;
+				} else {
+					publishedTime = "2024-01-01T00:00:00.000Z";
+					modifiedTime = buildTime;
+				}
+			} else if (oldSnapshot.contentHash === contentHash) {
+				publishedTime = oldSnapshot.publishedTime;
+				modifiedTime = oldSnapshot.modifiedTime;
+				isUnchanged = true;
+			} else {
+				publishedTime = oldSnapshot.publishedTime;
+				modifiedTime = buildTime;
+			}
+			if (!isUnchanged) {
+				const categoryDir = path.dirname(categoryMetaPath);
+				yield* fileSystem.makeDirectory(categoryDir, { recursive: true }).pipe(Effect.orDie);
+				yield* fileSystem.writeFileString(categoryMetaPath, content).pipe(Effect.orDie);
+				yield* Metric.increment(BuildMetrics.filesTotal);
+				if (oldSnapshot) yield* Metric.increment(BuildMetrics.filesModified);
+				else yield* Metric.increment(BuildMetrics.filesNew);
+			} else {
+				yield* Metric.increment(BuildMetrics.filesTotal);
+				yield* Metric.increment(BuildMetrics.filesUnchanged);
+			}
+			generatedFiles.add(relPath);
+			if (isUnchanged) return null;
+			return {
+				outputDir: resolvedOutputDir,
+				filePath: relPath,
+				publishedTime,
+				modifiedTime,
+				contentHash,
+				frontmatterHash: "",
+				buildTime
+			};
+		}), { concurrency: "unbounded" })).filter((s) => s !== null);
+		if (metaSnapshotsToUpdate.length > 0) yield* snapshotSvc.batchUpsert(metaSnapshotsToUpdate).pipe(Effect.ignore);
+	});
+}
+/**
+* Batch-upsert snapshots for written files, then delete stale and orphaned files
+* from disk and the snapshot database. Finally, remove any empty subdirectories.
+*
+* Steps:
+* 1. Filter fileResults to written files (status !== "unchanged"), extract snapshots,
+*    and batch-upsert them into the snapshot DB.
+* 2. Call snapshotManager.cleanupStaleFiles() to find files tracked in DB but not
+*    generated in this build, then delete them from disk.
+* 3. Read the output directory recursively; for each .mdx or _meta.json file not in
+*    generatedFiles, delete it from disk and remove its snapshot.
+* 4. After deleting orphans, remove empty subdirectories deepest-first.
+*/
+function cleanupAndCommit(input) {
+	return Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem;
+		const snapshotSvc = yield* SnapshotService;
+		const { fileResults, resolvedOutputDir, generatedFiles } = input;
+		const snapshotsToUpdate = fileResults.filter((r) => r.status !== "unchanged").map((r) => r.snapshot);
+		if (snapshotsToUpdate.length > 0) yield* snapshotSvc.batchUpsert(snapshotsToUpdate).pipe(Effect.ignore);
+		const staleFiles = yield* snapshotSvc.cleanupStale(resolvedOutputDir, generatedFiles).pipe(Effect.orElseSucceed(() => []));
+		yield* Effect.forEach(staleFiles, (staleFile) => Effect.gen(function* () {
+			const fullPath = path.join(resolvedOutputDir, staleFile);
+			yield* fileSystem.remove(fullPath).pipe(Effect.ignore);
+			yield* Effect.logDebug(`🗑️  DELETED STALE: ${staleFile}`);
+		}), { concurrency: "unbounded" });
+		const allFiles = yield* fileSystem.readDirectory(resolvedOutputDir, { recursive: true }).pipe(Effect.orElseSucceed(() => []));
+		const orphanedFiles = [];
+		for (const entry of allFiles) {
+			const relPath = typeof entry === "string" ? entry : String(entry);
+			if (!relPath.endsWith(".mdx") && !relPath.endsWith("_meta.json")) continue;
+			const normalizedRelPath = relPath.replace(/\\/g, "/");
+			if (!generatedFiles.has(normalizedRelPath)) orphanedFiles.push(normalizedRelPath);
+		}
+		yield* Effect.forEach(orphanedFiles, (orphan) => Effect.gen(function* () {
+			const fullPath = path.join(resolvedOutputDir, orphan);
+			yield* fileSystem.remove(fullPath).pipe(Effect.ignore);
+			yield* snapshotSvc.deleteSnapshot(resolvedOutputDir, orphan).pipe(Effect.ignore);
+			yield* Effect.logDebug(`🗑️  DELETED ORPHAN: ${orphan}`);
+		}), { concurrency: "unbounded" });
+		if (orphanedFiles.length > 0) {
+			const dirs = /* @__PURE__ */ new Set();
+			for (const orphan of orphanedFiles) {
+				const dir = path.dirname(orphan);
+				if (dir !== ".") dirs.add(dir);
+			}
+			const sortedDirs = [...dirs].sort((a, b) => b.split("/").length - a.split("/").length);
+			for (const dir of sortedDirs) {
+				const fullDir = path.join(resolvedOutputDir, dir);
+				if ((yield* fileSystem.readDirectory(fullDir).pipe(Effect.orElseSucceed(() => ["placeholder"]))).length === 0) {
+					yield* fileSystem.remove(fullDir).pipe(Effect.ignore);
+					yield* Effect.logDebug(`🗑️  REMOVED EMPTY DIR: ${dir}`);
+				}
+			}
+		}
+	});
+}
+/**
+* Effect Stream pipeline: workItems → generate → write (no-op for unchanged) → fold
+*
+* Unchanged files are NOT filtered out. They flow through the write stage as
+* no-ops and appear in the fold output with status: "unchanged". This is
+* required because ALL generated files must be tracked for:
+* - generatedFiles set (stale/orphan cleanup)
+* - fileContextMap (remark plugin Twoslash error attribution)
+* - _meta.json navigation entries
+*
+* The Stream.filter only removes nulls (unsupported ApiItemKind). All other
+* items — including unchanged ones — flow through to the fold accumulator.
+*/
+function buildPipelineForApi(input) {
+	const generateCtx = {
+		existingSnapshots: input.existingSnapshots,
+		baseRoute: input.baseRoute,
+		packageName: input.packageName,
+		apiScope: input.apiScope,
+		...input.apiName != null ? { apiName: input.apiName } : {},
+		...input.source != null ? { source: input.source } : {},
+		buildTime: input.buildTime,
+		resolvedOutputDir: input.resolvedOutputDir,
+		...input.suppressExampleErrors != null ? { suppressExampleErrors: input.suppressExampleErrors } : {},
+		...input.llmsPlugin != null ? { llmsPlugin: input.llmsPlugin } : {}
+	};
+	const writeCtx = {
+		resolvedOutputDir: input.resolvedOutputDir,
+		buildTime: input.buildTime,
+		...input.ogResolver !== void 0 ? { ogResolver: input.ogResolver } : {},
+		...input.siteUrl != null ? { siteUrl: input.siteUrl } : {},
+		...input.ogImage != null ? { ogImage: input.ogImage } : {},
+		...input.packageName != null ? { packageName: input.packageName } : {},
+		...input.apiName != null ? { apiName: input.apiName } : {}
+	};
+	return Stream.fromIterable(input.workItems).pipe(Stream.mapEffect((workItem) => generateSinglePage(workItem, generateCtx), { concurrency: input.pageConcurrency }), Stream.filter((result) => result !== null), Stream.mapEffect((result) => writeSingleFile(result, writeCtx), { concurrency: input.pageConcurrency }), Stream.runFold([], (acc, result) => [...acc, result]));
+}
+
+//#endregion
+export { buildPipelineForApi, cleanupAndCommit, prepareWorkItems, writeMetadata };