rspress-plugin-api-extractor 0.10.0 → 0.12.0

package/observability/sync-emitter.js

@@ -0,0 +1,78 @@
+import { BuildId, Thresholds } from "../BuildEnv.js";
+import { emit } from "./EventBus.js";
+import { Effect } from "effect";
+
+//#region src/observability/sync-emitter.ts
+/**
+* The one bridge from synchronous, fiber-less code to the EventBus.
+*
+* @remarks
+* Seven modules run outside any Effect fiber — remark visitors, Shiki's
+* `preprocess` hook, Prettier callbacks, the page-generation stages — and each
+* carried its own byte-identical copy of this seam: a module-level
+* `emitEvent`, a module-level `currentBuildId`, and a `setXEventEmitter(fn,
+* buildId)` for `plugin.ts` to call. Two of them had already grown a third
+* parameter for `slowCodeBlockMs`, which is how a duplicated seam decays: the
+* copies stop being identical one caller at a time.
+*
+* The seam itself is forced. The duplication was not, and neither was the
+* threading: every value those setters carried is now a `Context.Reference`
+* read from the runtime, so the signature is one runtime and nothing else.
+*
+* **The runtime handed here must be synchronously buildable.** `runSync`
+* builds the runtime's layer before running anything, so a runtime whose layer
+* opens a database fails with `AsyncFiberError` at the first emit — from a
+* remark plugin, during RSPress's render pass, invisible to every unit test.
+* `plugin.ts` builds a small observability-only runtime for exactly this
+* reason.
+*
+* @packageDocumentation
+*/
+const NOOP = {
+	emit: () => {},
+	buildId: "",
+	slowCodeBlockMs: Number.POSITIVE_INFINITY
+};
+let current = NOOP;
+/**
+* Bind the sync islands to a runtime.
+*
+* @remarks
+* Call once, immediately after constructing the observability runtime. The
+* References are read here rather than per emit: an emit happens per code
+* block on a large site, and these values are fixed for the build.
+*/
+function installSyncEmitter(runtime) {
+	const env = runtime.runSync(Effect.gen(function* () {
+		return {
+			buildId: yield* BuildId,
+			slowCodeBlockMs: (yield* Thresholds).slowCodeBlock
+		};
+	}));
+	current = {
+		emit: (event) => runtime.runSync(emit(event)),
+		buildId: env.buildId,
+		slowCodeBlockMs: env.slowCodeBlockMs
+	};
+}
+/** Emit an event from synchronous code. A no-op when nothing is installed. */
+function emitSync(event) {
+	current.emit(event);
+}
+/** The current build's id, for a sync site assembling an `EventContext`. */
+function syncBuildId() {
+	return current.buildId;
+}
+/**
+* The slow-code-block threshold, for the two remark plugins that time blocks.
+*
+* @remarks
+* The only piece of configuration a sync island needs beyond the build id, and
+* the reason the old seams had begun growing divergent signatures.
+*/
+function syncSlowCodeBlockMs() {
+	return current.slowCodeBlockMs;
+}
+
+//#endregion
+export { emitSync, installSyncEmitter, syncBuildId, syncSlowCodeBlockMs };

package/og-resolver.js

@@ -1,19 +1,6 @@
-import { PluginEvent } from "./observability/events.js";
-import fs from "node:fs";
-import path from "node:path";
-import { imageSizeFromFile } from "image-size/fromFile";
-
 //#region src/og-resolver.ts
-/** Module-level emitter injected by plugin.ts at startup. */
-let emitEvent = () => {};
-let currentBuildId = "";
-function setOgResolverEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
 /**
-* MIME type mappings for common image formats.
-* Used to determine the `og:image:type` meta tag value.
+* MIME type mappings for common image formats, used for `og:image:type`.
 */
 const IMAGE_MIME_TYPES = {
 	jpg: "image/jpeg",
@@ -24,282 +11,85 @@ const IMAGE_MIME_TYPES = {
 	svg: "image/svg+xml"
 };
 /**
-* Resolves Open Graph image configurations into fully-qualified metadata.
+* The `og:image:type` value for a detected image format, or `undefined` for a
+* format with no mapping.
+*/
+function imageMimeType(type) {
+	if (type == null) return void 0;
+	return IMAGE_MIME_TYPES[type.toLowerCase()];
+}
+/**
+* Turn a configured image URL into an absolute one.
 *
-* This class handles the conversion of flexible OG image configuration formats
-* (strings or metadata objects) into complete `OpenGraphImageMetadata` objects
-* with resolved URLs and auto-detected dimensions for local images.
+* @returns The absolute URL, or `undefined` when the input is neither an
+* absolute `http(s)` URL nor a site-root-relative path. A bare relative path
+* is deliberately rejected rather than guessed at — there is no base to
+* resolve it against that would not silently produce a broken link.
+*/
+function resolveOgUrl(siteUrl, url) {
+	if (url.startsWith("http://") || url.startsWith("https://")) return url;
+	if (url.startsWith("/")) return `${siteUrl}${url}`;
+}
+/**
+* Derive the site URL prefix from RSPress's own config.
 *
 * @remarks
-* The resolver supports two input formats:
-* - **String format**: A URL or path that will be resolved and optionally enhanced
-*   with auto-detected dimensions if pointing to a local file.
-* - **Object format**: Detailed metadata with explicit properties that will be
-*   validated and URL-resolved.
+* Replaces the plugin's former `siteUrl` option. RSPress already knows where a
+* site is deployed — {@link https://rspress.rs/api/config/config-basic#siteorigin | `siteOrigin`}
+* plus `base` — so asking for it a second time invited the two to disagree, and
+* a plugin-level answer that contradicted the site's own would silently emit
+* canonical and `og:url` tags pointing at a host the site is not served from.
 *
-* @example Basic usage with a relative path
-* ```typescript
-* const resolver = new OpenGraphResolver({
-*   siteUrl: "https://example.com",
-*   docsRoot: "/path/to/docs"
-* });
+* RSPress concatenates as `siteOrigin + base + routePath`, and **this follows
+* its documented fallback exactly**: with no `siteOrigin`, RSPress uses
+* `base + routePath`. So an unset origin yields a ROOT-RELATIVE prefix rather
+* than nothing.
 *
-* const metadata = await resolver.resolve(
-*   "/images/og-api.png",
-*   "my-package",
-*   "MyClass"
-* );
-* // Result: { url: "https://example.com/images/og-api.png", width: 1200, height: 630, ... }
-* ```
+* That fallback is what makes the tags inspectable in `rspress dev`, where the
+* site is served from `localhost` and no configured origin could be correct
+* anyway. A root-relative `/images/og.png` resolves against the page's own
+* origin in the browser; it is a *relative* path (`images/og.png`, no leading
+* slash) that has no base to resolve against, and this never emits one.
 *
-* @example Using detailed configuration
-* ```typescript
-* const metadata = await resolver.resolve(
-*   {
-*     url: "/images/og.png",
-*     alt: "Custom alt text",
-*     width: 1200,
-*     height: 630
-*   },
-*   "my-package"
-* );
-* ```
+* @returns The prefix to put in front of a route that already begins with `/`.
+* `""` when the site declares neither `siteOrigin` nor a non-root `base`, which
+* leaves every URL root-relative. Never has a trailing slash, since every
+* caller appends a route starting with `/`.
 */
-var OpenGraphResolver = class {
-	siteUrl;
-	docsRoot;
-	/**
-	* Creates a new OpenGraphResolver instance.
-	*
-	* @param options - Configuration options for the resolver.
-	*   `siteUrl`: Base URL for the website (e.g., "https://example.com"),
-	*   used to construct absolute URLs from relative paths.
-	*   `docsRoot`: Optional root directory for documentation files;
-	*   when provided, enables auto-detection of image dimensions for local files
-	*   by looking in the `public` subdirectory.
-	*/
-	constructor(options) {
-		this.siteUrl = options.siteUrl;
-		if (options.docsRoot != null) this.docsRoot = options.docsRoot;
-	}
-	/**
-	* Resolves an Open Graph image configuration into complete metadata.
-	*
-	* Handles both string URLs/paths and detailed metadata objects, converting them
-	* into fully-qualified `OpenGraphImageMetadata` with absolute URLs.
-	*
-	* @param config - The OG image configuration to resolve. Can be:
-	*   - A string URL (absolute or relative path starting with `/`)
-	*   - An `OpenGraphImageMetadata` object with explicit properties
-	*   - `undefined` to indicate no OG image
-	* @param packageName - The package name for generating default alt text
-	* @param apiName - Optional API name for more descriptive alt text
-	* @returns Resolved metadata with absolute URLs, or `undefined` if:
-	*   - `config` is `undefined`
-	*   - The URL format is invalid
-	*
-	* @example Resolve a relative path
-	* ```typescript
-	* const metadata = await resolver.resolve("/images/og.png", "my-lib");
-	* // Returns: { url: "https://example.com/images/og.png", alt: "my-lib API Documentation", ... }
-	* ```
-	*
-	* @example Resolve an absolute URL
-	* ```typescript
-	* const metadata = await resolver.resolve("https://cdn.example.com/og.png", "my-lib");
-	* // Returns: { url: "https://cdn.example.com/og.png", alt: "my-lib API Documentation" }
-	* ```
-	*/
-	async resolve(config, packageName, apiName) {
-		if (!config) return;
-		if (typeof config === "object") return this.resolveFromMetadata(config, packageName, apiName);
-		return this.resolveFromString(config, packageName, apiName);
-	}
-	/**
-	* Resolves a metadata object configuration into complete OG image metadata.
-	*
-	* Validates and resolves URLs in the provided metadata object, ensuring all
-	* URLs are absolute and properly formatted.
-	*
-	* @param metadata - The metadata object containing OG image properties
-	* @param packageName - Package name for default alt text generation
-	* @param apiName - Optional API name for more descriptive alt text
-	* @returns Resolved metadata with absolute URLs, or `undefined` if URL is invalid
-	*/
-	async resolveFromMetadata(metadata, packageName, apiName) {
-		const { url, secureUrl, type, width, height, alt } = metadata;
-		const resolvedUrl = this.resolveUrl(url);
-		if (!resolvedUrl) {
-			emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage.url",
-				value: url,
-				reason: "invalid URL format",
-				level: "warn"
-			}));
-			return;
-		}
-		let resolvedSecureUrl;
-		if (secureUrl) {
-			if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
-			else emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage.secureUrl",
-				value: secureUrl,
-				reason: "secureUrl must be absolute HTTPS",
-				level: "warn"
-			}));
-		}
-		return {
-			url: resolvedUrl,
-			secureUrl: resolvedSecureUrl,
-			type,
-			width,
-			height,
-			alt: alt ?? this.generateAltText(packageName, apiName)
-		};
-	}
-	/**
-	* Resolves a string URL/path into complete OG image metadata.
-	*
-	* For relative paths pointing to local files, this method will attempt to:
-	* 1. Locate the file in the docs `public` directory
-	* 2. Read the image dimensions using `image-size`
-	* 3. Determine the MIME type from the file extension
-	*
-	* @param imageUrl - The image URL or path to resolve
-	* @param packageName - Package name for alt text generation
-	* @param apiName - Optional API name for more descriptive alt text
-	* @returns Resolved metadata with auto-detected dimensions for local files,
-	*   or `undefined` if the URL format is invalid
-	*/
-	async resolveFromString(imageUrl, packageName, apiName) {
-		const resolvedUrl = this.resolveUrl(imageUrl);
-		if (!resolvedUrl) {
-			emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage",
-				value: imageUrl,
-				reason: "invalid URL format",
-				level: "warn"
-			}));
-			return;
-		}
-		const localPath = this.findLocalImage(imageUrl);
-		const dimensions = localPath ? await this.readImageDimensions(localPath) : void 0;
-		return {
-			url: resolvedUrl,
-			type: dimensions?.type,
-			width: dimensions?.width,
-			height: dimensions?.height,
-			alt: this.generateAltText(packageName, apiName)
-		};
-	}
-	/**
-	* Resolves a URL string to an absolute URL.
-	*
-	* @param url - The URL to resolve (absolute URL or relative path)
-	* @returns The absolute URL, or `undefined` if the format is invalid
-	*/
-	resolveUrl(url) {
-		if (url.startsWith("http://") || url.startsWith("https://")) return url;
-		if (url.startsWith("/")) return `${this.siteUrl}${url}`;
-	}
-	/**
-	* Attempts to find a local image file in the docs public directory.
-	*
-	* @param imagePath - The relative image path (starting with `/`)
-	* @returns The absolute file path if found, or `undefined` if not found
-	*   or if `docsRoot` is not configured
-	*/
-	findLocalImage(imagePath) {
-		if (!this.docsRoot || !imagePath.startsWith("/")) return;
-		const publicPath = path.join(this.docsRoot, "public", imagePath);
-		if (fs.existsSync(publicPath)) return publicPath;
-	}
-	/**
-	* Reads image dimensions and type from a local file.
-	*
-	* @param filePath - Absolute path to the image file
-	* @returns Object containing width, height, and MIME type if successful,
-	*   or `undefined` if the file cannot be read or analyzed
-	*/
-	async readImageDimensions(filePath) {
-		try {
-			const dimensions = await imageSizeFromFile(filePath);
-			let mimeType;
-			if (dimensions.type) mimeType = IMAGE_MIME_TYPES[dimensions.type.toLowerCase()];
-			return {
-				width: dimensions.width,
-				height: dimensions.height,
-				...mimeType != null ? { type: mimeType } : {}
-			};
-		} catch (error) {
-			emitEvent(PluginEvent.ConfigValidationWarning({
-				ctx: { buildId: currentBuildId },
-				field: "ogImage",
-				value: filePath,
-				reason: error.message ?? String(error),
-				level: "warn"
-			}));
-			return;
-		}
-	}
-	/**
-	* Generates descriptive alt text for the OG image.
-	*
-	* @param packageName - The package name
-	* @param apiName - Optional API name for more specific text
-	* @returns Generated alt text string
-	*/
-	generateAltText(packageName, apiName) {
-		if (apiName) return `${apiName} - ${packageName} API Documentation`;
-		return `${packageName} API Documentation`;
-	}
-	/**
-	* Creates complete Open Graph metadata for an API documentation page.
-	*
-	* This static factory method builds a complete `OpenGraphMetadata` object
-	* suitable for inclusion in page frontmatter, combining resolved image
-	* metadata with article-specific information.
-	*
-	* @param options - Configuration for the OG metadata.
-	*   Includes `siteUrl`, `pageRoute`, `description`, `publishedTime`,
-	*   `modifiedTime`, `section`, `packageName`, and optional `ogImage`.
-	* @returns Complete Open Graph metadata object
-	*
-	* @example
-	* ```typescript
-	* const ogMetadata = OpenGraphResolver.createPageMetadata({
-	*   siteUrl: "https://example.com",
-	*   pageRoute: "/api/classes/MyClass",
-	*   description: "MyClass provides...",
-	*   publishedTime: "2024-01-15T10:00:00Z",
-	*   modifiedTime: "2024-01-20T15:30:00Z",
-	*   section: "Classes",
-	*   packageName: "my-library",
-	*   ogImage: resolvedImageMetadata
-	* });
-	* ```
-	*/
-	static createPageMetadata(options) {
-		return {
-			siteUrl: options.siteUrl,
-			pageRoute: options.pageRoute,
-			description: options.description,
-			publishedTime: options.publishedTime,
-			modifiedTime: options.modifiedTime,
-			section: options.section,
-			tags: [
-				"TypeScript",
-				"API",
-				options.packageName
-			],
-			...options.ogImage != null ? { ogImage: options.ogImage } : {},
-			ogType: "article"
-		};
-	}
-};
+function deriveSiteUrl(siteOrigin, base) {
+	const origin = (siteOrigin ?? "").trim().replace(/\/+$/, "");
+	const path = (base ?? "/").trim();
+	return `${origin}${path === "" || path === "/" ? "" : `/${path.replace(/^\/+/, "").replace(/\/+$/, "")}`}`;
+}
+/** Descriptive alt text for a package's (or one API's) OG image. */
+function ogAltText(packageName, apiName) {
+	return apiName ? `${apiName} - ${packageName} API Documentation` : `${packageName} API Documentation`;
+}
+/**
+* Assemble the complete Open Graph metadata for one documentation page.
+*
+* @remarks
+* Was `OpenGraphResolver.createPageMetadata`. It never touched the resolver's
+* instance state, so it is a free function now rather than a static on a class
+* that no longer exists.
+*/
+function createPageMetadata(options) {
+	return {
+		siteUrl: options.siteUrl,
+		pageRoute: options.pageRoute,
+		description: options.description,
+		publishedTime: options.publishedTime,
+		modifiedTime: options.modifiedTime,
+		section: options.section,
+		tags: [
+			"TypeScript",
+			"API",
+			options.packageName
+		],
+		...options.ogImage != null ? { ogImage: options.ogImage } : {},
+		ogType: "article"
+	};
+}
 
 //#endregion
-export { OpenGraphResolver, setOgResolverEventEmitter };
+export { createPageMetadata, deriveSiteUrl, imageMimeType, ogAltText, resolveOgUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -53,16 +53,15 @@
 		"@microsoft/api-extractor-model": "^7.33.11",
 		"@shikijs/twoslash": "^4.4.3",
 		"@tsdoctor/bundle": "0.2.0",
-		"@tsdoctor/model": "0.2.2",
+		"@tsdoctor/model": "0.3.0",
 		"@tsdoctor/registry": "0.2.1",
-		"@tsdoctor/snapshot": "0.1.1",
+		"@tsdoctor/snapshot": "0.2.0",
 		"@typescript/vfs": "^1.6.4",
 		"clsx": "^2.1.1",
 		"effect": "4.0.0-rc.109",
 		"hast-util-to-jsx-runtime": "^2.3.6",
 		"image-size": "^2.0.2",
 		"ioredis": "^5.7.0",
-		"mdast-util-from-markdown": "^2.0.3",
 		"mdast-util-to-hast": "^13.2.1",
 		"open": "^11.0.0",
 		"prettier": "^3.9.6",

package/path-derivation.js

@@ -43,6 +43,24 @@ function deriveOutputPaths(input) {
 	}
 	return results;
 }
+/**
+* The API scope key derived from a base route.
+*
+* @remarks
+* Load-bearing and previously duplicated. Config resolution registers each
+* API's Twoslash environment under this key and the build program looks it up
+* by the same key; if the two derivations disagree, every lookup misses and
+* `getTransformer` falls back to the build-wide environment. Per-scope
+* type-checking degrades to build-wide with no error and nothing visibly
+* wrong in the output — the failure mode is silent, which is why one
+* definition matters more here than the duplication was costing.
+*
+* Falls back to the package name so a single-API site mounted at `/` still
+* gets a non-empty scope.
+*/
+function apiScopeOf(baseRoute, packageName) {
+	return baseRoute.replace(/^\//, "").split("/")[0] || packageName;
+}
 
 //#endregion
-export { deriveOutputPaths, normalizeBaseRoute, unscopedName };
+export { apiScopeOf, deriveOutputPaths, normalizeBaseRoute, unscopedName };