rspress-plugin-api-extractor 0.3.8 → 0.4.0

package/README.md

@@ -49,6 +49,7 @@ The plugin reads your `.api.json` model and writes one MDX page per public API i
 - 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.
 - 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.
 - Handles multi-entry-point packages: it deduplicates re-exports and notes which entry points each item is available from.
 - Writes per-package `llms*.txt` files and in-page actions for pointing an assistant at one package's docs.

package/build-stages.js

@@ -18,6 +18,7 @@ import { resolveEntryPoints } from "./multi-entry-resolver.js";
 import { OpenGraphResolver } from "./og-resolver.js";
 import { assertNoRouteCollisions } from "./route-collisions.js";
 import { SnapshotService } from "./services/SnapshotService.js";
+import { BASE_CLASS_ANCHOR, detectSyntheticBases } from "./synthetic-bases.js";
 import path from "node:path";
 import { Effect, Metric, Stream } from "effect";
 import { FileSystem } from "@effect/platform";
@@ -67,13 +68,15 @@ function sanitizeId(displayName) {
 function prepareWorkItems(input) {
 	const { apiPackage, categories, baseRoute } = input;
 	const resolvedItems = resolveEntryPoints(apiPackage);
+	const syntheticBases = detectSyntheticBases(resolvedItems.map((r) => r.item));
+	const docItems = syntheticBases.bases.size ? resolvedItems.filter((r) => !syntheticBases.bases.has(r.item)) : resolvedItems;
 	const resolvedLookup = /* @__PURE__ */ new Map();
-	for (const resolved of resolvedItems) {
+	for (const resolved of docItems) {
 		const key = `${resolved.item.displayName}::${resolved.item.kind}`;
 		resolvedLookup.set(key, resolved);
 	}
-	const items = ApiParser.categorizeApiItems(resolvedItems, categories);
-	const namespaceMembers = ApiParser.extractNamespaceMembers(resolvedItems);
+	const items = ApiParser.categorizeApiItems(docItems, categories);
+	const namespaceMembers = ApiParser.extractNamespaceMembers(docItems);
 	const candidates = [];
 	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) candidates.push({
 		id: `${item.displayName}::${item.kind}`,
@@ -142,17 +145,28 @@ function prepareWorkItems(input) {
 			kinds.set(displayName, nsMember.item.kind);
 		}
 	}
+	for (const [baseItem, syntheticBase] of syntheticBases.bases) {
+		const baseName = baseItem.displayName;
+		if (routes.has(baseName)) continue;
+		const owner = syntheticBase.ownerClasses[0];
+		const ownerRoute = owner ? routes.get(owner.displayName) : void 0;
+		if (!ownerRoute) continue;
+		routes.set(baseName, `${ownerRoute}#${BASE_CLASS_ANCHOR}`);
+		kinds.set(baseName, baseItem.kind);
+	}
 	const workItems = [];
 	for (const [categoryKey, categoryConfig] of Object.entries(categories)) {
 		const categoryItems = items[categoryKey] || [];
 		for (const item of categoryItems) {
 			const lookupKey = `${item.displayName}::${item.kind}`;
 			const resolved = resolvedLookup.get(lookupKey);
+			const syntheticBase = syntheticBases.baseByOwner.get(item);
 			workItems.push({
 				item,
 				categoryKey,
 				categoryConfig,
-				...resolved?.availableFrom != null ? { availableFrom: resolved.availableFrom } : {}
+				...resolved?.availableFrom != null ? { availableFrom: resolved.availableFrom } : {},
+				...syntheticBase != null ? { syntheticBase } : {}
 			});
 		}
 	}
@@ -197,7 +211,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));
+				page = yield* Effect.promise(() => generator.generate(item, baseRoute, packageName, categoryConfig.singularName, apiScope, apiName, source, suppressExampleErrors, llmsPlugin, workItem.availableFrom, workItem.syntheticBase));
 				page = {
 					routePath: page.routePath.replace("/class/", `/${categoryConfig.folderName}/`),
 					content: page.content

package/markdown/page-generators/class-page.js

@@ -62,7 +62,7 @@ var ClassPageGenerator = class {
 	*
 	* @param apiScope - API scope identifier for VFS lookup
 	*/
-	async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
+	async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom, syntheticBase) {
 		const shouldSuppressErrors = suppressExampleErrors ?? true;
 		const name = apiClass.displayName;
 		const summary = ApiParser.getSummary(apiClass) || "No description available.";
@@ -95,6 +95,7 @@ var ClassPageGenerator = class {
 		const skeleton = this.generateClassSkeletonWithTwoslash(apiClass, packageName);
 		const displayCode = stripTwoslashDirectives(skeleton);
 		content += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(skeleton)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+		content += this.generateBaseClassSection(apiClass, syntheticBase, packageName, apiScope);
 		const constructors = apiClass.members.filter((m) => m.kind === "Constructor");
 		if (constructors.length > 0) {
 			content += `## Constructors\n\n`;
@@ -214,6 +215,28 @@ var ClassPageGenerator = class {
 		};
 	}
 	/**
+	* Render the inline "Base Class" section for a synthetic base declaration
+	* (an unexported item referenced by the class's extends clause, e.g. the
+	* `Foo_base` variable TypeScript emits for `Schema.Class`-style patterns).
+	*
+	* The `## Base Class` heading slugs to `BASE_CLASS_ANCHOR` from
+	* `synthetic-bases.ts`, which is where the cross-link route for the base
+	* name points.
+	*/
+	generateBaseClassSection(apiClass, syntheticBase, packageName, apiScope) {
+		const baseDecl = syntheticBase;
+		if (!baseDecl?.excerpt?.text) return "";
+		let section = `## Base Class\n\n`;
+		section += `\`${apiClass.displayName}\` extends \`${baseDecl.displayName}\`, a compiler-generated declaration that is not exported from \`${packageName}\`.\n\n`;
+		const signature = this.typeFormatter.format(baseDecl.excerpt).trim();
+		let source = signature;
+		const apiPackage = apiClass.getAssociatedPackage?.();
+		if (apiPackage) source = prependHiddenImports(signature, new TypeReferenceExtractor(apiPackage, packageName).extractImportsForApiItem(baseDecl));
+		const displayCode = stripTwoslashDirectives(source);
+		section += `<ApiSignature code={${JSON.stringify(displayCode)}} source={${JSON.stringify(source)}} apiScope={${JSON.stringify(apiScope)}} />\n\n`;
+		return section;
+	}
+	/**
 	* Group class members by their type (static, instance, getters/setters)
 	*/
 	groupClassMembers(members) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rspress-plugin-api-extractor",
-	"version": "0.3.8",
+	"version": "0.4.0",
 	"private": false,
 	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
 	"keywords": [

package/synthetic-bases.js

@@ -0,0 +1,74 @@
+import { ApiExportedMixin, ApiItemKind, ExcerptTokenKind } from "@microsoft/api-extractor-model";
+
+//#region src/synthetic-bases.ts
+/**
+* Anchor id of the inline "Base Class" section rendered on the owner class
+* page. Must match the slug RSPress derives from the `## Base Class` heading
+* emitted by ClassPageGenerator.
+*/
+const BASE_CLASS_ANCHOR = "base-class";
+const EMPTY_DETECTION = {
+	bases: /* @__PURE__ */ new Map(),
+	baseByOwner: /* @__PURE__ */ new Map()
+};
+/**
+* Strip the trailing meaning (`:class`, `:var`, `:function(1)`, ...) from a
+* canonical reference string so the reference token in an extends clause
+* (`example!~Person_base`) matches the declaration's canonical reference
+* (`example!~Person_base:var`).
+*/
+function stripMeaning(canonicalRef) {
+	return canonicalRef.replace(/:[a-z]+(\(\d+\))?$/i, "");
+}
+/** True when the item carries ApiExportedMixin and is NOT exported from its entry point. */
+function isUnexported(item) {
+	return ApiExportedMixin.isBaseClassOf(item) && !item.isExported;
+}
+/**
+* Detect synthetic base declarations among top-level API items.
+*
+* An item qualifies when it is unexported (hoisted into the model only because
+* something references it) AND at least one class's extends clause references
+* its canonical symbol. Unexported items with no class referencing them
+* (genuine forgotten exports) are left alone, as are extends references whose
+* target is absent from the model.
+*/
+function detectSyntheticBases(items) {
+	const unexportedByRef = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		if (!isUnexported(item)) continue;
+		const ref = item.canonicalReference?.toString();
+		if (ref) unexportedByRef.set(stripMeaning(ref), item);
+	}
+	if (unexportedByRef.size === 0) return EMPTY_DETECTION;
+	const owners = /* @__PURE__ */ new Map();
+	const baseByOwner = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		if (item.kind !== ApiItemKind.Class) continue;
+		const apiClass = item;
+		const extendsType = apiClass.extendsType;
+		if (!extendsType) continue;
+		for (const token of extendsType.excerpt.spannedTokens) {
+			if (token.kind !== ExcerptTokenKind.Reference || !token.canonicalReference) continue;
+			const base = unexportedByRef.get(stripMeaning(token.canonicalReference.toString()));
+			if (!base || base === item || baseByOwner.has(item)) continue;
+			baseByOwner.set(item, base);
+			const ownerList = owners.get(base);
+			if (ownerList) ownerList.push(apiClass);
+			else owners.set(base, [apiClass]);
+		}
+	}
+	if (owners.size === 0) return EMPTY_DETECTION;
+	const bases = /* @__PURE__ */ new Map();
+	for (const [baseItem, ownerClasses] of owners) bases.set(baseItem, {
+		baseItem,
+		ownerClasses
+	});
+	return {
+		bases,
+		baseByOwner
+	};
+}
+
+//#endregion
+export { BASE_CLASS_ANCHOR, detectSyntheticBases };