rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/rspress-plugin-api-extractor?label=npm&color=cb3837)](https://www.npmjs.com/package/rspress-plugin-api-extractor)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
-[![Node.js %3E%3D24.1.0](https://img.shields.io/badge/Node.js-%3E%3D24.1.0-5fa04e.svg)](https://nodejs.org/)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
 
 An [RSPress](https://rspress.dev/) 2.0 plugin that generates interactive API documentation from [Microsoft API Extractor](https://api-extractor.com/) models. Point it at your `.api.json` files and you get a documentation site: syntax-highlighted signatures, Twoslash hover tooltips, type references that cross-link between pages and copy-paste code examples.
@@ -57,7 +57,7 @@ The plugin reads your `.api.json` model and writes one MDX page per public API i
 
 - [Getting started](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/01-getting-started.md) — Install, minimal config, first build.
 - [Configuration](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/02-configuration.md) — Full plugin-options reference.
-- [Config helpers](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/03-config-helpers.md) — `fromFolder` and `fromModelsDir` for discovering config from package folders.
+- [Config helpers](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/03-config-helpers.md) — `api.fromDir` and `apis.fromDir` for discovering config from package folders.
 - [Single package](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/04-single-package.md) — The single-API recipe.
 - [Multi-package](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/05-multi-package.md) — The multi-API portal recipe.
 - [Versioned](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/06-versioned.md) — Documenting major versions side by side.

package/api-extracted-package.js

@@ -0,0 +1,426 @@
+import { ApiItemKind, ApiModel } from "@microsoft/api-extractor-model";
+import { VirtualPackage } from "type-registry-effect";
+
+//#region src/api-extracted-package.ts
+const VirtualPackageClass = VirtualPackage.VirtualPackage;
+/**
+* Reconstructs TypeScript declaration files from an API Extractor model.
+*
+* Extends {@link VirtualPackage} with the ability to generate high-fidelity
+* `.d.ts` output from API Extractor's `ApiPackage` — including enum values,
+* full JSDoc, namespace members, and all interface member kinds.
+*
+* Use the factory methods {@link fromApiModel} or {@link fromPackage} to create instances.
+*/
+var ApiExtractedPackage = class ApiExtractedPackage extends VirtualPackageClass {
+	apiPackage;
+	constructor(apiPackage, packageName, entries) {
+		super(packageName, "1.0.0", entries);
+		this.apiPackage = apiPackage;
+	}
+	/**
+	* Create an ApiExtractedPackage from an API model JSON file path.
+	*/
+	static fromApiModel(modelPath) {
+		const apiPackage = new ApiModel().loadPackage(modelPath);
+		return ApiExtractedPackage.fromPackage(apiPackage, apiPackage.name);
+	}
+	/**
+	* Create an ApiExtractedPackage from an existing ApiPackage instance.
+	*/
+	static fromPackage(apiPackage, packageName) {
+		const tempEntries = /* @__PURE__ */ new Map();
+		const tempInstance = new ApiExtractedPackage(apiPackage, packageName, tempEntries);
+		for (const ep of apiPackage.entryPoints) {
+			const entryName = tempInstance.getEntryPointName(ep);
+			const fileName = entryName ? `${entryName}.d.ts` : "index.d.ts";
+			tempEntries.set(fileName, tempInstance.generateDeclarations(ep));
+		}
+		return tempInstance;
+	}
+	/**
+	* Generate the .d.ts content for a specific entry point.
+	*/
+	generateDeclarations(entryPoint) {
+		const ep = entryPoint ?? this.apiPackage.entryPoints[0];
+		if (!ep) return "";
+		const parts = [];
+		const packageDoc = this.extractPackageDocumentation();
+		if (packageDoc) {
+			parts.push(packageDoc);
+			parts.push("");
+		}
+		for (const member of ep.members) {
+			const decl = this.generateDeclaration(member);
+			if (decl) {
+				parts.push(decl);
+				parts.push("");
+			}
+		}
+		parts.push("export { }");
+		parts.push("");
+		return parts.join("\n");
+	}
+	/**
+	* Generate a TypeScript declaration for a single API item.
+	*/
+	generateDeclaration(apiItem) {
+		switch (apiItem.kind) {
+			case ApiItemKind.Class: return this.generateClassDeclaration(apiItem);
+			case ApiItemKind.Interface: return this.generateInterfaceDeclaration(apiItem);
+			case ApiItemKind.TypeAlias: return this.generateTypeAliasDeclaration(apiItem);
+			case ApiItemKind.Function: return this.generateFunctionDeclaration(apiItem);
+			case ApiItemKind.Enum: return this.generateEnumDeclaration(apiItem);
+			case ApiItemKind.Variable: return this.generateVariableDeclaration(apiItem);
+			case ApiItemKind.Namespace: return this.generateNamespaceDeclaration(apiItem);
+			default: return null;
+		}
+	}
+	generateClassDeclaration(apiClass) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiClass);
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiClass.displayName;
+		if (apiClass.typeParameters?.length) name += this.formatTypeParameters(apiClass.typeParameters);
+		const headerParts = ["export declare class", name];
+		if (apiClass.extendsType) headerParts.push(`extends ${apiClass.extendsType.excerpt.text}`);
+		if (apiClass.implementsTypes?.length) {
+			const impl = apiClass.implementsTypes.map((t) => t.excerpt.text).join(", ");
+			headerParts.push(`implements ${impl}`);
+		}
+		lines.push(`${headerParts.join(" ")} {`);
+		for (const member of apiClass.members) {
+			const memberDecl = this.generateClassMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateInterfaceDeclaration(apiInterface) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiInterface);
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiInterface.displayName;
+		if (apiInterface.typeParameters?.length) name += this.formatTypeParameters(apiInterface.typeParameters);
+		const headerParts = ["export declare interface", name];
+		if (apiInterface.extendsTypes?.length) {
+			const ext = apiInterface.extendsTypes.map((t) => t.excerpt.text).join(", ");
+			headerParts.push(`extends ${ext}`);
+		}
+		lines.push(`${headerParts.join(" ")} {`);
+		for (const member of apiInterface.members) {
+			const memberDecl = this.generateInterfaceMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateTypeAliasDeclaration(typeAlias) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(typeAlias);
+		if (jsDoc) lines.push(jsDoc);
+		let name = typeAlias.displayName;
+		if (typeAlias.typeParameters?.length) name += this.formatTypeParameters(typeAlias.typeParameters);
+		lines.push(`export declare type ${name} = ${typeAlias.typeExcerpt.text};`);
+		return lines.join("\n");
+	}
+	generateFunctionDeclaration(apiFunction) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiFunction);
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(apiFunction.excerpt.text);
+		lines.push(`export declare ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateEnumDeclaration(apiEnum) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiEnum);
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`export declare enum ${apiEnum.displayName} {`);
+		const enumMembers = apiEnum.members.filter((m) => m.kind === ApiItemKind.EnumMember);
+		for (let i = 0; i < enumMembers.length; i++) {
+			const enumMember = enumMembers[i];
+			const memberJsDoc = this.formatJSDoc(enumMember, "    ");
+			if (memberJsDoc) lines.push(memberJsDoc);
+			const suffix = i === enumMembers.length - 1 ? "" : ",";
+			const initExcerpt = enumMember.initializerExcerpt;
+			if (initExcerpt?.text.trim()) lines.push(`    ${enumMember.displayName} = ${initExcerpt.text.trim()}${suffix}`);
+			else lines.push(`    ${enumMember.displayName}${suffix}`);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateVariableDeclaration(apiVariable) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiVariable);
+		if (jsDoc) lines.push(jsDoc);
+		let cleaned = this.cleanExcerpt(apiVariable.excerpt.text);
+		if (!cleaned.startsWith("const ") && !cleaned.startsWith("let ") && !cleaned.startsWith("var ")) cleaned = `const ${cleaned}`;
+		lines.push(`export declare ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceDeclaration(apiNamespace) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiNamespace);
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`export declare namespace ${apiNamespace.displayName} {`);
+		for (const member of apiNamespace.members) {
+			const memberDecl = this.generateNamespaceMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateNamespaceMember(apiItem) {
+		switch (apiItem.kind) {
+			case ApiItemKind.Function: return this.generateNamespaceFunction(apiItem);
+			case ApiItemKind.Interface: return this.generateNamespaceInterface(apiItem);
+			case ApiItemKind.Enum: return this.generateNamespaceEnum(apiItem);
+			case ApiItemKind.TypeAlias: return this.generateNamespaceTypeAlias(apiItem);
+			case ApiItemKind.Variable: return this.generateNamespaceVariable(apiItem);
+			case ApiItemKind.Class: return this.generateNamespaceClass(apiItem);
+			default: return null;
+		}
+	}
+	generateNamespaceFunction(apiFunction) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiFunction, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(apiFunction.excerpt.text);
+		lines.push(`    export ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceInterface(apiInterface) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiInterface, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiInterface.displayName;
+		if (apiInterface.typeParameters?.length) name += this.formatTypeParameters(apiInterface.typeParameters);
+		const headerParts = ["export interface", name];
+		if (apiInterface.extendsTypes?.length) {
+			const ext = apiInterface.extendsTypes.map((t) => t.excerpt.text).join(", ");
+			headerParts.push(`extends ${ext}`);
+		}
+		lines.push(`    ${headerParts.join(" ")} {`);
+		for (const member of apiInterface.members) {
+			const memberDecl = this.generateInterfaceMember(member, "        ");
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("    }");
+		return lines.join("\n");
+	}
+	generateNamespaceEnum(apiEnum) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiEnum, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`    export enum ${apiEnum.displayName} {`);
+		const enumMembers = apiEnum.members.filter((m) => m.kind === ApiItemKind.EnumMember);
+		for (let i = 0; i < enumMembers.length; i++) {
+			const enumMember = enumMembers[i];
+			const memberJsDoc = this.formatJSDoc(enumMember, "        ");
+			if (memberJsDoc) lines.push(memberJsDoc);
+			const suffix = i === enumMembers.length - 1 ? "" : ",";
+			const initExcerpt = enumMember.initializerExcerpt;
+			if (initExcerpt?.text.trim()) lines.push(`        ${enumMember.displayName} = ${initExcerpt.text.trim()}${suffix}`);
+			else lines.push(`        ${enumMember.displayName}${suffix}`);
+		}
+		lines.push("    }");
+		return lines.join("\n");
+	}
+	generateNamespaceTypeAlias(typeAlias) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(typeAlias, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let name = typeAlias.displayName;
+		if (typeAlias.typeParameters?.length) name += this.formatTypeParameters(typeAlias.typeParameters);
+		lines.push(`    export type ${name} = ${typeAlias.typeExcerpt.text};`);
+		return lines.join("\n");
+	}
+	generateNamespaceVariable(apiVariable) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiVariable, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let cleaned = this.cleanExcerpt(apiVariable.excerpt.text);
+		if (!cleaned.startsWith("const ") && !cleaned.startsWith("let ") && !cleaned.startsWith("var ")) cleaned = `const ${cleaned}`;
+		lines.push(`    export ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceClass(apiClass) {
+		const decl = this.generateClassDeclaration(apiClass);
+		if (!decl) return "";
+		return decl.replace(/\bexport declare class\b/, "export class").split("\n").map((line) => line.trim() ? `    ${line}` : line).join("\n");
+	}
+	generateClassMember(member, indent = "    ") {
+		switch (member.kind) {
+			case ApiItemKind.Constructor: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.Method: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.Property: return this.generateMemberFromExcerpt(member, indent);
+			default: return null;
+		}
+	}
+	generateInterfaceMember(member, indent = "    ") {
+		switch (member.kind) {
+			case ApiItemKind.MethodSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.PropertySignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.CallSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.ConstructSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.IndexSignature: return this.generateMemberFromExcerpt(member, indent);
+			default: return null;
+		}
+	}
+	generateMemberFromExcerpt(member, indent) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(member, indent);
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(member.excerpt.text);
+		lines.push(`${indent}${cleaned};`);
+		return lines.join("\n");
+	}
+	/**
+	* Clean an excerpt text: strip export/declare keywords and trailing semicolons/whitespace.
+	*/
+	cleanExcerpt(text) {
+		return text.replace(/^export\s+/, "").replace(/^declare\s+/, "").replace(/;+\s*$/, "").trim();
+	}
+	formatTypeParameters(typeParameters) {
+		if (!typeParameters.length) return "";
+		return `<${typeParameters.map((tp) => {
+			const parts = [tp.name];
+			if (tp.constraintExcerpt?.text.trim()) parts.push(`extends ${tp.constraintExcerpt.text.trim()}`);
+			if (tp.defaultTypeExcerpt?.text.trim()) parts.push(`= ${tp.defaultTypeExcerpt.text.trim()}`);
+			return parts.join(" ");
+		}).join(", ")}>`;
+	}
+	extractPackageDocumentation() {
+		const pkg = this.apiPackage;
+		if (!pkg.tsdocComment?.summarySection) return null;
+		const summary = this.extractPlainText(pkg.tsdocComment.summarySection).trim();
+		if (!summary) return null;
+		const lines = [];
+		for (const line of summary.split("\n")) lines.push(line);
+		lines.push("");
+		lines.push("@packageDocumentation");
+		return `/**\n${lines.map((line) => line ? ` * ${line}` : " *").join("\n")}\n */`;
+	}
+	/**
+	* Format JSDoc comment from an API item's TSDoc.
+	* Produces output matching the TypeScript compiler's JSDoc style.
+	*/
+	formatJSDoc(apiItem, indent = "") {
+		const item = apiItem;
+		if (!item.tsdocComment) return null;
+		const tsdoc = item.tsdocComment;
+		const lines = [];
+		if (tsdoc.summarySection) {
+			const summary = this.extractPlainText(tsdoc.summarySection).trim();
+			if (summary) for (const line of summary.split("\n")) lines.push(line);
+		}
+		const typeParamLines = [];
+		if (tsdoc.typeParams?.blocks) for (const block of tsdoc.typeParams.blocks) {
+			const blockAny = block;
+			const name = blockAny.parameterName || "";
+			const desc = this.extractPlainText(blockAny.content).replace(/\s+/g, " ").trim();
+			if (name && desc) typeParamLines.push(`@typeParam ${name} - ${desc}`);
+		}
+		const paramLines = [];
+		if (tsdoc.params?.blocks) for (const paramBlock of tsdoc.params.blocks) {
+			const param = paramBlock;
+			const name = param.parameterName || "";
+			const desc = this.extractPlainText(param.content).replace(/\s+/g, " ").trim();
+			if (name && desc) paramLines.push(`@param ${name} - ${desc}`);
+		}
+		let returnsLine = null;
+		if (tsdoc.returnsBlock) {
+			const desc = this.extractPlainText(tsdoc.returnsBlock.content).replace(/\s+/g, " ").trim();
+			if (desc) returnsLine = `@returns ${desc}`;
+		}
+		if (typeParamLines.length || paramLines.length || returnsLine) {
+			if (lines.length > 0) lines.push("");
+			lines.push(...typeParamLines);
+			lines.push(...paramLines);
+			if (returnsLine) lines.push(returnsLine);
+		}
+		if (tsdoc.deprecatedBlock) {
+			const msg = this.extractPlainText(tsdoc.deprecatedBlock.content).replace(/\s+/g, " ").trim();
+			if (msg) {
+				if (lines.length > 0) lines.push("");
+				lines.push(`@deprecated ${msg}`);
+			}
+		}
+		if (tsdoc.remarksBlock) {
+			const remarks = this.extractPlainText(tsdoc.remarksBlock.content).trim();
+			if (remarks) {
+				if (lines.length > 0) lines.push("");
+				lines.push("@remarks");
+				for (const line of remarks.split("\n")) lines.push(line);
+			}
+		}
+		if (tsdoc.customBlocks) for (const block of tsdoc.customBlocks) {
+			const blockAny = block;
+			if (blockAny.blockTag?.tagName === "@example") {
+				const exampleText = this.extractPlainText(blockAny.content).trim();
+				if (exampleText) {
+					if (lines.length > 0) lines.push("");
+					lines.push("@example");
+					for (const line of exampleText.split("\n")) lines.push(line);
+				}
+			}
+		}
+		try {
+			if (tsdoc.modifierTagSet?.isPublic?.()) {
+				if (lines.length > 0) lines.push("");
+				lines.push("@public");
+			}
+		} catch {}
+		if (lines.length === 0) return null;
+		if (lines.length === 1 && !lines[0].includes("\n")) return `${indent}/** ${lines[0]} */`;
+		return `${indent}/**\n${lines.map((line) => line ? `${indent} * ${line}` : `${indent} *`).join("\n")}\n${indent} */`;
+	}
+	/**
+	* Recursively extract plain text from a TSDoc DocNode tree.
+	*/
+	extractPlainText(node) {
+		const n = node;
+		if (n.kind === "PlainText") return n.text || "";
+		if (n.kind === "SoftBreak") return "\n";
+		if (n.kind === "CodeSpan") return `\`${n.code || ""}\``;
+		if (n.kind === "EscapedText") return n.encodedText || n.decodedText || "";
+		if (n.kind === "ErrorText") return n.text || "";
+		if (n.kind === "FencedCode") return `\`\`\`${n.language || ""}\n${(n.code || "").replace(/\n+$/, "")}\n\`\`\``;
+		if (n.kind === "LinkTag") {
+			let target = "";
+			if (n.codeDestination?.memberReferences) {
+				const identifiers = [];
+				for (const ref of n.codeDestination.memberReferences) if (ref.memberIdentifier?.identifier) identifiers.push(ref.memberIdentifier.identifier);
+				target = identifiers.join(".");
+			}
+			const displayText = typeof n.linkText === "string" ? n.linkText : "";
+			if (target && displayText) return `{@link ${target} | ${displayText}}`;
+			if (target) return `{@link ${target}}`;
+			if (displayText) return displayText;
+			return "";
+		}
+		if (n.kind === "Section") {
+			const children = n.getChildNodes?.() || [];
+			const paragraphs = [];
+			for (const child of children) {
+				const trimmed = this.extractPlainText(child).trim();
+				if (trimmed) paragraphs.push(trimmed);
+			}
+			return paragraphs.join("\n\n");
+		}
+		const parts = [];
+		if (n.getChildNodes && typeof n.getChildNodes === "function") for (const child of n.getChildNodes()) {
+			const text = this.extractPlainText(child);
+			if (text) parts.push(text);
+		}
+		return parts.join("");
+	}
+	getEntryPointName(entryPoint) {
+		if (entryPoint.displayName === "") return void 0;
+		return entryPoint.displayName;
+	}
+};
+
+//#endregion
+export { ApiExtractedPackage };

package/build-program.js

@@ -0,0 +1,120 @@
+import { markdownCrossLinker } from "./markdown/cross-linker.js";
+import "./markdown/index.js";
+import { SnapshotService } from "./services/SnapshotService.js";
+import { buildPipelineForApi, cleanupAndCommit, prepareWorkItems, writeMetadata } from "./build-stages.js";
+import { TwoslashManager } from "./twoslash-transformer.js";
+import { VfsRegistry } from "./vfs-registry.js";
+import path from "node:path";
+import { Effect } from "effect";
+import { FileSystem } from "@effect/platform";
+
+//#region src/build-program.ts
+/**
+* Generate markdown documentation for a single API as a native Effect program.
+*
+* Orchestrates the 5 build stages:
+* 1. prepareWorkItems — categorize items, build cross-link data, flatten work items
+* 2. generatePages — generate page content, hash, resolve timestamps
+* 3. writeFiles — write changed files to disk
+* 4. writeMetadata — write root _meta.json, main index, category _meta.json files
+* 5. cleanupAndCommit — batch upsert snapshots, delete stale/orphan files
+*
+* Returns build result metadata including CrossLinkData for cross-link merging
+* and generated file paths for LLMs post-processing.
+*/
+function generateApiDocs(apiConfig, buildContext, fileContextMap) {
+	return Effect.gen(function* () {
+		const fileSystem = yield* FileSystem.FileSystem;
+		const snapshotSvc = yield* SnapshotService;
+		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage } = apiConfig;
+		const suppressExampleErrors = apiConfig.suppressExampleErrors ?? true;
+		const { shikiCrossLinker, highlighter, hideCutTransformer, hideCutLinesTransformer, twoslashTransformer, ogResolver, pageConcurrency } = buildContext;
+		const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
+		const buildTime = (/* @__PURE__ */ new Date()).toISOString();
+		const allSnapshots = yield* snapshotSvc.getAllForDirectory(resolvedOutputDir).pipe(Effect.orDie);
+		const existingSnapshots = new Map(allSnapshots.map((s) => [s.filePath, s]));
+		yield* fileSystem.makeDirectory(resolvedOutputDir, { recursive: true }).pipe(Effect.orDie);
+		const { workItems, crossLinkData } = prepareWorkItems({
+			apiPackage,
+			categories,
+			baseRoute,
+			packageName
+		});
+		markdownCrossLinker.setRoutes(crossLinkData.routes);
+		const apiScope = baseRoute.replace(/^\//, "").split("/")[0] || packageName;
+		shikiCrossLinker.reinitialize(crossLinkData.routes, crossLinkData.kinds, apiScope);
+		TwoslashManager.addTypeRoutes(crossLinkData.routes);
+		if (highlighter) {
+			const vfsConfig = {
+				vfs: /* @__PURE__ */ new Map(),
+				highlighter,
+				crossLinker: shikiCrossLinker,
+				packageName,
+				apiScope
+			};
+			if (twoslashTransformer != null) vfsConfig.twoslashTransformer = twoslashTransformer;
+			if (hideCutTransformer != null) vfsConfig.hideCutTransformer = hideCutTransformer;
+			if (hideCutLinesTransformer != null) vfsConfig.hideCutLinesTransformer = hideCutLinesTransformer;
+			if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;
+			VfsRegistry.register(apiScope, vfsConfig);
+		}
+		yield* Effect.logInfo(`Generating ${workItems.length} pages across ${Object.keys(categories).length} categories in parallel`);
+		const fileResults = yield* buildPipelineForApi({
+			workItems,
+			baseRoute,
+			packageName,
+			apiScope,
+			...apiName != null ? { apiName } : {},
+			...source != null ? { source } : {},
+			buildTime,
+			resolvedOutputDir,
+			pageConcurrency,
+			existingSnapshots,
+			...suppressExampleErrors != null ? { suppressExampleErrors } : {},
+			...llmsPlugin != null ? { llmsPlugin } : {},
+			...ogResolver !== void 0 ? { ogResolver } : {},
+			...siteUrl != null ? { siteUrl } : {},
+			...ogImage != null ? { ogImage } : {}
+		});
+		const changedCount = fileResults.filter((r) => r.status !== "unchanged").length;
+		yield* Effect.logInfo(`Generated ${changedCount} pages`);
+		const generatedFiles = /* @__PURE__ */ new Set();
+		for (const r of fileResults) {
+			generatedFiles.add(r.relativePathWithExt);
+			const ctx = { file: r.relativePathWithExt };
+			if (apiName != null) ctx.api = apiName;
+			if (packageJson?.version != null) ctx.version = packageJson.version;
+			fileContextMap.set(r.absolutePath, ctx);
+		}
+		yield* writeMetadata({
+			fileResults,
+			categories,
+			resolvedOutputDir,
+			existingSnapshots,
+			buildTime,
+			baseRoute,
+			packageName,
+			...apiName != null ? { apiName } : {},
+			generatedFiles
+		});
+		yield* cleanupAndCommit({
+			fileResults,
+			resolvedOutputDir,
+			generatedFiles
+		});
+		yield* Effect.logInfo(`Generated ${changedCount} API documentation files for ${packageName}`);
+		return {
+			crossLinkData,
+			generatedFiles,
+			resolvedOutputDir,
+			baseRoute,
+			packageName,
+			apiName: apiName ?? void 0,
+			packageVersion: packageJson?.version,
+			packageDescription: typeof packageJson?.description === "string" ? packageJson.description : void 0
+		};
+	});
+}
+
+//#endregion
+export { generateApiDocs };