rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/type-reference-extractor.js

@@ -0,0 +1,201 @@
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+
+//#region src/type-reference-extractor.ts
+/**
+* Extracts type references from API Extractor models to generate import statements.
+*
+* This class analyzes API items and their excerpt tokens to identify external type
+* references that need to be imported in the generated TypeScript declaration files.
+*
+* **How it works:**
+* 1. Walks through all API items (classes, interfaces, functions, etc.)
+* 2. Extracts type references from excerpt tokens
+* 3. Filters out built-in types and internal references
+* 4. Groups external references by package
+* 5. Generates `import type` statements
+*
+* **Reference Types:**
+* - **Built-in:** TypeScript types like `Promise`, `Record`, `NonNullable` (skipped)
+* - **Internal:** References to types in the same package (skipped)
+* - **External:** References to types from npm packages (imported)
+*
+* **Canonical Reference Format:**
+* API Extractor uses canonical references like:
+* - `"zod!ZodType:interface"` → External reference to `zod` package
+* - `"mypackage!MyType:type"` → Internal reference (same package)
+* - `"!Promise:interface"` → Built-in TypeScript type
+* - `"!\"node:buffer\".__global.Buffer:interface"` → Node.js built-in (treated as built-in)
+*
+* @example
+* ```ts
+* const extractor = new TypeReferenceExtractor(apiPackage, "my-package");
+* const imports = extractor.extractImports();
+*
+* for (const stmt of imports) {
+*   console.log(`import type { ${[...stmt.symbols].join(", ")} } from "${stmt.packageName}";`);
+* }
+* // Output:
+* // import type { ZodType } from "zod";
+* // import type { Effect } from "@effect/schema";
+* ```
+*/
+var TypeReferenceExtractor = class {
+	apiPackage;
+	currentPackageName;
+	/**
+	* All type references found in the API package
+	*/
+	references = /* @__PURE__ */ new Map();
+	constructor(apiPackage, currentPackageName) {
+		this.apiPackage = apiPackage;
+		this.currentPackageName = currentPackageName;
+	}
+	/**
+	* Extract all type references from the API package and generate import statements.
+	* Returns an array of import statements grouped by package.
+	*/
+	extractImports() {
+		this.walkApiPackage();
+		return this.generateImportStatements();
+	}
+	/**
+	* Extract type references for a specific entry point only.
+	* This enables per-entry-point import optimization for multi-entry packages.
+	*
+	* @param entryPoint - The specific entry point to extract imports for
+	* @returns Import statements containing only types used in this entry point
+	*/
+	extractImportsForEntryPoint(entryPoint) {
+		this.references.clear();
+		for (const member of entryPoint.members) this.walkApiItem(member);
+		return this.generateImportStatements();
+	}
+	/**
+	* Extract type references for a single API item.
+	* This enables generating imports for individual signatures.
+	*
+	* @param apiItem - The specific API item to extract imports for
+	* @returns Import statements containing only types used in this item
+	*/
+	extractImportsForApiItem(apiItem) {
+		this.references.clear();
+		this.walkApiItem(apiItem);
+		return this.generateImportStatements();
+	}
+	/**
+	* Generate import statements from collected references.
+	* Used by both extractImports() and extractImportsForEntryPoint().
+	*/
+	generateImportStatements() {
+		const packageMap = /* @__PURE__ */ new Map();
+		for (const ref of this.references.values()) {
+			if (ref.isBuiltIn || ref.isInternal) continue;
+			if (!packageMap.has(ref.packageName)) packageMap.set(ref.packageName, /* @__PURE__ */ new Set());
+			packageMap.get(ref.packageName)?.add(ref.symbolName);
+		}
+		const imports = [];
+		for (const [packageName, symbols] of packageMap.entries()) imports.push({
+			packageName,
+			symbols,
+			typeOnly: true
+		});
+		imports.sort((a, b) => a.packageName.localeCompare(b.packageName));
+		return imports;
+	}
+	/**
+	* Generate import statement strings from ImportStatement objects.
+	* Returns an array of formatted import statements.
+	*/
+	static formatImports(imports) {
+		const statements = [];
+		for (const stmt of imports) {
+			const sortedSymbols = Array.from(stmt.symbols).sort();
+			const statement = `${stmt.typeOnly ? "import type" : "import"} { ${sortedSymbols.join(", ")} } from "${stmt.packageName}";`;
+			statements.push(statement);
+		}
+		return statements;
+	}
+	/**
+	* Walk through the entire API package and extract all type references
+	*/
+	walkApiPackage() {
+		for (const entryPoint of this.apiPackage.entryPoints) for (const member of entryPoint.members) this.walkApiItem(member);
+	}
+	/**
+	* Recursively walk through an API item and its children to extract type references
+	*/
+	walkApiItem(apiItem) {
+		this.extractFromExcerpt(apiItem);
+		if ("members" in apiItem) {
+			const members = apiItem.members;
+			if (Array.isArray(members)) for (const member of members) this.walkApiItem(member);
+		}
+	}
+	/**
+	* Extract type references from an API item using its excerpt
+	*/
+	extractFromExcerpt(apiItem) {
+		const excerpt = this.getExcerpt(apiItem);
+		if (!excerpt) return;
+		this.extractFromExcerptTokens(excerpt);
+	}
+	/**
+	* Get the appropriate excerpt from an API item based on its kind
+	*/
+	getExcerpt(apiItem) {
+		const item = apiItem;
+		if (item.excerpt) return item.excerpt;
+		if (apiItem.kind === ApiItemKind.TypeAlias && item.typeExcerpt) return item.typeExcerpt;
+		if ((apiItem.kind === ApiItemKind.Property || apiItem.kind === ApiItemKind.PropertySignature) && item.propertyTypeExcerpt) return item.propertyTypeExcerpt;
+		if (item.returnTypeExcerpt) return item.returnTypeExcerpt;
+		return null;
+	}
+	/**
+	* Extract type references from excerpt tokens
+	*/
+	extractFromExcerptTokens(excerpt) {
+		if (!excerpt.spannedTokens || excerpt.spannedTokens.length === 0) return;
+		for (const token of excerpt.spannedTokens) {
+			if (token.kind !== "Reference") continue;
+			const canonicalRef = token.canonicalReference?.toString();
+			if (!canonicalRef || typeof canonicalRef !== "string") continue;
+			const ref = this.parseCanonicalReference(canonicalRef, token.text);
+			if (ref) this.references.set(ref.canonicalReference, ref);
+		}
+	}
+	/**
+	* Parse a canonical reference string to extract type reference information.
+	*
+	* Canonical reference format: "packageName!symbolName:kind"
+	* Examples:
+	* - "zod!ZodType:interface" → External reference
+	* - "mypackage!MyType:type" → Internal reference
+	* - "!Promise:interface" → Built-in type
+	* - "!\"node:buffer\".__global.Buffer:interface" → Node.js built-in
+	*/
+	parseCanonicalReference(canonicalRef, symbolText) {
+		const exclamationIndex = canonicalRef.indexOf("!");
+		if (exclamationIndex === -1) return null;
+		const packagePart = canonicalRef.substring(0, exclamationIndex);
+		const rest = canonicalRef.substring(exclamationIndex + 1);
+		const colonIndex = rest.indexOf(":");
+		const symbolFromCanonical = colonIndex !== -1 ? rest.substring(0, colonIndex) : rest;
+		const isBuiltIn = packagePart === "" || packagePart.startsWith("\"");
+		const isInternal = packagePart === this.currentPackageName;
+		let symbolName;
+		if (symbolText.includes(".")) {
+			const parts = symbolText.split(".");
+			symbolName = parts[parts.length - 1].trim();
+		} else symbolName = symbolFromCanonical.trim();
+		return {
+			symbolName,
+			packageName: packagePart,
+			canonicalReference: canonicalRef,
+			isBuiltIn,
+			isInternal
+		};
+	}
+};
+
+//#endregion
+export { TypeReferenceExtractor };

package/typescript-config.js

@@ -0,0 +1,168 @@
+import { TsConfigParseError, parseTsConfig } from "./tsconfig-parser.js";
+
+//#region src/typescript-config.ts
+/**
+* Default TypeScript compiler options for Twoslash and type resolution.
+*
+* These defaults are optimized for documentation:
+* - Modern ES targets (ESNext)
+* - Bundler module resolution for broad compatibility
+* - Lenient settings (non-strict) since docs often show simplified examples
+* - Skip lib checks for faster processing
+*
+* @remarks
+* Numeric values correspond to TypeScript enums:
+* - target: 99 = ESNext
+* - module: 99 = ESNext
+* - moduleResolution: 100 = Bundler
+*/
+const DEFAULT_COMPILER_OPTIONS = {
+	target: 99,
+	module: 99,
+	moduleResolution: 100,
+	lib: ["ESNext", "DOM"],
+	strict: false,
+	skipLibCheck: true,
+	esModuleInterop: true,
+	allowSyntheticDefaultImports: true
+};
+/**
+* Merge two TypeResolutionCompilerOptions objects.
+* Properties from `override` take precedence over `base`.
+*
+* @param base - Base compiler options
+* @param override - Options to merge on top (takes precedence)
+* @returns Merged options
+*
+* @example
+* ```ts
+* const base = { target: 99, lib: ["ESNext"] };
+* const override = { lib: ["ESNext", "DOM"], strict: true };
+* const merged = mergeCompilerOptions(base, override);
+* // Result: { target: 99, lib: ["ESNext", "DOM"], strict: true }
+* ```
+*/
+function mergeCompilerOptions(base, override) {
+	if (!override) return { ...base };
+	const merged = { ...base };
+	if (override.target !== void 0) merged.target = override.target;
+	if (override.module !== void 0) merged.module = override.module;
+	if (override.moduleResolution !== void 0) merged.moduleResolution = override.moduleResolution;
+	if (override.lib !== void 0) merged.lib = override.lib;
+	if (override.strict !== void 0) merged.strict = override.strict;
+	if (override.skipLibCheck !== void 0) merged.skipLibCheck = override.skipLibCheck;
+	if (override.esModuleInterop !== void 0) merged.esModuleInterop = override.esModuleInterop;
+	if (override.allowSyntheticDefaultImports !== void 0) merged.allowSyntheticDefaultImports = override.allowSyntheticDefaultImports;
+	if (override.jsx !== void 0) merged.jsx = override.jsx;
+	if (override.types !== void 0) merged.types = override.types;
+	return merged;
+}
+/**
+* Resolve a single TypeScriptConfig to compiler options (async version).
+* Handles both path-based and function-based tsconfig.
+*
+* Follows the priority cascade:
+* 1. Load tsconfig (from path or function)
+* 2. Merge compilerOptions on top
+*
+* @param config - TypeScript config with optional tsconfig path/function and/or compilerOptions
+* @param projectRoot - Project root for resolving relative tsconfig paths
+* @returns Promise resolving to compiler options (not merged with defaults)
+*
+* @example
+* ```ts
+* // Path-based tsconfig
+* await resolveTypeScriptConfigSingleAsync({ tsconfig: "tsconfig.json" }, "/project");
+*
+* // Function-based tsconfig
+* await resolveTypeScriptConfigSingleAsync({
+*   tsconfig: async () => ({ target: 99, lib: ["ESNext"] })
+* }, "/project");
+*
+* // Both (compilerOptions override tsconfig)
+* await resolveTypeScriptConfigSingleAsync({
+*   tsconfig: async () => ({ target: 99 }),
+*   compilerOptions: { strict: false }
+* }, "/project");
+* ```
+*/
+async function resolveTypeScriptConfigSingleAsync(config, projectRoot) {
+	if (!config) return {};
+	let options = {};
+	if (config.tsconfig) if (typeof config.tsconfig === "function") options = await config.tsconfig();
+	else {
+		const tsconfigPath = String(config.tsconfig);
+		try {
+			options = parseTsConfig(tsconfigPath, projectRoot);
+		} catch (error) {
+			if (error instanceof TsConfigParseError) throw error;
+			throw new TsConfigParseError(tsconfigPath, error instanceof Error ? error.message : String(error), error);
+		}
+	}
+	if (config.compilerOptions) options = mergeCompilerOptions(options, config.compilerOptions);
+	return options;
+}
+/**
+* Resolve TypeScript compiler options from a cascade of configurations (async).
+*
+* Resolution order (later levels override earlier):
+* 1. DEFAULT_COMPILER_OPTIONS (sensible defaults)
+* 2. Global plugin config
+* 3. API-level config
+* 4. Version-level config
+* 5. Per-package override (for external packages)
+*
+* At each level, if a TypeScriptConfig has both `tsconfig` and `compilerOptions`,
+* the tsconfig is loaded first, then compilerOptions are merged on top.
+*
+* @param projectRoot - Project root directory for resolving relative paths
+* @param global - Global plugin TypeScript configuration
+* @param api - API-level TypeScript configuration
+* @param version - Version-level TypeScript configuration
+* @param packageOverride - Per-package TypeScript configuration override
+* @returns Promise resolving to fully resolved compiler options
+*
+* @example
+* ```ts
+* // Simple global config
+* const options = await resolveTypeScriptConfig("/project", {
+*   tsconfig: "tsconfig.json"
+* });
+*
+* // With async tsconfig loader
+* const options = await resolveTypeScriptConfig("/project", {
+*   tsconfig: async () => ({ target: 99, lib: ["ESNext"] })
+* });
+*
+* // With API override
+* const options = await resolveTypeScriptConfig(
+*   "/project",
+*   { tsconfig: "tsconfig.json" },
+*   { compilerOptions: { strict: false } }
+* );
+*
+* // Full cascade
+* const options = await resolveTypeScriptConfig(
+*   "/project",
+*   { tsconfig: "tsconfig.json" },           // global
+*   { compilerOptions: { strict: false } },  // API
+*   { compilerOptions: { target: 9 } },      // version
+*   { compilerOptions: { module: 1 } }       // package override
+* );
+* ```
+*/
+async function resolveTypeScriptConfig(projectRoot, global, api, version, packageOverride) {
+	let options = { ...DEFAULT_COMPILER_OPTIONS };
+	const globalOptions = await resolveTypeScriptConfigSingleAsync(global, projectRoot);
+	options = mergeCompilerOptions(options, globalOptions);
+	const apiOptions = await resolveTypeScriptConfigSingleAsync(api, projectRoot);
+	options = mergeCompilerOptions(options, apiOptions);
+	const versionOptions = await resolveTypeScriptConfigSingleAsync(version, projectRoot);
+	options = mergeCompilerOptions(options, versionOptions);
+	const packageOptions = await resolveTypeScriptConfigSingleAsync(packageOverride, projectRoot);
+	options = mergeCompilerOptions(options, packageOptions);
+	return options;
+}
+
+//#endregion
+export { DEFAULT_COMPILER_OPTIONS, resolveTypeScriptConfig };

package/vfs-registry.js

@@ -0,0 +1,121 @@
+//#region src/vfs-registry.ts
+/**
+* Module-scoped registry for VFS configurations.
+*
+* This is a singleton registry that stores VFS data keyed by:
+* - API scope (e.g., "claude-binary-plugin")
+*
+* The registry is designed to be:
+* - Written to during `beforeBuild` (when VFS is generated)
+* - Read from during MDX compilation (when remark plugin transforms code blocks)
+* - Thread-safe for reads (VFS is immutable after registration)
+*/
+var VfsRegistryImpl = class {
+	/**
+	* Map of API scope to VFS configuration
+	*/
+	configs = /* @__PURE__ */ new Map();
+	/**
+	* Register a VFS configuration for an API scope.
+	*
+	* @param apiScope - The API scope identifier (e.g., "claude-binary-plugin")
+	* @param config - The VFS configuration to register
+	*/
+	register(apiScope, config) {
+		this.configs.set(apiScope, config);
+	}
+	/**
+	* Get the VFS configuration for an API scope.
+	*
+	* @param apiScope - The API scope to look up
+	* @returns The VFS configuration, or undefined if not found
+	*/
+	get(apiScope) {
+		return this.configs.get(apiScope);
+	}
+	/**
+	* Get the VFS configuration by matching a file path to an API scope.
+	*
+	* This method extracts the API scope from a file path and returns
+	* the corresponding VFS configuration.
+	*
+	* @param filePath - The absolute file path being processed
+	* @returns The VFS configuration, or undefined if not found
+	*/
+	getByFilePath(filePath) {
+		const apiScope = this.extractApiScope(filePath);
+		if (!apiScope) return;
+		return this.get(apiScope);
+	}
+	/**
+	* Extract the API scope from a file path.
+	*
+	* Path patterns:
+	* - `docs/en/api-scope/rest.mdx`
+	* - `website/docs/en/api-scope/rest.mdx`
+	*
+	* @param filePath - The file path to extract from
+	* @returns The API scope, or undefined if not matched
+	*/
+	extractApiScope(filePath) {
+		const match = filePath.replace(/\\/g, "/").match(/(?:^|\/)(docs\/en|website\/docs\/en)\/([^/]+)(?:\/|$)/);
+		if (!match) return;
+		return match[2];
+	}
+	/**
+	* Check if any VFS configurations are registered.
+	*
+	* @returns True if at least one configuration is registered
+	*/
+	hasConfigs() {
+		return this.configs.size > 0;
+	}
+	/**
+	* Get all registered API scopes.
+	*
+	* @returns Array of registered API scope identifiers
+	*/
+	getScopes() {
+		return Array.from(this.configs.keys());
+	}
+	/**
+	* Clear all registered configurations.
+	*
+	* This should be called between builds to avoid stale data.
+	*/
+	clear() {
+		this.configs.clear();
+	}
+};
+/**
+* Global VFS Registry singleton instance.
+*
+* Use this to register and retrieve VFS configurations:
+*
+* @example
+* ```ts
+* // In beforeBuild hook:
+* VfsRegistry.register("claude-binary-plugin", {
+*   vfs: combinedVfs,
+*   highlighter,
+*   twoslashTransformer,
+*   crossLinker: shikiCrossLinker,
+*   packageName: "claude-binary-plugin",
+*   apiScope: "claude-binary-plugin",
+* });
+*
+* // In remark plugin:
+* const config = VfsRegistry.getByFilePath(file.path);
+* if (config) {
+*   // Generate HAST with Shiki, then post-process with cross-linker
+*   let hast = await generateShikiHast(code, config.highlighter, transformers);
+*   if (hast && config.crossLinker) {
+*     hast = config.crossLinker.transformHast(hast, config.apiScope);
+*   }
+* }
+* ```
+*/
+const VfsRegistry = new VfsRegistryImpl();
+
+//#endregion
+export { VfsRegistry };