rspress-plugin-api-extractor 0.9.2 → 0.11.0

package/BuildEnv.js

@@ -0,0 +1,58 @@
+import { Context } from "effect";
+
+//#region src/BuildEnv.ts
+/**
+* Per-build configuration, as `Context.Reference` values rather than threaded
+* parameters.
+*
+* @remarks
+* Each of these used to travel by hand. `thresholds` made a four-hop journey —
+* `plugin.ts` → `ConfigServiceLive`'s fourth constructor argument →
+* a `ResolvedBuildContext` field → destructured in `build-program.ts` → every
+* `withPhase` call — while `obs.thresholds` already held the same value one
+* scope away. `buildId` was worse: 24 event emit sites wrote
+* `ctx: { buildId: "" }` because the value was not reachable from where they
+* stood, and in `TypeRegistryServiceLive` it genuinely was not — that layer is
+* module-level and has no build to name. A Reference is the fix precisely
+* because it reaches module-level code that no parameter can.
+*
+* A `Context.Reference` carries a default, so nothing has to provide these for
+* a program to run. That is convenient and it is also the hazard: a wiring
+* mistake does not fail, it silently substitutes the default. The tests for
+* this module provide NON-default values and assert the provided value is the
+* one observed, which is the only way to tell the two apart.
+*
+* @packageDocumentation
+*/
+/**
+* Identifier correlating every event emitted by one build.
+*
+* @remarks
+* The empty-string default is deliberate: an event emitted outside a build —
+* a test, a stray sync callback — is better tagged empty than crashing. Every
+* production path provides a real id.
+*/
+const BuildId = Context.Reference("rspress-plugin-api-extractor/BuildId", { defaultValue: () => "" });
+/** Duration thresholds above which an operation is reported as slow. */
+const Thresholds = Context.Reference("rspress-plugin-api-extractor/Thresholds", { defaultValue: () => ({
+	slowCodeBlock: 100,
+	slowPageGeneration: 500,
+	slowApiLoad: 1e3,
+	slowFileOperation: 50,
+	slowHttpRequest: 2e3,
+	slowDbOperation: 100
+}) });
+/**
+* How many pages the build pipeline generates concurrently.
+*
+* @remarks
+* Defaults to the CPU count, which is what `ConfigServiceLive` computed
+* inline. Kept a Reference rather than a constant so a consumer with a
+* constrained CI runner can lower it without a code change.
+*/
+const PageConcurrency = Context.Reference("rspress-plugin-api-extractor/PageConcurrency", { defaultValue: () => 1 });
+/** Whether Twoslash diagnostics inside `@example` blocks are suppressed. */
+const SuppressExampleErrors = Context.Reference("rspress-plugin-api-extractor/SuppressExampleErrors", { defaultValue: () => true });
+
+//#endregion
+export { BuildId, PageConcurrency, SuppressExampleErrors, Thresholds };

package/README.md

@@ -47,7 +47,8 @@ The plugin reads your `.api.json` model and writes one MDX page per public API i
 ## Features
 
 - Generates API docs from `.api.json` models for classes, interfaces, functions, type aliases, enums, variables and namespaces.
-- Type-checks code examples and adds Twoslash hover tooltips that show inferred types.
+- Type-checks code examples and adds Twoslash hover tooltips that show inferred types, each documented package under its own `tsconfig`.
+- Caches Twoslash results between builds, so repeat builds over an unchanged API render code blocks near-instantly.
 - Cross-links type references between pages, so a type named in a signature links to its own page.
 - Inlines compiler-generated base declarations (the `Foo_base` pattern from Effect `Schema.Class`, `Data.TaggedError` and mixin factories) in a "Base Class" section on the owning class page instead of documenting them as orphan variables.
 - Drives single-package sites, multi-package portals, RSPress multiVersion and i18n from one plugin.

package/build-program.js

@@ -1,8 +1,13 @@
+import { BuildId, PageConcurrency, SuppressExampleErrors } from "./BuildEnv.js";
 import { setProseLinker } from "./markdown/prose-linker.js";
 import "./markdown/index.js";
 import { buildPipelineForApi, cleanupAndCommit, prepareWorkItems, writeMetadata } from "./build-stages.js";
+import { HideCutLinesTransformer, MemberFormatTransformer } from "./hide-cut-transformer.js";
 import { withPhase } from "./observability/spans.js";
-import { TwoslashManager } from "./twoslash-transformer.js";
+import { HighlighterService } from "./services/HighlighterService.js";
+import { TwoslashEnvironments } from "./services/TwoslashEnvironments.js";
+import { ShikiCrossLinker } from "./shiki-transformer.js";
+import { addTypeRoutes } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import path from "node:path";
 import { SnapshotService } from "@tsdoctor/snapshot";
@@ -22,17 +27,17 @@ import { Effect, FileSystem } from "effect";
 * Returns build result metadata including CrossLinkData for cross-link merging
 * and generated file paths for LLMs post-processing.
 */
-function generateApiDocs(apiConfig, buildContext, fileContextMap) {
+function generateApiDocs(apiConfig, fileContextMap) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
+		const { highlighter } = yield* HighlighterService;
+		const environments = yield* TwoslashEnvironments;
+		const buildId = yield* BuildId;
+		const pageConcurrency = yield* PageConcurrency;
+		const suppressExampleErrors = yield* SuppressExampleErrors;
 		const snapshotSvc = yield* SnapshotService;
 		const { apiPackage, packageName, apiName, outputDir, baseRoute, categories, source, packageJson, llmsPlugin, siteUrl, ogImage } = apiConfig;
-		const suppressExampleErrors = apiConfig.suppressExampleErrors ?? true;
-		const { shikiCrossLinker, highlighter, hideCutTransformer, hideCutLinesTransformer, twoslashTransformer, ogResolver, pageConcurrency, thresholds, buildId } = buildContext;
-		const phaseCtx = {
-			buildId,
-			packageName
-		};
+		const phaseCtx = { packageName };
 		const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
 		const buildTime = (/* @__PURE__ */ new Date()).toISOString();
 		const allSnapshots = yield* snapshotSvc.getAllForDirectory(resolvedOutputDir).pipe(Effect.orDie);
@@ -43,28 +48,27 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			categories,
 			baseRoute,
 			packageName
-		})), thresholds);
+		})));
 		setProseLinker(crossLinkData.routes);
 		const apiScope = baseRoute.replace(/^\//, "").split("/")[0] || packageName;
-		shikiCrossLinker.reinitialize(crossLinkData.routes, crossLinkData.kinds, apiScope);
-		TwoslashManager.addTypeRoutes(crossLinkData.routes);
-		if (highlighter) {
-			const vfsConfig = {
-				vfs: /* @__PURE__ */ new Map(),
-				highlighter,
-				crossLinker: shikiCrossLinker,
-				packageName,
-				apiScope
-			};
-			if (twoslashTransformer != null) vfsConfig.twoslashTransformer = twoslashTransformer;
-			if (hideCutTransformer != null) vfsConfig.hideCutTransformer = hideCutTransformer;
-			if (hideCutLinesTransformer != null) vfsConfig.hideCutLinesTransformer = hideCutLinesTransformer;
-			if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;
-			VfsRegistry.register(apiScope, vfsConfig);
-		}
+		const shikiCrossLinker = ShikiCrossLinker.fromRoutes(crossLinkData.routes, crossLinkData.kinds, apiScope);
+		addTypeRoutes(crossLinkData.routes);
+		const vfsConfig = {
+			highlighter,
+			crossLinker: shikiCrossLinker,
+			packageName,
+			apiScope
+		};
+		const scopeTransformer = environments.transformerFor(apiScope);
+		if (scopeTransformer != null) vfsConfig.twoslashTransformer = scopeTransformer;
+		vfsConfig.hideCutTransformer = MemberFormatTransformer;
+		vfsConfig.hideCutLinesTransformer = HideCutLinesTransformer;
+		if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;
+		VfsRegistry.register(apiScope, vfsConfig);
 		yield* Effect.logDebug(`Generating ${workItems.length} pages across ${Object.keys(categories).length} categories in parallel`);
 		const fileResults = yield* withPhase("generate", phaseCtx, buildPipelineForApi({
 			buildId,
+			pageConcurrency,
 			workItems,
 			baseRoute,
 			packageName,
@@ -73,14 +77,13 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			...source != null ? { source } : {},
 			buildTime,
 			resolvedOutputDir,
-			pageConcurrency,
 			existingSnapshots,
 			...suppressExampleErrors != null ? { suppressExampleErrors } : {},
 			...llmsPlugin != null ? { llmsPlugin } : {},
-			...ogResolver !== void 0 ? { ogResolver } : {},
+			...apiConfig.docsRoot != null ? { docsRoot: apiConfig.docsRoot } : {},
 			...siteUrl != null ? { siteUrl } : {},
 			...ogImage != null ? { ogImage } : {}
-		}), thresholds);
+		}));
 		const changedCount = fileResults.filter((r) => r.status !== "unchanged").length;
 		yield* Effect.logDebug(`Generated ${changedCount} pages`);
 		const generatedFiles = /* @__PURE__ */ new Set();
@@ -102,13 +105,13 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			packageName,
 			...apiName != null ? { apiName } : {},
 			generatedFiles
-		}), thresholds);
+		}));
 		yield* withPhase("cleanup", phaseCtx, cleanupAndCommit({
 			buildId,
 			fileResults,
 			resolvedOutputDir,
 			generatedFiles
-		}), thresholds);
+		}));
 		yield* Effect.logDebug(`Generated ${changedCount} API documentation files for ${packageName}`);
 		return {
 			crossLinkData,

package/build-stages.js

@@ -3,6 +3,7 @@ import { PluginEvent } from "./observability/events.js";
 import { emit } from "./observability/EventBus.js";
 import { BuildMetrics } from "./layers/build-metrics.js";
 import "./layers/ObservabilityLive.js";
+import { emitSync, syncBuildId } from "./observability/sync-emitter.js";
 import { generateFrontmatter } from "./markdown/helpers.js";
 import { ClassPageGenerator } from "./markdown/page-generators/class-page.js";
 import { EnumPageGenerator } from "./markdown/page-generators/enum-page.js";
@@ -13,10 +14,11 @@ import { NamespacePageGenerator } from "./markdown/page-generators/namespace-pag
 import { TypeAliasPageGenerator } from "./markdown/page-generators/type-alias-page.js";
 import { VariablePageGenerator } from "./markdown/page-generators/variable-page.js";
 import "./markdown/index.js";
-import { OpenGraphResolver } from "./og-resolver.js";
+import { createPageMetadata } from "./og-resolver.js";
+import { OgService } from "./services/OgService.js";
 import path from "node:path";
 import { SnapshotService, hashContent, hashFrontmatter } from "@tsdoctor/snapshot";
-import { Effect, FileSystem, Metric, Stream } from "effect";
+import { Effect, FileSystem, Metric, Option, Stream } from "effect";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
 import { ApiItems, EntryPoints, Routes, SyntheticBases } from "@tsdoctor/model";
 
@@ -41,24 +43,6 @@ function crossLinkKindPriority(kind) {
 	return CROSS_LINK_KIND_PRIORITY[kind] ?? 100;
 }
 /**
-* Module-level emitter seam. `prepareWorkItems` runs synchronously outside any
-* Effect fiber, so a route collision cannot `yield* emit(...)` — it mirrors the
-* sync-island pattern used by `twoslash-transformer.ts` (`setEventEmitter`) and
-* `loader.ts` (`setLoaderEventEmitter`). Default is a no-op; wired in plugin.ts
-* via `setBuildStagesEventEmitter(emitSync, buildId)` right after the runtime
-* emitter is created.
-*/
-let emitEvent = () => {};
-let currentBuildId = "";
-/**
-* Inject the runtime-bound emitter into the build-stages module.
-* Call this right after `makeRuntimeEmitter` in plugin.ts.
-*/
-function setBuildStagesEventEmitter(fn, buildId = "") {
-	emitEvent = fn;
-	currentBuildId = buildId;
-}
-/**
 * Prepare the flat list of WorkItems to process and the cross-link data maps.
 *
 * This function:
@@ -82,8 +66,8 @@ function prepareWorkItems(input) {
 		resolvedLookup.set(key, resolved);
 	}
 	const { items, uncategorized } = ApiItems.categorize(docItems, categories);
-	for (const skipped of uncategorized) emitEvent(PluginEvent.ItemSkipped({
-		ctx: { buildId: currentBuildId },
+	for (const skipped of uncategorized) emitSync(PluginEvent.ItemSkipped({
+		ctx: { buildId: syncBuildId() },
 		item: skipped.displayName,
 		kind: String(skipped.kind),
 		reason: "uncategorized",
@@ -115,9 +99,9 @@ function prepareWorkItems(input) {
 	const collisions = Routes.detectCollisions(candidates);
 	if (collisions.length > 0) {
 		try {
-			for (const collision of collisions) emitEvent(PluginEvent.RouteCollisionDetected({
+			for (const collision of collisions) emitSync(PluginEvent.RouteCollisionDetected({
 				ctx: {
-					buildId: currentBuildId,
+					buildId: syncBuildId(),
 					route: collision.route
 				},
 				level: "error",
@@ -145,13 +129,14 @@ function prepareWorkItems(input) {
 			}
 			if (item.kind === "Class" || item.kind === "Interface") {
 				const itemWithMembers = item;
-				for (const member of itemWithMembers.members) {
-					const memberName = member.displayName;
-					const memberId = Routes.sanitizeId(memberName);
-					const fullMemberName = `${item.displayName}.${memberName}`;
-					const memberRoute = `${itemRoute}#${memberId}`;
-					routes.set(fullMemberName, memberRoute);
-					kinds.set(fullMemberName, member.kind);
+				const anchors = ApiItems.memberAnchors(itemWithMembers);
+				const byCanonicalRef = new Map(itemWithMembers.members.map((member) => [member.canonicalReference?.toString() ?? member.displayName, member]));
+				for (const [routeKey, memberId] of ApiItems.memberRouteKeys(itemWithMembers)) {
+					const member = byCanonicalRef.get(memberId);
+					if (!member) continue;
+					const anchor = anchors.get(memberId) ?? Routes.memberAnchor(member.displayName);
+					routes.set(routeKey, `${itemRoute}#${anchor}`);
+					kinds.set(routeKey, member.kind);
 				}
 			}
 		}
@@ -190,12 +175,14 @@ function prepareWorkItems(input) {
 			const lookupKey = `${item.displayName}::${item.kind}`;
 			const resolved = resolvedLookup.get(lookupKey);
 			const syntheticBase = syntheticBases.baseByOwner.get(item);
+			const memberAnchors = item.kind === "Class" || item.kind === "Interface" ? ApiItems.memberAnchors(item) : void 0;
 			workItems.push({
 				item,
 				categoryKey,
 				categoryConfig,
 				...resolved?.availableFrom != null ? { availableFrom: resolved.availableFrom } : {},
-				...syntheticBase != null ? { syntheticBase } : {}
+				...syntheticBase != null ? { syntheticBase } : {},
+				...memberAnchors != null ? { memberAnchors } : {}
 			});
 		}
 	}
@@ -240,7 +227,7 @@ function generateSinglePage(workItem, ctx) {
 		switch (item.kind) {
 			case ApiItemKind.Class: {
 				const generator = new ClassPageGenerator();
-				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom, workItem.syntheticBase));
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom, workItem.syntheticBase, workItem.memberAnchors));
 				page = {
 					routePath: page.routePath.replace("/class/", `/${categoryConfig.folderName}/`),
 					content: page.content
@@ -402,7 +389,7 @@ function generateSinglePage(workItem, ctx) {
 function writeSingleFile(result, ctx) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
-		const { buildId, resolvedOutputDir, buildTime, ogResolver, siteUrl, ogImage, packageName, apiName } = ctx;
+		const { buildId, resolvedOutputDir, buildTime, siteUrl, docsRoot, ogImage, packageName, apiName } = ctx;
 		const { workItem, bodyContent, frontmatter, contentHash, frontmatterHash, publishedTime, modifiedTime, isUnchanged, routePath, relativePathWithExt } = result;
 		const { item, categoryKey, categoryConfig, namespaceMember } = workItem;
 		const absolutePath = path.join(resolvedOutputDir, relativePathWithExt);
@@ -440,8 +427,29 @@ function writeSingleFile(result, ctx) {
 			};
 		}
 		let finalContent = stringifyFrontmatter(bodyContent, frontmatter);
-		if (ogResolver && siteUrl && packageName) {
-			const ogImageMetadata = yield* Effect.promise(() => ogResolver.resolve(ogImage, packageName, apiName));
+		if (siteUrl && packageName) {
+			const ogSvc = yield* OgService;
+			const ogImageResult = yield* Effect.result(ogSvc.resolveImage({
+				config: ogImage,
+				siteUrl,
+				docsRoot,
+				packageName,
+				...apiName != null ? { apiName } : {}
+			}));
+			if (ogImageResult._tag === "Failure") {
+				const failure = ogImageResult.failure;
+				yield* emit(PluginEvent.ConfigValidationWarning({
+					ctx: {
+						buildId,
+						packageName
+					},
+					field: failure.field,
+					value: failure.value,
+					reason: failure.message,
+					level: "warn"
+				}));
+			}
+			const ogImageMetadata = ogImageResult._tag === "Success" && Option.isSome(ogImageResult.success) ? ogImageResult.success.value : void 0;
 			const ogMetadataOptions = {
 				siteUrl,
 				pageRoute: routePath,
@@ -452,7 +460,7 @@ function writeSingleFile(result, ctx) {
 				packageName
 			};
 			if (ogImageMetadata) ogMetadataOptions.ogImage = ogImageMetadata;
-			const ogMetadata = OpenGraphResolver.createPageMetadata(ogMetadataOptions);
+			const ogMetadata = createPageMetadata(ogMetadataOptions);
 			finalContent = generateFrontmatter(item.displayName, frontmatter.description, categoryConfig.singularName, apiName, ogMetadata) + bodyContent;
 		}
 		const fileExisted = yield* fileSystem.exists(absolutePath).pipe(Effect.orElseSucceed(() => false));
@@ -793,7 +801,7 @@ function buildPipelineForApi(input) {
 		buildId: input.buildId,
 		resolvedOutputDir: input.resolvedOutputDir,
 		buildTime: input.buildTime,
-		...input.ogResolver !== void 0 ? { ogResolver: input.ogResolver } : {},
+		...input.docsRoot !== void 0 ? { docsRoot: input.docsRoot } : {},
 		...input.siteUrl != null ? { siteUrl: input.siteUrl } : {},
 		...input.ogImage != null ? { ogImage: input.ogImage } : {},
 		...input.packageName != null ? { packageName: input.packageName } : {},
@@ -803,4 +811,4 @@ function buildPipelineForApi(input) {
 }
 
 //#endregion
-export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, normalizeMarkdownSpacing, prepareWorkItems, setBuildStagesEventEmitter, writeMetadata, writeSingleFile };
+export { buildPipelineForApi, cleanupAndCommit, crossLinkKindPriority, generateSinglePage, prepareWorkItems, writeMetadata, writeSingleFile };

package/errors.js

@@ -8,7 +8,6 @@ var ConfigValidationError = class extends ConfigValidationErrorBase {
 	}
 };
 const ApiModelLoadErrorBase = Data.TaggedError("ApiModelLoadError");
-const PathDerivationErrorBase = Data.TaggedError("PathDerivationError");
 const TypeRegistryErrorBase = Data.TaggedError("TypeRegistryError");
 var TypeRegistryError = class extends TypeRegistryErrorBase {
 	get message() {

package/index.d.ts

@@ -390,15 +390,19 @@ declare const MultiApiConfig: Schema.Struct<{
    * Path to a `tsconfig.json` for Twoslash.
    *
    * @remarks
-   * Twoslash runs against a single shared TypeScript environment for the
-   * whole build, so per-API tsconfigs are not honored in multi-API mode:
-   * the first API that provides one wins and the rest are ignored (a
-   * `ConfigCascadeWarning` is emitted when they differ). Ensure the
-   * configured tsconfigs are equivalent, or set the intended one on the
-   * first API only.
+   * This API's code blocks are type-checked under this config. APIs that
+   * declare the same config share one TypeScript environment; the file set
+   * is shared across all documented APIs either way, so a type owned by
+   * another documented package still resolves.
    */
   readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
-  /** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
+  /**
+   * TypeScript compiler options for Twoslash, applying to this API only.
+   *
+   * @remarks
+   * Merged on top of the defaults and of this API's `tsconfig`, so declaring
+   * a single option overrides just that one.
+   */
   readonly compilerOptions: Schema.optional<Schema.Unknown>;
 }>;
 /** @public */
@@ -650,15 +654,19 @@ declare const PluginOptions: Schema.Struct<{
      * Path to a `tsconfig.json` for Twoslash.
      *
      * @remarks
-     * Twoslash runs against a single shared TypeScript environment for the
-     * whole build, so per-API tsconfigs are not honored in multi-API mode:
-     * the first API that provides one wins and the rest are ignored (a
-     * `ConfigCascadeWarning` is emitted when they differ). Ensure the
-     * configured tsconfigs are equivalent, or set the intended one on the
-     * first API only.
+     * This API's code blocks are type-checked under this config. APIs that
+     * declare the same config share one TypeScript environment; the file set
+     * is shared across all documented APIs either way, so a type owned by
+     * another documented package still resolves.
      */
     readonly tsconfig: Schema.optional<Schema.declare<string | URL | ((...args: Array<unknown>) => unknown), string | URL | ((...args: Array<unknown>) => unknown)>>;
-    /** TypeScript compiler options for Twoslash. First API wins, as with `tsconfig`. */
+    /**
+     * TypeScript compiler options for Twoslash, applying to this API only.
+     *
+     * @remarks
+     * Merged on top of the defaults and of this API's `tsconfig`, so declaring
+     * a single option overrides just that one.
+     */
     readonly compilerOptions: Schema.optional<Schema.Unknown>;
   }>>>>>;
   /** Canonical site URL used for Open Graph absolute URLs. */