@tsdoctor/model 0.4.1 → 0.6.0

package/ApiExtractedPackage.js

@@ -0,0 +1,477 @@
+import { ApiItemKind, ApiModel, ExcerptTokenKind } from "@microsoft/api-extractor-model";
+import { VirtualPackage } from "@tsdoctor/vfs";
+
+//#region src/ApiExtractedPackage.ts
+/**
+* Reconstructs TypeScript declaration files from an API Extractor model.
+*
+* Extends `VirtualPackage` with the ability to generate high-fidelity
+* `.d.ts` output from API Extractor's `ApiPackage` — including enum values,
+* full JSDoc, namespace members, and all interface member kinds.
+*
+* Use the factory methods `fromApiModel` or `fromPackage` to create instances.
+*
+* @public
+*/
+var ApiExtractedPackage = class ApiExtractedPackage extends VirtualPackage {
+	apiPackage;
+	constructor(apiPackage, packageName, entries) {
+		super({
+			name: packageName,
+			version: "1.0.0",
+			entries
+		});
+		this.apiPackage = apiPackage;
+	}
+	/**
+	* Create an ApiExtractedPackage from an API model JSON file path.
+	*/
+	static fromApiModel(modelPath) {
+		const apiPackage = new ApiModel().loadPackage(modelPath);
+		return ApiExtractedPackage.fromPackage(apiPackage, apiPackage.name);
+	}
+	/**
+	* Create an ApiExtractedPackage from an existing ApiPackage instance.
+	*/
+	static fromPackage(apiPackage, packageName) {
+		const scratch = new ApiExtractedPackage(apiPackage, packageName, /* @__PURE__ */ new Map([["index.d.ts", ""]]));
+		const entries = /* @__PURE__ */ new Map();
+		for (const ep of apiPackage.entryPoints) {
+			const entryName = scratch.getEntryPointName(ep);
+			const fileName = entryName ? `${entryName}.d.ts` : "index.d.ts";
+			entries.set(fileName, scratch.generateDeclarations(ep));
+		}
+		return new ApiExtractedPackage(apiPackage, packageName, entries);
+	}
+	/**
+	* Generate the .d.ts content for a specific entry point.
+	*/
+	generateDeclarations(entryPoint) {
+		const ep = entryPoint ?? this.apiPackage.entryPoints[0];
+		if (!ep) return "";
+		const parts = [];
+		const packageDoc = this.extractPackageDocumentation();
+		if (packageDoc) {
+			parts.push(packageDoc);
+			parts.push("");
+		}
+		for (const member of ep.members) {
+			const decl = this.generateDeclaration(member);
+			if (decl) {
+				parts.push(decl);
+				parts.push("");
+			}
+		}
+		parts.push("export { }");
+		parts.push("");
+		return parts.join("\n");
+	}
+	/**
+	* Generate a TypeScript declaration for a single API item.
+	*/
+	generateDeclaration(apiItem) {
+		switch (apiItem.kind) {
+			case ApiItemKind.Class: return this.generateClassDeclaration(apiItem);
+			case ApiItemKind.Interface: return this.generateInterfaceDeclaration(apiItem);
+			case ApiItemKind.TypeAlias: return this.generateTypeAliasDeclaration(apiItem);
+			case ApiItemKind.Function: return this.generateFunctionDeclaration(apiItem);
+			case ApiItemKind.Enum: return this.generateEnumDeclaration(apiItem);
+			case ApiItemKind.Variable: return this.generateVariableDeclaration(apiItem);
+			case ApiItemKind.Namespace: return this.generateNamespaceDeclaration(apiItem);
+			default: return null;
+		}
+	}
+	generateClassDeclaration(apiClass) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiClass);
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiClass.displayName;
+		if (apiClass.typeParameters?.length) name += this.formatTypeParameters(apiClass.typeParameters);
+		const headerParts = apiClass.isAbstract ? ["export declare abstract class", name] : ["export declare class", name];
+		if (apiClass.extendsType) headerParts.push(`extends ${this.renderExcerpt(apiClass.extendsType.excerpt)}`);
+		if (apiClass.implementsTypes?.length) {
+			const impl = apiClass.implementsTypes.map((t) => this.renderExcerpt(t.excerpt)).join(", ");
+			headerParts.push(`implements ${impl}`);
+		}
+		lines.push(`${headerParts.join(" ")} {`);
+		for (const member of apiClass.members) {
+			const memberDecl = this.generateClassMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateInterfaceDeclaration(apiInterface) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiInterface);
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiInterface.displayName;
+		if (apiInterface.typeParameters?.length) name += this.formatTypeParameters(apiInterface.typeParameters);
+		const headerParts = ["export declare interface", name];
+		if (apiInterface.extendsTypes?.length) {
+			const ext = apiInterface.extendsTypes.map((t) => this.renderExcerpt(t.excerpt)).join(", ");
+			headerParts.push(`extends ${ext}`);
+		}
+		lines.push(`${headerParts.join(" ")} {`);
+		for (const member of apiInterface.members) {
+			const memberDecl = this.generateInterfaceMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateTypeAliasDeclaration(typeAlias) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(typeAlias);
+		if (jsDoc) lines.push(jsDoc);
+		let name = typeAlias.displayName;
+		if (typeAlias.typeParameters?.length) name += this.formatTypeParameters(typeAlias.typeParameters);
+		lines.push(`export declare type ${name} = ${this.renderExcerpt(typeAlias.typeExcerpt)};`);
+		return lines.join("\n");
+	}
+	generateFunctionDeclaration(apiFunction) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiFunction);
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(this.renderExcerpt(apiFunction.excerpt));
+		const decl = cleaned.startsWith("function ") ? cleaned : `const ${cleaned}`;
+		lines.push(`export declare ${decl};`);
+		return lines.join("\n");
+	}
+	generateEnumDeclaration(apiEnum) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiEnum);
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`export declare enum ${apiEnum.displayName} {`);
+		const enumMembers = apiEnum.members.filter((m) => m.kind === ApiItemKind.EnumMember);
+		for (let i = 0; i < enumMembers.length; i++) {
+			const enumMember = enumMembers[i];
+			const memberJsDoc = this.formatJSDoc(enumMember, "    ");
+			if (memberJsDoc) lines.push(memberJsDoc);
+			const suffix = i === enumMembers.length - 1 ? "" : ",";
+			const initExcerpt = enumMember.initializerExcerpt;
+			if (initExcerpt?.text.trim()) lines.push(`    ${enumMember.displayName} = ${initExcerpt.text.trim()}${suffix}`);
+			else lines.push(`    ${enumMember.displayName}${suffix}`);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateVariableDeclaration(apiVariable) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiVariable);
+		if (jsDoc) lines.push(jsDoc);
+		let cleaned = this.cleanExcerpt(this.renderExcerpt(apiVariable.excerpt));
+		if (!cleaned.startsWith("const ") && !cleaned.startsWith("let ") && !cleaned.startsWith("var ")) cleaned = `const ${cleaned}`;
+		lines.push(`export declare ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceDeclaration(apiNamespace) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiNamespace);
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`export declare namespace ${apiNamespace.displayName} {`);
+		for (const member of apiNamespace.members) {
+			const memberDecl = this.generateNamespaceMember(member);
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("}");
+		return lines.join("\n");
+	}
+	generateNamespaceMember(apiItem) {
+		switch (apiItem.kind) {
+			case ApiItemKind.Function: return this.generateNamespaceFunction(apiItem);
+			case ApiItemKind.Interface: return this.generateNamespaceInterface(apiItem);
+			case ApiItemKind.Enum: return this.generateNamespaceEnum(apiItem);
+			case ApiItemKind.TypeAlias: return this.generateNamespaceTypeAlias(apiItem);
+			case ApiItemKind.Variable: return this.generateNamespaceVariable(apiItem);
+			case ApiItemKind.Class: return this.generateNamespaceClass(apiItem);
+			default: return null;
+		}
+	}
+	generateNamespaceFunction(apiFunction) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiFunction, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(this.renderExcerpt(apiFunction.excerpt));
+		lines.push(`    export ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceInterface(apiInterface) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiInterface, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let name = apiInterface.displayName;
+		if (apiInterface.typeParameters?.length) name += this.formatTypeParameters(apiInterface.typeParameters);
+		const headerParts = ["export interface", name];
+		if (apiInterface.extendsTypes?.length) {
+			const ext = apiInterface.extendsTypes.map((t) => this.renderExcerpt(t.excerpt)).join(", ");
+			headerParts.push(`extends ${ext}`);
+		}
+		lines.push(`    ${headerParts.join(" ")} {`);
+		for (const member of apiInterface.members) {
+			const memberDecl = this.generateInterfaceMember(member, "        ");
+			if (memberDecl) lines.push(memberDecl);
+		}
+		lines.push("    }");
+		return lines.join("\n");
+	}
+	generateNamespaceEnum(apiEnum) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiEnum, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		lines.push(`    export enum ${apiEnum.displayName} {`);
+		const enumMembers = apiEnum.members.filter((m) => m.kind === ApiItemKind.EnumMember);
+		for (let i = 0; i < enumMembers.length; i++) {
+			const enumMember = enumMembers[i];
+			const memberJsDoc = this.formatJSDoc(enumMember, "        ");
+			if (memberJsDoc) lines.push(memberJsDoc);
+			const suffix = i === enumMembers.length - 1 ? "" : ",";
+			const initExcerpt = enumMember.initializerExcerpt;
+			if (initExcerpt?.text.trim()) lines.push(`        ${enumMember.displayName} = ${initExcerpt.text.trim()}${suffix}`);
+			else lines.push(`        ${enumMember.displayName}${suffix}`);
+		}
+		lines.push("    }");
+		return lines.join("\n");
+	}
+	generateNamespaceTypeAlias(typeAlias) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(typeAlias, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let name = typeAlias.displayName;
+		if (typeAlias.typeParameters?.length) name += this.formatTypeParameters(typeAlias.typeParameters);
+		lines.push(`    export type ${name} = ${this.renderExcerpt(typeAlias.typeExcerpt)};`);
+		return lines.join("\n");
+	}
+	generateNamespaceVariable(apiVariable) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(apiVariable, "    ");
+		if (jsDoc) lines.push(jsDoc);
+		let cleaned = this.cleanExcerpt(this.renderExcerpt(apiVariable.excerpt));
+		if (!cleaned.startsWith("const ") && !cleaned.startsWith("let ") && !cleaned.startsWith("var ")) cleaned = `const ${cleaned}`;
+		lines.push(`    export ${cleaned};`);
+		return lines.join("\n");
+	}
+	generateNamespaceClass(apiClass) {
+		const decl = this.generateClassDeclaration(apiClass);
+		if (!decl) return "";
+		return decl.replace(/\bexport declare (abstract )?class\b/, "export $1class").split("\n").map((line) => line.trim() ? `    ${line}` : line).join("\n");
+	}
+	generateClassMember(member, indent = "    ") {
+		switch (member.kind) {
+			case ApiItemKind.Constructor: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.Method: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.Property: return this.generateMemberFromExcerpt(member, indent);
+			default: return null;
+		}
+	}
+	generateInterfaceMember(member, indent = "    ") {
+		switch (member.kind) {
+			case ApiItemKind.MethodSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.PropertySignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.CallSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.ConstructSignature: return this.generateMemberFromExcerpt(member, indent);
+			case ApiItemKind.IndexSignature: return this.generateMemberFromExcerpt(member, indent);
+			default: return null;
+		}
+	}
+	generateMemberFromExcerpt(member, indent) {
+		const lines = [];
+		const jsDoc = this.formatJSDoc(member, indent);
+		if (jsDoc) lines.push(jsDoc);
+		const cleaned = this.cleanExcerpt(this.renderExcerpt(member.excerpt));
+		lines.push(`${indent}${cleaned};`);
+		return lines.join("\n");
+	}
+	/**
+	* Render an excerpt to source text, normalizing dts-rollup disambiguation
+	* aliases. The dts rollup renames a re-imported symbol as `Name$1`, but its
+	* canonical reference is the un-suffixed `Name` (the same symbol). The import
+	* prepender ({@link TypeReferenceExtractor}) imports the canonical name, so
+	* emitting the suffixed text would leave `Name$1` undefined (TS2304). Emit the
+	* canonical name so the body and the prepended import agree.
+	*
+	* Equivalent to `excerpt.text` for excerpts without rollup aliases (the text
+	* is the concatenation of the spanned tokens), so unaliased output is unchanged.
+	*/
+	renderExcerpt(excerpt) {
+		return excerpt.spannedTokens.map((token) => this.normalizeTokenText(token)).join("");
+	}
+	/**
+	* Strip a dts-rollup `$N` suffix from a reference token when the de-suffixed
+	* text matches the token's canonical symbol. Never touches a non-reference
+	* token or a legitimate identifier that genuinely ends in `$N` (its canonical
+	* name would carry the suffix too).
+	*/
+	normalizeTokenText(token) {
+		if (token.kind !== ExcerptTokenKind.Reference) return token.text;
+		const match = /^(.+)\$\d+$/.exec(token.text);
+		if (!match) return token.text;
+		const canonical = token.canonicalReference?.toString();
+		if (!canonical) return token.text;
+		const afterBang = canonical.slice(canonical.indexOf("!") + 1);
+		const colon = afterBang.indexOf(":");
+		const symbol = colon === -1 ? afterBang : afterBang.slice(0, colon);
+		const leaf = symbol.includes(".") ? symbol.slice(symbol.lastIndexOf(".") + 1) : symbol;
+		return match[1] === symbol || match[1] === leaf ? match[1] : token.text;
+	}
+	/**
+	* Clean an excerpt text: strip export/declare keywords and trailing semicolons/whitespace.
+	*/
+	cleanExcerpt(text) {
+		return text.replace(/^export\s+/, "").replace(/^declare\s+/, "").replace(/;+\s*$/, "").trim();
+	}
+	formatTypeParameters(typeParameters) {
+		if (!typeParameters.length) return "";
+		return `<${typeParameters.map((tp) => {
+			const parts = [tp.name];
+			if (tp.constraintExcerpt && this.renderExcerpt(tp.constraintExcerpt).trim()) parts.push(`extends ${this.renderExcerpt(tp.constraintExcerpt).trim()}`);
+			if (tp.defaultTypeExcerpt && this.renderExcerpt(tp.defaultTypeExcerpt).trim()) parts.push(`= ${this.renderExcerpt(tp.defaultTypeExcerpt).trim()}`);
+			return parts.join(" ");
+		}).join(", ")}>`;
+	}
+	extractPackageDocumentation() {
+		const pkg = this.apiPackage;
+		if (!pkg.tsdocComment?.summarySection) return null;
+		const summary = this.extractPlainText(pkg.tsdocComment.summarySection).trim();
+		if (!summary) return null;
+		const lines = [];
+		for (const line of summary.split("\n")) lines.push(line);
+		lines.push("");
+		lines.push("@packageDocumentation");
+		return `/**\n${lines.map((line) => line ? ` * ${line}` : " *").join("\n")}\n */`;
+	}
+	/**
+	* Format JSDoc comment from an API item's TSDoc.
+	* Produces output matching the TypeScript compiler's JSDoc style.
+	*/
+	formatJSDoc(apiItem, indent = "") {
+		const item = apiItem;
+		if (!item.tsdocComment) return null;
+		const tsdoc = item.tsdocComment;
+		const lines = [];
+		if (tsdoc.summarySection) {
+			const summary = this.extractPlainText(tsdoc.summarySection).trim();
+			if (summary) for (const line of summary.split("\n")) lines.push(line);
+		}
+		const typeParamLines = [];
+		if (tsdoc.typeParams?.blocks) for (const block of tsdoc.typeParams.blocks) {
+			const blockAny = block;
+			const name = blockAny.parameterName || "";
+			const desc = this.extractPlainText(blockAny.content).replace(/\s+/g, " ").trim();
+			if (name && desc) typeParamLines.push(`@typeParam ${name} - ${desc}`);
+		}
+		const paramLines = [];
+		if (tsdoc.params?.blocks) for (const paramBlock of tsdoc.params.blocks) {
+			const param = paramBlock;
+			const name = param.parameterName || "";
+			const desc = this.extractPlainText(param.content).replace(/\s+/g, " ").trim();
+			if (name && desc) paramLines.push(`@param ${name} - ${desc}`);
+		}
+		let returnsLine = null;
+		if (tsdoc.returnsBlock) {
+			const desc = this.extractPlainText(tsdoc.returnsBlock.content).replace(/\s+/g, " ").trim();
+			if (desc) returnsLine = `@returns ${desc}`;
+		}
+		if (typeParamLines.length || paramLines.length || returnsLine) {
+			if (lines.length > 0) lines.push("");
+			lines.push(...typeParamLines);
+			lines.push(...paramLines);
+			if (returnsLine) lines.push(returnsLine);
+		}
+		if (tsdoc.deprecatedBlock) {
+			const msg = this.extractPlainText(tsdoc.deprecatedBlock.content).replace(/\s+/g, " ").trim();
+			if (msg) {
+				if (lines.length > 0) lines.push("");
+				lines.push(`@deprecated ${msg}`);
+			}
+		}
+		if (tsdoc.remarksBlock) {
+			const remarks = this.extractPlainText(tsdoc.remarksBlock.content).trim();
+			if (remarks) {
+				if (lines.length > 0) lines.push("");
+				lines.push("@remarks");
+				for (const line of remarks.split("\n")) lines.push(line);
+			}
+		}
+		if (tsdoc.customBlocks) for (const block of tsdoc.customBlocks) {
+			const blockAny = block;
+			if (blockAny.blockTag?.tagName === "@example") {
+				const exampleText = this.extractPlainText(blockAny.content).trim();
+				if (exampleText) {
+					if (lines.length > 0) lines.push("");
+					lines.push("@example");
+					for (const line of exampleText.split("\n")) lines.push(line);
+				}
+			}
+		}
+		try {
+			if (tsdoc.modifierTagSet?.isPublic?.()) {
+				if (lines.length > 0) lines.push("");
+				lines.push("@public");
+			}
+		} catch {}
+		if (lines.length === 0) return null;
+		if (lines.length === 1 && !lines[0].includes("\n")) return `${indent}/** ${lines[0]} */`;
+		return `${indent}/**\n${lines.map((line) => line ? `${indent} * ${line}` : `${indent} *`).join("\n")}\n${indent} */`;
+	}
+	/**
+	* Recursively extract plain text from a TSDoc DocNode tree.
+	*
+	* @remarks
+	* NOT interchangeable with this package's `Tsdoc` prose extraction, despite
+	* the overlapping name and shape. This one **preserves** `{@link X.Y}` TSDoc
+	* syntax and reconstructs fenced code blocks, because its output is a
+	* `.d.ts` file whose JSDoc must survive round-tripping into a virtual
+	* TypeScript environment. `Tsdoc`'s flattens `{@link}` to its display text
+	* and drops code fences, because its output is rendered prose.
+	*
+	* They looked like duplicates from two packages away and now sit in one, so
+	* this is the note that should stop the merge: collapsing them would either
+	* put display text where a declaration reference belongs, or leak link
+	* syntax into rendered documentation.
+	*/
+	extractPlainText(node) {
+		const n = node;
+		if (n.kind === "PlainText") return n.text || "";
+		if (n.kind === "SoftBreak") return "\n";
+		if (n.kind === "CodeSpan") return `\`${n.code || ""}\``;
+		if (n.kind === "EscapedText") return n.encodedText || n.decodedText || "";
+		if (n.kind === "ErrorText") return n.text || "";
+		if (n.kind === "FencedCode") return `\`\`\`${n.language || ""}\n${(n.code || "").replace(/\n+$/, "")}\n\`\`\``;
+		if (n.kind === "LinkTag") {
+			let target = "";
+			if (n.codeDestination?.memberReferences) {
+				const identifiers = [];
+				for (const ref of n.codeDestination.memberReferences) if (ref.memberIdentifier?.identifier) identifiers.push(ref.memberIdentifier.identifier);
+				target = identifiers.join(".");
+			}
+			const displayText = typeof n.linkText === "string" ? n.linkText : "";
+			if (target && displayText) return `{@link ${target} | ${displayText}}`;
+			if (target) return `{@link ${target}}`;
+			if (displayText) return displayText;
+			return "";
+		}
+		if (n.kind === "Section") {
+			const children = n.getChildNodes?.() || [];
+			const paragraphs = [];
+			for (const child of children) {
+				const trimmed = this.extractPlainText(child).trim();
+				if (trimmed) paragraphs.push(trimmed);
+			}
+			return paragraphs.join("\n\n");
+		}
+		const parts = [];
+		if (n.getChildNodes && typeof n.getChildNodes === "function") for (const child of n.getChildNodes()) {
+			const text = this.extractPlainText(child);
+			if (text) parts.push(text);
+		}
+		return parts.join("");
+	}
+	getEntryPointName(entryPoint) {
+		if (entryPoint.displayName === "") return void 0;
+		return entryPoint.displayName;
+	}
+};
+
+//#endregion
+export { ApiExtractedPackage };

package/Frontmatter.js

@@ -0,0 +1,152 @@
+import { Effect } from "effect";
+import { FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit } from "@effected/markdown";
+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. The 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. `quoteCompat: "yaml-1.1"` quotes exactly the
+* plain scalars a YAML 1.1 resolver would coerce (timestamps, `yes`/`no`/
+* `on`/`off` booleans, legacy octal/sexagesimal numbers), keeping the
+* decoded representation identical across YAML 1.1 and 1.2 parsers without
+* quoting every value; `quoteStyle: "double"` makes the quotes that do
+* appear double quotes.
+*/
+const STRINGIFY_OPTIONS = YamlStringifyOptions.make({
+	lineWidth: 0,
+	quoteCompat: "yaml-1.1",
+	quoteStyle: "double"
+});
+/**
+* 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.
+*
+* `@effected/markdown`'s `FrontmatterSource.split` was evaluated for this
+* path and deliberately NOT adopted: its grammar is strict by design (a
+* fence line is exactly `---`, an unterminated block is not frontmatter),
+* while this contract pins gray-matter's `indexOf`-based quirks (`\n----`
+* closes, trailing-space close lines close, a missing close means
+* all-frontmatter). The emission half (`stringifyFrontmatter` /
+* `emitFrontmatterBlock`) does use `FrontmatterSource.join`.
+*
+* 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;
+	const split = FrontmatterSource.split(text);
+	if (split.frontmatter === void 0 || split.frontmatter.format !== "yaml") return {
+		data: {},
+		content: split.body
+	};
+	if (split.frontmatter.value.trim() === "") return {
+		data: {},
+		content: split.body
+	};
+	const value = Effect.runSync(Yaml.parse(split.frontmatter.value));
+	return {
+		data: value == null ? {} : value,
+		content: split.body
+	};
+}
+/**
+* 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;
+	const yaml = Effect.runSync(Yaml.stringify(data, STRINGIFY_OPTIONS));
+	return FrontmatterSource.join(FrontmatterSourceSplit.make({
+		frontmatter: FrontmatterSourceBlock.make({
+			format: "yaml",
+			value: yaml
+		}),
+		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) {
+	const yaml = Effect.runSync(Yaml.stringify(data, STRINGIFY_OPTIONS));
+	return FrontmatterSource.join(FrontmatterSourceSplit.make({
+		frontmatter: FrontmatterSourceBlock.make({
+			format: "yaml",
+			value: yaml
+		}),
+		body: "\n"
+	}));
+}
+
+//#endregion
+export { emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter };

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Framework-neutral analysis and rendering for Microsoft API Extractor `.api.json` models: Effect-typed loading, pure TSDoc extraction, categorization, multi-entry-point resolution, route/collision computation, synthetic-base detection, type-signature formatting, prose cross-linking and markdown rendering.
+Framework-neutral analysis and rendering for Microsoft API Extractor `.api.json` models: Effect-typed loading, pure TSDoc extraction, categorization, multi-entry-point resolution, route/collision computation, synthetic-base detection, type-signature formatting, prose cross-linking, declaration reconstruction and markdown rendering.
 
 ## Why @tsdoctor/model
 
@@ -23,7 +23,7 @@ pnpm add @tsdoctor/model
 
 Requires Node.js >=24.11.0. This is an ESM-only package.
 
-`@effected/markdown` and `effect` are required peers (`Render` builds its output as `@effected/markdown` node trees). `@effected/package-json` is an optional peer, needed only by the `StructuredData` seam.
+`@effected/markdown`, `@effected/yaml` and `effect` are required peers — `Render` builds its output as `@effected/markdown` node trees, and the frontmatter helpers parse and emit through `@effected/yaml`. [`@tsdoctor/vfs`](https://www.npmjs.com/package/@tsdoctor/vfs) is an ordinary dependency, resolved for you: `ApiExtractedPackage` extends its `VirtualPackage`.
 
 ## Quick start
 
@@ -100,7 +100,9 @@ Supplying `filter` fully replaces the default, so compose it with `Render.isEmit
 - **`Signature`** — `format(excerpt)` turns an API Extractor `Excerpt` into a clean, line-wrapped type signature string; `stripExportDeclare` strips `export`/`declare` modifiers from declaration text.
 - **`CrossLinker`** — an immutable class that wraps known item names in prose with links, skipping code spans and existing links. Build one per build from a precomputed route map (`CrossLinker.fromRoutes`) or from item refs plus an injected URL scheme (`CrossLinker.fromRefs`); `link` returns markdown links, `linkHtml` returns `<a>` anchors.
 - **`Render`** — the markdown output system. `Render.docs(pkg, opts)` renders a whole package; `Render.item(apiItem, opts)` renders one item; `Render.isEmittable` is the default emit rule. `Render.tree` (`@alpha`) exposes the pre-serialization `@effected/markdown` node tree for a future page-IR consumer.
-- **`StructuredData`** (`@alpha`) — a reserved seam for schema.org JSON-LD derivation. `StructuredData.derive` is not implemented yet and throws if called.
+- **`ApiExtractedPackage`** — reconstructs `.d.ts` text from a model and renders it to a `Vfs`, one declaration file per entry point behind a synthetic `package.json`, so a type-checker can resolve the documented package the way a consumer would. Built on `VirtualPackage` from `@tsdoctor/vfs`; `fromApiModel(path)` loads a model file, `fromPackage(apiPackage, name)` takes one already in memory.
+- **`TypeReferenceExtractor`** — finds the types a package's declarations reference but do not own, and emits the `import type` statements those declarations need. `extractImports` covers a package, `extractImportsForEntryPoint` one entry point, and the static `formatImports` renders an `ImportStatement[]` to source lines. Built-in and self-referencing types are filtered out, and a namespaced reference imports its namespace root rather than the leaf member.
+- **Frontmatter** — `parseFrontmatter(text)` splits a document into `{ data, content }`, `stringifyFrontmatter(data)` emits the YAML block, and `emitFrontmatterBlock(data, body)` assembles a whole document. Quoting is chosen so a YAML 1.1 consumer decodes the same values a YAML 1.2 one does — an unquoted ISO timestamp would otherwise arrive as a `Date` in one and a string in the other.
 
 ## License