rspress-plugin-api-extractor 0.10.0 → 0.11.0

package/twoslash-transformer.js

@@ -1,26 +1,14 @@
 import { PluginEvent } from "./observability/events.js";
+import { emitSync, syncBuildId } from "./observability/sync-emitter.js";
 import { DEFAULT_COMPILER_OPTIONS } from "./typescript-config.js";
+import { Result } from "effect";
+import { Markdown, Mdast } from "@effected/markdown";
+import { TsEnumCodec } from "@effected/tsconfig-json";
 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
-/**
-* Module-level emitter seam. Default is a no-op; wire in `setEventEmitter(emitSync)`
-* from plugin.ts right after the runtime emitter is created so that Twoslash error
-* events flow through the EventBus even though they fire in a sync Shiki callback
-* outside any Effect fiber.
-*/
-let emitEvent = () => {};
-let currentBuildId = "";
-/**
-* Inject the runtime-bound emitter into the Twoslash module.
-* Call this right after `makeRuntimeEmitter` in plugin.ts.
-*/
-function setEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
+/* 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.
@@ -115,8 +103,10 @@ function addLinkClasses(node) {
 * 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.
+* that can be rendered in Twoslash hover popups. It parses with
+* `@effected/markdown` (CommonMark dialect) and converts to HAST with
+* `mdast-util-to-hast`, which stays because markdown-to-HTML is permanently
+* out of scope for the kit.
 *
 * TSDoc link references are transformed to markdown links before parsing.
 * Whitespace is normalized for proper inline display.
@@ -130,8 +120,12 @@ function renderMarkdown(markdown) {
 	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 mdast = fromMarkdown(transformed);
-		const hast = toHast(mdast);
+		const parsed = Markdown.parseResult(transformed, { dialect: "commonmark" });
+		if (Result.isFailure(parsed)) return [{
+			type: "text",
+			value: markdown
+		}];
+		const hast = toHast(Mdast.toMdast(parsed.success));
 		if (hast && "children" in hast) {
 			const children = hast.children;
 			for (const child of children) addLinkClasses(child);
@@ -232,12 +226,63 @@ function renderMarkdownInline(markdown, context) {
 * blocks routed to the right one. Keys are sorted, so two configurations that
 * differ only in property order share an environment.
 */
+/**
+* Convert resolved compiler options from the tsconfig JSON spelling to the
+* programmatic one a real compiler expects.
+*
+* @remarks
+* Two spellings meet here, and only here. `tsconfig.json` writes
+* `lib: ["ESNext", "DOM"]` and `target: "esnext"`; `ts.CompilerOptions` wants
+* lib FILE NAMES (`lib.esnext.d.ts`) and numeric enums. `DEFAULT_COMPILER_OPTIONS`
+* is authored in the tsconfig spelling, and a tsconfig discovered from disk
+* arrives already converted by `ts.parseJsonConfigFileContent`, so both forms
+* reach this function — which is why the conversion must be idempotent rather
+* than one-directional.
+*
+* Exported for the four-path regression test: no runtime path in this repo
+* reaches the broken spelling (an unscoped block inherits the first registered
+* environment, not the raw default), so a synthetic test compiling each
+* resolution path through the real compiler is the only verification there is.
+*/
+function toProgrammaticCompilerOptions(options) {
+	return TsEnumCodec.encodeCompilerOptions(options);
+}
+/**
+* Fingerprint a compiler configuration, for keying the environment map.
+*
+* @remarks
+* INVARIANT: every call site must pass options that have already been through
+* {@link toProgrammaticCompilerOptions}. There are two — `initialize`, which
+* stores an environment under this key, and `registerScope`, which looks one
+* up by it. Both must encode, and encode the same way.
+*
+* The failure mode is SILENT. Encode at one site and not the other and the
+* keys stop matching, so `getTransformer(scope)` finds nothing and falls back
+* to the default environment: per-scope type-checking quietly degrades to
+* build-wide, no error is raised, and nothing in the output looks wrong.
+*
+* This is not hypothetical. Task 1.2 moved the `initialize` fingerprint behind
+* the encoder as a step specified — and reviewed — as a no-op, left
+* `registerScope` on the raw options, and the full 994-test suite stayed green
+* over the defect. The mutation that should have caught it (fingerprinting the
+* pre-encoded value) also survived that suite. What caught it was a test
+* written specifically for the hazard, which then failed for this second,
+* unanticipated reason. `__test__/twoslash-transformer.test.ts` now pins both
+* halves; keep that test whenever this code moves.
+*/
 function twoslashConfigKey(options) {
 	const entries = Object.entries(options).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
 	return JSON.stringify(entries);
 }
-var TwoslashManager = class TwoslashManager {
-	static instance = null;
+/**
+* The mutable registry behind {@link TwoslashEnvironments}.
+*
+* @remarks
+* A plain class the Layer constructs, not a singleton. `getInstance()` and the
+* static `reset()` that stood in for layer substitution are gone: a test that
+* wants a different environment set provides a different layer.
+*/
+var TwoslashEnvironmentRegistry = class {
 	/**
 	* Transformers keyed by compiler-config fingerprint.
 	*
@@ -265,7 +310,7 @@ var TwoslashManager = class TwoslashManager {
 	* Resolved compiler options captured at initialize() time.
 	* Returned by compilerOptionsSnapshot() for TwoslashCheckFailed events.
 	*/
-	_resolvedCompilerOptions = DEFAULT_COMPILER_OPTIONS;
+	_resolvedCompilerOptions = toProgrammaticCompilerOptions(DEFAULT_COMPILER_OPTIONS);
 	/**
 	* Path of the file whose code block is currently being processed.
 	* Used to attribute Twoslash error events to a source file. Defaults to
@@ -274,31 +319,20 @@ var TwoslashManager = class TwoslashManager {
 	*/
 	currentFilePath = "unknown";
 	/**
-	* 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.
+	* Build an environment for a configuration, or return if one exists.
 	*
-	* @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)
+	* @remarks
+	* The signature this replaces took six positional parameters, two named
+	* `_reserved`/`_reserved2` and one (`tsEnvCache`) that every call site
+	* passed as `undefined`. Dropping `tsEnvCache` changes nothing at runtime
+	* for exactly that reason — Twoslash was never handed a shared environment
+	* cache.
 	*/
-	initialize(vfs, _reserved, _reserved2, tsEnvCache, compilerOptions, typesCache) {
+	registerEnvironment({ vfs, compilerOptions, typesCache }) {
 		const extraFiles = {};
 		for (const [path, content] of vfs.entries()) extraFiles[path] = content;
 		this._vfsKeys = Array.from(vfs.keys());
-		const resolvedOptions = compilerOptions ?? DEFAULT_COMPILER_OPTIONS;
+		const resolvedOptions = toProgrammaticCompilerOptions(compilerOptions ?? DEFAULT_COMPILER_OPTIONS);
 		this._resolvedCompilerOptions = resolvedOptions;
 		const configKey = twoslashConfigKey(resolvedOptions);
 		if (this.defaultConfigKey === null) this.defaultConfigKey = configKey;
@@ -312,7 +346,6 @@ var TwoslashManager = class TwoslashManager {
 				renderMarkdown,
 				renderMarkdownInline
 			}),
-			...tsEnvCache != null ? { cache: tsEnvCache } : {},
 			...typesCache != null ? { typesCache } : {},
 			twoslashOptions: {
 				extraFiles,
@@ -332,7 +365,7 @@ var TwoslashManager = class TwoslashManager {
 	* under, so its code blocks are type-checked with that configuration.
 	*/
 	registerScope(apiScope, compilerOptions) {
-		this.scopeConfigs.set(apiScope, twoslashConfigKey(compilerOptions));
+		this.scopeConfigs.set(apiScope, twoslashConfigKey(toProgrammaticCompilerOptions(compilerOptions)));
 	}
 	/**
 	* Get the Twoslash transformer for an API scope.
@@ -342,7 +375,7 @@ var TwoslashManager = class TwoslashManager {
 	* route, and type-checking it under some configuration beats not checking it.
 	* Returns null before any environment is initialized.
 	*/
-	getTransformer(apiScope) {
+	transformerFor(apiScope) {
 		const key = (apiScope != null ? this.scopeConfigs.get(apiScope) : void 0) ?? this.defaultConfigKey;
 		return key != null ? this.environments.get(key) ?? null : null;
 	}
@@ -363,12 +396,6 @@ var TwoslashManager = class TwoslashManager {
 		this.scopeConfigs.clear();
 		this.defaultConfigKey = null;
 	}
-	/**
-	* Reset the singleton instance (useful for testing)
-	*/
-	static reset() {
-		TwoslashManager.instance = null;
-	}
 	/** Returns VFS keys snapshotted at initialize() time. Empty array before initialize(). */
 	vfsKeysSnapshot() {
 		return this._vfsKeys;
@@ -381,9 +408,9 @@ var TwoslashManager = class TwoslashManager {
 		const message = error instanceof Error ? error.message : String(error);
 		const match = /TS(\d+)/.exec(message);
 		const tsCode = match ? Number(match[1]) : 0;
-		emitEvent(PluginEvent.TwoslashDiagnostic({
+		emitSync(PluginEvent.TwoslashDiagnostic({
 			ctx: {
-				buildId: currentBuildId,
+				buildId: syncBuildId(),
 				file
 			},
 			level: "warn",
@@ -394,9 +421,9 @@ var TwoslashManager = class TwoslashManager {
 			message,
 			snippet: ""
 		}));
-		emitEvent(PluginEvent.TwoslashCheckFailed({
+		emitSync(PluginEvent.TwoslashCheckFailed({
 			ctx: {
-				buildId: currentBuildId,
+				buildId: syncBuildId(),
 				file
 			},
 			level: "trace",
@@ -410,34 +437,30 @@ var TwoslashManager = class TwoslashManager {
 	* Test seam: drive `handleTwoslashError` directly without going through the Shiki transformer.
 	* @internal
 	*/
-	handleTwoslashErrorForTest(error, code, file) {
+	reportErrorForTest(error, code, file) {
 		this.handleTwoslashError(error, code, file);
 	}
-	/**
-	* 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();
-	}
 };
+/** Merge routes in, so a multi-API build accumulates every scope's names. */
+function addTypeRoutes(routes) {
+	for (const [name, route] of routes) typeRoutes.set(name, route);
+}
+/**
+* Clear the accumulated type routes.
+*
+* @remarks
+* Called from `config()` at the start of every build. `addTypeRoutes` only
+* ever adds, so without this a dev session keeps routes for items that have
+* since been renamed or removed, and a multi-API build leaks every scope's
+* names into one map.
+*
+* Clears ONLY the routes. The environments are per-build too, but they are
+* owned by the layer now, so nothing here can discard the per-scope
+* transformers `ConfigServiceLive` just built.
+*/
+function clearTypeRoutes() {
+	typeRoutes.clear();
+}
 
 //#endregion
-export { TwoslashManager, setEventEmitter };
+export { TwoslashEnvironmentRegistry, addTypeRoutes, clearTypeRoutes, toProgrammaticCompilerOptions };

package/vfs-registry.js

@@ -34,35 +34,6 @@ var VfsRegistryImpl = class {
 		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
@@ -96,7 +67,6 @@ var VfsRegistryImpl = class {
 * ```ts
 * // In beforeBuild hook:
 * VfsRegistry.register("claude-binary-plugin", {
-*   vfs: combinedVfs,
 *   highlighter,
 *   twoslashTransformer,
 *   crossLinker: shikiCrossLinker,
@@ -105,7 +75,7 @@ var VfsRegistryImpl = class {
 * });
 *
 * // In remark plugin:
-* const config = VfsRegistry.getByFilePath(file.path);
+* const config = VfsRegistry.get(apiScope);
 * if (config) {
 *   // Generate HAST with Shiki, then post-process with cross-linker
 *   let hast = await generateShikiHast(code, config.highlighter, transformers);

package/layers/PathDerivationServiceLive.js

@@ -1,16 +0,0 @@
-import { deriveOutputPaths, normalizeBaseRoute } from "../path-derivation.js";
-import { PathDerivationService } from "../services/PathDerivationService.js";
-import { Effect, Layer } from "effect";
-
-//#region src/layers/PathDerivationServiceLive.ts
-const PathDerivationServiceLive = Layer.succeed(PathDerivationService, {
-	derivePaths: (input) => Effect.succeed(deriveOutputPaths({
-		...input,
-		locales: [...input.locales],
-		versions: [...input.versions]
-	})),
-	normalizeBaseRoute: (route) => Effect.succeed(normalizeBaseRoute(route))
-});
-
-//#endregion
-export { PathDerivationServiceLive };

package/services/PathDerivationService.js

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