rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/markdown/page-generators/type-alias-page.js

@@ -0,0 +1,110 @@
+import { ApiParser } from "../../loader.js";
+import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
+import { markdownCrossLinker } from "../cross-linker.js";
+import { TypeSignatureFormatter } from "../../formatter.js";
+
+//#region src/markdown/page-generators/type-alias-page.ts
+/**
+* Generates MDX documentation pages for TypeScript type aliases.
+*
+* This class transforms API Extractor type alias models into rich MDX documentation
+* pages with syntax-highlighted signatures and cross-linked type references.
+*
+* **Page Structure:**
+* 1. Frontmatter with title, description, and Open Graph metadata
+* 2. Component imports
+* 3. Page title (H1) and summary
+* 4. Optional deprecation warning and release tag badge
+* 5. Source code link toolbar
+* 6. Type alias signature block (full type definition)
+* 7. Examples section with Twoslash-enabled code blocks
+* 8. See Also references
+*
+* **Relationships:**
+* - Created and invoked by {@link ApiExtractorPlugin} during page generation
+* - Uses {@link TypeSignatureFormatter} for formatting type signatures
+* - Uses {@link ApiParser} for extracting documentation from API models
+* - Uses {@link MarkdownCrossLinker} for adding type reference links
+*
+* @see {@link InterfacePageGenerator} for interface documentation
+* @see {@link EnumPageGenerator} for enum documentation
+*/
+var TypeAliasPageGenerator = class {
+	typeFormatter = new TypeSignatureFormatter();
+	/**
+	* Generate a markdown page for a type alias
+	*
+	* @param apiScope - API scope identifier for VFS lookup
+	*/
+	async generate(apiTypeAlias, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
+		const shouldSuppressErrors = suppressExampleErrors ?? true;
+		const name = apiTypeAlias.displayName;
+		const summary = ApiParser.getSummary(apiTypeAlias) || "No description available.";
+		const releaseTag = ApiParser.getReleaseTag(apiTypeAlias);
+		let content = generateFrontmatter(name, summary, singularName, apiName);
+		content += `import { SourceCode } from "@rspress/core/theme";\n`;
+		content += `import { ParametersTable } from "rspress-plugin-api-extractor/runtime";\n`;
+		content += `import { ApiSignature, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
+		content += `# ${name}\n\n`;
+		const deprecation = ApiParser.getDeprecation(apiTypeAlias);
+		if (deprecation) {
+			const message = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(deprecation.message));
+			content += `> ⚠️ **Deprecated:** ${message}\n\n`;
+		}
+		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
+		content += `${summary}\n\n`;
+		content += generateAvailableFrom(packageName, availableFrom);
+		const sourceLink = ApiParser.getSourceLink(apiTypeAlias, sourceConfig);
+		if (sourceLink) {
+			content += `<div className="api-docs-toolbar">\n`;
+			content += `  <div className="api-docs-toolbar-left">\n`;
+			content += `    <SourceCode href="${sourceLink}" />\n`;
+			content += `  </div>\n`;
+			if (llmsPlugin?.enabled) {
+				content += `  <div className="api-docs-toolbar-right">\n`;
+				content += `  </div>\n`;
+			}
+			content += `</div>\n\n`;
+		}
+		if (apiTypeAlias.excerpt.text) {
+			const signature = this.typeFormatter.format(apiTypeAlias.excerpt).trim();
+			let signatureWithImports = signature;
+			const apiPackage = apiTypeAlias.getAssociatedPackage?.();
+			if (apiPackage) signatureWithImports = prependHiddenImports(signature, new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiTypeAlias));
+			const displayCode = stripTwoslashDirectives(signatureWithImports);
+			content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(signatureWithImports)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+		}
+		const examples = ApiParser.getExamples(apiTypeAlias);
+		if (examples.length > 0) {
+			content += `## Examples\n\n`;
+			for (const example of examples) {
+				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
+				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
+					api: packageName,
+					blockType: "example"
+				});
+				if (prepared.isTypeScript) {
+					const displayCode = stripTwoslashDirectives(formattedCode);
+					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
+			}
+		}
+		const seeReferences = ApiParser.getSeeReferences(apiTypeAlias);
+		if (seeReferences.length > 0) {
+			content += `## See Also\n\n`;
+			for (const reference of seeReferences) {
+				const refText = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(reference.text));
+				content += `- ${refText}\n`;
+			}
+			content += `\n`;
+		}
+		return {
+			routePath: `${baseRoute}/type/${name.toLowerCase()}`,
+			content
+		};
+	}
+};
+
+//#endregion
+export { TypeAliasPageGenerator };

package/markdown/page-generators/variable-page.js

@@ -0,0 +1,110 @@
+import { ApiParser } from "../../loader.js";
+import { TypeReferenceExtractor } from "../../type-reference-extractor.js";
+import { escapeMdxGenerics, formatExampleCode, generateAvailableFrom, generateFrontmatter, prepareExampleCode, prependHiddenImports, stripTwoslashDirectives } from "../helpers.js";
+import { markdownCrossLinker } from "../cross-linker.js";
+import { TypeSignatureFormatter } from "../../formatter.js";
+
+//#region src/markdown/page-generators/variable-page.ts
+/**
+* Generates MDX documentation pages for exported variables and constants.
+*
+* This class transforms API Extractor variable models into rich MDX documentation
+* pages with syntax-highlighted signatures and cross-linked type references.
+*
+* **Page Structure:**
+* 1. Frontmatter with title, description, and Open Graph metadata
+* 2. Component imports
+* 3. Page title (H1) and summary
+* 4. Optional deprecation warning and release tag badge
+* 5. Source code link toolbar
+* 6. Variable signature block (const/let declaration with type)
+* 7. Examples section with Twoslash-enabled code blocks
+* 8. See Also references
+*
+* **Relationships:**
+* - Created and invoked by {@link ApiExtractorPlugin} during page generation
+* - Uses {@link TypeSignatureFormatter} for formatting type signatures
+* - Uses {@link ApiParser} for extracting documentation from API models
+* - Uses {@link MarkdownCrossLinker} for adding type reference links
+*
+* @see {@link FunctionPageGenerator} for function documentation
+* @see {@link EnumPageGenerator} for enum documentation
+*/
+var VariablePageGenerator = class {
+	typeFormatter = new TypeSignatureFormatter();
+	/**
+	* Generate a markdown page for a variable
+	*
+	* @param apiScope - API scope identifier for VFS lookup
+	*/
+	async generate(apiVariable, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
+		const shouldSuppressErrors = suppressExampleErrors ?? true;
+		const name = apiVariable.displayName;
+		const summary = ApiParser.getSummary(apiVariable) || "No description available.";
+		const releaseTag = ApiParser.getReleaseTag(apiVariable);
+		let content = generateFrontmatter(name, summary, singularName, apiName);
+		content += `import { SourceCode } from "@rspress/core/theme";\n`;
+		content += `import { ParametersTable } from "rspress-plugin-api-extractor/runtime";\n`;
+		content += `import { ApiSignature, ApiExample } from "rspress-plugin-api-extractor/runtime";\n\n`;
+		content += `# ${name}\n\n`;
+		const deprecation = ApiParser.getDeprecation(apiVariable);
+		if (deprecation) {
+			const message = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(deprecation.message));
+			content += `> ⚠️ **Deprecated:** ${message}\n\n`;
+		}
+		if (releaseTag !== "Public") content += `\`${releaseTag}\`\n\n`;
+		content += `${summary}\n\n`;
+		content += generateAvailableFrom(packageName, availableFrom);
+		const sourceLink = ApiParser.getSourceLink(apiVariable, sourceConfig);
+		if (sourceLink) {
+			content += `<div className="api-docs-toolbar">\n`;
+			content += `  <div className="api-docs-toolbar-left">\n`;
+			content += `    <SourceCode href="${sourceLink}" />\n`;
+			content += `  </div>\n`;
+			if (llmsPlugin?.enabled) {
+				content += `  <div className="api-docs-toolbar-right">\n`;
+				content += `  </div>\n`;
+			}
+			content += `</div>\n\n`;
+		}
+		if (apiVariable.excerpt.text) {
+			const signature = this.typeFormatter.format(apiVariable.excerpt).trim();
+			let signatureWithImports = signature;
+			const apiPackage = apiVariable.getAssociatedPackage?.();
+			if (apiPackage) signatureWithImports = prependHiddenImports(signature, new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(apiVariable));
+			const displayCode = stripTwoslashDirectives(signatureWithImports);
+			content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(signatureWithImports)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+		}
+		const examples = ApiParser.getExamples(apiVariable);
+		if (examples.length > 0) {
+			content += `## Examples\n\n`;
+			for (const example of examples) {
+				const prepared = prepareExampleCode(example, name, packageName, shouldSuppressErrors);
+				const formattedCode = await formatExampleCode(prepared.code, prepared.language, {
+					api: packageName,
+					blockType: "example"
+				});
+				if (prepared.isTypeScript) {
+					const displayCode = stripTwoslashDirectives(formattedCode);
+					content += `<ApiExample code={${JSON.stringify(displayCode)}} source={${JSON.stringify(formattedCode)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+				} else content += `\`\`\`${prepared.language}\n${formattedCode}\n\`\`\`\n\n`;
+			}
+		}
+		const seeReferences = ApiParser.getSeeReferences(apiVariable);
+		if (seeReferences.length > 0) {
+			content += `## See Also\n\n`;
+			for (const reference of seeReferences) {
+				const refText = escapeMdxGenerics(markdownCrossLinker.addCrossLinks(reference.text));
+				content += `- ${refText}\n`;
+			}
+			content += `\n`;
+		}
+		return {
+			routePath: `${baseRoute}/variable/${name.toLowerCase()}`,
+			content
+		};
+	}
+};
+
+//#endregion
+export { VariablePageGenerator };

package/markdown/shiki-utils.js

@@ -0,0 +1,48 @@
+//#region src/markdown/shiki-utils.ts
+/**
+* Default Shiki theme configuration
+*/
+const DEFAULT_SHIKI_THEMES = {
+	light: "github-light-default",
+	dark: "github-dark-default"
+};
+/**
+* Generate a HAST (Hypertext Abstract Syntax Tree) from TypeScript code using Shiki.
+*
+* This function replaces the duplicated `generateShikiHtml` methods across page generators.
+* It produces a JSON-serializable HAST tree instead of HTML strings, which:
+* - Eliminates MDX parsing issues caused by long HTML strings with special characters
+* - Allows clean JSON serialization in generated MDX files
+* - Enables runtime rendering via `hast-util-to-jsx-runtime` without `dangerouslySetInnerHTML`
+*
+* @param code - The TypeScript code to highlight
+* @param highlighter - Shiki highlighter instance (optional, returns null if not provided)
+* @param transformers - Optional array of Shiki transformers (e.g., Twoslash, cross-linker)
+* @param enableTwoslash - If true, adds meta to trigger Twoslash directive processing
+* @param theme - Optional theme configuration (defaults to github-light/github-dark)
+* @returns A HAST root node, or null if no highlighter is provided or an error occurs
+*/
+async function generateShikiHast(code, highlighter, transformers, enableTwoslash, theme) {
+	if (!highlighter) return null;
+	const resolvedTheme = theme ?? DEFAULT_SHIKI_THEMES;
+	try {
+		const options = {
+			lang: "typescript",
+			themes: {
+				light: resolvedTheme.light,
+				dark: resolvedTheme.dark
+			},
+			defaultColor: false,
+			cssVariablePrefix: "--api-shiki-",
+			transformers: transformers || []
+		};
+		if (enableTwoslash) options.meta = { __raw: "twoslash" };
+		return await highlighter.codeToHast(code, options);
+	} catch (error) {
+		console.error("Failed to generate Shiki HAST:", error);
+		return null;
+	}
+}
+
+//#endregion
+export { DEFAULT_SHIKI_THEMES, generateShikiHast };

package/migrations/001_create_snapshots.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import * as SqlClient from "@effect/sql/SqlClient";
+
+//#region src/migrations/001_create_snapshots.ts
+const migration = Effect.gen(function* () {
+	const sql = yield* SqlClient.SqlClient;
+	yield* sql`
+		CREATE TABLE IF NOT EXISTS file_snapshots (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			output_dir TEXT NOT NULL,
+			file_path TEXT NOT NULL,
+			published_time TEXT NOT NULL,
+			modified_time TEXT NOT NULL,
+			content_hash TEXT NOT NULL,
+			frontmatter_hash TEXT NOT NULL,
+			build_time TEXT NOT NULL,
+			UNIQUE(output_dir, file_path)
+		)
+	`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_output_dir ON file_snapshots(output_dir)`;
+	yield* sql`CREATE INDEX IF NOT EXISTS idx_file_path ON file_snapshots(file_path)`;
+});
+
+//#endregion
+export { migration as default };

package/model-loader.js

@@ -0,0 +1,95 @@
+import { isLoadedModel, isVersionConfig } from "./config-utils.js";
+import fs from "node:fs";
+import path from "node:path";
+import { loadApiModel } from "api-extractor-llms";
+
+//#region src/model-loader.ts
+/**
+* Utility class for loading API models from various sources
+*/
+var ApiModelLoader = class ApiModelLoader {
+	/**
+	* Private constructor to prevent instantiation
+	*/
+	constructor() {}
+	/**
+	* Load an API model from a path (string, URL, or Buffer)
+	*/
+	static async loadFromPath(modelPath) {
+		const resolvedPath = path.resolve(modelPath.toString());
+		if (!fs.existsSync(resolvedPath)) throw new Error(`API model file not found: ${resolvedPath}`);
+		return loadApiModel(resolvedPath);
+	}
+	/**
+	* Load package.json from a path (string, URL, or Buffer)
+	*/
+	static async loadPackageJsonFromPath(pkgPath) {
+		const resolvedPath = path.resolve(pkgPath.toString());
+		if (!fs.existsSync(resolvedPath)) throw new Error(`Package.json file not found: ${resolvedPath}`);
+		const content = fs.readFileSync(resolvedPath, "utf-8");
+		try {
+			return JSON.parse(content);
+		} catch (error) {
+			throw new Error(`Failed to parse package.json at ${resolvedPath}: ${error.message}`);
+		}
+	}
+	/**
+	* Load package.json from PathLike or async function
+	*/
+	static async loadPackageJson(loader) {
+		if (typeof loader === "function") return await loader();
+		return await ApiModelLoader.loadPackageJsonFromPath(loader);
+	}
+	/**
+	* Load an API model from PathLike or async function
+	*/
+	static async loadApiModel(loader) {
+		if (typeof loader === "function") {
+			const result = await loader();
+			if (isLoadedModel(result)) {
+				const model = result.model;
+				if (model && typeof model === "object" && "packages" in model) {
+					const packages = model.packages;
+					if (packages.length === 0) throw new Error("API model returned by function contains no packages");
+					const loadedResult = { apiPackage: packages[0] };
+					if (result.source != null) loadedResult.source = result.source;
+					return loadedResult;
+				}
+				throw new Error("API model loader function must return an ApiModel");
+			}
+			if (result && typeof result === "object" && "packages" in result) {
+				const packages = result.packages;
+				if (packages.length === 0) throw new Error("API model returned by function contains no packages");
+				return { apiPackage: packages[0] };
+			}
+			throw new Error("API model loader function must return an ApiModel or LoadedModel");
+		}
+		return { apiPackage: await ApiModelLoader.loadFromPath(loader) };
+	}
+	/**
+	* Resolve and load a version config
+	*/
+	static async loadVersionModel(versionValue) {
+		if (isVersionConfig(versionValue)) {
+			const { apiPackage, source: loaderSource } = await ApiModelLoader.loadApiModel(versionValue.model);
+			const packageJson = versionValue.packageJson ? await ApiModelLoader.loadPackageJson(versionValue.packageJson) : void 0;
+			const versionResult = { apiPackage };
+			if (packageJson != null) versionResult.packageJson = packageJson;
+			if (versionValue.categories != null) versionResult.categories = versionValue.categories;
+			const resolvedSource = loaderSource || versionValue.source;
+			if (resolvedSource != null) versionResult.source = resolvedSource;
+			if (versionValue.externalPackages != null) versionResult.externalPackages = versionValue.externalPackages;
+			if (versionValue.autoDetectDependencies != null) versionResult.autoDetectDependencies = versionValue.autoDetectDependencies;
+			if (versionValue.ogImage != null) versionResult.ogImage = versionValue.ogImage;
+			if (versionValue.llmsPlugin != null) versionResult.llmsPlugin = versionValue.llmsPlugin;
+			return versionResult;
+		}
+		const { apiPackage, source } = await ApiModelLoader.loadApiModel(versionValue);
+		const simpleResult = { apiPackage };
+		if (source != null) simpleResult.source = source;
+		return simpleResult;
+	}
+};
+
+//#endregion
+export { ApiModelLoader };

package/multi-entry-resolver.js

@@ -0,0 +1,70 @@
+//#region src/multi-entry-resolver.ts
+/**
+* Derive an entry point name from its display name in the API model.
+*
+* - Empty string (main entry "." in package.json) maps to "default"
+* - Named entries (e.g., "testing") keep their name
+*/
+function getEntryPointName(displayName) {
+	return displayName === "" ? "default" : displayName;
+}
+/**
+* Create a stable identity key for an API item based on its display name and kind.
+* Used to detect re-exports across entry points.
+*/
+function itemKey(item) {
+	return `${item.displayName}::${item.kind}`;
+}
+/**
+* Resolve all entry points from an API package into a flat list of
+* deduplicated items.
+*
+* - Re-exported items (same displayName + kind across entries) are
+*   deduplicated to a single entry with availableFrom listing all
+*   entry points. The defining entry point prefers "default".
+* - Items with different kinds but the same displayName (e.g. the
+*   Effect const + type companion pattern) remain as separate entries.
+*
+* @param apiPackage - The merged API package with 1+ entry points
+* @returns Flat array of resolved items
+*/
+function resolveEntryPoints(apiPackage) {
+	const itemsByKey = /* @__PURE__ */ new Map();
+	for (const entryPoint of apiPackage.entryPoints) {
+		const epName = getEntryPointName(entryPoint.displayName);
+		for (const member of entryPoint.members) {
+			const key = itemKey(member);
+			const existing = itemsByKey.get(key) || [];
+			existing.push({
+				item: member,
+				entryPointName: epName
+			});
+			itemsByKey.set(key, existing);
+		}
+	}
+	const intermediate = [];
+	for (const [, entries] of itemsByKey) if (entries.length === 1) {
+		const { item, entryPointName } = entries[0];
+		intermediate.push({
+			item,
+			definingEntryPoint: entryPointName,
+			availableFrom: [entryPointName]
+		});
+	} else {
+		const definingEntry = entries.find((e) => e.entryPointName === "default") || entries[0];
+		const allEntryPoints = [...new Set(entries.map((e) => e.entryPointName))];
+		intermediate.push({
+			item: definingEntry.item,
+			definingEntryPoint: definingEntry.entryPointName,
+			availableFrom: allEntryPoints
+		});
+	}
+	return intermediate.map((r) => ({
+		item: r.item,
+		definingEntryPoint: r.definingEntryPoint,
+		availableFrom: r.availableFrom
+	}));
+}
+
+//#endregion
+export { resolveEntryPoints };