rspress-plugin-api-extractor 0.2.1 → 0.3.0

package/api-extracted-package.js

@@ -129,7 +129,8 @@ var ApiExtractedPackage = class ApiExtractedPackage extends VirtualPackageClass
 		const jsDoc = this.formatJSDoc(apiFunction);
 		if (jsDoc) lines.push(jsDoc);
 		const cleaned = this.cleanExcerpt(apiFunction.excerpt.text);
-		lines.push(`export declare ${cleaned};`);
+		const decl = cleaned.startsWith("function ") ? cleaned : `const ${cleaned}`;
+		lines.push(`export declare ${decl};`);
 		return lines.join("\n");
 	}
 	generateEnumDeclaration(apiEnum) {

package/build-program.js

@@ -2,6 +2,7 @@ import { markdownCrossLinker } from "./markdown/cross-linker.js";
 import "./markdown/index.js";
 import { SnapshotService } from "./services/SnapshotService.js";
 import { buildPipelineForApi, cleanupAndCommit, prepareWorkItems, writeMetadata } from "./build-stages.js";
+import { withPhase } from "./observability/spans.js";
 import { TwoslashManager } from "./twoslash-transformer.js";
 import { VfsRegistry } from "./vfs-registry.js";
 import path from "node:path";
@@ -28,18 +29,22 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 		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 } = buildContext;
+		const { shikiCrossLinker, highlighter, hideCutTransformer, hideCutLinesTransformer, twoslashTransformer, ogResolver, pageConcurrency, thresholds, buildId } = buildContext;
+		const phaseCtx = {
+			buildId,
+			packageName
+		};
 		const resolvedOutputDir = path.resolve(process.cwd(), outputDir);
 		const buildTime = (/* @__PURE__ */ new Date()).toISOString();
 		const allSnapshots = yield* snapshotSvc.getAllForDirectory(resolvedOutputDir).pipe(Effect.orDie);
 		const existingSnapshots = new Map(allSnapshots.map((s) => [s.filePath, s]));
 		yield* fileSystem.makeDirectory(resolvedOutputDir, { recursive: true }).pipe(Effect.orDie);
-		const { workItems, crossLinkData } = prepareWorkItems({
+		const { workItems, crossLinkData } = yield* withPhase("resolve", phaseCtx, Effect.sync(() => prepareWorkItems({
 			apiPackage,
 			categories,
 			baseRoute,
 			packageName
-		});
+		})), thresholds);
 		markdownCrossLinker.setRoutes(crossLinkData.routes);
 		const apiScope = baseRoute.replace(/^\//, "").split("/")[0] || packageName;
 		shikiCrossLinker.reinitialize(crossLinkData.routes, crossLinkData.kinds, apiScope);
@@ -58,8 +63,9 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			if (apiConfig.theme != null) vfsConfig.theme = apiConfig.theme;
 			VfsRegistry.register(apiScope, vfsConfig);
 		}
-		yield* Effect.logInfo(`Generating ${workItems.length} pages across ${Object.keys(categories).length} categories in parallel`);
-		const fileResults = yield* buildPipelineForApi({
+		yield* Effect.logDebug(`Generating ${workItems.length} pages across ${Object.keys(categories).length} categories in parallel`);
+		const fileResults = yield* withPhase("generate", phaseCtx, buildPipelineForApi({
+			buildId,
 			workItems,
 			baseRoute,
 			packageName,
@@ -75,9 +81,9 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			...ogResolver !== void 0 ? { ogResolver } : {},
 			...siteUrl != null ? { siteUrl } : {},
 			...ogImage != null ? { ogImage } : {}
-		});
+		}), thresholds);
 		const changedCount = fileResults.filter((r) => r.status !== "unchanged").length;
-		yield* Effect.logInfo(`Generated ${changedCount} pages`);
+		yield* Effect.logDebug(`Generated ${changedCount} pages`);
 		const generatedFiles = /* @__PURE__ */ new Set();
 		for (const r of fileResults) {
 			generatedFiles.add(r.relativePathWithExt);
@@ -86,7 +92,8 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			if (packageJson?.version != null) ctx.version = packageJson.version;
 			fileContextMap.set(r.absolutePath, ctx);
 		}
-		yield* writeMetadata({
+		yield* withPhase("write", phaseCtx, writeMetadata({
+			buildId,
 			fileResults,
 			categories,
 			resolvedOutputDir,
@@ -96,13 +103,14 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			packageName,
 			...apiName != null ? { apiName } : {},
 			generatedFiles
-		});
-		yield* cleanupAndCommit({
+		}), thresholds);
+		yield* withPhase("cleanup", phaseCtx, cleanupAndCommit({
+			buildId,
 			fileResults,
 			resolvedOutputDir,
 			generatedFiles
-		});
-		yield* Effect.logInfo(`Generated ${changedCount} API documentation files for ${packageName}`);
+		}), thresholds);
+		yield* Effect.logDebug(`Generated ${changedCount} API documentation files for ${packageName}`);
 		return {
 			crossLinkData,
 			generatedFiles,

package/build-stages.js

@@ -1,5 +1,8 @@
 import { hashContent, hashFrontmatter } from "./content-hash.js";
-import { BuildMetrics } from "./layers/ObservabilityLive.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 { ApiParser } from "./loader.js";
 import { generateFrontmatter } from "./markdown/helpers.js";
 import { ClassPageGenerator } from "./markdown/page-generators/class-page.js";
@@ -187,8 +190,9 @@ function normalizeMarkdownSpacing(content) {
 function generateSinglePage(workItem, ctx) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
-		const { existingSnapshots, baseRoute, packageName, apiScope, apiName, source, buildTime, resolvedOutputDir, suppressExampleErrors, llmsPlugin } = ctx;
+		const { buildId, existingSnapshots, baseRoute, packageName, apiScope, apiName, source, buildTime, resolvedOutputDir, suppressExampleErrors, llmsPlugin } = ctx;
 		const { item, categoryConfig, namespaceMember } = workItem;
+		const pageGenStart = performance.now();
 		let page = null;
 		switch (item.kind) {
 			case ApiItemKind.Class: {
@@ -255,7 +259,17 @@ function generateSinglePage(workItem, ctx) {
 				break;
 			}
 			default:
-				yield* Effect.logDebug(`Skipping item "${item.displayName}" with unsupported kind: ${item.kind} (${ApiItemKind[item.kind] || "unknown"}) in category "${categoryConfig.displayName}"`);
+				yield* emit(PluginEvent.ItemSkipped({
+					ctx: {
+						buildId,
+						packageName,
+						apiScope
+					},
+					item: item.displayName,
+					kind: String(item.kind),
+					reason: "unsupported kind",
+					level: "trace"
+				}));
 				return null;
 		}
 		if (!page) return null;
@@ -267,7 +281,20 @@ function generateSinglePage(workItem, ctx) {
 				content: page.content
 			};
 		}
-		yield* Metric.increment(BuildMetrics.pagesGenerated);
+		const codeblockCount = (page.content.match(/<(ApiSignature|ApiMember|ApiExample)\b/g) ?? []).length;
+		yield* emit(PluginEvent.PageGenerated({
+			ctx: {
+				buildId,
+				packageName,
+				apiScope,
+				route: page.routePath
+			},
+			item: item.displayName,
+			category: categoryConfig.displayName,
+			codeblockCount,
+			durationMs: Math.round(performance.now() - pageGenStart),
+			level: "debug"
+		}));
 		const parsed = matter(page.content);
 		const bodyContent = normalizeMarkdownSpacing(parsed.content);
 		const frontmatterData = parsed.data;
@@ -331,7 +358,7 @@ function generateSinglePage(workItem, ctx) {
 function writeSingleFile(result, ctx) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
-		const { resolvedOutputDir, buildTime, ogResolver, siteUrl, ogImage, packageName, apiName } = ctx;
+		const { buildId, resolvedOutputDir, buildTime, ogResolver, siteUrl, 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);
@@ -346,8 +373,18 @@ function writeSingleFile(result, ctx) {
 			buildTime
 		};
 		if (isUnchanged) {
-			yield* Metric.increment(BuildMetrics.filesTotal);
-			yield* Metric.increment(BuildMetrics.filesUnchanged);
+			yield* emit(PluginEvent.FileDecision({
+				ctx: {
+					buildId,
+					...packageName != null ? { packageName } : {}
+				},
+				file: relativePathWithExt,
+				status: "unchanged",
+				contentHash,
+				frontmatterHash,
+				source: "snapshot",
+				level: "debug"
+			}));
 			return {
 				relativePathWithExt,
 				absolutePath,
@@ -379,9 +416,18 @@ function writeSingleFile(result, ctx) {
 		yield* fileSystem.makeDirectory(dirPath, { recursive: true }).pipe(Effect.orDie);
 		yield* fileSystem.writeFileString(absolutePath, finalContent).pipe(Effect.orDie);
 		const status = fileExisted ? "modified" : "new";
-		yield* Metric.increment(BuildMetrics.filesTotal);
-		if (status === "new") yield* Metric.increment(BuildMetrics.filesNew);
-		else yield* Metric.increment(BuildMetrics.filesModified);
+		yield* emit(PluginEvent.FileDecision({
+			ctx: {
+				buildId,
+				...packageName != null ? { packageName } : {}
+			},
+			file: relativePathWithExt,
+			status,
+			contentHash,
+			frontmatterHash,
+			source: "snapshot",
+			level: "debug"
+		}));
 		return {
 			relativePathWithExt,
 			absolutePath,
@@ -411,7 +457,7 @@ function writeMetadata(input) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
 		const snapshotSvc = yield* SnapshotService;
-		const { fileResults, categories, resolvedOutputDir, existingSnapshots, buildTime, baseRoute, packageName, generatedFiles } = input;
+		const { buildId, fileResults, categories, resolvedOutputDir, existingSnapshots, buildTime, baseRoute, packageName, generatedFiles } = input;
 		const categoriesWithItems = /* @__PURE__ */ new Set();
 		for (const result of fileResults) categoriesWithItems.add(result.categoryKey);
 		const apiMetaEntries = [];
@@ -456,13 +502,30 @@ function writeMetadata(input) {
 		}
 		if (!apiMetaUnchanged) {
 			yield* fileSystem.writeFileString(apiMetaJsonPath, apiMetaJsonContent).pipe(Effect.orDie);
-			yield* Metric.increment(BuildMetrics.filesTotal);
-			if (apiMetaOldSnapshot) yield* Metric.increment(BuildMetrics.filesModified);
-			else yield* Metric.increment(BuildMetrics.filesNew);
-		} else {
-			yield* Metric.increment(BuildMetrics.filesTotal);
-			yield* Metric.increment(BuildMetrics.filesUnchanged);
-		}
+			yield* emit(PluginEvent.FileDecision({
+				ctx: {
+					buildId,
+					packageName
+				},
+				file: apiMetaJsonRelPath,
+				status: apiMetaOldSnapshot ? "modified" : "new",
+				contentHash: apiMetaContentHash,
+				frontmatterHash: "",
+				source: "snapshot",
+				level: "debug"
+			}));
+		} else yield* emit(PluginEvent.FileDecision({
+			ctx: {
+				buildId,
+				packageName
+			},
+			file: apiMetaJsonRelPath,
+			status: "unchanged",
+			contentHash: apiMetaContentHash,
+			frontmatterHash: "",
+			source: "snapshot",
+			level: "debug"
+		}));
 		yield* snapshotSvc.upsert({
 			outputDir: resolvedOutputDir,
 			filePath: apiMetaJsonRelPath,
@@ -543,13 +606,30 @@ function writeMetadata(input) {
 				const categoryDir = path.dirname(categoryMetaPath);
 				yield* fileSystem.makeDirectory(categoryDir, { recursive: true }).pipe(Effect.orDie);
 				yield* fileSystem.writeFileString(categoryMetaPath, content).pipe(Effect.orDie);
-				yield* Metric.increment(BuildMetrics.filesTotal);
-				if (oldSnapshot) yield* Metric.increment(BuildMetrics.filesModified);
-				else yield* Metric.increment(BuildMetrics.filesNew);
-			} else {
-				yield* Metric.increment(BuildMetrics.filesTotal);
-				yield* Metric.increment(BuildMetrics.filesUnchanged);
-			}
+				yield* emit(PluginEvent.FileDecision({
+					ctx: {
+						buildId,
+						packageName
+					},
+					file: relPath,
+					status: oldSnapshot ? "modified" : "new",
+					contentHash,
+					frontmatterHash: "",
+					source: "snapshot",
+					level: "debug"
+				}));
+			} else yield* emit(PluginEvent.FileDecision({
+				ctx: {
+					buildId,
+					packageName
+				},
+				file: relPath,
+				status: "unchanged",
+				contentHash,
+				frontmatterHash: "",
+				source: "snapshot",
+				level: "debug"
+			}));
 			generatedFiles.add(relPath);
 			if (isUnchanged) return null;
 			return {
@@ -582,14 +662,18 @@ function cleanupAndCommit(input) {
 	return Effect.gen(function* () {
 		const fileSystem = yield* FileSystem.FileSystem;
 		const snapshotSvc = yield* SnapshotService;
-		const { fileResults, resolvedOutputDir, generatedFiles } = input;
+		const { buildId, fileResults, resolvedOutputDir, generatedFiles } = input;
 		const snapshotsToUpdate = fileResults.filter((r) => r.status !== "unchanged").map((r) => r.snapshot);
 		if (snapshotsToUpdate.length > 0) yield* snapshotSvc.batchUpsert(snapshotsToUpdate).pipe(Effect.ignore);
 		const staleFiles = yield* snapshotSvc.cleanupStale(resolvedOutputDir, generatedFiles).pipe(Effect.orElseSucceed(() => []));
 		yield* Effect.forEach(staleFiles, (staleFile) => Effect.gen(function* () {
 			const fullPath = path.join(resolvedOutputDir, staleFile);
 			yield* fileSystem.remove(fullPath).pipe(Effect.ignore);
-			yield* Effect.logDebug(`🗑️  DELETED STALE: ${staleFile}`);
+			yield* emit(PluginEvent.StaleDeleted({
+				ctx: { buildId },
+				file: staleFile,
+				level: "trace"
+			}));
 		}), { concurrency: "unbounded" });
 		const allFiles = yield* fileSystem.readDirectory(resolvedOutputDir, { recursive: true }).pipe(Effect.orElseSucceed(() => []));
 		const orphanedFiles = [];
@@ -603,7 +687,11 @@ function cleanupAndCommit(input) {
 			const fullPath = path.join(resolvedOutputDir, orphan);
 			yield* fileSystem.remove(fullPath).pipe(Effect.ignore);
 			yield* snapshotSvc.deleteSnapshot(resolvedOutputDir, orphan).pipe(Effect.ignore);
-			yield* Effect.logDebug(`🗑️  DELETED ORPHAN: ${orphan}`);
+			yield* emit(PluginEvent.OrphanDeleted({
+				ctx: { buildId },
+				file: orphan,
+				level: "trace"
+			}));
 		}), { concurrency: "unbounded" });
 		if (orphanedFiles.length > 0) {
 			const dirs = /* @__PURE__ */ new Set();
@@ -616,7 +704,11 @@ function cleanupAndCommit(input) {
 				const fullDir = path.join(resolvedOutputDir, dir);
 				if ((yield* fileSystem.readDirectory(fullDir).pipe(Effect.orElseSucceed(() => ["placeholder"]))).length === 0) {
 					yield* fileSystem.remove(fullDir).pipe(Effect.ignore);
-					yield* Effect.logDebug(`🗑️  REMOVED EMPTY DIR: ${dir}`);
+					yield* emit(PluginEvent.EmptyDirRemoved({
+						ctx: { buildId },
+						dir,
+						level: "trace"
+					}));
 				}
 			}
 		}
@@ -637,6 +729,7 @@ function cleanupAndCommit(input) {
 */
 function buildPipelineForApi(input) {
 	const generateCtx = {
+		buildId: input.buildId,
 		existingSnapshots: input.existingSnapshots,
 		baseRoute: input.baseRoute,
 		packageName: input.packageName,
@@ -649,6 +742,7 @@ function buildPipelineForApi(input) {
 		...input.llmsPlugin != null ? { llmsPlugin: input.llmsPlugin } : {}
 	};
 	const writeCtx = {
+		buildId: input.buildId,
 		resolvedOutputDir: input.resolvedOutputDir,
 		buildTime: input.buildTime,
 		...input.ogResolver !== void 0 ? { ogResolver: input.ogResolver } : {},

package/config-utils.js

@@ -118,17 +118,19 @@ function extractTypeUtilities(packageJson) {
 *   devDependencies: { "type-fest": "^4.0.0" }
 * };
 *
-* // Default: only peerDependencies + type utilities
+* // Default: dependencies + peerDependencies + type utilities (devDependencies excluded).
+* // The documented type surface is usually written against runtime dependencies,
+* // so those must be loaded for Twoslash to resolve them.
 * extractAutoDetectedPackages(pkg);
-* // Returns: [{ name: "zod", version: "^3.22.4" }, { name: "type-fest", version: "^4.0.0" }]
-*
-* // Include all dependency types
-* extractAutoDetectedPackages(pkg, { dependencies: true, peerDependencies: true, autoDependencies: true });
 * // Returns: [{ name: "effect", ... }, { name: "zod", ... }, { name: "type-fest", ... }]
+*
+* // Opt out of dependencies (peerDependencies + type utilities only)
+* extractAutoDetectedPackages(pkg, { dependencies: false });
+* // Returns: [{ name: "zod", version: "^3.22.4" }, { name: "type-fest", version: "^4.0.0" }]
 * ```
 */
 function extractAutoDetectedPackages(packageJson, options = {}) {
-	const { dependencies = false, devDependencies = false, peerDependencies = true, autoDependencies = true } = options;
+	const { dependencies = true, devDependencies = false, peerDependencies = true, autoDependencies = true } = options;
 	const packages = [];
 	if (dependencies && packageJson?.dependencies) packages.push(...Object.entries(packageJson.dependencies).map(([name, version]) => ({
 		name,
@@ -185,6 +187,33 @@ function resolvePackageVersionConflicts(packages) {
 	return resolved;
 }
 /**
+* Resolve each external package's version spec to an exact, published version.
+*
+* The type registry's CDN (jsDelivr) requires an exact version — its flat-file
+* API 404s on semver ranges (`^4.1.0`), npm tags, and unpublished/workspace
+* versions. This helper maps each spec through the supplied `resolve` function
+* and drops any package whose resolution fails. Failures are the intended skip
+* signal: a workspace-only or unpublished package (e.g. `@scope/pkg@1.0.0` that
+* was never pushed to the registry) resolves to an error and is omitted, so it
+* never poisons the batch load. Input order is preserved for survivors.
+*
+* @param packages - External package specs (typically post-deduplication)
+* @param resolve - Resolver mapping a spec to its exact published version
+* @returns Effect yielding the resolved specs with unresolvable packages dropped
+*
+* @example
+* ```ts
+* // [{ name: "vitest", version: "^4.1.0" }] -> [{ name: "vitest", version: "4.1.9" }]
+* // an unpublished workspace package resolves to an error and is dropped
+* ```
+*/
+function resolveExternalPackageVersions(packages, resolve) {
+	return Effect.forEach(packages, (pkg) => resolve(pkg).pipe(Effect.map((version) => ({
+		name: pkg.name,
+		version
+	})), Effect.catchAll(() => Effect.succeed(null))), { concurrency: 5 }).pipe(Effect.map((results) => results.filter((spec) => spec !== null)));
+}
+/**
 * Strip range prefixes from a version string to get a clean semver.
 */
 function stripRangePrefix(version) {
@@ -255,4 +284,4 @@ function validateExternalPackages(externalPackages, packageJson) {
 }
 
 //#endregion
-export { extractAutoDetectedPackages, isLoadedModel, isVersionConfig, mergeLlmsPluginConfig, validateExternalPackages };
+export { extractAutoDetectedPackages, isLoadedModel, isVersionConfig, mergeLlmsPluginConfig, resolveExternalPackageVersions, validateExternalPackages };