rspress-plugin-api-extractor 0.1.2 → 0.2.0

package/tsconfig-parser.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import ts from "typescript";
+
+//#region src/tsconfig-parser.ts
+/**
+* Error thrown when tsconfig.json parsing fails.
+*/
+var TsConfigParseError = class extends Error {
+	configPath;
+	cause;
+	constructor(configPath, message, cause) {
+		super(`Failed to parse tsconfig at ${configPath}: ${message}`);
+		this.configPath = configPath;
+		this.cause = cause;
+		this.name = "TsConfigParseError";
+	}
+};
+/**
+* Parse a tsconfig.json file and extract compiler options relevant for type resolution.
+*
+* This function uses TypeScript's native config parsing which automatically handles:
+* - `extends` chains (resolves and merges all extended configs)
+* - Comments in JSON (JSONC support)
+* - Relative path resolution
+*
+* @param configPath - Path to tsconfig.json (relative or absolute)
+* @param projectRoot - Project root directory for resolving relative paths
+* @returns Parsed compiler options
+* @throws TsConfigParseError if the config cannot be read or parsed
+*
+* @example
+* ```ts
+* const options = parseTsConfig("tsconfig.json", "/path/to/project");
+* // Returns: { target: 99, module: 99, lib: ["ESNext", "DOM"], ... }
+* ```
+*/
+function parseTsConfig(configPath, projectRoot) {
+	return parseTsConfigWithMetadata(configPath, projectRoot).compilerOptions;
+}
+/**
+* Parse a tsconfig.json file and return detailed metadata including extended paths.
+*
+* @param configPath - Path to tsconfig.json (relative or absolute)
+* @param projectRoot - Project root directory for resolving relative paths
+* @returns Parse result with compiler options and metadata
+* @throws TsConfigParseError if the config cannot be read or parsed
+*
+* @example
+* ```ts
+* const result = parseTsConfigWithMetadata("tsconfig.json", "/path/to/project");
+* console.log(result.configPath);      // Absolute path to resolved config
+* console.log(result.extendedPaths);   // ["base.json", "tsconfig.json"]
+* console.log(result.compilerOptions); // Merged compiler options
+* ```
+*/
+function parseTsConfigWithMetadata(configPath, projectRoot) {
+	const absolutePath = isAbsolute(configPath) ? configPath : resolve(projectRoot, configPath);
+	if (!existsSync(absolutePath)) throw new TsConfigParseError(absolutePath, "File not found");
+	const configFileContent = ts.readConfigFile(absolutePath, (path) => readFileSync(path, "utf-8"));
+	if (configFileContent.error) throw new TsConfigParseError(absolutePath, ts.flattenDiagnosticMessageText(configFileContent.error.messageText, "\n"), configFileContent.error);
+	const configDir = dirname(absolutePath);
+	const parsedConfig = ts.parseJsonConfigFileContent(configFileContent.config, ts.sys, configDir, void 0, absolutePath);
+	const significantErrors = parsedConfig.errors.filter((error) => {
+		const message = ts.flattenDiagnosticMessageText(error.messageText, "\n");
+		return error.code !== 18003 && !message.includes("No inputs were found");
+	});
+	if (significantErrors.length > 0) throw new TsConfigParseError(absolutePath, significantErrors.map((error) => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("; "), significantErrors);
+	const extendedPaths = [absolutePath];
+	collectExtendedPaths(configFileContent.config, configDir, extendedPaths);
+	const tsOptions = parsedConfig.options;
+	return {
+		compilerOptions: extractTypeResolutionOptions(tsOptions),
+		configPath: absolutePath,
+		extendedPaths
+	};
+}
+/**
+* Recursively collect extended config paths.
+* @internal
+*/
+function collectExtendedPaths(config, baseDir, paths) {
+	if (!config || typeof config !== "object") return;
+	const extendsValue = config.extends;
+	if (typeof extendsValue === "string") {
+		const extendedPath = resolveExtendedPath(extendsValue, baseDir);
+		if (extendedPath && !paths.includes(extendedPath)) paths.unshift(extendedPath);
+	} else if (Array.isArray(extendsValue)) {
+		for (const ext of extendsValue) if (typeof ext === "string") {
+			const extendedPath = resolveExtendedPath(ext, baseDir);
+			if (extendedPath && !paths.includes(extendedPath)) paths.unshift(extendedPath);
+		}
+	}
+}
+/**
+* Resolve an extended config path.
+* @internal
+*/
+function resolveExtendedPath(extendsValue, baseDir) {
+	try {
+		if (extendsValue.startsWith(".")) return resolve(baseDir, extendsValue);
+		return extendsValue;
+	} catch {
+		return null;
+	}
+}
+/**
+* Extract TypeResolutionCompilerOptions from full TypeScript CompilerOptions.
+* @internal
+*/
+function extractTypeResolutionOptions(tsOptions) {
+	const options = {};
+	if (tsOptions.target !== void 0) options.target = tsOptions.target;
+	if (tsOptions.module !== void 0) options.module = tsOptions.module;
+	if (tsOptions.moduleResolution !== void 0) options.moduleResolution = tsOptions.moduleResolution;
+	if (tsOptions.lib !== void 0 && tsOptions.lib.length > 0) options.lib = tsOptions.lib;
+	if (tsOptions.strict !== void 0) options.strict = tsOptions.strict;
+	if (tsOptions.skipLibCheck !== void 0) options.skipLibCheck = tsOptions.skipLibCheck;
+	if (tsOptions.esModuleInterop !== void 0) options.esModuleInterop = tsOptions.esModuleInterop;
+	if (tsOptions.allowSyntheticDefaultImports !== void 0) options.allowSyntheticDefaultImports = tsOptions.allowSyntheticDefaultImports;
+	if (tsOptions.jsx !== void 0) options.jsx = tsOptions.jsx;
+	if (tsOptions.types !== void 0 && tsOptions.types.length > 0) options.types = tsOptions.types;
+	return options;
+}
+
+//#endregion
+export { TsConfigParseError, parseTsConfig };

package/tsdoc-metadata.json

@@ -1,11 +1,11 @@
-// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
-// It should be published with your NPM package.  It should not be tracked by Git.
-{
-  "tsdocVersion": "0.12",
-  "toolPackages": [
-    {
-      "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.7"
-    }
-  ]
-}
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}

package/twoslash-patterns.js

@@ -0,0 +1,87 @@
+//#region src/twoslash-patterns.ts
+/**
+* Twoslash directive detection patterns.
+*
+* These regexes mirror the upstream Twoslash source at:
+* https://github.com/twoslashes/twoslash/blob/main/packages/twoslash/src/regexp.ts
+*
+* All patterns allow an optional space after `//` (e.g., both `// @noErrors`
+* and `//@noErrors` are valid Twoslash syntax).
+*/
+/**
+* Config directives: boolean flags and key-value pairs.
+*
+* Upstream: `reConfigBoolean` + `reConfigValue` + `reFilenamesMakers`
+*
+* @example
+* ```
+* // @noErrors
+* //@strict
+* // @errors: 2304
+* // @target: ES2020
+* // @filename: example.ts
+* ```
+*/
+const RE_CONFIG = /^\/\/\s?@\w+/;
+/**
+* Annotation markers: query, completion, and highlight markers.
+*
+* Upstream: `reAnnonateMarkers` — `/^\s*\/\/\s*\^(\?|\||\^+)( .*)?$/gm`
+*
+* These are positioned under code lines with `^` characters for alignment.
+* After `line.trim()`, leading whitespace is removed but internal spaces
+* between `//` and `^` are preserved.
+*
+* @example
+* ```
+* // ^? — query (show type info)
+* //    ^? — query with alignment spaces
+* // ^| — completion (show autocomplete)
+* // ^^^ — highlight range
+* // ^^^^ description text
+* ```
+*/
+const RE_ANNOTATION = /^\/\/\s*\^[?|^]/;
+/**
+* Cut directives: control which code is visible in output.
+*
+* Upstream: `reCutBefore`, `reCutAfter`, `reCutStart`, `reCutEnd`
+*
+* @example
+* ```
+* // ---cut---
+* //---cut-before---
+* // ---cut-after---
+* // ---cut-start---
+* // ---cut-end---
+* ```
+*/
+const RE_CUT = /^\/\/\s?---cut/;
+/**
+* Test whether a trimmed line is any Twoslash directive.
+*
+* Covers all directive types: config flags, config values, filename markers,
+* annotation markers (query/completion/highlight), and cut directives.
+*
+* @param trimmedLine - The line with leading/trailing whitespace removed
+* @returns true if the line is a Twoslash directive
+*/
+function isTwoslashDirective(trimmedLine) {
+	return RE_CONFIG.test(trimmedLine) || RE_ANNOTATION.test(trimmedLine) || RE_CUT.test(trimmedLine);
+}
+/**
+* Classify a cut directive line.
+*
+* @param trimmedLine - The line with leading/trailing whitespace removed
+* @returns The cut type, or null if not a cut directive
+*/
+function classifyCutDirective(trimmedLine) {
+	if (/^\/\/\s?---cut(-before)?---$/.test(trimmedLine)) return "cut-before";
+	if (/^\/\/\s?---cut-after---$/.test(trimmedLine)) return "cut-after";
+	if (/^\/\/\s?---cut-start---$/.test(trimmedLine)) return "cut-start";
+	if (/^\/\/\s?---cut-end---$/.test(trimmedLine)) return "cut-end";
+	return null;
+}
+
+//#endregion
+export { classifyCutDirective, isTwoslashDirective };

package/twoslash-transformer.js

@@ -0,0 +1,316 @@
+import { BuildMetrics } from "./layers/ObservabilityLive.js";
+import { DEFAULT_COMPILER_OPTIONS } from "./typescript-config.js";
+import { Effect, Metric } from "effect";
+import { rendererRich, transformerTwoslash } from "@shikijs/twoslash";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toHast } from "mdast-util-to-hast";
+
+//#region src/twoslash-transformer.ts
+/* v8 ignore start -- Shiki/Twoslash integration, requires full highlighter setup for testing */
+/**
+* Module-level type routes map for resolving link references.
+* This is set by TwoslashManager.setTypeRoutes() before initialization.
+*/
+let typeRoutes = /* @__PURE__ */ new Map();
+/**
+* Transform TSDoc link tag syntax to markdown links or plain text.
+*
+* Handles various TSDoc link formats:
+* - Simple type reference
+* - Type with pipe-separated display text
+* - Type with space-separated display text
+*
+* Also handles multiline links where the content may be split across lines.
+*
+* @param text - Text containing TSDoc link references
+* @returns Text with links transformed to markdown or plain text
+*/
+function transformTsDocLinks(text) {
+	return text.replace(/\{@link\s+([\s\S]*?)\}/g, (_match, content) => {
+		const normalized = content.replace(/\s+/g, " ").trim();
+		if (!normalized) return "";
+		const pipeIndex = normalized.indexOf("|");
+		let typeName;
+		let displayText;
+		if (pipeIndex !== -1) {
+			typeName = normalized.substring(0, pipeIndex).trim();
+			displayText = normalized.substring(pipeIndex + 1).trim();
+		} else {
+			const spaceIndex = normalized.indexOf(" ");
+			if (spaceIndex !== -1 && /^[A-Z]/.test(normalized)) {
+				typeName = normalized.substring(0, spaceIndex).trim();
+				displayText = normalized.substring(spaceIndex + 1).trim();
+			} else {
+				typeName = normalized;
+				displayText = normalized;
+			}
+		}
+		const route = typeRoutes.get(typeName);
+		if (route) return `[${displayText}](${route})`;
+		return displayText;
+	});
+}
+/**
+* Process TSDoc documentation content for display in Twoslash hover popups.
+*
+* This function:
+* - Transforms TSDoc link references to markdown links or plain text
+* - Normalizes whitespace around links for proper inline display
+* - Removes example blocks (including their code content)
+* - Removes the remarks tag while keeping the body text
+* - Removes modifier tags (public, internal, private, etc.)
+* - Removes see, param, returns, throws tags (these are rendered separately)
+*
+* @param docs - Raw TSDoc documentation string
+* @returns Cleaned documentation string ready for markdown rendering
+*/
+function processHoverDocs(docs) {
+	let cleaned = transformTsDocLinks(docs);
+	cleaned = cleaned.split(/\n\n+/).map((para) => para.replace(/\s+/g, " ").trim()).filter((para) => para.length > 0).join("\n\n");
+	cleaned = cleaned.replace(/@example[\s\S]*?(?=@[a-zA-Z]|$)/g, "");
+	cleaned = cleaned.replace(/@remarks\s*/g, "");
+	cleaned = cleaned.replace(/@(public|internal|private|protected|readonly|sealed|virtual|override)\s*/g, "");
+	cleaned = cleaned.replace(/@see\s+[^\n]*/g, "");
+	cleaned = cleaned.replace(/@(param|returns?|throws?)\s+[^\n]*/g, "");
+	cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+	return cleaned.trim();
+}
+/**
+* Add rp-link class to all anchor elements in a HAST tree.
+* This enables RSPress link styling in hover popups.
+*
+* @param node - HAST node to process
+*/
+function addLinkClasses(node) {
+	if (node.type === "element") {
+		if (node.tagName === "a") {
+			const existing = node.properties?.class;
+			if (typeof existing === "string") node.properties = {
+				...node.properties,
+				class: `${existing} rp-link`
+			};
+			else node.properties = {
+				...node.properties,
+				class: "rp-link"
+			};
+		}
+		if (node.children) for (const child of node.children) addLinkClasses(child);
+	}
+}
+/**
+* Render markdown content to HAST (Hypertext Abstract Syntax Tree) elements.
+*
+* This function converts markdown strings (from TSDoc comments) into HAST nodes
+* that can be rendered in Twoslash hover popups. It uses mdast-util-from-markdown
+* to parse the markdown and mdast-util-to-hast to convert to HAST.
+*
+* TSDoc link references are transformed to markdown links before parsing.
+* Whitespace is normalized for proper inline display.
+* Links are given the rp-link class for RSPress styling.
+*
+* @param markdown - Markdown string to render
+* @returns Array of HAST ElementContent nodes
+*/
+function renderMarkdown(markdown) {
+	if (!markdown?.trim()) return [];
+	try {
+		let transformed = transformTsDocLinks(markdown);
+		transformed = transformed.split(/\n\n+/).map((para) => para.replace(/\s+/g, " ").trim()).filter((para) => para.length > 0).join("\n\n");
+		const hast = toHast(fromMarkdown(transformed));
+		if (hast && "children" in hast) {
+			const children = hast.children;
+			for (const child of children) addLinkClasses(child);
+			return children;
+		}
+		return [];
+	} catch {
+		return [{
+			type: "text",
+			value: markdown
+		}];
+	}
+}
+/**
+* Tags to hide entirely in hover popups.
+* These are either redundant with the API documentation structure or add noise.
+*/
+const HIDDEN_TAGS = new Set([
+	"example",
+	"public",
+	"internal",
+	"private",
+	"protected",
+	"readonly",
+	"sealed",
+	"virtual",
+	"override"
+]);
+/**
+* Render inline markdown for JSDoc tags with identifying CSS classes.
+*
+* This function wraps tag content in spans with tag-specific classes,
+* allowing CSS to selectively show/hide or style specific tags.
+*
+* @param markdown - The tag content to render
+* @param context - Context string like "tag:remarks", "tag:example", etc.
+* @returns Array of HAST ElementContent nodes
+*/
+function renderMarkdownInline(markdown, context) {
+	const tagName = context.startsWith("tag:") ? context.slice(4) : "";
+	if (HIDDEN_TAGS.has(tagName)) return [{
+		type: "element",
+		tagName: "span",
+		properties: { class: `twoslash-tag-hidden twoslash-tag-${tagName}` },
+		children: []
+	}];
+	const children = renderMarkdown(markdown);
+	return [{
+		type: "element",
+		tagName: "span",
+		properties: { class: `twoslash-tag-content twoslash-tag-${tagName}` },
+		children
+	}];
+}
+/**
+* Singleton manager for the Twoslash transformer, enabling type-aware documentation.
+*
+* The TwoslashManager initializes and manages a Shiki transformer that provides
+* TypeScript IntelliSense features (hover types, error highlighting, completions)
+* in documentation code blocks. It uses a virtual file system (VFS) to provide
+* type definitions without requiring actual file system access.
+*
+* **How it works:**
+* 1. Plugin initializes the manager with a VFS containing all package type definitions
+* 2. Code blocks marked with `twoslash` are processed by the transformer
+* 3. TypeScript language services provide hover information and error checking
+* 4. Results are rendered as HTML with interactive hover popups
+*
+* **VFS Integration:**
+* The VFS is populated by {@link TypeRegistryService} with:
+* - The documented package's own type definitions (from API Extractor)
+* - External package types (fetched via type-registry-effect)
+*
+* **Error Handling:**
+* TypeScript errors in code blocks are captured (not thrown) and:
+* - Counted via Effect Metric (BuildMetrics.twoslashErrors)
+* - Logged inline via console.error
+* - Displayed in the rendered output as error annotations
+*
+* **Relationships:**
+* - Initialized by {@link ApiExtractorPlugin} in the beforeBuild hook
+* - Receives VFS from {@link TypeRegistryService}
+* - The transformer is used by page generators for rendering code blocks
+*
+* @example
+* ```ts
+* const manager = TwoslashManager.getInstance();
+* manager.initialize(vfs, undefined, logger);
+*
+* const transformer = manager.getTransformer();
+* // Use transformer with Shiki highlighter
+* ```
+*
+* @see {@link TypeRegistryService} for VFS generation
+*/
+var TwoslashManager = class TwoslashManager {
+	static instance = null;
+	/**
+	* Twoslash transformer instance
+	*/
+	transformer = null;
+	/**
+	* Private constructor to enforce singleton pattern
+	*/
+	constructor() {}
+	/**
+	* Get the singleton instance of TwoslashManager
+	*/
+	static getInstance() {
+		if (!TwoslashManager.instance) TwoslashManager.instance = new TwoslashManager();
+		return TwoslashManager.instance;
+	}
+	/**
+	* Initialize the Twoslash transformer with a TypeScript environment cache.
+	* This enables type-aware documentation with hover information and IntelliSense.
+	*
+	* @param vfs - Virtual file system mapping file paths to .d.ts content
+	* @param _reserved - Reserved parameter (previously errorStatsCollector, now tracked via Effect Metrics)
+	* @param _reserved2 - Reserved parameter (previously logger, now uses console)
+	* @param tsEnvCache - TypeScript virtual environment cache for reusing language services
+	* @param compilerOptions - TypeScript compiler options for Twoslash (defaults to DEFAULT_COMPILER_OPTIONS)
+	*/
+	initialize(vfs, _reserved, _reserved2, tsEnvCache, compilerOptions) {
+		const extraFiles = {};
+		for (const [path, content] of vfs.entries()) extraFiles[path] = content;
+		const resolvedOptions = compilerOptions ?? DEFAULT_COMPILER_OPTIONS;
+		this.transformer = transformerTwoslash({
+			renderer: rendererRich({
+				processHoverInfo: (info) => {
+					return info.replace(/^\(([\w-]+)\)\s+/gm, "").replace(/\nimport .*$/gm, "").trim();
+				},
+				processHoverDocs,
+				renderMarkdown,
+				renderMarkdownInline
+			}),
+			...tsEnvCache != null ? { cache: tsEnvCache } : {},
+			twoslashOptions: {
+				extraFiles,
+				compilerOptions: resolvedOptions,
+				handbookOptions: { noErrorValidation: true }
+			},
+			explicitTrigger: true,
+			throws: false,
+			onTwoslashError: (error, _code) => {
+				Effect.runSync(Metric.increment(BuildMetrics.twoslashErrors));
+				const errorMsg = error instanceof Error ? error.message : String(error);
+				console.error(`🔴 Twoslash error: ${errorMsg}`);
+			}
+		});
+	}
+	/**
+	* Get the initialized Twoslash transformer.
+	* Returns null if not initialized.
+	*/
+	getTransformer() {
+		return this.transformer;
+	}
+	/**
+	* Clear the Twoslash transformer (useful for testing or reinitializing)
+	*/
+	clear() {
+		this.transformer = null;
+	}
+	/**
+	* Reset the singleton instance (useful for testing)
+	*/
+	static reset() {
+		TwoslashManager.instance = null;
+	}
+	/**
+	* Set the type routes map for resolving link references in hover docs.
+	* This should be called before initialize() to enable type linking.
+	*
+	* @param routes - Map of type names to their documentation URLs
+	*/
+	static setTypeRoutes(routes) {
+		typeRoutes = routes;
+	}
+	/**
+	* Add routes to the existing type routes map.
+	* Useful for adding routes from multiple packages.
+	*
+	* @param routes - Map of type names to their documentation URLs
+	*/
+	static addTypeRoutes(routes) {
+		for (const [name, route] of routes) typeRoutes.set(name, route);
+	}
+	/**
+	* Clear the type routes map (useful for testing)
+	*/
+	static clearTypeRoutes() {
+		typeRoutes.clear();
+	}
+};
+
+//#endregion
+export { TwoslashManager };