@tsdoctor/model 0.4.1 → 0.6.0

package/Render.js

@@ -31,6 +31,9 @@ const KIND_SLUG = {
 * `ApiExportedMixin`. Every other item, including any lacking the flag, is
 * kept.
 *
+* @deprecated Use `prepareWorkItems` from `@tsdoctor/pages`, which decides
+* which items receive a page (`isPageKind` for the kind, `SyntheticBases.detect`
+* for the hoisted `*_base` declarations this rule was written to drop).
 * @public
 */
 const isEmittable = (item) => item.isExported !== false;
@@ -42,6 +45,8 @@ const signatureOf = (item) => {
 * Render one API item's markdown body as flow nodes — the pre-serialization
 * form of {@link item}.
 *
+* @deprecated Use `buildPage` + `markdownTree` from `@tsdoctor/pages`, which
+* yields the same `FlowContent` nodes from a typed `Page`.
 * @alpha
 */
 function tree(apiItem, opts) {
@@ -128,6 +133,7 @@ function tree(apiItem, opts) {
 /**
 * Render one API item to a markdown body string (no frontmatter).
 *
+* @deprecated Use `buildPage` + `renderMarkdown` from `@tsdoctor/pages`.
 * @public
 */
 function item(apiItem, opts) {
@@ -139,6 +145,9 @@ function item(apiItem, opts) {
 * Walk a package's first entry point and assemble one RenderedDoc per
 * top-level member.
 *
+* @deprecated Use `prepareWorkItems` + `buildPage` + `renderMarkdown` from
+* `@tsdoctor/pages`; frontmatter is assembled by the adapter from the
+* `Page`'s facts and head tags.
 * @public
 */
 function docs(apiPackage, opts) {

package/TypeReferenceExtractor.js

@@ -0,0 +1,201 @@
+import { ApiItemKind } from "@microsoft/api-extractor-model";
+
+//#region src/TypeReferenceExtractor.ts
+/**
+* Extracts type references from API Extractor models to generate import statements.
+*
+* This class analyzes API items and their excerpt tokens to identify external type
+* references that need to be imported in the generated TypeScript declaration files.
+*
+* **How it works:**
+* 1. Walks through all API items (classes, interfaces, functions, etc.)
+* 2. Extracts type references from excerpt tokens
+* 3. Filters out built-in types and internal references
+* 4. Groups external references by package
+* 5. Generates `import type` statements
+*
+* **Reference Types:**
+* - **Built-in:** TypeScript types like `Promise`, `Record`, `NonNullable` (skipped)
+* - **Internal:** References to types in the same package (skipped)
+* - **External:** References to types from npm packages (imported)
+*
+* **Canonical Reference Format:**
+* API Extractor uses canonical references like:
+* - `"zod!ZodType:interface"` → External reference to `zod` package
+* - `"mypackage!MyType:type"` → Internal reference (same package)
+* - `"!Promise:interface"` → Built-in TypeScript type
+* - `"!\"node:buffer\".__global.Buffer:interface"` → Node.js built-in (treated as built-in)
+*
+* @example
+* ```ts
+* const extractor = new TypeReferenceExtractor(apiPackage, "my-package");
+* const imports = extractor.extractImports();
+*
+* for (const stmt of imports) {
+*   console.log(`import type { ${[...stmt.symbols].join(", ")} } from "${stmt.packageName}";`);
+* }
+* // Output:
+* // import type { ZodType } from "zod";
+* // import type { Effect } from "@effect/schema";
+* ```
+*
+* @public
+*/
+var TypeReferenceExtractor = class {
+	apiPackage;
+	currentPackageName;
+	/**
+	* All type references found in the API package
+	*/
+	references = /* @__PURE__ */ new Map();
+	constructor(apiPackage, currentPackageName) {
+		this.apiPackage = apiPackage;
+		this.currentPackageName = currentPackageName;
+	}
+	/**
+	* Extract all type references from the API package and generate import statements.
+	* Returns an array of import statements grouped by package.
+	*/
+	extractImports() {
+		this.walkApiPackage();
+		return this.generateImportStatements();
+	}
+	/**
+	* Extract type references for a specific entry point only.
+	* This enables per-entry-point import optimization for multi-entry packages.
+	*
+	* @param entryPoint - The specific entry point to extract imports for
+	* @returns Import statements containing only types used in this entry point
+	*/
+	extractImportsForEntryPoint(entryPoint) {
+		this.references.clear();
+		for (const member of entryPoint.members) this.walkApiItem(member);
+		return this.generateImportStatements();
+	}
+	/**
+	* Extract type references for a single API item.
+	* This enables generating imports for individual signatures.
+	*
+	* @param apiItem - The specific API item to extract imports for
+	* @returns Import statements containing only types used in this item
+	*/
+	extractImportsForApiItem(apiItem) {
+		this.references.clear();
+		this.walkApiItem(apiItem);
+		return this.generateImportStatements();
+	}
+	/**
+	* Generate import statements from collected references.
+	* Used by both extractImports() and extractImportsForEntryPoint().
+	*/
+	generateImportStatements() {
+		const packageMap = /* @__PURE__ */ new Map();
+		for (const ref of this.references.values()) {
+			if (ref.isBuiltIn || ref.isInternal) continue;
+			if (!packageMap.has(ref.packageName)) packageMap.set(ref.packageName, /* @__PURE__ */ new Set());
+			packageMap.get(ref.packageName)?.add(ref.symbolName);
+		}
+		const imports = [];
+		for (const [packageName, symbols] of packageMap.entries()) imports.push({
+			packageName,
+			symbols,
+			typeOnly: true
+		});
+		imports.sort((a, b) => a.packageName.localeCompare(b.packageName));
+		return imports;
+	}
+	/**
+	* Generate import statement strings from ImportStatement objects.
+	* Returns an array of formatted import statements.
+	*/
+	static formatImports(imports) {
+		const statements = [];
+		for (const stmt of imports) {
+			const sortedSymbols = Array.from(stmt.symbols).sort();
+			const statement = `${stmt.typeOnly ? "import type" : "import"} { ${sortedSymbols.join(", ")} } from "${stmt.packageName}";`;
+			statements.push(statement);
+		}
+		return statements;
+	}
+	/**
+	* Walk through the entire API package and extract all type references
+	*/
+	walkApiPackage() {
+		for (const entryPoint of this.apiPackage.entryPoints) for (const member of entryPoint.members) this.walkApiItem(member);
+	}
+	/**
+	* Recursively walk through an API item and its children to extract type references
+	*/
+	walkApiItem(apiItem) {
+		this.extractFromExcerpt(apiItem);
+		if ("members" in apiItem) {
+			const members = apiItem.members;
+			if (Array.isArray(members)) for (const member of members) this.walkApiItem(member);
+		}
+	}
+	/**
+	* Extract type references from an API item using its excerpt
+	*/
+	extractFromExcerpt(apiItem) {
+		const excerpt = this.getExcerpt(apiItem);
+		if (!excerpt) return;
+		this.extractFromExcerptTokens(excerpt);
+	}
+	/**
+	* Get the appropriate excerpt from an API item based on its kind
+	*/
+	getExcerpt(apiItem) {
+		const item = apiItem;
+		if (item.excerpt) return item.excerpt;
+		if (apiItem.kind === ApiItemKind.TypeAlias && item.typeExcerpt) return item.typeExcerpt;
+		if ((apiItem.kind === ApiItemKind.Property || apiItem.kind === ApiItemKind.PropertySignature) && item.propertyTypeExcerpt) return item.propertyTypeExcerpt;
+		if (item.returnTypeExcerpt) return item.returnTypeExcerpt;
+		return null;
+	}
+	/**
+	* Extract type references from excerpt tokens
+	*/
+	extractFromExcerptTokens(excerpt) {
+		if (!excerpt.spannedTokens || excerpt.spannedTokens.length === 0) return;
+		for (const token of excerpt.spannedTokens) {
+			if (token.kind !== "Reference") continue;
+			const canonicalRef = token.canonicalReference?.toString();
+			if (!canonicalRef || typeof canonicalRef !== "string") continue;
+			const ref = this.parseCanonicalReference(canonicalRef, token.text);
+			if (ref) this.references.set(ref.canonicalReference, ref);
+		}
+	}
+	/**
+	* Parse a canonical reference string to extract type reference information.
+	*
+	* Canonical reference format: "packageName!symbolName:kind"
+	* Examples:
+	* - "zod!ZodType:interface" → External reference
+	* - "mypackage!MyType:type" → Internal reference
+	* - "!Promise:interface" → Built-in type
+	* - "!\"node:buffer\".__global.Buffer:interface" → Node.js built-in
+	*/
+	parseCanonicalReference(canonicalRef, symbolText) {
+		const exclamationIndex = canonicalRef.indexOf("!");
+		if (exclamationIndex === -1) return null;
+		const packagePart = canonicalRef.substring(0, exclamationIndex);
+		const rest = canonicalRef.substring(exclamationIndex + 1);
+		const colonIndex = rest.indexOf(":");
+		const symbolFromCanonical = colonIndex !== -1 ? rest.substring(0, colonIndex) : rest;
+		const isBuiltIn = packagePart === "" || packagePart.startsWith("\"");
+		const isInternal = packagePart === this.currentPackageName;
+		let symbolName;
+		if (symbolText.includes(".")) symbolName = symbolText.split(".")[0].trim();
+		else symbolName = symbolFromCanonical.trim();
+		return {
+			symbolName,
+			packageName: packagePart,
+			canonicalReference: canonicalRef,
+			isBuiltIn,
+			isInternal
+		};
+	}
+};
+
+//#endregion
+export { TypeReferenceExtractor };

package/index.d.ts

@@ -1,7 +1,106 @@
-import { ApiClass, ApiInterface, ApiItem, ApiModel, ApiNamespace, ApiPackage, Excerpt } from "@microsoft/api-extractor-model";
+import { ApiClass, ApiEntryPoint, ApiInterface, ApiItem, ApiModel, ApiNamespace, ApiPackage, Excerpt } from "@microsoft/api-extractor-model";
+import { VirtualPackage } from "@tsdoctor/vfs";
 import { Effect, Schema } from "effect";
 import { FlowContent, MarkdownNode } from "@effected/markdown";
 import { DocNode } from "@microsoft/tsdoc";
+//#endregion
+//#region src/ApiExtractedPackage.d.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
+ */
+declare class ApiExtractedPackage extends VirtualPackage {
+  readonly apiPackage: ApiPackage;
+  private constructor();
+  /**
+   * Create an ApiExtractedPackage from an API model JSON file path.
+   */
+  static fromApiModel(modelPath: string): ApiExtractedPackage;
+  /**
+   * Create an ApiExtractedPackage from an existing ApiPackage instance.
+   */
+  static fromPackage(apiPackage: ApiPackage, packageName: string): ApiExtractedPackage;
+  /**
+   * Generate the .d.ts content for a specific entry point.
+   */
+  generateDeclarations(entryPoint?: ApiEntryPoint): string;
+  /**
+   * Generate a TypeScript declaration for a single API item.
+   */
+  private generateDeclaration;
+  private generateClassDeclaration;
+  private generateInterfaceDeclaration;
+  private generateTypeAliasDeclaration;
+  private generateFunctionDeclaration;
+  private generateEnumDeclaration;
+  private generateVariableDeclaration;
+  private generateNamespaceDeclaration;
+  private generateNamespaceMember;
+  private generateNamespaceFunction;
+  private generateNamespaceInterface;
+  private generateNamespaceEnum;
+  private generateNamespaceTypeAlias;
+  private generateNamespaceVariable;
+  private generateNamespaceClass;
+  private generateClassMember;
+  private generateInterfaceMember;
+  private generateMemberFromExcerpt;
+  /**
+   * 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.
+   */
+  private renderExcerpt;
+  /**
+   * 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).
+   */
+  private normalizeTokenText;
+  /**
+   * Clean an excerpt text: strip export/declare keywords and trailing semicolons/whitespace.
+   */
+  private cleanExcerpt;
+  private formatTypeParameters;
+  private extractPackageDocumentation;
+  /**
+   * Format JSDoc comment from an API item's TSDoc.
+   * Produces output matching the TypeScript compiler's JSDoc style.
+   */
+  private formatJSDoc;
+  /**
+   * 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.
+   */
+  private extractPlainText;
+  private getEntryPointName;
+}
 declare namespace EntryPoints_d_exports {
   export { ResolvedEntryItem, entryPointName, resolve };
 }
@@ -182,6 +281,8 @@ interface ApiItemRef {
 /**
  * Metadata handed to the injected frontmatter renderer for one doc.
  *
+ * @deprecated Exists only for `Render.docs`; use the `Page` facts from
+ * `@tsdoctor/pages` (`buildPage`) instead.
  * @public
  */
 interface DocMeta extends ApiItemRef {
@@ -197,12 +298,16 @@ type RouteFormatter = (ref: ApiItemRef) => string;
 /**
  * Injected: produce the frontmatter block (incl. trailing blank line) for a doc, or "".
  *
+ * @deprecated Exists only for `Render.docs`; adapters assemble frontmatter
+ * from a `@tsdoctor/pages` `Page` (see `emitFrontmatterBlock`).
  * @public
  */
 type FrontmatterRenderer = (meta: DocMeta) => string;
 /**
  * One rendered API doc = its metadata plus the assembled markdown (frontmatter + body).
  *
+ * @deprecated Exists only for `Render.docs`; use `buildPage` +
+ * `renderMarkdown` from `@tsdoctor/pages`.
  * @public
  */
 interface RenderedDoc extends DocMeta {
@@ -212,6 +317,8 @@ interface RenderedDoc extends DocMeta {
  * Options for `Render.docs`: the package name plus the optional injected
  * route, frontmatter, and filter services.
  *
+ * @deprecated Exists only for `Render.docs`; use `BuildPageInput` from
+ * `@tsdoctor/pages`.
  * @public
  */
 interface RenderPackageOptions {
@@ -265,6 +372,109 @@ declare class CrossLinker {
    */
   linkHtml(text: string): string;
 }
+//#endregion
+//#region src/Frontmatter.d.ts
+/**
+ * A parsed frontmatter document: the decoded frontmatter data and the body
+ * content that followed the closing delimiter.
+ *
+ * @public
+ */
+interface ParsedFrontmatter {
+  /** Decoded frontmatter data (`{}` when there is no frontmatter block). */
+  readonly data: Record<string, unknown>;
+  /** Body content after the closing delimiter (whole input when no block). */
+  readonly content: string;
+}
+/**
+ * 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
+ */
+declare function parseFrontmatter(source: string): ParsedFrontmatter;
+/**
+ * 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
+ */
+declare function stringifyFrontmatter(content: string, data: Record<string, unknown>): string;
+/**
+ * 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
+ */
+declare function emitFrontmatterBlock(data: Record<string, unknown>): string;
 declare namespace Model_d_exports {
   export { EmptyModelError, ModelNotFoundError, ModelParseError, firstPackage, load };
 }
@@ -327,6 +537,9 @@ declare namespace Render_d_exports {
  * `ApiExportedMixin`. Every other item, including any lacking the flag, is
  * kept.
  *
+ * @deprecated Use `prepareWorkItems` from `@tsdoctor/pages`, which decides
+ * which items receive a page (`isPageKind` for the kind, `SyntheticBases.detect`
+ * for the hoisted `*_base` declarations this rule was written to drop).
  * @public
  */
 declare const isEmittable: (item: ApiItem) => boolean;
@@ -334,6 +547,8 @@ declare const isEmittable: (item: ApiItem) => boolean;
  * Options for {@link item} and {@link tree}: the package name used in
  * fallbacks and an optional crosslinker applied to the rendered prose.
  *
+ * @deprecated Use `BuildPageInput` from `@tsdoctor/pages`, which carries the
+ * per-API `CrossLinker` as `linker`.
  * @public
  */
 interface RenderItemOptions {
@@ -345,12 +560,15 @@ interface RenderItemOptions {
  * Render one API item's markdown body as flow nodes — the pre-serialization
  * form of {@link item}.
  *
+ * @deprecated Use `buildPage` + `markdownTree` from `@tsdoctor/pages`, which
+ * yields the same `FlowContent` nodes from a typed `Page`.
  * @alpha
  */
 declare function tree(apiItem: ApiItem, opts: RenderItemOptions): ReadonlyArray<FlowContent>;
 /**
  * Render one API item to a markdown body string (no frontmatter).
  *
+ * @deprecated Use `buildPage` + `renderMarkdown` from `@tsdoctor/pages`.
  * @public
  */
 declare function item(apiItem: ApiItem, opts: RenderItemOptions): string;
@@ -358,6 +576,9 @@ declare function item(apiItem: ApiItem, opts: RenderItemOptions): string;
  * Walk a package's first entry point and assemble one RenderedDoc per
  * top-level member.
  *
+ * @deprecated Use `prepareWorkItems` + `buildPage` + `renderMarkdown` from
+ * `@tsdoctor/pages`; frontmatter is assembled by the adapter from the
+ * `Page`'s facts and head tags.
  * @public
  */
 declare function docs(apiPackage: ApiPackage, opts: RenderPackageOptions): RenderedDoc[];
@@ -724,5 +945,167 @@ declare function seeReferences(item: ApiItem): ReadonlyArray<{
   readonly text: string;
 }>;
 //#endregion
-export { type ApiItemRef, ApiItems_d_exports as ApiItems, CrossLinker, type DocMeta, EntryPoints_d_exports as EntryPoints, type FrontmatterRenderer, type ItemKindSlug, Model_d_exports as Model, Render_d_exports as Render, type RenderPackageOptions, type RenderedDoc, type RouteFormatter, Routes_d_exports as Routes, Signature_d_exports as Signature, SyntheticBases_d_exports as SyntheticBases, Tsdoc_d_exports as Tsdoc };
+//#region src/TypeReferenceExtractor.d.ts
+/**
+ * Represents a type reference extracted from an API item.
+ * Contains information about where the type comes from and how to import it.
+ *
+ * @public
+ */
+interface TypeReference {
+  /**
+   * The symbol name to import (e.g., "ZodType", "Effect")
+   */
+  symbolName: string;
+  /**
+   * The package name (e.g., "zod", "\@effect/schema").
+   * Empty string for built-in TypeScript types.
+   */
+  packageName: string;
+  /**
+   * The canonical reference from API Extractor
+   * Format: "packageName!symbolName:kind"
+   */
+  canonicalReference: string;
+  /**
+   * Whether this is a built-in TypeScript type (Promise, Record, etc.)
+   */
+  isBuiltIn: boolean;
+  /**
+   * Whether this reference is from the current package being documented
+   */
+  isInternal: boolean;
+}
+/**
+ * Import statement to be generated for a package
+ *
+ * @public
+ */
+interface ImportStatement {
+  /**
+   * Package name to import from
+   */
+  packageName: string;
+  /**
+   * Named imports from this package
+   */
+  symbols: Set<string>;
+  /**
+   * Whether to use type-only import
+   */
+  typeOnly: boolean;
+}
+/**
+ * Extracts type references from API Extractor models to generate import statements.
+ *
+ * This class analyzes API items and their excerpt tokens to identify external type
+ * references that need to be imported in the generated TypeScript declaration files.
+ *
+ * **How it works:**
+ * 1. Walks through all API items (classes, interfaces, functions, etc.)
+ * 2. Extracts type references from excerpt tokens
+ * 3. Filters out built-in types and internal references
+ * 4. Groups external references by package
+ * 5. Generates `import type` statements
+ *
+ * **Reference Types:**
+ * - **Built-in:** TypeScript types like `Promise`, `Record`, `NonNullable` (skipped)
+ * - **Internal:** References to types in the same package (skipped)
+ * - **External:** References to types from npm packages (imported)
+ *
+ * **Canonical Reference Format:**
+ * API Extractor uses canonical references like:
+ * - `"zod!ZodType:interface"` → External reference to `zod` package
+ * - `"mypackage!MyType:type"` → Internal reference (same package)
+ * - `"!Promise:interface"` → Built-in TypeScript type
+ * - `"!\"node:buffer\".__global.Buffer:interface"` → Node.js built-in (treated as built-in)
+ *
+ * @example
+ * ```ts
+ * const extractor = new TypeReferenceExtractor(apiPackage, "my-package");
+ * const imports = extractor.extractImports();
+ *
+ * for (const stmt of imports) {
+ *   console.log(`import type { ${[...stmt.symbols].join(", ")} } from "${stmt.packageName}";`);
+ * }
+ * // Output:
+ * // import type { ZodType } from "zod";
+ * // import type { Effect } from "@effect/schema";
+ * ```
+ *
+ * @public
+ */
+declare class TypeReferenceExtractor {
+  private readonly apiPackage;
+  private readonly currentPackageName;
+  /**
+   * All type references found in the API package
+   */
+  private readonly references;
+  constructor(apiPackage: ApiPackage, currentPackageName: string);
+  /**
+   * Extract all type references from the API package and generate import statements.
+   * Returns an array of import statements grouped by package.
+   */
+  extractImports(): ImportStatement[];
+  /**
+   * Extract type references for a specific entry point only.
+   * This enables per-entry-point import optimization for multi-entry packages.
+   *
+   * @param entryPoint - The specific entry point to extract imports for
+   * @returns Import statements containing only types used in this entry point
+   */
+  extractImportsForEntryPoint(entryPoint: ApiEntryPoint): ImportStatement[];
+  /**
+   * Extract type references for a single API item.
+   * This enables generating imports for individual signatures.
+   *
+   * @param apiItem - The specific API item to extract imports for
+   * @returns Import statements containing only types used in this item
+   */
+  extractImportsForApiItem(apiItem: ApiItem): ImportStatement[];
+  /**
+   * Generate import statements from collected references.
+   * Used by both extractImports() and extractImportsForEntryPoint().
+   */
+  private generateImportStatements;
+  /**
+   * Generate import statement strings from ImportStatement objects.
+   * Returns an array of formatted import statements.
+   */
+  static formatImports(imports: ImportStatement[]): string[];
+  /**
+   * Walk through the entire API package and extract all type references
+   */
+  private walkApiPackage;
+  /**
+   * Recursively walk through an API item and its children to extract type references
+   */
+  private walkApiItem;
+  /**
+   * Extract type references from an API item using its excerpt
+   */
+  private extractFromExcerpt;
+  /**
+   * Get the appropriate excerpt from an API item based on its kind
+   */
+  private getExcerpt;
+  /**
+   * Extract type references from excerpt tokens
+   */
+  private extractFromExcerptTokens;
+  /**
+   * Parse a canonical reference string to extract type reference information.
+   *
+   * Canonical reference format: "packageName!symbolName:kind"
+   * Examples:
+   * - "zod!ZodType:interface" → External reference
+   * - "mypackage!MyType:type" → Internal reference
+   * - "!Promise:interface" → Built-in type
+   * - "!\"node:buffer\".__global.Buffer:interface" → Node.js built-in
+   */
+  private parseCanonicalReference;
+}
+//#endregion
+export { ApiExtractedPackage, type ApiItemRef, ApiItems_d_exports as ApiItems, CrossLinker, type DocMeta, EntryPoints_d_exports as EntryPoints, type FrontmatterRenderer, type ImportStatement, type ItemKindSlug, Model_d_exports as Model, type ParsedFrontmatter, Render_d_exports as Render, type RenderPackageOptions, type RenderedDoc, type RouteFormatter, Routes_d_exports as Routes, Signature_d_exports as Signature, SyntheticBases_d_exports as SyntheticBases, Tsdoc_d_exports as Tsdoc, type TypeReference, TypeReferenceExtractor, emitFrontmatterBlock, parseFrontmatter, stringifyFrontmatter };
 //# sourceMappingURL=index.d.ts.map