rspress-plugin-api-extractor 0.8.8 → 0.9.0

package/README.md

@@ -56,17 +56,17 @@ The plugin reads your `.api.json` model and writes one MDX page per public API i
 
 ## Documentation
 
-- [Getting started](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/01-getting-started.md) — Install, minimal config, first build.
-- [Configuration](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/02-configuration.md) — Full plugin-options reference.
-- [Config helpers](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/03-config-helpers.md) — `api.fromDir` and `apis.fromDir` for discovering config from package folders.
-- [Single package](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/04-single-package.md) — The single-API recipe.
-- [Multi-package](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/05-multi-package.md) — The multi-API portal recipe.
-- [Versioned](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/06-versioned.md) — Documenting major versions side by side.
-- [i18n](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/07-i18n.md) — Internationalized documentation.
-- [Multi-entry points](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/08-multi-entry-points.md) — Deduplication, "Available from" and route collisions.
-- [LLMs](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/09-llms.md) — Per-package `llms*.txt` files and assistant actions.
-- [Runtime components](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/10-runtime-components.md) — The runtime components and live `with-api` code blocks.
-- [Troubleshooting](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/11-troubleshooting.md) — Route collisions, forgotten exports, Twoslash errors and stale caches.
+- [Getting started](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/01-getting-started.md) — Install, minimal config, first build.
+- [Configuration](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/02-configuration.md) — Full plugin-options reference.
+- [Config helpers](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/03-config-helpers.md) — `api.fromDir` and `apis.fromDir` for discovering config from package folders.
+- [Single package](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/04-single-package.md) — The single-API recipe.
+- [Multi-package](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/05-multi-package.md) — The multi-API portal recipe.
+- [Versioned](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/06-versioned.md) — Documenting major versions side by side.
+- [i18n](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/07-i18n.md) — Internationalized documentation.
+- [Multi-entry points](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/08-multi-entry-points.md) — Deduplication, "Available from" and route collisions.
+- [LLMs](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/09-llms.md) — Per-package `llms*.txt` files and assistant actions.
+- [Runtime components](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/10-runtime-components.md) — The runtime components and live `with-api` code blocks.
+- [Troubleshooting](https://github.com/spencerbeggs/tsdoctor/blob/main/docs/11-troubleshooting.md) — Route collisions, forgotten exports, Twoslash errors and stale caches.
 
 ## License
 

package/api-extracted-package.js

@@ -1,5 +1,5 @@
 import { ApiItemKind, ApiModel, ExcerptTokenKind } from "@microsoft/api-extractor-model";
-import { VirtualPackage } from "type-registry-effect";
+import { VirtualPackage } from "@tsdoctor/registry";
 
 //#region src/api-extracted-package.ts
 /**

package/build-program.js

@@ -1,11 +1,11 @@
-import { markdownCrossLinker } from "./markdown/cross-linker.js";
+import { setProseLinker } from "./markdown/prose-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";
+import { SnapshotService } from "@tsdoctor/snapshot";
 import { Effect, FileSystem } from "effect";
 
 //#region src/build-program.ts
@@ -44,7 +44,7 @@ function generateApiDocs(apiConfig, buildContext, fileContextMap) {
 			baseRoute,
 			packageName
 		})), thresholds);
-		markdownCrossLinker.setRoutes(crossLinkData.routes);
+		setProseLinker(crossLinkData.routes);
 		const apiScope = baseRoute.replace(/^\//, "").split("/")[0] || packageName;
 		shikiCrossLinker.reinitialize(crossLinkData.routes, crossLinkData.kinds, apiScope);
 		TwoslashManager.addTypeRoutes(crossLinkData.routes);

package/build-stages.js

@@ -1,9 +1,8 @@
-import { hashContent, hashFrontmatter } from "./content-hash.js";
+import { parseFrontmatter, stringifyFrontmatter } from "./frontmatter.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";
 import { EnumPageGenerator } from "./markdown/page-generators/enum-page.js";
@@ -14,15 +13,12 @@ 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 { resolveEntryPoints } from "./multi-entry-resolver.js";
 import { OpenGraphResolver } from "./og-resolver.js";
-import { detectRouteCollisions, formatRouteCollisionError } 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 { SnapshotService, hashContent, hashFrontmatter } from "@tsdoctor/snapshot";
 import { Effect, FileSystem, Metric, Stream } from "effect";
 import { ApiItemKind } from "@microsoft/api-extractor-model";
-import matter from "gray-matter";
+import { ApiItems, EntryPoints, Routes, SyntheticBases } from "@tsdoctor/model";
 
 //#region src/build-stages.ts
 /**
@@ -63,60 +59,60 @@ function setBuildStagesEventEmitter(fn, buildId = "") {
 	currentBuildId = buildId;
 }
 /**
-* Sanitize a display name to create a valid HTML ID.
-* Mirrors the logic in MarkdownCrossLinker.sanitizeId().
-*/
-function sanitizeId(displayName) {
-	return displayName.toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/^-+|-+$/g, "");
-}
-/**
 * Prepare the flat list of WorkItems to process and the cross-link data maps.
 *
 * This function:
 * 1. Categorizes API items from the model
-* 2. Builds cross-link routes and kinds maps (replicating MarkdownCrossLinker.initialize())
+* 2. Builds cross-link routes and kinds maps for the prose and Shiki cross-linkers
 * 3. Extracts namespace members and adds their routes (with collision detection)
 * 4. Flattens all items into a single WorkItem[]
 *
-* NOTE: This function does NOT call the markdownCrossLinker singleton. The caller
+* NOTE: This function does NOT install the prose linker. The caller
 * is responsible for passing the returned crossLinkData to the cross-linker and
 * Shiki cross-linker as needed.
 */
 function prepareWorkItems(input) {
 	const { apiPackage, categories, baseRoute } = input;
-	const resolvedItems = resolveEntryPoints(apiPackage);
-	const syntheticBases = detectSyntheticBases(resolvedItems.map((r) => r.item));
+	const resolvedItems = EntryPoints.resolve(apiPackage);
+	const syntheticBases = SyntheticBases.detect(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 docItems) {
 		const key = `${resolved.item.displayName}::${resolved.item.kind}`;
 		resolvedLookup.set(key, resolved);
 	}
-	const items = ApiParser.categorizeApiItems(docItems, categories);
-	const namespaceMembers = ApiParser.extractNamespaceMembers(docItems);
+	const { items, uncategorized } = ApiItems.categorize(docItems, categories);
+	for (const skipped of uncategorized) emitEvent(PluginEvent.ItemSkipped({
+		ctx: { buildId: currentBuildId },
+		item: skipped.displayName,
+		kind: String(skipped.kind),
+		reason: "uncategorized",
+		level: "warn"
+	}));
+	const namespaceMembers = ApiItems.namespaceMembers(docItems);
 	const candidates = [];
-	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) candidates.push({
+	for (const [categoryKey, categoryConfig] of Object.entries(categories)) for (const item of items[categoryKey] || []) candidates.push(new Routes.RouteCandidate({
 		id: `${item.displayName}::${item.kind}`,
 		displayName: item.displayName,
 		folder: categoryConfig.folderName,
 		baseName: item.displayName.toLowerCase(),
 		kind: String(item.kind),
 		canonicalRef: item.canonicalReference?.toString() ?? item.displayName
-	});
+	}));
 	for (const nsMember of namespaceMembers) {
 		const nsCategoryEntry = Object.entries(categories).find(([, config]) => config.itemKinds?.includes(nsMember.item.kind));
 		if (!nsCategoryEntry) continue;
 		const [, nsCategoryConfig] = nsCategoryEntry;
-		candidates.push({
+		candidates.push(new Routes.RouteCandidate({
 			id: nsMember.qualifiedName,
 			displayName: nsMember.qualifiedName,
 			folder: nsCategoryConfig.folderName,
 			baseName: nsMember.qualifiedName.toLowerCase(),
 			kind: String(nsMember.item.kind),
 			canonicalRef: nsMember.item.canonicalReference?.toString() ?? nsMember.qualifiedName
-		});
+		}));
 	}
-	const collisions = detectRouteCollisions(candidates);
+	const collisions = Routes.detectCollisions(candidates);
 	if (collisions.length > 0) {
 		try {
 			for (const collision of collisions) emitEvent(PluginEvent.RouteCollisionDetected({
@@ -128,7 +124,10 @@ function prepareWorkItems(input) {
 				items: collision.items.map((item) => `${item.displayName} (${item.kind}) [${item.canonicalRef}]`)
 			}));
 		} catch {}
-		throw new Error(formatRouteCollisionError(collisions, baseRoute));
+		throw new Routes.RouteCollisionError({
+			baseRoute,
+			collisions
+		});
 	}
 	const routes = /* @__PURE__ */ new Map();
 	const kinds = /* @__PURE__ */ new Map();
@@ -148,7 +147,7 @@ function prepareWorkItems(input) {
 				const itemWithMembers = item;
 				for (const member of itemWithMembers.members) {
 					const memberName = member.displayName;
-					const memberId = sanitizeId(memberName);
+					const memberId = Routes.sanitizeId(memberName);
 					const fullMemberName = `${item.displayName}.${memberName}`;
 					const memberRoute = `${itemRoute}#${memberId}`;
 					routes.set(fullMemberName, memberRoute);
@@ -181,7 +180,7 @@ function prepareWorkItems(input) {
 		const owner = syntheticBase.ownerClasses[0];
 		const ownerRoute = owner ? routes.get(owner.displayName) : void 0;
 		if (!ownerRoute) continue;
-		routes.set(baseName, `${ownerRoute}#${BASE_CLASS_ANCHOR}`);
+		routes.set(baseName, `${ownerRoute}#${SyntheticBases.BASE_CLASS_ANCHOR}`);
 		kinds.set(baseName, baseItem.kind);
 	}
 	const workItems = [];
@@ -339,7 +338,7 @@ function generateSinglePage(workItem, ctx) {
 			durationMs: Math.round(performance.now() - pageGenStart),
 			level: "debug"
 		}));
-		const parsed = matter(page.content);
+		const parsed = parseFrontmatter(page.content);
 		const bodyContent = normalizeMarkdownSpacing(parsed.content);
 		const frontmatterData = parsed.data;
 		const relativePathWithExt = `${page.routePath.replace(baseRoute, "").replace(/^\//, "")}.mdx`;
@@ -354,7 +353,7 @@ function generateSinglePage(workItem, ctx) {
 			if (yield* fileSystem.exists(absolutePath).pipe(Effect.orElseSucceed(() => false))) {
 				const existingContent = yield* fileSystem.readFileString(absolutePath).pipe(Effect.orElseSucceed(() => null));
 				if (existingContent !== null) {
-					const { data: existingFrontmatter, content: existingBody } = matter(existingContent);
+					const { data: existingFrontmatter, content: existingBody } = parseFrontmatter(existingContent);
 					const normalizedExistingBody = normalizeMarkdownSpacing(existingBody);
 					const existingContentHash = hashContent(normalizedExistingBody);
 					const existingFrontmatterHash = hashFrontmatter(existingFrontmatter);
@@ -440,7 +439,7 @@ function writeSingleFile(result, ctx) {
 				routePath
 			};
 		}
-		let finalContent = matter.stringify(bodyContent, frontmatter);
+		let finalContent = stringifyFrontmatter(bodyContent, frontmatter);
 		if (ogResolver && siteUrl && packageName) {
 			const ogImageMetadata = yield* Effect.promise(() => ogResolver.resolve(ogImage, packageName, apiName));
 			const ogMetadataOptions = {

package/config-helpers.js

@@ -1,19 +1,21 @@
-import { normalizeBaseRoute, unscopedName } from "./path-derivation.js";
+import { normalizeBaseRoute } from "./path-derivation.js";
+import { SyncDiscoveryLayer } from "./sync-node-fs.js";
 import fs from "node:fs";
 import path from "node:path";
+import { Effect, Result } from "effect";
+import { discoverBundle } from "@tsdoctor/bundle";
 
 //#region src/config-helpers.ts
 const PREFIX = "[rspress-plugin-api-extractor]";
-function discoverModel(dir, packageName) {
-	const apiJsonFiles = fs.readdirSync(dir).filter((f) => f.endsWith(".api.json"));
-	if (apiJsonFiles.length === 1) return path.join(dir, apiJsonFiles[0]);
-	if (apiJsonFiles.length === 0) throw new Error(`${PREFIX} api.fromDir: no *.api.json model found in ${dir}. Pass an explicit \`model\` to override.`);
-	const unscoped = unscopedName(packageName);
-	const preferred = apiJsonFiles.find((f) => f === `${unscoped}.api.json`);
-	if (preferred) return path.join(dir, preferred);
-	throw new Error(`${PREFIX} api.fromDir: multiple *.api.json files in ${dir} (${apiJsonFiles.join(", ")}) and none match "${unscoped}.api.json". Pass an explicit \`model\`.`);
-}
-function discoverDir(dir) {
+/**
+* The adapter's strictness gate over `@tsdoctor/bundle`'s layer-0-only
+* discovery: the plugin's public contract requires a `package.json` with a
+* `name` (the bundle spec does not), so the gate runs FIRST and keeps the
+* historical error messages. Returning the parsed name/version also lets the
+* bundle discovery skip its api.json name fallback entirely (the model file
+* is never parsed here, exactly as before).
+*/
+function requirePackageJson(dir) {
 	let stat;
 	try {
 		stat = fs.statSync(dir);
@@ -29,13 +31,34 @@ function discoverDir(dir) {
 	}
 	if (!pkg.name) throw new Error(`${PREFIX} api.fromDir: package.json in ${dir} has no "name" field`);
 	return {
-		dir,
-		dirname: path.basename(dir),
-		packageName: pkg.name,
-		version: pkg.version ?? "",
-		modelPath: discoverModel(dir, pkg.name)
+		name: pkg.name,
+		...pkg.version !== void 0 ? { version: pkg.version } : {}
 	};
 }
+/**
+* Run `@tsdoctor/bundle`'s `discoverBundle` synchronously (over the sync
+* `FileSystem` bridge — see `sync-node-fs.ts`) and translate its typed
+* failures into the plugin's historical error messages.
+*/
+function discoverDescriptor(dir, name, version) {
+	const result = Effect.runSync(Effect.result(discoverBundle(dir, { overrides: {
+		name,
+		...version !== void 0 ? { version } : {}
+	} }).pipe(Effect.provide(SyncDiscoveryLayer))));
+	if (Result.isSuccess(result)) return result.success;
+	const error = result.failure;
+	if (error._tag === "BundleDiscoveryError") switch (error.reason) {
+		case "noApiModel": throw new Error(`${PREFIX} api.fromDir: no *.api.json model found in ${dir}. Pass an explicit \`model\` to override.`);
+		case "ambiguousApiModel": {
+			const facts = (error.detail ?? "multiple *.api.json files").split(";")[0];
+			throw new Error(`${PREFIX} api.fromDir: ${facts} in ${dir}. Pass an explicit \`model\`.`);
+		}
+		case "notFound": throw new Error(`${PREFIX} api.fromDir: directory not found: ${dir}`);
+		case "notADirectory": throw new Error(`${PREFIX} api.fromDir: not a directory: ${dir}`);
+		default: throw new Error(`${PREFIX} api.fromDir: ${error.message}`);
+	}
+	throw new Error(`${PREFIX} api.fromDir: ${String(error)}`);
+}
 function resolveBaseRoute(baseRoute, info) {
 	const interpolated = (typeof baseRoute === "function" ? baseRoute(info) : baseRoute).replace(/\{dirname\}/g, info.dirname).replace(/\{packageName\}/g, info.packageName);
 	return normalizeBaseRoute(interpolated);
@@ -46,21 +69,36 @@ function resolveBaseRoute(baseRoute, info) {
 * `ApiExtractorPlugin.api.fromDir`; the returned config can be passed to the
 * single-API `api:` option or used as an element of the multi-API `apis:` array.
 *
+* Discovery (model-file selection, unscoped-name disambiguation, tsconfig
+* detection) delegates to `@tsdoctor/bundle`'s `discoverBundle`; the
+* RSPress-specific concerns — `baseRoute` templating and `MultiApiConfig`
+* assembly — stay here, as does the plugin's stricter contract that the
+* folder carry a named `package.json` (the bundle spec itself accepts
+* layer-0-only folders).
+*
 * `baseRoute` is intentionally left unset unless overridden, so the plugin
 * applies its own context-aware default (`/api` under `api:`,
 * `/{packageName}/api` under `apis:`). See {@link BaseRoute}.
 */
 function fromDir(dir, overrides = {}) {
 	const { baseRoute, cwd, ...rest } = overrides;
-	const info = discoverDir(path.resolve(cwd ?? process.cwd(), dir));
-	const tsconfigPath = path.join(info.dir, "tsconfig.json");
+	const abs = path.resolve(cwd ?? process.cwd(), dir);
+	const pkg = requirePackageJson(abs);
+	const descriptor = discoverDescriptor(abs, pkg.name, pkg.version);
+	const info = {
+		dir: descriptor.dir,
+		dirname: descriptor.dirname,
+		packageName: descriptor.name,
+		version: descriptor.version ?? "",
+		modelPath: descriptor.modelPath
+	};
 	return {
 		packageName: info.packageName,
 		name: info.packageName,
 		model: info.modelPath,
 		packageJson: path.join(info.dir, "package.json"),
 		...baseRoute !== void 0 ? { baseRoute: resolveBaseRoute(baseRoute, info) } : {},
-		...fs.existsSync(tsconfigPath) ? { tsconfig: tsconfigPath } : {},
+		...descriptor.tsconfigPath !== void 0 ? { tsconfig: descriptor.tsconfigPath } : {},
 		...rest
 	};
 }
@@ -76,8 +114,10 @@ function isModelFolder(dir) {
 * Strictly scan a parent directory of package folders and build one
 * `MultiApiConfig` per subfolder. Exposed as `ApiExtractorPlugin.apis.fromDir`;
 * the returned array is intended for the multi-API `apis:` option. Every
-* non-dotfile subdirectory MUST be a valid model folder. `options` (minus
-* `cwd`) is applied as shared defaults to each `api.fromDir` call.
+* non-dotfile subdirectory MUST be a valid model folder — including a
+* `package.json`, which is this adapter's stricter contract over the bundle
+* spec's layer-0-only discovery. `options` (minus `cwd`) is applied as shared
+* defaults to each `api.fromDir` call.
 */
 function fromParentDir(parentDir, options = {}) {
 	const { cwd, ...rest } = options;

package/errors.js

@@ -8,12 +8,6 @@ var ConfigValidationError = class extends ConfigValidationErrorBase {
 	}
 };
 const ApiModelLoadErrorBase = Data.TaggedError("ApiModelLoadError");
-const SnapshotDbErrorBase = Data.TaggedError("SnapshotDbError");
-var SnapshotDbError = class extends SnapshotDbErrorBase {
-	get message() {
-		return `Snapshot DB error during '${this.operation}' at '${this.dbPath}': ${this.reason}`;
-	}
-};
 const PathDerivationErrorBase = Data.TaggedError("PathDerivationError");
 const TypeRegistryErrorBase = Data.TaggedError("TypeRegistryError");
 var TypeRegistryError = class extends TypeRegistryErrorBase {
@@ -26,4 +20,4 @@ const TwoslashProcessingErrorBase = Data.TaggedError("TwoslashProcessingError");
 const PrettierFormatErrorBase = Data.TaggedError("PrettierFormatError");
 
 //#endregion
-export { ConfigValidationError, ConfigValidationErrorBase, SnapshotDbError, SnapshotDbErrorBase, TypeRegistryError, TypeRegistryErrorBase };
+export { ConfigValidationError, ConfigValidationErrorBase, TypeRegistryError, TypeRegistryErrorBase };

package/frontmatter.js

@@ -0,0 +1,149 @@
+import { Effect } from "effect";
+import { Yaml, YamlStringifyOptions } from "@effected/yaml";
+
+//#region src/frontmatter.ts
+/**
+* Stringify options shared by both emit sites.
+*
+* `lineWidth: 0` disables wrapping so long titles/descriptions/URLs stay on
+* one line, and `defaultScalarStyle: "double-quoted"` quotes every string
+* value. The forced quoting matters for downstream consumers: RSPress parses
+* the emitted frontmatter with js-yaml (YAML 1.1-flavored), where an unquoted
+* ISO timestamp such as `2024-01-15T12:00:00.000Z` decodes to a `Date` object
+* instead of a string. Quoting every value keeps the decoded representation
+* identical across YAML 1.1 and 1.2 parsers.
+*/
+const STRINGIFY_OPTIONS = YamlStringifyOptions.make({
+	lineWidth: 0,
+	defaultScalarStyle: "double-quoted"
+});
+const OPEN_DELIMITER = "---";
+const CLOSE_SEARCH = "\n---";
+/**
+* Split markdown source into frontmatter data and body content, preserving
+* gray-matter's exact boundary semantics.
+*
+* @remarks
+* This is a byte-for-byte port of the `gray-matter` split contract the
+* snapshot system's hashes depend on (see `@tsdoctor/snapshot`
+* `hashContent`/`hashFrontmatter` and the disk-fallback comparison in
+* `build-stages.ts`), with `@effected/yaml` (`Yaml.parse`, YAML 1.2) as the
+* YAML engine instead of js-yaml:
+*
+* - No opening `---` line at offset 0 → `data: {}` and the whole input as
+*   `content` (a leading BOM is stripped first, as gray-matter does).
+* - The closing delimiter is the first `\n---` after the opening line
+*   (gray-matter uses a plain `indexOf`, so `\n----` also closes and the
+*   leftover `-` stays in the body — preserved deliberately).
+* - Exactly one newline (`\n` or `\r\n`) immediately after the closing `---`
+*   is consumed; everything else is the body verbatim. A build's generated
+*   page (`---\n…\n---\n\n# Title`) therefore yields a body starting with a
+*   single `\n`, exactly as gray-matter returned it.
+* - A block with no closing delimiter is all frontmatter and yields an empty
+*   body; an empty/blank block yields `data: {}`.
+* - Invalid YAML throws (a defect), matching gray-matter's js-yaml throw.
+*
+* One deliberate delta: gray-matter treats text on the opening line
+* (`---toml`) as an engine name and throws for unregistered engines; this
+* split treats such input as "no frontmatter" instead. The plugin never emits
+* or consumes language-tagged frontmatter.
+*
+* Representation parity with js-yaml is verified by characterization tests
+* (`__test__/frontmatter.test.ts`) pinning hashes captured under gray-matter.
+* The one input where the engines disagree — an *unquoted* ISO timestamp
+* (js-yaml: `Date`, YAML 1.2: string) — is unreachable from this plugin's
+* emitters, which always quote timestamp values, and hashes identically
+* anyway because `hashFrontmatter` JSON-serializes (a `Date` serializes to
+* the same ISO string).
+*
+* @param source - The markdown source, with or without a frontmatter block
+* @returns The decoded frontmatter data and the body content
+*
+* @public
+*/
+function parseFrontmatter(source) {
+	const text = source.charCodeAt(0) === 65279 ? source.slice(1) : source;
+	if (!text.startsWith(OPEN_DELIMITER)) return {
+		data: {},
+		content: text
+	};
+	const afterOpen = text.charAt(3);
+	if (text === OPEN_DELIMITER) return {
+		data: {},
+		content: ""
+	};
+	if (afterOpen !== "\n" && !(afterOpen === "\r" && text.charAt(4) === "\n")) return {
+		data: {},
+		content: text
+	};
+	const fmStart = afterOpen === "\r" ? 5 : 4;
+	const closeIndex = text.indexOf(CLOSE_SEARCH, fmStart - 1);
+	let frontmatterText;
+	let content;
+	if (closeIndex === -1) {
+		frontmatterText = text.slice(fmStart);
+		content = "";
+	} else {
+		frontmatterText = closeIndex < fmStart ? "" : text.slice(fmStart, closeIndex);
+		let bodyStart = closeIndex + 4;
+		if (text.charAt(bodyStart) === "\r" && text.charAt(bodyStart + 1) === "\n") bodyStart += 2;
+		else if (text.charAt(bodyStart) === "\n") bodyStart += 1;
+		content = text.slice(bodyStart);
+	}
+	if (frontmatterText.trim() === "") return {
+		data: {},
+		content
+	};
+	const value = Effect.runSync(Yaml.parse(frontmatterText));
+	return {
+		data: value == null ? {} : value,
+		content
+	};
+}
+/**
+* Serialize frontmatter data and body content back into a markdown document,
+* preserving gray-matter's `matter.stringify` contract.
+*
+* @remarks
+* Emits `---\n<yaml>---\n<content>` with the body's trailing newline ensured,
+* and returns the body unchanged (no fences) when `data` has no keys — both
+* gray-matter behaviors the write path relied on. The YAML is emitted by
+* `@effected/yaml` with every string value double-quoted (see
+* `STRINGIFY_OPTIONS` for why); byte output differs from js-yaml's dump, but
+* the decoded representation is identical, which is the invariant the
+* snapshot hashes depend on. Unchanged pages are never rewritten, so the byte
+* difference only ever lands in files that were being rewritten anyway.
+*
+* @param content - The body content
+* @param data - The frontmatter data to serialize
+* @returns The combined markdown document
+*
+* @public
+*/
+function stringifyFrontmatter(content, data) {
+	const body = content.endsWith("\n") ? content : `${content}\n`;
+	if (Object.keys(data).length === 0) return body;
+	return `---\n${Effect.runSync(Yaml.stringify(data, STRINGIFY_OPTIONS))}---\n${body}`;
+}
+/**
+* Serialize a data object to a YAML frontmatter block (fences included, plus
+* the trailing blank line the page generators emit before the body).
+*
+* @remarks
+* Used by `generateFrontmatter` (`markdown/helpers.ts`) as the emission half
+* of the page generators' frontmatter. Every string value is double-quoted
+* (see `STRINGIFY_OPTIONS`), so values that a YAML 1.1 consumer would
+* otherwise coerce (timestamps, `yes`/`no`, numeric-looking strings) stay
+* strings for RSPress's js-yaml parse.
+*
+* @param data - The frontmatter data to serialize
+* @returns A `---`-fenced YAML block ending with a blank line
+*
+* @public
+*/
+function emitFrontmatterBlock(data) {
+	return `---\n${Effect.runSync(Yaml.stringify(data, STRINGIFY_OPTIONS))}---\n\n`;
+}
+
+//#endregion
+export { emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter };

package/index.d.ts

@@ -874,6 +874,13 @@ type FromDirOptions = Omit<Partial<MultiApiConfig>, "baseRoute"> & {
  * `ApiExtractorPlugin.api.fromDir`; the returned config can be passed to the
  * single-API `api:` option or used as an element of the multi-API `apis:` array.
  *
+ * Discovery (model-file selection, unscoped-name disambiguation, tsconfig
+ * detection) delegates to `@tsdoctor/bundle`'s `discoverBundle`; the
+ * RSPress-specific concerns — `baseRoute` templating and `MultiApiConfig`
+ * assembly — stay here, as does the plugin's stricter contract that the
+ * folder carry a named `package.json` (the bundle spec itself accepts
+ * layer-0-only folders).
+ *
  * `baseRoute` is intentionally left unset unless overridden, so the plugin
  * applies its own context-aware default (`/api` under `api:`,
  * `/{packageName}/api` under `apis:`). See {@link BaseRoute}.
@@ -883,8 +890,10 @@ declare function fromDir(dir: string, overrides?: FromDirOptions): MultiApiConfi
  * Strictly scan a parent directory of package folders and build one
  * `MultiApiConfig` per subfolder. Exposed as `ApiExtractorPlugin.apis.fromDir`;
  * the returned array is intended for the multi-API `apis:` option. Every
- * non-dotfile subdirectory MUST be a valid model folder. `options` (minus
- * `cwd`) is applied as shared defaults to each `api.fromDir` call.
+ * non-dotfile subdirectory MUST be a valid model folder — including a
+ * `package.json`, which is this adapter's stricter contract over the bundle
+ * spec's layer-0-only discovery. `options` (minus `cwd`) is applied as shared
+ * defaults to each `api.fromDir` call.
  */
 declare function fromParentDir(parentDir: string, options?: FromDirOptions): MultiApiConfig[];
 //#endregion