rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/runtime/index.js

@@ -1,11 +1,13 @@
 import "./components/shared/variables.css";
 import "./components/shared/_twoslash.css";
-export { ApiExample } from "./components/ApiExample/index.js";
-export { ApiMember } from "./components/ApiMember/index.js";
-export { ApiSignature } from "./components/ApiSignature/index.js";
-export { EnumMembersTable } from "./components/EnumMembersTable/index.js";
-export { ExampleBlock } from "./components/ExampleBlock/index.js";
-export { MemberSignature } from "./components/MemberSignature/index.js";
-export { ParametersTable } from "./components/ParametersTable/index.js";
-export { SignatureBlock } from "./components/SignatureBlock/index.js";
-export { hastToReact } from "./utils/hast-renderer.js";
+import { hastToReact } from "./utils/hast-renderer.js";
+import { ExampleBlock } from "./components/ExampleBlock/index.js";
+import { ApiExample } from "./components/ApiExample/index.js";
+import { MemberSignature } from "./components/MemberSignature/index.js";
+import { ApiMember } from "./components/ApiMember/index.js";
+import { SignatureBlock } from "./components/SignatureBlock/index.js";
+import { ApiSignature } from "./components/ApiSignature/index.js";
+import { EnumMembersTable } from "./components/EnumMembersTable/index.js";
+import { ParametersTable } from "./components/ParametersTable/index.js";
+
+export { ApiExample, ApiMember, ApiSignature, EnumMembersTable, ExampleBlock, MemberSignature, ParametersTable, SignatureBlock, hastToReact };

package/runtime/utils/decode-hast.js

@@ -1,18 +1,33 @@
+//#region src/runtime/utils/decode-hast.ts
+/**
+* Decode a HAST value that may be base64-encoded, plain JSON, or already parsed.
+*
+* Supports multiple input formats:
+* - Root object (direct HAST) - returned as-is
+* - Base64-encoded JSON string (from serializeHastForMdx)
+* - Plain JSON string (legacy format)
+*
+* @param hast - The HAST value to decode
+* @param componentName - Optional component name for warning messages
+* @returns Parsed HAST Root or null if decoding fails
+*/
 function decodeHast(hast, componentName) {
-    if (!hast) return null;
-    if ("string" != typeof hast) return hast;
-    try {
-        if (/^[A-Za-z0-9+/=]+$/.test(hast) && hast.length > 20) {
-            const binaryString = atob(hast);
-            const bytes = Uint8Array.from(binaryString, (char)=>char.charCodeAt(0));
-            const json = new TextDecoder("utf-8").decode(bytes);
-            return JSON.parse(json);
-        }
-        return JSON.parse(hast);
-    } catch  {
-        const name = componentName ? `${componentName}: ` : "";
-        console.warn(`${name}Failed to decode HAST`);
-        return null;
-    }
+	if (!hast) return null;
+	if (typeof hast !== "string") return hast;
+	try {
+		if (/^[A-Za-z0-9+/=]+$/.test(hast) && hast.length > 20) {
+			const binaryString = atob(hast);
+			const bytes = Uint8Array.from(binaryString, (char) => char.charCodeAt(0));
+			const json = new TextDecoder("utf-8").decode(bytes);
+			return JSON.parse(json);
+		}
+		return JSON.parse(hast);
+	} catch {
+		const name = componentName ? `${componentName}: ` : "";
+		console.warn(`${name}Failed to decode HAST`);
+		return null;
+	}
 }
-export { decodeHast };
+
+//#endregion
+export { decodeHast };

package/runtime/utils/hast-renderer.js

@@ -1,10 +1,24 @@
-import { toJsxRuntime } from "hast-util-to-jsx-runtime";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { toJsxRuntime } from "hast-util-to-jsx-runtime";
+
+//#region src/runtime/utils/hast-renderer.tsx
+/**
+* Convert a HAST (Hypertext Abstract Syntax Tree) root to a React element.
+*
+* This function is used to render pre-generated Shiki HAST trees at runtime,
+* avoiding the need for `dangerouslySetInnerHTML` and eliminating MDX parsing
+* issues caused by long HTML strings with special characters.
+*
+* @param hast - The HAST root node from Shiki's `codeToHast()`
+* @returns A React element representing the HAST tree
+*/
 function hastToReact(hast) {
-    return toJsxRuntime(hast, {
-        Fragment: Fragment,
-        jsx: jsx,
-        jsxs: jsxs
-    });
+	return toJsxRuntime(hast, {
+		Fragment,
+		jsx,
+		jsxs
+	});
 }
-export { hastToReact };
+
+//#endregion
+export { hastToReact };

package/schemas/config.js

@@ -0,0 +1,199 @@
+import { OpenGraphImageConfig } from "./opengraph.js";
+import { PerformanceConfig } from "./performance.js";
+import { Schema } from "effect";
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+
+//#region src/schemas/config.ts
+/**
+* Opaque input type for config fields that accept a file path string,
+* an async loader function, or a URL.
+*/
+const ModelInput = Schema.declare((input) => typeof input === "string" || typeof input === "function" || input instanceof URL);
+const LogLevel$1 = Schema.Literal("none", "info", "verbose", "debug", "warn", "error");
+const ExternalPackageSpec = Schema.mutable(Schema.Struct({
+	name: Schema.String,
+	version: Schema.String,
+	tsconfig: Schema.optional(ModelInput),
+	compilerOptions: Schema.optional(Schema.Unknown)
+}));
+const AutoDetectDependencies = Schema.mutable(Schema.Struct({
+	dependencies: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	devDependencies: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	peerDependencies: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	autoDependencies: Schema.optionalWith(Schema.Boolean, { default: () => true })
+}));
+const ErrorConfig = Schema.mutable(Schema.Struct({ example: Schema.optional(Schema.Literal("suppress", "show")) }));
+const LlmsPlugin = Schema.mutable(Schema.Struct({
+	enabled: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	scopes: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	apiTxt: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	showCopyButton: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	showViewOptions: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	copyButtonText: Schema.optionalWith(Schema.String, { default: () => "Copy Markdown" }),
+	viewOptions: Schema.optionalWith(Schema.mutable(Schema.Array(Schema.Literal("markdownLink", "chatgpt", "claude"))), { default: () => [
+		"markdownLink",
+		"chatgpt",
+		"claude"
+	] })
+}));
+const ApiItemKindSchema = Schema.declare((input) => typeof input === "number");
+const CategoryConfig = Schema.mutable(Schema.Struct({
+	displayName: Schema.String,
+	singularName: Schema.String,
+	folderName: Schema.String,
+	itemKinds: Schema.optional(Schema.mutable(Schema.Array(ApiItemKindSchema))),
+	tsdocModifier: Schema.optional(Schema.String),
+	collapsible: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	collapsed: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	overviewHeaders: Schema.optionalWith(Schema.mutable(Schema.Array(Schema.Number)), { default: () => [2] })
+}));
+const SourceConfig = Schema.mutable(Schema.Struct({
+	url: Schema.String,
+	ref: Schema.optional(Schema.String)
+}));
+const ThemeConfig = Schema.Union(Schema.String, Schema.mutable(Schema.Struct({
+	light: Schema.String,
+	dark: Schema.String
+})), Schema.mutable(Schema.Record({
+	key: Schema.String,
+	value: Schema.Unknown
+})));
+/**
+* Built-in default categories
+*/
+const DEFAULT_CATEGORIES = {
+	classes: {
+		displayName: "Classes",
+		singularName: "Class",
+		folderName: "class",
+		itemKinds: [ApiItemKind.Class],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	},
+	interfaces: {
+		displayName: "Interfaces",
+		singularName: "Interface",
+		folderName: "interface",
+		itemKinds: [ApiItemKind.Interface],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	},
+	functions: {
+		displayName: "Functions",
+		singularName: "Function",
+		folderName: "function",
+		itemKinds: [ApiItemKind.Function],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	},
+	types: {
+		displayName: "Types",
+		singularName: "Type",
+		folderName: "type",
+		itemKinds: [ApiItemKind.TypeAlias],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	},
+	enums: {
+		displayName: "Enums",
+		singularName: "Enum",
+		folderName: "enum",
+		itemKinds: [ApiItemKind.Enum],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	},
+	variables: {
+		displayName: "Variables",
+		singularName: "Variable",
+		folderName: "variable",
+		itemKinds: [ApiItemKind.Variable],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	},
+	namespaces: {
+		displayName: "Namespaces",
+		singularName: "Namespace",
+		folderName: "namespace",
+		itemKinds: [ApiItemKind.Namespace],
+		collapsible: true,
+		collapsed: true,
+		overviewHeaders: [2]
+	}
+};
+/** Reusable categories record (internal helper) */
+const CategoriesRecord = Schema.mutable(Schema.Record({
+	key: Schema.String,
+	value: CategoryConfig
+}));
+const VersionConfig = Schema.mutable(Schema.Struct({
+	model: ModelInput,
+	packageJson: Schema.optional(ModelInput),
+	categories: Schema.optional(CategoriesRecord),
+	source: Schema.optional(SourceConfig),
+	externalPackages: Schema.optional(Schema.mutable(Schema.Array(ExternalPackageSpec))),
+	autoDetectDependencies: Schema.optional(AutoDetectDependencies),
+	ogImage: Schema.optional(OpenGraphImageConfig),
+	llmsPlugin: Schema.optional(LlmsPlugin),
+	tsconfig: Schema.optional(ModelInput),
+	compilerOptions: Schema.optional(Schema.Unknown)
+}));
+/** Union for the versions record value: can be a path/function OR a full VersionConfig */
+const VersionValue = Schema.Union(ModelInput, VersionConfig);
+const SingleApiConfig = Schema.mutable(Schema.Struct({
+	packageName: Schema.String,
+	name: Schema.optional(Schema.String),
+	baseRoute: Schema.optional(Schema.String),
+	apiFolder: Schema.optional(Schema.Union(Schema.String, Schema.Null)),
+	model: Schema.optional(ModelInput),
+	packageJson: Schema.optional(ModelInput),
+	versions: Schema.optional(Schema.mutable(Schema.Record({
+		key: Schema.String,
+		value: VersionValue
+	}))),
+	theme: Schema.optional(ThemeConfig),
+	categories: Schema.optional(CategoriesRecord),
+	source: Schema.optional(SourceConfig),
+	externalPackages: Schema.optional(Schema.mutable(Schema.Array(ExternalPackageSpec))),
+	autoDetectDependencies: Schema.optional(AutoDetectDependencies),
+	ogImage: Schema.optional(OpenGraphImageConfig),
+	llmsPlugin: Schema.optional(LlmsPlugin),
+	tsconfig: Schema.optional(ModelInput),
+	compilerOptions: Schema.optional(Schema.Unknown)
+}));
+const MultiApiConfig = Schema.mutable(Schema.Struct({
+	packageName: Schema.String,
+	name: Schema.optional(Schema.String),
+	baseRoute: Schema.optional(Schema.String),
+	apiFolder: Schema.optional(Schema.Union(Schema.String, Schema.Null)),
+	model: ModelInput,
+	packageJson: Schema.optional(ModelInput),
+	theme: Schema.optional(ThemeConfig),
+	categories: Schema.optional(CategoriesRecord),
+	source: Schema.optional(SourceConfig),
+	externalPackages: Schema.optional(Schema.mutable(Schema.Array(ExternalPackageSpec))),
+	autoDetectDependencies: Schema.optional(AutoDetectDependencies),
+	ogImage: Schema.optional(OpenGraphImageConfig),
+	llmsPlugin: Schema.optional(LlmsPlugin),
+	tsconfig: Schema.optional(ModelInput),
+	compilerOptions: Schema.optional(Schema.Unknown)
+}));
+const PluginOptions = Schema.mutable(Schema.Struct({
+	api: Schema.optional(SingleApiConfig),
+	apis: Schema.optional(Schema.mutable(Schema.Array(MultiApiConfig))),
+	siteUrl: Schema.optional(Schema.String),
+	ogImage: Schema.optional(OpenGraphImageConfig),
+	defaultCategories: Schema.optional(CategoriesRecord),
+	errors: Schema.optional(ErrorConfig),
+	llmsPlugin: Schema.optional(Schema.Union(Schema.Boolean, LlmsPlugin)),
+	logLevel: Schema.optional(LogLevel$1),
+	performance: Schema.optional(PerformanceConfig)
+}));
+
+//#endregion
+export { AutoDetectDependencies, CategoryConfig, DEFAULT_CATEGORIES, ErrorConfig, ExternalPackageSpec, LlmsPlugin, LogLevel$1 as LogLevel, ModelInput, MultiApiConfig, PluginOptions, SingleApiConfig, SourceConfig, ThemeConfig, VersionConfig };

package/schemas/index.js

@@ -0,0 +1,5 @@
+import { OpenGraphImageConfig, OpenGraphImageMetadata } from "./opengraph.js";
+import { PerformanceConfig, PerformanceThresholds } from "./performance.js";
+import { AutoDetectDependencies, CategoryConfig, DEFAULT_CATEGORIES, ErrorConfig, ExternalPackageSpec, LlmsPlugin, LogLevel, ModelInput, MultiApiConfig, PluginOptions, SingleApiConfig, SourceConfig, ThemeConfig, VersionConfig } from "./config.js";
+
+export {  };

package/schemas/opengraph.js

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+
+//#region src/schemas/opengraph.ts
+const OpenGraphImageMetadata = Schema.mutable(Schema.Struct({
+	url: Schema.String,
+	secureUrl: Schema.optional(Schema.String),
+	type: Schema.optional(Schema.String),
+	width: Schema.optional(Schema.Number),
+	height: Schema.optional(Schema.Number),
+	alt: Schema.optional(Schema.String)
+}));
+const OpenGraphImageConfig = Schema.Union(Schema.String, OpenGraphImageMetadata);
+const OpenGraphMetadata = Schema.mutable(Schema.Struct({
+	siteUrl: Schema.String,
+	pageRoute: Schema.String,
+	description: Schema.String,
+	publishedTime: Schema.String,
+	modifiedTime: Schema.String,
+	section: Schema.String,
+	tags: Schema.mutable(Schema.Array(Schema.String)),
+	ogImage: Schema.optional(OpenGraphImageMetadata),
+	ogType: Schema.String
+}));
+
+//#endregion
+export { OpenGraphImageConfig, OpenGraphImageMetadata };

package/schemas/performance.js

@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+
+//#region src/schemas/performance.ts
+const PerformanceThresholds = Schema.mutable(Schema.Struct({
+	slowCodeBlock: Schema.optionalWith(Schema.Number, { default: () => 100 }),
+	slowPageGeneration: Schema.optionalWith(Schema.Number, { default: () => 500 }),
+	slowApiLoad: Schema.optionalWith(Schema.Number, { default: () => 1e3 }),
+	slowFileOperation: Schema.optionalWith(Schema.Number, { default: () => 50 }),
+	slowHttpRequest: Schema.optionalWith(Schema.Number, { default: () => 2e3 }),
+	slowDbOperation: Schema.optionalWith(Schema.Number, { default: () => 100 })
+}));
+const PerformanceConfig = Schema.mutable(Schema.Struct({
+	thresholds: Schema.optional(PerformanceThresholds),
+	showInsights: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	trackDetailedMetrics: Schema.optionalWith(Schema.Boolean, { default: () => false })
+}));
+
+//#endregion
+export { PerformanceConfig, PerformanceThresholds };

package/serve.js

@@ -0,0 +1,133 @@
+import { execFileSync, spawn } from "node:child_process";
+
+//#region src/serve.ts
+const DEFAULT_PORT = 4173;
+/**
+* Readiness heuristic over a chunk of server output. Both RSPress `dev` and
+* `preview` print a `Local:` address line once the server is listening, which
+* is the reliable cross-mode signal. `dev` additionally prints a
+* "ready ... built in" line, kept as a fallback in case the address-line format
+* changes. Pure and exported so it can be unit-tested and reused as a
+* {@link ServeOptions.readyWhen} building block.
+*/
+function isServerReady(mode, output) {
+	if (output.includes("Local:")) return true;
+	if (mode === "dev") return output.includes("ready") && output.includes("built in");
+	return false;
+}
+/**
+* Resolve {@link ServeOptions} into a concrete {@link ResolvedServeConfig},
+* applying all defaults. Pure (modulo reading `process.env`) and exported so
+* the resolution logic can be unit-tested without spawning a server.
+*/
+function resolveServeConfig(options = {}) {
+	const mode = options.mode ?? "dev";
+	const port = options.port ?? (mode === "dev" ? Number(process.env.DEV_PORT) || DEFAULT_PORT : DEFAULT_PORT);
+	const open = options.open ?? !process.env.NO_OPEN;
+	const openPath = options.openPath ?? "/";
+	const packageManager = options.packageManager ?? "pnpm";
+	const cwd = options.cwd ?? process.cwd();
+	const isReady = options.readyWhen ?? ((output) => isServerReady(mode, output));
+	const normalizedPath = openPath.startsWith("/") ? openPath : `/${openPath}`;
+	return {
+		mode,
+		port,
+		open,
+		openPath,
+		packageManager,
+		cwd,
+		args: [
+			"rspress",
+			mode,
+			"--port",
+			String(port)
+		],
+		url: `http://localhost:${port}${normalizedPath}`,
+		isReady
+	};
+}
+/* v8 ignore start -- spawns child processes / opens a browser; covered by the site smoke test, not unit tests */
+/**
+* Best-effort kill of any process listening on `port` (frees a stale dev/preview
+* server). Invokes `lsof` directly via `execFileSync` (no shell), so the port is
+* never interpolated into a shell string. A no-op on platforms without `lsof`
+* (e.g. Windows) or for a non-positive-integer port.
+*/
+function killProcessOnPort(port) {
+	if (!Number.isInteger(port) || port <= 0) return;
+	try {
+		const pids = execFileSync("lsof", [
+			"-t",
+			"-i",
+			`:${port}`
+		], { encoding: "utf-8" }).trim().split("\n").filter(Boolean);
+		for (const pid of pids) process.kill(Number(pid), "SIGTERM");
+		if (pids.length > 0) console.log(`Killed process(es) on port ${port}: ${pids.join(", ")}`);
+	} catch {}
+}
+/**
+* Run an RSPress `dev` or `preview` server, freeing the port first and opening a
+* browser once the server is ready. A drop-in replacement for the per-site
+* `dev.mts` / `preview.mts` scripts:
+*
+* ```ts
+* import { serve } from "rspress-plugin-api-extractor";
+*
+* await serve({ mode: "dev", openPath: "/api/" });
+* ```
+*
+* This runs the server for the lifetime of the host process and calls
+* `process.exit` when the server exits (matching a top-level script runner). The
+* returned promise resolves once the server is ready and the browser has been
+* opened; it does not resolve when the server stops. Port-freeing and browser
+* opening are best-effort and never reject.
+*/
+async function serve(options = {}) {
+	const config = resolveServeConfig(options);
+	killProcessOnPort(config.port);
+	const child = spawn(config.packageManager, config.args, {
+		cwd: config.cwd,
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		],
+		env: {
+			...process.env,
+			FORCE_COLOR: "1"
+		}
+	});
+	const waitForReady = new Promise((resolve) => {
+		let resolved = false;
+		const handleOutput = (data) => {
+			const output = data.toString();
+			process.stdout.write(data);
+			if (!resolved && config.isReady(output)) {
+				resolved = true;
+				resolve();
+			}
+		};
+		child.stdout?.on("data", handleOutput);
+		child.stderr?.on("data", handleOutput);
+	});
+	child.on("error", (error) => {
+		console.error(`Failed to start rspress ${config.mode} server:`, error);
+		process.exit(1);
+	});
+	child.on("exit", (code) => {
+		console.log(`Rspress ${config.mode} server exited`);
+		process.exit(code ?? 0);
+	});
+	await waitForReady;
+	if (config.open) try {
+		const { default: open } = await import("open");
+		await open(config.url);
+		console.log(`✅ Opened ${config.url}`);
+	} catch (error) {
+		console.error("Failed to open browser:", error);
+	}
+}
+/* v8 ignore stop */
+
+//#endregion
+export { isServerReady, resolveServeConfig, serve };

package/services/ConfigService.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+//#region src/services/ConfigService.ts
+var ConfigService = class extends Context.Tag("rspress-plugin-api-extractor/ConfigService")() {};
+
+//#endregion
+export { ConfigService };

package/services/PathDerivationService.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+//#region src/services/PathDerivationService.ts
+var PathDerivationService = class extends Context.Tag("rspress-plugin-api-extractor/PathDerivationService")() {};
+
+//#endregion
+export { PathDerivationService };

package/services/SnapshotService.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+//#region src/services/SnapshotService.ts
+var SnapshotService = class extends Context.Tag("rspress-plugin-api-extractor/SnapshotService")() {};
+
+//#endregion
+export { SnapshotService };

package/services/TypeRegistryService.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+//#region src/services/TypeRegistryService.ts
+var TypeRegistryService = class extends Context.Tag("rspress-plugin-api-extractor/TypeRegistryService")() {};
+
+//#endregion
+export { TypeRegistryService };