rspress-plugin-api-extractor 0.15.2 → 0.16.0

package/build-program.js

@@ -36,7 +36,7 @@ function generateApiDocs(apiConfig, fileContextMap) {
 		const pageConcurrency = yield* PageConcurrency;
 		const suppressExampleErrors = yield* SuppressExampleErrors;
 		const snapshotSvc = yield* SnapshotService;
-		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage, manifest } = apiConfig;
+		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage, manifest, siteName, bundleOgImage } = apiConfig;
 		const phaseCtx = { packageName };
 		const structuredDataPkg = manifest != null && siteUrl != null ? packageContext({
 			siteUrl,
@@ -91,7 +91,9 @@ function generateApiDocs(apiConfig, fileContextMap) {
 			...apiConfig.docsRoot != null ? { docsRoot: apiConfig.docsRoot } : {},
 			...siteUrl != null ? { siteUrl } : {},
 			...ogImage != null ? { ogImage } : {},
-			...structuredDataPkg != null ? { structuredDataPkg } : {}
+			...structuredDataPkg != null ? { structuredDataPkg } : {},
+			...siteName != null ? { siteName } : {},
+			...bundleOgImage != null ? { bundleOgImage } : {}
 		}));
 		const changedCount = fileResults.filter((r) => r.status !== "unchanged").length;
 		yield* Effect.logDebug(`Generated ${changedCount} pages`);

package/build-stages.js

@@ -163,7 +163,8 @@ function generateSinglePage(workItem, ctx) {
 				siteUrl,
 				docsRoot: ctx.docsRoot,
 				packageName,
-				...apiName != null ? { apiName } : {}
+				...apiName != null ? { apiName } : {},
+				fallbackAlt: `${apiName ?? packageName} API documentation`
 			}));
 			if (ogImageResult._tag === "Failure") {
 				const failure = ogImageResult.failure;
@@ -178,6 +179,7 @@ function generateSinglePage(workItem, ctx) {
 					level: "warn"
 				}));
 			} else if (Option.isSome(ogImageResult.success)) ogImageMetadata = ogImageResult.success.value;
+			if (ogImageMetadata == null && ctx.bundleOgImage != null) ogImageMetadata = ctx.bundleOgImage;
 			if (ctx.structuredDataPkg != null) {
 				const graphResult = deriveScriptBody(ctx.structuredDataPkg, {
 					pageRoute: page.routePath,
@@ -215,11 +217,13 @@ function generateSinglePage(workItem, ctx) {
 		const finalFrontmatter = (published, modified) => seoEnabled ? generateFrontmatter(item.displayName, description, categoryConfig.singularName, apiName, headTags({
 			siteUrl: ctx.siteUrl,
 			pageRoute: page.routePath,
+			title: item.displayName,
 			description,
 			publishedTime: published,
 			modifiedTime: modified,
 			section: categoryConfig.displayName,
 			packageName,
+			...ctx.siteName != null ? { siteName: ctx.siteName } : {},
 			...ogImageMetadata != null ? { ogImage: ogImageMetadata } : {},
 			...structuredData != null ? { structuredData } : {}
 		})) : stringifyFrontmatter("", frontmatterData);
@@ -649,7 +653,9 @@ function buildPipelineForApi(input) {
 		...input.docsRoot !== void 0 ? { docsRoot: input.docsRoot } : {},
 		...input.siteUrl != null ? { siteUrl: input.siteUrl } : {},
 		...input.ogImage != null ? { ogImage: input.ogImage } : {},
-		...input.structuredDataPkg != null ? { structuredDataPkg: input.structuredDataPkg } : {}
+		...input.structuredDataPkg != null ? { structuredDataPkg: input.structuredDataPkg } : {},
+		...input.siteName != null ? { siteName: input.siteName } : {},
+		...input.bundleOgImage != null ? { bundleOgImage: input.bundleOgImage } : {}
 	};
 	const writeCtx = {
 		buildId: input.buildId,

package/layers/AppLayer.js

@@ -9,7 +9,7 @@ import { TypeRegistryService } from "../services/TypeRegistryService.js";
 import { TwoslashCacheService } from "../services/TwoslashCacheService.js";
 import { ConfigService } from "../services/ConfigService.js";
 import { makeSummaryLoggerLayer } from "./observability.js";
-import { Layer } from "effect";
+import { Layer, Path } from "effect";
 import { SnapshotService } from "@tsdoctor/snapshot";
 import { NodeFileSystem } from "@effect/platform-node";
 
@@ -58,7 +58,7 @@ function makeAppLayers(input) {
 	/** Services scoped to this build's configuration. */
 	const BuildLayer = Layer.mergeAll(Layer.succeed(PluginConfig, input.options), HighlighterLive, TwoslashEnvironments.layer, BuildEnvLayer);
 	return {
-		app: Layer.provideMerge(ConfigService.layer, Layer.mergeAll(BuildLayer, CoreLayer, ObservabilityLayer, NodeFileSystem.layer)),
+		app: Layer.provideMerge(ConfigService.layer, Layer.mergeAll(BuildLayer, CoreLayer, ObservabilityLayer, NodeFileSystem.layer, Path.layer)),
 		emitter: Layer.mergeAll(ObservabilityLayer, BuildEnvLayer)
 	};
 }

package/layers/config-resolution.js

@@ -15,11 +15,13 @@ import { TypeRegistryService } from "../services/TypeRegistryService.js";
 import { emitVfsPayloadEvents, mergeApiResult } from "./api-results.js";
 import { mergeExternalTypes } from "./external-types.js";
 import { registerTypeEnvironments, resolveTsConfigTyped } from "./type-environment.js";
+import path from "node:path";
 import { apiScopeOf, normalizeBaseRoute, unscopedName } from "@tsdoctor/pages";
 import { Effect, Metric } from "effect";
 import { ApiExtractedPackage, TypeReferenceExtractor } from "@tsdoctor/model";
 import { deriveSiteUrl } from "@tsdoctor/seo";
 import { hashContent } from "@tsdoctor/snapshot";
+import { loadBundle, publishBundleAssets, resolveBundleFrom } from "@tsdoctor/bundle";
 import { PackageManifest } from "@effected/package-json";
 
 //#region src/layers/config-resolution.ts
@@ -95,6 +97,83 @@ function decodeManifest(packageJson, buildId, packageName) {
 	});
 }
 /**
+* Resolve an API's bundle — display identity and Open Graph images — from its
+* model directory, with provenance across the manifest tiers.
+*
+* @remarks
+* Every API resolves a bundle, even one declared with a loader function
+* rather than a path: a loader has no directory to discover a `tsdoctor.json`
+* sidecar beside, so resolution falls back to an inferred bundle carrying
+* only the package name — the same floor {@link resolveBundleFrom} itself
+* guarantees for `name`.
+*
+* A present-but-malformed `tsdoctor.json` fails the build typed, the same
+* posture as a malformed tsconfig: {@link ConfigValidationError} with
+* `field: "bundle"`. Asset publishing degrades instead — a malformed or
+* unreadable image must not stop the docs from generating, it should just
+* render without a bundle-supplied `og:image`.
+*/
+function resolveApiBundle(input) {
+	const inferredBundle = {
+		bundle: { name: {
+			value: input.packageName,
+			source: "inferred"
+		} },
+		siteName: input.packageName
+	};
+	return Effect.gen(function* () {
+		const modelPath = input.model;
+		if (typeof modelPath !== "string") return inferredBundle;
+		const modelDir = path.dirname(modelPath);
+		const degradeToWarning = (cause) => Effect.andThen(emit(PluginEvent.ConfigValidationWarning({
+			ctx: {
+				buildId: input.buildId,
+				packageName: input.packageName
+			},
+			field: "bundle",
+			value: cause.path,
+			reason: cause.message,
+			level: "warn"
+		})), Effect.succeed(void 0));
+		const bundle = yield* loadBundle(modelDir, { overrides: {
+			modelPath,
+			name: input.packageName
+		} }).pipe(Effect.catchTag("BundleManifestError", (cause) => Effect.fail(new ConfigValidationError({
+			field: "bundle",
+			reason: cause.message,
+			cause
+		}))), Effect.catchTags({
+			BundleDiscoveryError: degradeToWarning,
+			BundleLayerError: degradeToWarning
+		}));
+		if (bundle === void 0) return inferredBundle;
+		const resolved = resolveBundleFrom(bundle, {});
+		const siteName = resolved.project?.value.name ?? resolved.name.value;
+		const published = resolved.openGraph !== void 0 && input.siteUrl != null ? yield* publishBundleAssets({
+			bundleDir: bundle.descriptor.dir,
+			images: resolved.openGraph.value.images,
+			publicDir: path.join(input.rspressRoot, "public"),
+			siteUrl: input.siteUrl,
+			unscopedName: unscopedName(input.packageName),
+			...input.assetSubdir != null ? { subdir: input.assetSubdir } : {}
+		}).pipe(Effect.tapError((error) => emit(PluginEvent.ConfigValidationWarning({
+			ctx: {
+				buildId: input.buildId,
+				packageName: input.packageName
+			},
+			field: "openGraph",
+			value: error.path,
+			reason: error.message,
+			level: "warn"
+		}))), Effect.orElseSucceed(() => [])) : [];
+		return {
+			bundle: resolved,
+			siteName,
+			...published[0] != null ? { bundleOgImage: published[0] } : {}
+		};
+	});
+}
+/**
 * Validate plugin options and return an Effect that fails with ConfigValidationError.
 */
 function validateOptions(options, rspressConfig) {
@@ -244,6 +323,13 @@ const makeConfigService = Effect.gen(function* () {
 				const vfsPayloads = prependImportsToVfs(vfs, apiPackage, api.packageName, wantTrace);
 				const resolvedOgImage = api.ogImage ?? options.ogImage;
 				const resolvedTheme = normalizeThemeConfig(api.theme);
+				const { bundle, siteName, bundleOgImage } = yield* resolveApiBundle({
+					model,
+					packageName: api.packageName,
+					buildId,
+					siteUrl,
+					rspressRoot
+				});
 				return {
 					vfs,
 					vfsPayloads,
@@ -262,7 +348,10 @@ const makeConfigService = Effect.gen(function* () {
 						...siteUrl != null ? { siteUrl } : {},
 						...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
 						...docsRoot != null ? { docsRoot } : {},
-						...resolvedTheme != null ? { theme: resolvedTheme } : {}
+						...resolvedTheme != null ? { theme: resolvedTheme } : {},
+						bundle,
+						siteName,
+						...bundleOgImage != null ? { bundleOgImage } : {}
 					}
 				};
 			}
@@ -325,6 +414,14 @@ const makeConfigService = Effect.gen(function* () {
 							const resolvedTheme = normalizeThemeConfig(api.theme);
 							const outputDir = versionDp.outputDir;
 							const fullRoute = versionDp.routeBase;
+							const { bundle, siteName, bundleOgImage } = yield* resolveApiBundle({
+								model: versionConfig.model,
+								packageName: api.packageName,
+								buildId,
+								siteUrl,
+								rspressRoot,
+								assetSubdir: version
+							});
 							return {
 								vfs,
 								vfsPayloads,
@@ -343,7 +440,10 @@ const makeConfigService = Effect.gen(function* () {
 									...siteUrl != null ? { siteUrl } : {},
 									...resolvedOgImage != null ? { ogImage: resolvedOgImage } : {},
 									...docsRoot != null ? { docsRoot } : {},
-									...resolvedTheme != null ? { theme: resolvedTheme } : {}
+									...resolvedTheme != null ? { theme: resolvedTheme } : {},
+									bundle,
+									siteName,
+									...bundleOgImage != null ? { bundleOgImage } : {}
 								}
 							};
 						}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.15.2",
+	"version": "0.16.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [
@@ -52,11 +52,12 @@
 		"@effected/yaml": "^0.12.0",
 		"@microsoft/api-extractor-model": "^7.33.11",
 		"@shikijs/twoslash": "^4.4.3",
-		"@tsdoctor/bundle": "0.2.4",
+		"@tsdoctor/bundle": "0.3.0",
+		"@tsdoctor/manifest": "0.1.0",
 		"@tsdoctor/model": "0.6.1",
-		"@tsdoctor/pages": "0.1.1",
+		"@tsdoctor/pages": "0.1.2",
 		"@tsdoctor/registry": "0.3.2",
-		"@tsdoctor/seo": "0.1.2",
+		"@tsdoctor/seo": "0.2.0",
 		"@tsdoctor/snapshot": "0.2.4",
 		"@tsdoctor/vfs": "0.2.1",
 		"@typescript/vfs": "^1.6.4",

package/services/OgService.js

@@ -1,7 +1,7 @@
 import { PluginEvent } from "../observability/events.js";
 import { emit } from "../observability/EventBus.js";
 import { Context, Data, Effect, FileSystem, Layer, Option, Path } from "effect";
-import { imageMimeType, ogAltText, resolveUrl } from "@tsdoctor/seo";
+import { imageMimeType, resolveUrl } from "@tsdoctor/seo";
 import { imageSize } from "image-size";
 
 //#region src/services/OgService.ts
@@ -127,7 +127,7 @@ const make = () => Effect.gen(function* () {
 			type: facts?.type,
 			width: facts?.width,
 			height: facts?.height,
-			alt: ogAltText(request.packageName, request.apiName)
+			alt: request.fallbackAlt
 		});
 	});
 	const resolveFromMetadata = (metadata, request) => Effect.gen(function* () {
@@ -162,7 +162,7 @@ const make = () => Effect.gen(function* () {
 			type,
 			width,
 			height,
-			alt: alt ?? ogAltText(request.packageName, request.apiName)
+			alt: alt ?? request.fallbackAlt
 		});
 	});
 	return { resolveImage: (request) => {