rspress-plugin-api-extractor 0.11.0 → 0.12.0

package/BuildEnv.js

@@ -7,12 +7,12 @@ import { Context } from "effect";
 *
 * @remarks
 * Each of these used to travel by hand. `thresholds` made a four-hop journey —
-* `plugin.ts` → `ConfigServiceLive`'s fourth constructor argument →
+* `plugin.ts` → `ConfigService.layer`'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
+* stood, and in `TypeRegistryService.layer` 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.
 *
@@ -46,7 +46,7 @@ const Thresholds = Context.Reference("rspress-plugin-api-extractor/Thresholds",
 * How many pages the build pipeline generates concurrently.
 *
 * @remarks
-* Defaults to the CPU count, which is what `ConfigServiceLive` computed
+* Defaults to the CPU count, which is what `ConfigService.layer` computed
 * inline. Kept a Reference rather than a constant so a consumer with a
 * constrained CI runner can lower it without a code change.
 */

package/build-program.js

@@ -1,17 +1,16 @@
 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 { HighlighterService } from "./services/HighlighterService.js";
+import { addTypeRoutes } from "./twoslash-transformer.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";
 import { Effect, FileSystem } from "effect";
+import { SnapshotService } from "@tsdoctor/snapshot";
 
 //#region src/build-program.ts
 /**

package/build-stages.js

@@ -1,8 +1,7 @@
 import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.js";
+import { BuildMetrics } from "./layers/build-metrics.js";
 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";
@@ -13,12 +12,11 @@ import { InterfacePageGenerator } from "./markdown/page-generators/interface-pag
 import { NamespacePageGenerator } from "./markdown/page-generators/namespace-page.js";
 import { TypeAliasPageGenerator } from "./markdown/page-generators/type-alias-page.js";
 import { VariablePageGenerator } from "./markdown/page-generators/variable-page.js";
-import "./markdown/index.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, Option, Stream } from "effect";
+import { SnapshotService, hashContent, hashFrontmatter } from "@tsdoctor/snapshot";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
 import { ApiItems, EntryPoints, Routes, SyntheticBases } from "@tsdoctor/model";
 
@@ -427,7 +425,7 @@ function writeSingleFile(result, ctx) {
 			};
 		}
 		let finalContent = stringifyFrontmatter(bodyContent, frontmatter);
-		if (siteUrl && packageName) {
+		if (siteUrl != null && packageName) {
 			const ogSvc = yield* OgService;
 			const ogImageResult = yield* Effect.result(ogSvc.resolveImage({
 				config: ogImage,

package/config-helpers.js

@@ -1,6 +1,6 @@
 import { normalizeBaseRoute } from "./path-derivation.js";
 import { SyncDiscoveryLayer } from "./sync-node-fs.js";
-import fs from "node:fs";
+import fsSync from "node:fs";
 import path from "node:path";
 import { Effect, Result } from "effect";
 import { discoverBundle } from "@tsdoctor/bundle";
@@ -18,14 +18,14 @@ const PREFIX = "[rspress-plugin-api-extractor]";
 function requirePackageJson(dir) {
 	let stat;
 	try {
-		stat = fs.statSync(dir);
+		stat = fsSync.statSync(dir);
 	} catch {
 		throw new Error(`${PREFIX} api.fromDir: directory not found: ${dir}`);
 	}
 	if (!stat.isDirectory()) throw new Error(`${PREFIX} api.fromDir: not a directory: ${dir}`);
 	let pkg;
 	try {
-		pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+		pkg = JSON.parse(fsSync.readFileSync(path.join(dir, "package.json"), "utf8"));
 	} catch {
 		throw new Error(`${PREFIX} api.fromDir: missing or unreadable package.json in ${dir}`);
 	}
@@ -103,9 +103,9 @@ function fromDir(dir, overrides = {}) {
 	};
 }
 function isModelFolder(dir) {
-	if (!fs.existsSync(path.join(dir, "package.json"))) return false;
+	if (!fsSync.existsSync(path.join(dir, "package.json"))) return false;
 	try {
-		return fs.readdirSync(dir).some((f) => f.endsWith(".api.json"));
+		return fsSync.readdirSync(dir).some((f) => f.endsWith(".api.json"));
 	} catch {
 		return false;
 	}
@@ -124,12 +124,12 @@ function fromParentDir(parentDir, options = {}) {
 	const absParent = path.resolve(cwd ?? process.cwd(), parentDir);
 	let stat;
 	try {
-		stat = fs.statSync(absParent);
+		stat = fsSync.statSync(absParent);
 	} catch {
 		throw new Error(`${PREFIX} apis.fromDir: directory not found: ${absParent}`);
 	}
 	if (!stat.isDirectory()) throw new Error(`${PREFIX} apis.fromDir: not a directory: ${absParent}`);
-	const subdirs = fs.readdirSync(absParent, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name).sort();
+	const subdirs = fsSync.readdirSync(absParent, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name).sort();
 	const configs = [];
 	for (const name of subdirs) {
 		const subdir = path.join(absParent, name);

package/errors.js

@@ -7,16 +7,12 @@ var ConfigValidationError = class extends ConfigValidationErrorBase {
 		return `Config validation failed for '${this.field}': ${this.reason}`;
 	}
 };
-const ApiModelLoadErrorBase = Data.TaggedError("ApiModelLoadError");
 const TypeRegistryErrorBase = Data.TaggedError("TypeRegistryError");
 var TypeRegistryError = class extends TypeRegistryErrorBase {
 	get message() {
 		return `Type registry error for '${this.packageName}@${this.version}': ${this.reason}`;
 	}
 };
-const PageGenerationErrorBase = Data.TaggedError("PageGenerationError");
-const TwoslashProcessingErrorBase = Data.TaggedError("TwoslashProcessingError");
-const PrettierFormatErrorBase = Data.TaggedError("PrettierFormatError");
 
 //#endregion
-export { ConfigValidationError, ConfigValidationErrorBase, TypeRegistryError, TypeRegistryErrorBase };
+export { ConfigValidationError, TypeRegistryError };

package/index.d.ts

@@ -669,8 +669,6 @@ declare const PluginOptions: Schema.Struct<{
      */
     readonly compilerOptions: Schema.optional<Schema.Unknown>;
   }>>>>>;
-  /** Canonical site URL used for Open Graph absolute URLs. */
-  readonly siteUrl: Schema.optional<Schema.String>;
   /** Global Open Graph image configuration (overridden per-API). */
   readonly ogImage: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
     readonly url: Schema.String;
@@ -746,90 +744,6 @@ declare const PluginOptions: Schema.Struct<{
 /** @public */
 type PluginOptions = typeof PluginOptions.Encoded;
 //#endregion
-//#region src/schemas/opengraph.d.ts
-/**
- * Structured Open Graph image metadata (alternative to a plain URL string).
- *
- * @public
- */
-declare const OpenGraphImageMetadata: Schema.Struct<{
-  /** Absolute URL of the image. */
-  readonly url: Schema.String;
-  /** HTTPS URL of the image (for secure contexts). */
-  readonly secureUrl: Schema.optional<Schema.String>;
-  /** MIME type of the image (e.g. `"image/png"`). */
-  readonly type: Schema.optional<Schema.String>;
-  /** Image width in pixels. */
-  readonly width: Schema.optional<Schema.Number>;
-  /** Image height in pixels. */
-  readonly height: Schema.optional<Schema.Number>;
-  /** Alt text for the image. */
-  readonly alt: Schema.optional<Schema.String>;
-}>;
-/** @public */
-type OpenGraphImageMetadata = typeof OpenGraphImageMetadata.Type;
-/**
- * Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
- *
- * @public
- */
-declare const OpenGraphImageConfig: Schema.Union<readonly [Schema.String, Schema.Struct<{
-  /** Absolute URL of the image. */
-  readonly url: Schema.String;
-  /** HTTPS URL of the image (for secure contexts). */
-  readonly secureUrl: Schema.optional<Schema.String>;
-  /** MIME type of the image (e.g. `"image/png"`). */
-  readonly type: Schema.optional<Schema.String>;
-  /** Image width in pixels. */
-  readonly width: Schema.optional<Schema.Number>;
-  /** Image height in pixels. */
-  readonly height: Schema.optional<Schema.Number>;
-  /** Alt text for the image. */
-  readonly alt: Schema.optional<Schema.String>;
-}>]>;
-/** @public */
-type OpenGraphImageConfig = typeof OpenGraphImageConfig.Type;
-/**
- * Resolved Open Graph metadata emitted into each generated page's frontmatter.
- *
- * @public
- */
-declare const OpenGraphMetadata: Schema.Struct<{
-  /** Canonical site base URL. */
-  readonly siteUrl: Schema.String;
-  /** Page route path (e.g. `/api/classes/myclass`). */
-  readonly pageRoute: Schema.String;
-  /** Page description for the `og:description` tag. */
-  readonly description: Schema.String;
-  /** ISO 8601 date string for `article:published_time`. */
-  readonly publishedTime: Schema.String;
-  /** ISO 8601 date string for `article:modified_time`. */
-  readonly modifiedTime: Schema.String;
-  /** Article section label (e.g. `"API"`). */
-  readonly section: Schema.String;
-  /** Article tag keywords. */
-  readonly tags: Schema.mutable<Schema.$Array<Schema.String>>;
-  /** Optional structured image metadata. */
-  readonly ogImage: Schema.optional<Schema.Struct<{
-    /** Absolute URL of the image. */
-    readonly url: Schema.String;
-    /** HTTPS URL of the image (for secure contexts). */
-    readonly secureUrl: Schema.optional<Schema.String>;
-    /** MIME type of the image (e.g. `"image/png"`). */
-    readonly type: Schema.optional<Schema.String>;
-    /** Image width in pixels. */
-    readonly width: Schema.optional<Schema.Number>;
-    /** Image height in pixels. */
-    readonly height: Schema.optional<Schema.Number>;
-    /** Alt text for the image. */
-    readonly alt: Schema.optional<Schema.String>;
-  }>>;
-  /** Open Graph object type (e.g. `"article"`). */
-  readonly ogType: Schema.String;
-}>;
-/** @public */
-type OpenGraphMetadata = typeof OpenGraphMetadata.Type;
-//#endregion
 //#region src/config-helpers.d.ts
 /**
  * Metadata discovered from a single rslib-builder localPaths package folder.
@@ -940,6 +854,90 @@ declare const ApiExtractorPlugin: typeof ApiExtractorPluginImpl & {
   };
 };
 //#endregion
+//#region src/schemas/opengraph.d.ts
+/**
+ * Structured Open Graph image metadata (alternative to a plain URL string).
+ *
+ * @public
+ */
+declare const OpenGraphImageMetadata: Schema.Struct<{
+  /** Absolute URL of the image. */
+  readonly url: Schema.String;
+  /** HTTPS URL of the image (for secure contexts). */
+  readonly secureUrl: Schema.optional<Schema.String>;
+  /** MIME type of the image (e.g. `"image/png"`). */
+  readonly type: Schema.optional<Schema.String>;
+  /** Image width in pixels. */
+  readonly width: Schema.optional<Schema.Number>;
+  /** Image height in pixels. */
+  readonly height: Schema.optional<Schema.Number>;
+  /** Alt text for the image. */
+  readonly alt: Schema.optional<Schema.String>;
+}>;
+/** @public */
+type OpenGraphImageMetadata = typeof OpenGraphImageMetadata.Type;
+/**
+ * Open Graph image: either a plain URL string or structured `OpenGraphImageMetadata`.
+ *
+ * @public
+ */
+declare const OpenGraphImageConfig: Schema.Union<readonly [Schema.String, Schema.Struct<{
+  /** Absolute URL of the image. */
+  readonly url: Schema.String;
+  /** HTTPS URL of the image (for secure contexts). */
+  readonly secureUrl: Schema.optional<Schema.String>;
+  /** MIME type of the image (e.g. `"image/png"`). */
+  readonly type: Schema.optional<Schema.String>;
+  /** Image width in pixels. */
+  readonly width: Schema.optional<Schema.Number>;
+  /** Image height in pixels. */
+  readonly height: Schema.optional<Schema.Number>;
+  /** Alt text for the image. */
+  readonly alt: Schema.optional<Schema.String>;
+}>]>;
+/** @public */
+type OpenGraphImageConfig = typeof OpenGraphImageConfig.Type;
+/**
+ * Resolved Open Graph metadata emitted into each generated page's frontmatter.
+ *
+ * @public
+ */
+declare const OpenGraphMetadata: Schema.Struct<{
+  /** Canonical site base URL. */
+  readonly siteUrl: Schema.String;
+  /** Page route path (e.g. `/api/classes/myclass`). */
+  readonly pageRoute: Schema.String;
+  /** Page description for the `og:description` tag. */
+  readonly description: Schema.String;
+  /** ISO 8601 date string for `article:published_time`. */
+  readonly publishedTime: Schema.String;
+  /** ISO 8601 date string for `article:modified_time`. */
+  readonly modifiedTime: Schema.String;
+  /** Article section label (e.g. `"API"`). */
+  readonly section: Schema.String;
+  /** Article tag keywords. */
+  readonly tags: Schema.mutable<Schema.$Array<Schema.String>>;
+  /** Optional structured image metadata. */
+  readonly ogImage: Schema.optional<Schema.Struct<{
+    /** Absolute URL of the image. */
+    readonly url: Schema.String;
+    /** HTTPS URL of the image (for secure contexts). */
+    readonly secureUrl: Schema.optional<Schema.String>;
+    /** MIME type of the image (e.g. `"image/png"`). */
+    readonly type: Schema.optional<Schema.String>;
+    /** Image width in pixels. */
+    readonly width: Schema.optional<Schema.Number>;
+    /** Image height in pixels. */
+    readonly height: Schema.optional<Schema.Number>;
+    /** Alt text for the image. */
+    readonly alt: Schema.optional<Schema.String>;
+  }>>;
+  /** Open Graph object type (e.g. `"article"`). */
+  readonly ogType: Schema.String;
+}>;
+/** @public */
+type OpenGraphMetadata = typeof OpenGraphMetadata.Type;
+//#endregion
 //#region src/serve.d.ts
 /**
  * Which RSPress server {@link serve} runs.

package/layers/AppLayer.js

@@ -0,0 +1,67 @@
+import { BuildId, PageConcurrency, SuppressExampleErrors, Thresholds } from "../BuildEnv.js";
+import { OgService } from "../services/OgService.js";
+import { collectShikiThemes } from "../markdown/shiki-utils.js";
+import { HighlighterService } from "../services/HighlighterService.js";
+import { TwoslashEnvironments } from "../services/TwoslashEnvironments.js";
+import { PluginConfig } from "../services/PluginConfig.js";
+import { PlatformLive } from "./xdg.js";
+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 { SnapshotService } from "@tsdoctor/snapshot";
+import { NodeFileSystem } from "@effect/platform-node";
+
+//#region src/layers/AppLayer.ts
+/**
+* The build's layer stack, tiered.
+*
+* @remarks
+* `plugin.ts` used to merge eleven layers side by side in one `Layer.mergeAll`
+* — `NodeFileSystem.layer` (platform) next to `TypeRegistryService.layer`
+* (domain) next to `makeSummaryLoggerLayer` (observability) — with one of them
+* carrying a local `Layer.provide` because a flat merge could not feed it its
+* dependencies. Reading that told you what the build contains but not what
+* depends on what.
+*
+* The tiers below are ordered by what they may reach: platform knows nothing
+* about this plugin, core services know the platform, and build-scoped services
+* know both.
+*
+* @packageDocumentation
+*/
+/**
+* Build both stacks for one build.
+*
+* @remarks
+* **A layer factory: call it once and bind the result to a `const`.** Layers
+* memoize by reference, so a second call mints a second stack — a second Shiki
+* highlighter, a second snapshot database, a second metric registry.
+*/
+function makeAppLayers(input) {
+	/**
+	* Per-build configuration, provided to BOTH stacks. Sharing these values is
+	* what lets a sync island and an Effect program agree on the build id and
+	* the slow-block threshold without either being handed them.
+	*/
+	const BuildEnvLayer = Layer.mergeAll(Layer.succeed(BuildId, input.buildId), Layer.succeed(Thresholds, input.obs.thresholds), Layer.succeed(PageConcurrency, input.pageConcurrency), Layer.succeed(SuppressExampleErrors, input.options.errors?.example !== "show"));
+	/**
+	* Sinks, metrics and the logger gate. Synchronously buildable, which is what
+	* lets the emitter stack below reuse it wholesale.
+	*/
+	const ObservabilityLayer = Layer.mergeAll(input.eventBus, input.metrics.layer, makeSummaryLoggerLayer(input.obs.logLevel));
+	/** Services that own a resource and need only the platform to build. */
+	const CoreLayer = Layer.mergeAll(TypeRegistryService.layer, TwoslashCacheService.layer, SnapshotService.layer(input.dbPath), Layer.provide(OgService.layer, PlatformLive));
+	/** Bound to a `const`: this is a factory, and a second call acquires a second highlighter. */
+	const HighlighterLive = HighlighterService.layer(collectShikiThemes(input.options.api ? [input.options.api] : input.options.apis ?? []));
+	/** 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)),
+		emitter: Layer.mergeAll(ObservabilityLayer, BuildEnvLayer)
+	};
+}
+
+//#endregion
+export { makeAppLayers };

package/layers/api-results.js

@@ -0,0 +1,83 @@
+import { PluginEvent } from "../observability/events.js";
+import { emit } from "../observability/EventBus.js";
+import { Effect } from "effect";
+
+//#region src/layers/api-results.ts
+/**
+* Accumulating one API's resolution result into the build-wide totals.
+*
+* @remarks
+* `ConfigService.layer` resolves APIs down three paths — versioned, single
+* non-versioned, and multi-API — and each one ended with a near-identical
+* ~35-line block that merged the same three accumulators and then emitted the
+* same two events per VFS entry. Three copies of one algorithm is three places
+* for it to drift, and the third copy had ALREADY drifted: it emits its events
+* inside the per-API effect and merges afterwards, rather than doing both in
+* one pass.
+*
+* Splitting the block in two is what makes all three paths expressible. The
+* merge is pure and the emission is effectful, and the multi-API path needs
+* them at different moments; a single combined helper would have fitted two
+* paths and forced the third to keep its own copy.
+*
+* @packageDocumentation
+*/
+/**
+* Merge one result into the build-wide accumulators.
+*
+* @remarks
+* Mutates `acc` rather than returning a new one. The accumulators are three
+* `const` collections in a long generator that appends to them from several
+* branches, and threading a replacement through every branch would be a larger
+* change than this task is buying.
+*
+* **The VFS is a single flat namespace shared by every documented API.** A
+* later entry silently overwrites an earlier one at the same path, which is
+* load-bearing rather than accidental: cross-package type references resolve
+* only because every package's declarations live in one environment (see
+* `type-loading-vfs.md`).
+*/
+function mergeApiResult(acc, result) {
+	for (const [filepath, content] of result.vfs.entries()) acc.combinedVfs.set(filepath, content);
+	if (result.externalPackages.length > 0) acc.allExternalPackages.push(...result.externalPackages);
+	if (result.config) acc.apiConfigs.push(result.config);
+}
+/**
+* Emit the per-entry VFS events for one API's payloads.
+*
+* @remarks
+* `ImportsPrepended` fires only when imports were actually prepended, so an
+* entry that needed none produces one event rather than two.
+*
+* `wantTrace` gates the two heavy fields — the full declaration text and the
+* resolved import refs. Both are only ever read by the JSONL trace sink, and
+* carrying them unconditionally would put every generated declaration file
+* through the event bus on every build.
+*/
+function emitVfsPayloadEvents(packageName, payloads, wantTrace) {
+	return Effect.gen(function* () {
+		for (const payload of payloads) {
+			const ctx = {
+				packageName,
+				...payload.entryPoint ? { entryPoint: payload.entryPoint } : {}
+			};
+			yield* emit(PluginEvent.VfsGenerated({
+				ctx,
+				level: "debug",
+				file: payload.file,
+				declCount: payload.declCount,
+				contentHash: payload.contentHash,
+				...wantTrace && payload.content ? { content: payload.content } : {}
+			}));
+			if (payload.hasImports) yield* emit(PluginEvent.ImportsPrepended({
+				ctx,
+				level: "debug",
+				file: payload.file,
+				imports: wantTrace ? payload.importRefs : []
+			}));
+		}
+	});
+}
+
+//#endregion
+export { emitVfsPayloadEvents, mergeApiResult };

package/layers/build-metrics.js

@@ -18,7 +18,7 @@ function makeMetricStore() {
 * build still gets its own counters — see {@link MetricRegistryLive}.
 *
 * Extracted into its own module so that `metrics-sink.ts` can import it
-* without creating a circular dependency through `ObservabilityLive.ts`
+* without creating a circular dependency through `observability.ts`
 * (which itself imports `metrics-sink.ts`).
 */
 const BuildMetrics = {