@openpkg-ts/sdk 0.32.1 → 0.33.0

package/dist/index.d.ts

@@ -1,5 +1,159 @@
 import { BreakingSeverity, CategorizedBreaking, calculateNextVersion, categorizeBreakingChanges, diffSpec, diffSpec as diffSpec2, MemberChangeInfo, recommendSemverBump, SemverBump, SemverRecommendation, SpecDiff } from "@openpkg-ts/spec";
-import { OpenPkg, SpecExport } from "@openpkg-ts/spec";
+import { OpenPkg } from "@openpkg-ts/spec";
+/** Configuration for resolving external package re-exports */
+interface ExternalsConfig {
+	/** Package patterns to resolve (globs supported, e.g., "@myorg/*") */
+	include?: string[];
+	/** Package patterns to never resolve */
+	exclude?: string[];
+	/** Max transitive depth for resolution (default: 1) */
+	depth?: number;
+}
+interface ExtractOptions {
+	entryFile: string;
+	baseDir?: string;
+	content?: string;
+	maxTypeDepth?: number;
+	maxExternalTypeDepth?: number;
+	resolveExternalTypes?: boolean;
+	schemaExtraction?: "static" | "hybrid";
+	/** Target JSON Schema dialect for runtime schema extraction */
+	schemaTarget?: "draft-2020-12" | "draft-07" | "openapi-3.0";
+	/** Include $schema URL in output */
+	includeSchema?: boolean;
+	/** Only extract these exports (supports * wildcards) */
+	only?: string[];
+	/** Ignore these exports (supports * wildcards) */
+	ignore?: string[];
+	/** Progress callback for tracking extraction progress */
+	onProgress?: (current: number, total: number, item: string) => void;
+	/** Whether source is a .d.ts file (degraded mode - TSDoc may be missing) */
+	isDtsSource?: boolean;
+	/** Include private/protected class members (default: false) */
+	includePrivate?: boolean;
+	/** Configuration for resolving external package re-exports */
+	externals?: ExternalsConfig;
+}
+interface ExtractResult {
+	spec: OpenPkg;
+	diagnostics: Diagnostic[];
+	forgottenExports?: ForgottenExport[];
+	/** Metadata about runtime schema extraction (when schemaExtraction: 'hybrid') */
+	runtimeSchemas?: {
+		/** Number of schema exports found */
+		extracted: number;
+		/** Number of schemas successfully merged with static types */
+		merged: number;
+		/** Schema vendors detected (e.g., 'zod', 'arktype', 'valibot', 'typebox') */
+		vendors: string[];
+		/** Any errors encountered during runtime extraction */
+		errors: string[];
+		/** Extraction method used: 'compiled' or 'direct-ts (runtime)' */
+		method?: string;
+	};
+	/** Degraded mode info when extracting from .d.ts files */
+	degradedMode?: {
+		reason: "dts-source";
+		stats: {
+			exportsWithoutDescription: number;
+			paramsWithoutDocs: number;
+			missingExamples: number;
+		};
+	};
+	/** Export verification comparing discovered vs extracted */
+	verification?: ExportVerification;
+}
+interface Diagnostic {
+	message: string;
+	severity: "error" | "warning" | "info";
+	code?: string;
+	suggestion?: string;
+	location?: {
+		file?: string;
+		line?: number;
+		column?: number;
+	};
+}
+/** Context tracking for type references in public API */
+interface TypeReference2 {
+	typeName: string;
+	exportName: string;
+	location: "return" | "parameter" | "property" | "extends" | "type-parameter";
+	path?: string;
+}
+/** Structured data for forgotten exports */
+interface ForgottenExport {
+	name: string;
+	definedIn?: string;
+	referencedBy: TypeReference2[];
+	isExternal: boolean;
+	fix?: string;
+}
+/** Tracks status of each discovered through serialization pipeline */
+interface ExportTracker {
+	name: string;
+	discovered: boolean;
+	status: "pending" | "success" | "skipped" | "failed";
+	skipReason?: "filtered" | "no-declaration" | "internal" | "external-unresolved";
+	/** Package name for external-unresolved skips */
+	externalPackage?: string;
+	error?: string;
+	kind?: string;
+}
+/** Detail for a skipped */
+interface SkippedExportDetail {
+	name: string;
+	reason: "filtered" | "no-declaration" | "internal" | "external-unresolved";
+	/** Package name when reason is external-unresolved */
+	package?: string;
+}
+/** Verification result comparing discovered vs extracted exports */
+interface ExportVerification {
+	/** Total exports discovered by TypeScript */
+	discovered: number;
+	/** Exports successfully extracted */
+	extracted: number;
+	/** Exports skipped (filtered, no-declaration, internal, external-unresolved) */
+	skipped: number;
+	/** Exports that failed during serialization */
+	failed: number;
+	/** Delta: discovered - extracted */
+	delta: number;
+	details: {
+		skipped: SkippedExportDetail[];
+		failed: Array<{
+			name: string;
+			error: string;
+		}>;
+	};
+}
+/** openpkg configuration from config file or package.json */
+interface OpenpkgConfig {
+	/** Configuration for resolving external package re-exports */
+	externals?: ExternalsConfig;
+}
+/** Default config filename */
+declare const CONFIG_FILENAME = "openpkg.config.json";
+/**
+* Load openpkg configuration from the project directory
+*
+* Looks for config in order of precedence:
+* 1. openpkg.config.json
+* 2. package.json "openpkg" field
+*
+* @param cwd - Directory to search for config
+* @returns Loaded config or null if not found
+*/
+declare function loadConfig(cwd: string): OpenpkgConfig | null;
+/**
+* Merge file config with CLI options (CLI takes precedence)
+*
+* @param fileConfig - Config loaded from file (or null)
+* @param cliOptions - Options provided via CLI flags
+* @returns Merged config
+*/
+declare function mergeConfig(fileConfig: OpenpkgConfig | null, cliOptions: Partial<OpenpkgConfig>): OpenpkgConfig;
+import { OpenPkg as OpenPkg2, SpecExport } from "@openpkg-ts/spec";
 interface DiagnosticItem {
 	exportId: string;
 	exportName: string;
@@ -33,7 +187,7 @@ declare function findMissingParamDocs(exp: SpecExport): string[];
 /**
 * Analyze a spec for quality issues.
 */
-declare function analyzeSpec(spec: OpenPkg): SpecDiagnostics;
+declare function analyzeSpec(spec: OpenPkg2): SpecDiagnostics;
 import { SpecMember } from "@openpkg-ts/spec";
 /**
 * Extract badge strings from a member's visibility and flags.
@@ -44,8 +198,8 @@ declare function getMemberBadges(member: SpecMember): string[];
 * Format badges array into a display string (space-separated).
 */
 declare function formatBadges(badges: string[]): string;
-import { OpenPkg as OpenPkg7, SpecExport as SpecExport3, SpecExportKind as SpecExportKind4, SpecType } from "@openpkg-ts/spec";
-import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg8, SpecExport as SpecExport3, SpecExportKind as SpecExportKind4, SpecType } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
 interface HTMLOptions {
 	/** Page title override */
 	title?: string;
@@ -83,8 +237,8 @@ interface HTMLOptions {
 * const fragment = docs.toHTML({ export: 'greet', fullDocument: false })
 * ```
 */
-declare function toHTML2(spec: OpenPkg2, options?: HTMLOptions): string;
-import { OpenPkg as OpenPkg3, SpecExportKind } from "@openpkg-ts/spec";
+declare function toHTML2(spec: OpenPkg3, options?: HTMLOptions): string;
+import { OpenPkg as OpenPkg4, SpecExportKind } from "@openpkg-ts/spec";
 interface JSONOptions {
 	/** Include raw spec data alongside simplified data */
 	includeRaw?: boolean;
@@ -178,7 +332,7 @@ interface SimplifiedSpec {
 * // { id, name, kind, signature, parameters, returns, ... }
 * ```
 */
-declare function toJSON2(spec: OpenPkg3, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+declare function toJSON2(spec: OpenPkg4, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
 /**
 * Serialize to JSON string with formatting.
 *
@@ -186,10 +340,10 @@ declare function toJSON2(spec: OpenPkg3, options?: JSONOptions): SimplifiedSpec
 * @param options - JSON options plus pretty formatting option
 * @returns JSON string
 */
-declare function toJSONString(spec: OpenPkg3, options?: JSONOptions & {
+declare function toJSONString(spec: OpenPkg4, options?: JSONOptions & {
 	pretty?: boolean;
 }): string;
-import { OpenPkg as OpenPkg4, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg5, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
 interface MarkdownOptions {
 	/** Include frontmatter in output */
 	frontmatter?: boolean;
@@ -255,8 +409,8 @@ declare function exportToMarkdown(exp: SpecExport2, options?: MarkdownOptions):
 * // Single * const fnMdx = docs.toMarkdown({ export: 'greet' })
 * ```
 */
-declare function toMarkdown2(spec: OpenPkg4, options?: ExportMarkdownOptions): string;
-import { OpenPkg as OpenPkg5, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
+declare function toMarkdown2(spec: OpenPkg5, options?: ExportMarkdownOptions): string;
+import { OpenPkg as OpenPkg6, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
 type NavFormat = "fumadocs" | "docusaurus" | "generic";
 type GroupBy = "kind" | "module" | "tag" | "none";
 interface NavOptions {
@@ -331,7 +485,7 @@ type DocusaurusSidebar = DocusaurusSidebarItem[];
 * const sidebar = docs.toNavigation({ format: 'docusaurus' })
 * ```
 */
-declare function toNavigation2(spec: OpenPkg5, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+declare function toNavigation2(spec: OpenPkg6, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
 /**
 * Generate Fumadocs meta.json file content.
 *
@@ -345,7 +499,7 @@ declare function toNavigation2(spec: OpenPkg5, options?: NavOptions): GenericNav
 * fs.writeFileSync('docs/api/meta.json', meta)
 * ```
 */
-declare function toFumadocsMetaJSON(spec: OpenPkg5, options?: Omit<NavOptions, "format">): string;
+declare function toFumadocsMetaJSON(spec: OpenPkg6, options?: Omit<NavOptions, "format">): string;
 /**
 * Generate Docusaurus sidebar config.
 *
@@ -359,8 +513,8 @@ declare function toFumadocsMetaJSON(spec: OpenPkg5, options?: Omit<NavOptions, "
 * fs.writeFileSync('sidebars.js', sidebar)
 * ```
 */
-declare function toDocusaurusSidebarJS(spec: OpenPkg5, options?: Omit<NavOptions, "format">): string;
-import { OpenPkg as OpenPkg6, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
+declare function toDocusaurusSidebarJS(spec: OpenPkg6, options?: Omit<NavOptions, "format">): string;
+import { OpenPkg as OpenPkg7, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
 interface SearchOptions {
 	/** Base URL for search result links */
 	baseUrl?: string;
@@ -453,7 +607,7 @@ interface SearchIndex {
 * // { records: [...], version: '1.0.0', packageName: 'my-lib' }
 * ```
 */
-declare function toSearchIndex2(spec: OpenPkg6, options?: SearchOptions): SearchIndex;
+declare function toSearchIndex2(spec: OpenPkg7, options?: SearchOptions): SearchIndex;
 /**
 * Generate Pagefind-compatible records.
 *
@@ -469,7 +623,7 @@ declare function toSearchIndex2(spec: OpenPkg6, options?: SearchOptions): Search
 * })
 * ```
 */
-declare function toPagefindRecords2(spec: OpenPkg6, options?: SearchOptions): PagefindRecord[];
+declare function toPagefindRecords2(spec: OpenPkg7, options?: SearchOptions): PagefindRecord[];
 /**
 * Generate Algolia-compatible records.
 *
@@ -483,7 +637,7 @@ declare function toPagefindRecords2(spec: OpenPkg6, options?: SearchOptions): Pa
 * // Upload to Algolia index
 * ```
 */
-declare function toAlgoliaRecords2(spec: OpenPkg6, options?: SearchOptions): AlgoliaRecord[];
+declare function toAlgoliaRecords2(spec: OpenPkg7, options?: SearchOptions): AlgoliaRecord[];
 /**
 * Serialize search index to JSON string.
 *
@@ -497,16 +651,16 @@ declare function toAlgoliaRecords2(spec: OpenPkg6, options?: SearchOptions): Alg
 * fs.writeFileSync('search-index.json', json)
 * ```
 */
-declare function toSearchIndexJSON(spec: OpenPkg6, options?: SearchOptions & {
+declare function toSearchIndexJSON(spec: OpenPkg7, options?: SearchOptions & {
 	pretty?: boolean;
 }): string;
 interface LoadOptions {
 	/** Path to openpkg.json file or the spec object directly */
-	input: string | OpenPkg7;
+	input: string | OpenPkg8;
 }
 interface DocsInstance {
 	/** The parsed OpenPkg spec */
-	spec: OpenPkg7;
+	spec: OpenPkg8;
 	/** Get an by its ID */
 	getExport(id: string): SpecExport3 | undefined;
 	/** Get a type definition by its ID */
@@ -554,7 +708,7 @@ interface DocsInstance {
 * const docs = loadSpec(spec)
 * ```
 */
-declare function loadSpec(spec: OpenPkg7): DocsInstance;
+declare function loadSpec(spec: OpenPkg8): DocsInstance;
 /**
 * Creates a docs instance for querying and rendering API documentation.
 *
@@ -576,8 +730,8 @@ declare function loadSpec(spec: OpenPkg7): DocsInstance;
 * docs.search('hook')
 * ```
 */
-declare function createDocs(input: string | OpenPkg7): DocsInstance;
-import { OpenPkg as OpenPkg8, SpecExport as SpecExport4, SpecMember as SpecMember2, SpecSchema, SpecSignature, SpecType as SpecType2, SpecTypeParameter } from "@openpkg-ts/spec";
+declare function createDocs(input: string | OpenPkg8): DocsInstance;
+import { OpenPkg as OpenPkg9, SpecExport as SpecExport4, SpecMember as SpecMember2, SpecSchema, SpecSignature, SpecType as SpecType2, SpecTypeParameter } from "@openpkg-ts/spec";
 interface FormatSchemaOptions {
 	/** Include package attribution for external types */
 	includePackage?: boolean;
@@ -672,7 +826,7 @@ declare function buildSignatureString(exp: SpecExport4, sigIndex?: number): stri
 * // { id: 'User', name: 'User', kind: 'interface', ... }
 * ```
 */
-declare function resolveTypeRef(ref: string, spec: OpenPkg8): SpecType2 | undefined;
+declare function resolveTypeRef(ref: string, spec: OpenPkg9): SpecType2 | undefined;
 /**
 * Check if a member is a method (has signatures).
 *
@@ -787,7 +941,7 @@ declare function formatConditionalType(condType: SpecConditionalType): string;
 * ```
 */
 declare function formatMappedType(mappedType: SpecMappedType): string;
-import { OpenPkg as OpenPkg9, SpecExportKind as SpecExportKind5 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg10, SpecExportKind as SpecExportKind5 } from "@openpkg-ts/spec";
 type FilterCriteria = {
 	/** Filter by kinds */
 	kinds?: SpecExportKind5[];
@@ -812,7 +966,7 @@ type FilterCriteria = {
 };
 type FilterResult = {
 	/** New spec with only matched exports (immutable) */
-	spec: OpenPkg9;
+	spec: OpenPkg10;
 	/** Number of exports that matched */
 	matched: number;
 	/** Total number of exports in original spec */
@@ -828,7 +982,7 @@ type FilterResult = {
 * @param criteria - Filter criteria (empty criteria matches all)
 * @returns FilterResult with new spec, matched count, total count
 */
-declare function filterSpec(spec: OpenPkg9, criteria: FilterCriteria): FilterResult;
+declare function filterSpec(spec: OpenPkg10, criteria: FilterCriteria): FilterResult;
 import { SpecExport as SpecExport5, SpecType as SpecType3 } from "@openpkg-ts/spec";
 interface GetExportOptions {
 	/** Entry point file path */
@@ -885,117 +1039,6 @@ interface ListExportsResult {
 * List all exports from a TypeScript entry point
 */
 declare function listExports(options: ListExportsOptions): Promise<ListExportsResult>;
-import { OpenPkg as OpenPkg10 } from "@openpkg-ts/spec";
-interface ExtractOptions {
-	entryFile: string;
-	baseDir?: string;
-	content?: string;
-	maxTypeDepth?: number;
-	maxExternalTypeDepth?: number;
-	resolveExternalTypes?: boolean;
-	schemaExtraction?: "static" | "hybrid";
-	/** Target JSON Schema dialect for runtime schema extraction */
-	schemaTarget?: "draft-2020-12" | "draft-07" | "openapi-3.0";
-	/** Include $schema URL in output */
-	includeSchema?: boolean;
-	/** Only extract these exports (supports * wildcards) */
-	only?: string[];
-	/** Ignore these exports (supports * wildcards) */
-	ignore?: string[];
-	/** Progress callback for tracking extraction progress */
-	onProgress?: (current: number, total: number, item: string) => void;
-	/** Whether source is a .d.ts file (degraded mode - TSDoc may be missing) */
-	isDtsSource?: boolean;
-	/** Include private/protected class members (default: false) */
-	includePrivate?: boolean;
-}
-interface ExtractResult {
-	spec: OpenPkg10;
-	diagnostics: Diagnostic[];
-	forgottenExports?: ForgottenExport[];
-	/** Metadata about runtime schema extraction (when schemaExtraction: 'hybrid') */
-	runtimeSchemas?: {
-		/** Number of schema exports found */
-		extracted: number;
-		/** Number of schemas successfully merged with static types */
-		merged: number;
-		/** Schema vendors detected (e.g., 'zod', 'arktype', 'valibot', 'typebox') */
-		vendors: string[];
-		/** Any errors encountered during runtime extraction */
-		errors: string[];
-		/** Extraction method used: 'compiled' or 'direct-ts (runtime)' */
-		method?: string;
-	};
-	/** Degraded mode info when extracting from .d.ts files */
-	degradedMode?: {
-		reason: "dts-source";
-		stats: {
-			exportsWithoutDescription: number;
-			paramsWithoutDocs: number;
-			missingExamples: number;
-		};
-	};
-	/** Export verification comparing discovered vs extracted */
-	verification?: ExportVerification;
-}
-interface Diagnostic {
-	message: string;
-	severity: "error" | "warning" | "info";
-	code?: string;
-	suggestion?: string;
-	location?: {
-		file?: string;
-		line?: number;
-		column?: number;
-	};
-}
-/** Context tracking for type references in public API */
-interface TypeReference2 {
-	typeName: string;
-	exportName: string;
-	location: "return" | "parameter" | "property" | "extends" | "type-parameter";
-	path?: string;
-}
-/** Structured data for forgotten exports */
-interface ForgottenExport {
-	name: string;
-	definedIn?: string;
-	referencedBy: TypeReference2[];
-	isExternal: boolean;
-	fix?: string;
-}
-/** Tracks status of each discovered through serialization pipeline */
-interface ExportTracker {
-	name: string;
-	discovered: boolean;
-	status: "pending" | "success" | "skipped" | "failed";
-	skipReason?: "filtered" | "no-declaration" | "internal";
-	error?: string;
-	kind?: string;
-}
-/** Verification result comparing discovered vs extracted exports */
-interface ExportVerification {
-	/** Total exports discovered by TypeScript */
-	discovered: number;
-	/** Exports successfully extracted */
-	extracted: number;
-	/** Exports skipped (filtered, no-declaration, internal) */
-	skipped: number;
-	/** Exports that failed during serialization */
-	failed: number;
-	/** Delta: discovered - extracted */
-	delta: number;
-	details: {
-		skipped: Array<{
-			name: string;
-			reason: "filtered" | "no-declaration" | "internal";
-		}>;
-		failed: Array<{
-			name: string;
-			error: string;
-		}>;
-	};
-}
 /**
 * Extract full OpenPkg spec from a TypeScript entry point
 *
@@ -1481,4 +1524,4 @@ declare function normalizeMembers(members: SpecMember3[], options?: NormalizeOpt
 import ts14 from "typescript";
 declare function isExported(node: ts14.Node): boolean;
 declare function getNodeName(node: ts14.Node): string | undefined;
-export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, loadSpec, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExport2 as getExport, getDeprecationMessage, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecDiagnostics, SpecConditionalType, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, FilterResult, FilterCriteria, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, DiagnosticItem, Diagnostic, CategorizedBreaking, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };
+export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExport2 as getExport, getDeprecationMessage, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, OpenpkgConfig, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, FilterResult, FilterCriteria, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExternalsConfig, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, DiagnosticItem, Diagnostic, CategorizedBreaking, CONFIG_FILENAME, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };

package/dist/index.js

@@ -6,6 +6,42 @@ import {
   diffSpec as diffSpec2,
   recommendSemverBump
 } from "@openpkg-ts/spec";
+// src/core/config.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+var CONFIG_FILENAME = "openpkg.config.json";
+function loadConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILENAME);
+  if (fs.existsSync(configPath)) {
+    try {
+      const content = fs.readFileSync(configPath, "utf-8");
+      return JSON.parse(content);
+    } catch {}
+  }
+  const pkgPath = path.join(cwd, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const content = fs.readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(content);
+      if (pkg.openpkg) {
+        return pkg.openpkg;
+      }
+    } catch {}
+  }
+  return null;
+}
+function mergeConfig(fileConfig, cliOptions) {
+  if (!fileConfig) {
+    return cliOptions;
+  }
+  return {
+    externals: {
+      include: cliOptions.externals?.include ?? fileConfig.externals?.include,
+      exclude: cliOptions.externals?.exclude ?? fileConfig.externals?.exclude,
+      depth: cliOptions.externals?.depth ?? fileConfig.externals?.depth
+    }
+  };
+}
 // src/core/diagnostics.ts
 function hasDeprecatedTag(exp) {
   if (exp.deprecated === true)
@@ -104,7 +140,7 @@ function formatBadges(badges) {
   return badges.join(" ");
 }
 // src/core/loader.ts
-import * as fs from "node:fs";
+import * as fs2 from "node:fs";
 
 // src/core/query.ts
 function formatFunctionSchema(schema) {
@@ -1502,7 +1538,7 @@ function loadSpec(spec) {
   return createDocsInstance(spec);
 }
 function createDocs(input) {
-  const spec = typeof input === "string" ? JSON.parse(fs.readFileSync(input, "utf-8")) : input;
+  const spec = typeof input === "string" ? JSON.parse(fs2.readFileSync(input, "utf-8")) : input;
   return createDocsInstance(spec);
 }
 function createDocsInstance(spec) {
@@ -1725,8 +1761,8 @@ function filterSpec(spec, criteria) {
 import ts11 from "typescript";
 
 // src/compiler/program.ts
-import * as fs2 from "node:fs";
-import * as path from "node:path";
+import * as fs3 from "node:fs";
+import * as path2 from "node:path";
 import ts from "typescript";
 function isJsFile(file) {
   return /\.(js|mjs|cjs|jsx)$/.test(file);
@@ -1752,16 +1788,16 @@ function resolveProjectReferences(configPath, parsedConfig) {
   if (!parsedConfig.projectReferences?.length) {
     return additionalFiles;
   }
-  const configDir = path.dirname(configPath);
+  const configDir = path2.dirname(configPath);
   for (const ref of parsedConfig.projectReferences) {
-    const refPath = path.resolve(configDir, ref.path);
-    const refConfigPath = fs2.existsSync(path.join(refPath, "tsconfig.json")) ? path.join(refPath, "tsconfig.json") : refPath;
-    if (!fs2.existsSync(refConfigPath))
+    const refPath = path2.resolve(configDir, ref.path);
+    const refConfigPath = fs3.existsSync(path2.join(refPath, "tsconfig.json")) ? path2.join(refPath, "tsconfig.json") : refPath;
+    if (!fs3.existsSync(refConfigPath))
       continue;
     const refConfigFile = ts.readConfigFile(refConfigPath, ts.sys.readFile);
     if (refConfigFile.error)
       continue;
-    const refParsed = ts.parseJsonConfigFileContent(refConfigFile.config, ts.sys, path.dirname(refConfigPath));
+    const refParsed = ts.parseJsonConfigFileContent(refConfigFile.config, ts.sys, path2.dirname(refConfigPath));
     additionalFiles.push(...refParsed.fileNames);
   }
   return additionalFiles;
@@ -1794,10 +1830,10 @@ function buildWorkspaceMap(baseDir) {
   let rootDir;
   let workspaceGlobs = [];
   for (let i = 0;i < 10; i++) {
-    const pnpmPath = path.join(currentDir, "pnpm-workspace.yaml");
-    if (fs2.existsSync(pnpmPath)) {
+    const pnpmPath = path2.join(currentDir, "pnpm-workspace.yaml");
+    if (fs3.existsSync(pnpmPath)) {
       try {
-        const yamlContent = fs2.readFileSync(pnpmPath, "utf-8");
+        const yamlContent = fs3.readFileSync(pnpmPath, "utf-8");
         workspaceGlobs = parsePnpmWorkspace(yamlContent);
         if (workspaceGlobs.length > 0) {
           rootDir = currentDir;
@@ -1805,10 +1841,10 @@ function buildWorkspaceMap(baseDir) {
         }
       } catch {}
     }
-    const pkgPath = path.join(currentDir, "package.json");
-    if (fs2.existsSync(pkgPath)) {
+    const pkgPath = path2.join(currentDir, "package.json");
+    if (fs3.existsSync(pkgPath)) {
       try {
-        const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+        const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
         if (pkg.workspaces) {
           rootDir = currentDir;
           workspaceGlobs = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages || [];
@@ -1816,7 +1852,7 @@ function buildWorkspaceMap(baseDir) {
         }
       } catch {}
     }
-    const parent = path.dirname(currentDir);
+    const parent = path2.dirname(currentDir);
     if (parent === currentDir)
       break;
     currentDir = parent;
@@ -1825,21 +1861,21 @@ function buildWorkspaceMap(baseDir) {
     return;
   const packages = new Map;
   for (const glob of workspaceGlobs) {
-    const globDir = path.join(rootDir, glob.replace(/\/\*$/, ""));
-    if (!fs2.existsSync(globDir) || !fs2.statSync(globDir).isDirectory())
+    const globDir = path2.join(rootDir, glob.replace(/\/\*$/, ""));
+    if (!fs3.existsSync(globDir) || !fs3.statSync(globDir).isDirectory())
       continue;
-    const entries = fs2.readdirSync(globDir, { withFileTypes: true });
+    const entries = fs3.readdirSync(globDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
-      const pkgDir = path.join(globDir, entry.name);
-      const pkgJsonPath = path.join(pkgDir, "package.json");
-      if (!fs2.existsSync(pkgJsonPath))
+      const pkgDir = path2.join(globDir, entry.name);
+      const pkgJsonPath = path2.join(pkgDir, "package.json");
+      if (!fs3.existsSync(pkgJsonPath))
         continue;
       try {
-        const pkg = JSON.parse(fs2.readFileSync(pkgJsonPath, "utf-8"));
+        const pkg = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
         if (pkg.name) {
-          const srcDir = fs2.existsSync(path.join(pkgDir, "src")) ? path.join(pkgDir, "src") : pkgDir;
+          const srcDir = fs3.existsSync(path2.join(pkgDir, "src")) ? path2.join(pkgDir, "src") : pkgDir;
           packages.set(pkg.name, srcDir);
         }
       } catch {}
@@ -1849,7 +1885,7 @@ function buildWorkspaceMap(baseDir) {
 }
 function createProgram({
   entryFile,
-  baseDir = path.dirname(entryFile),
+  baseDir = path2.dirname(entryFile),
   content
 }) {
   let configPath = ts.findConfigFile(baseDir, ts.sys.fileExists, "tsconfig.json");
@@ -1860,7 +1896,7 @@ function createProgram({
   let additionalRootFiles = [];
   if (configPath) {
     const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
-    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath));
+    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path2.dirname(configPath));
     compilerOptions = { ...compilerOptions, ...parsedConfig.options };
     additionalRootFiles = resolveProjectReferences(configPath, parsedConfig);
   }
@@ -1886,8 +1922,8 @@ function createProgram({
       return moduleNames.map((moduleName) => {
         const srcDir = workspaceMap.packages.get(moduleName);
         if (srcDir) {
-          const indexFile = path.join(srcDir, "index.ts");
-          if (fs2.existsSync(indexFile)) {
+          const indexFile = path2.join(srcDir, "index.ts");
+          if (fs3.existsSync(indexFile)) {
             return { resolvedFileName: indexFile, isExternalLibraryImport: false };
           }
         }
@@ -4779,7 +4815,7 @@ function serializeDeclaration(declaration, _exportSymbol, _targetSymbol, exportN
   return result;
 }
 // src/primitives/list.ts
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 import ts12 from "typescript";
 async function listExports(options) {
   const { entryFile, baseDir, content } = options;
@@ -4827,7 +4863,7 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
     return {
       name,
       kind: "namespace",
-      file: path2.relative(path2.dirname(entryFile), declaration.fileName),
+      file: path3.relative(path3.dirname(entryFile), declaration.fileName),
       line: 1,
       reexport: true
     };
@@ -4841,7 +4877,7 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
   return {
     name,
     kind,
-    file: path2.relative(path2.dirname(entryFile), sourceFile.fileName),
+    file: path3.relative(path3.dirname(entryFile), sourceFile.fileName),
     line: line + 1,
     ...description ? { description } : {},
     ...deprecated ? { deprecated: true } : {},
@@ -4893,10 +4929,10 @@ function getDescriptionPreview(symbol, checker) {
   return `${firstLine.slice(0, 77)}...`;
 }
 // src/builder/spec-builder.ts
-import * as fs4 from "node:fs";
-import * as path4 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
-import ts14 from "typescript";
+import ts15 from "typescript";
 
 // src/ast/resolve.ts
 import ts13 from "typescript";
@@ -4930,9 +4966,9 @@ function resolveExportTarget2(symbol, checker) {
 
 // src/schema/standard-schema.ts
 import { spawn, spawnSync } from "node:child_process";
-import * as fs3 from "node:fs";
+import * as fs4 from "node:fs";
 import * as os from "node:os";
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 function isStandardJSONSchema(obj) {
   if (typeof obj !== "object" || obj === null)
     return false;
@@ -5178,21 +5214,21 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
     result.errors.push("No TypeScript runtime available. Install bun, tsx, or ts-node, or use Node 22+.");
     return result;
   }
-  if (!fs3.existsSync(tsFilePath)) {
+  if (!fs4.existsSync(tsFilePath)) {
     result.errors.push(`TypeScript file not found: ${tsFilePath}`);
     return result;
   }
   const tempDir = os.tmpdir();
-  const workerPath = path3.join(tempDir, `openpkg-extract-worker-${Date.now()}.ts`);
+  const workerPath = path4.join(tempDir, `openpkg-extract-worker-${Date.now()}.ts`);
   try {
-    fs3.writeFileSync(workerPath, TS_WORKER_SCRIPT);
+    fs4.writeFileSync(workerPath, TS_WORKER_SCRIPT);
     const optionsJson = JSON.stringify({ target, libraryOptions });
     const args = [...runtime.args, workerPath, tsFilePath, optionsJson];
     return await new Promise((resolve2) => {
       const child = spawn(runtime.cmd, args, {
         timeout,
         stdio: ["ignore", "pipe", "pipe"],
-        cwd: path3.dirname(tsFilePath)
+        cwd: path4.dirname(tsFilePath)
       });
       let stdout = "";
       let stderr = "";
@@ -5204,7 +5240,7 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
       });
       child.on("close", (code) => {
         try {
-          fs3.unlinkSync(workerPath);
+          fs4.unlinkSync(workerPath);
         } catch {}
         if (code !== 0) {
           result.errors.push(`Extraction failed (${runtime.name}): ${stderr || `exit code ${code}`}`);
@@ -5233,7 +5269,7 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
       });
       child.on("error", (err) => {
         try {
-          fs3.unlinkSync(workerPath);
+          fs4.unlinkSync(workerPath);
         } catch {}
         result.errors.push(`Subprocess error: ${err.message}`);
         resolve2(result);
@@ -5241,19 +5277,19 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
     });
   } catch (e) {
     try {
-      fs3.unlinkSync(workerPath);
+      fs4.unlinkSync(workerPath);
     } catch {}
     result.errors.push(`Failed to create worker script: ${e}`);
     return result;
   }
 }
 function readTsconfigOutDir(baseDir) {
-  const tsconfigPath = path3.join(baseDir, "tsconfig.json");
+  const tsconfigPath = path4.join(baseDir, "tsconfig.json");
   try {
-    if (!fs3.existsSync(tsconfigPath)) {
+    if (!fs4.existsSync(tsconfigPath)) {
       return null;
     }
-    const content = fs3.readFileSync(tsconfigPath, "utf-8");
+    const content = fs4.readFileSync(tsconfigPath, "utf-8");
     const stripped = content.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
     const tsconfig = JSON.parse(stripped);
     if (tsconfig.compilerOptions?.outDir) {
@@ -5263,7 +5299,7 @@ function readTsconfigOutDir(baseDir) {
   return null;
 }
 function resolveCompiledPath(tsPath, baseDir) {
-  const relativePath = path3.relative(baseDir, tsPath);
+  const relativePath = path4.relative(baseDir, tsPath);
   const withoutExt = relativePath.replace(/\.tsx?$/, "");
   const srcPrefix = withoutExt.replace(/^src\//, "");
   const tsconfigOutDir = readTsconfigOutDir(baseDir);
@@ -5271,7 +5307,7 @@ function resolveCompiledPath(tsPath, baseDir) {
   const candidates = [];
   if (tsconfigOutDir) {
     for (const ext of extensions) {
-      candidates.push(path3.join(baseDir, tsconfigOutDir, `${srcPrefix}${ext}`));
+      candidates.push(path4.join(baseDir, tsconfigOutDir, `${srcPrefix}${ext}`));
     }
   }
   const commonOutDirs = ["dist", "build", "lib", "out"];
@@ -5279,21 +5315,21 @@ function resolveCompiledPath(tsPath, baseDir) {
     if (outDir === tsconfigOutDir)
       continue;
     for (const ext of extensions) {
-      candidates.push(path3.join(baseDir, outDir, `${srcPrefix}${ext}`));
+      candidates.push(path4.join(baseDir, outDir, `${srcPrefix}${ext}`));
     }
   }
   for (const ext of extensions) {
-    candidates.push(path3.join(baseDir, `${withoutExt}${ext}`));
+    candidates.push(path4.join(baseDir, `${withoutExt}${ext}`));
   }
   const workspaceMatch = baseDir.match(/^(.+\/packages\/[^/]+)$/);
   if (workspaceMatch) {
     const pkgRoot = workspaceMatch[1];
     for (const ext of extensions) {
-      candidates.push(path3.join(pkgRoot, "dist", `${srcPrefix}${ext}`));
+      candidates.push(path4.join(pkgRoot, "dist", `${srcPrefix}${ext}`));
     }
   }
   for (const candidate of candidates) {
-    if (fs3.existsSync(candidate)) {
+    if (fs4.existsSync(candidate)) {
       return candidate;
     }
   }
@@ -5305,7 +5341,7 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
     schemas: new Map,
     errors: []
   };
-  if (!fs3.existsSync(compiledJsPath)) {
+  if (!fs4.existsSync(compiledJsPath)) {
     result.errors.push(`Compiled JS not found: ${compiledJsPath}`);
     return result;
   }
@@ -5386,6 +5422,173 @@ async function extractStandardSchemasFromProject(entryFile, baseDir, options = {
   };
 }
 
+// src/builder/external-resolver.ts
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
+import picomatch from "picomatch";
+import ts14 from "typescript";
+function matchesExternalPattern(packageName, include, exclude) {
+  if (!include?.length)
+    return false;
+  const matchOptions = { bash: true };
+  const isIncluded = include.some((p) => picomatch.isMatch(packageName, p, matchOptions));
+  if (!isIncluded)
+    return false;
+  if (exclude?.length) {
+    const isExcluded = exclude.some((p) => picomatch.isMatch(packageName, p, matchOptions));
+    if (isExcluded)
+      return false;
+  }
+  return true;
+}
+function resolveExternalModule(moduleSpecifier, containingFile, compilerOptions) {
+  const resolved = ts14.resolveModuleName(moduleSpecifier, containingFile, compilerOptions, ts14.sys);
+  if (!resolved.resolvedModule) {
+    return null;
+  }
+  const resolvedPath = resolved.resolvedModule.resolvedFileName;
+  const packageJson = findPackageJson(resolvedPath, moduleSpecifier);
+  return {
+    resolvedPath,
+    packageName: moduleSpecifier,
+    packageVersion: packageJson?.version
+  };
+}
+function findPackageJson(resolvedPath, packageName) {
+  const isScoped = packageName.startsWith("@");
+  const packageParts = isScoped ? packageName.split("/").slice(0, 2) : [packageName.split("/")[0]];
+  const packageDir = packageParts.join("/");
+  let dir = path5.dirname(resolvedPath);
+  const maxDepth = 10;
+  for (let i = 0;i < maxDepth; i++) {
+    if (dir.endsWith(`node_modules/${packageDir}`)) {
+      const pkgPath = path5.join(dir, "package.json");
+      if (fs5.existsSync(pkgPath)) {
+        try {
+          return JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+        } catch {
+          return;
+        }
+      }
+    }
+    const parent = path5.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return;
+}
+function determineExportKind(symbol, checker) {
+  const declarations = symbol.declarations ?? [];
+  const decl = declarations[0];
+  if (!decl)
+    return "variable";
+  if (ts14.isFunctionDeclaration(decl) || ts14.isFunctionExpression(decl))
+    return "function";
+  if (ts14.isClassDeclaration(decl))
+    return "class";
+  if (ts14.isInterfaceDeclaration(decl))
+    return "interface";
+  if (ts14.isTypeAliasDeclaration(decl))
+    return "type";
+  if (ts14.isEnumDeclaration(decl))
+    return "enum";
+  if (ts14.isModuleDeclaration(decl))
+    return "namespace";
+  if (ts14.isVariableDeclaration(decl)) {
+    const type = checker.getTypeAtLocation(decl);
+    if (type.getCallSignatures().length > 0)
+      return "function";
+  }
+  return "variable";
+}
+function extractExternalExport(exportName, resolvedModule, program, ctx, visited) {
+  const key = `${resolvedModule.resolvedPath}:${exportName}`;
+  if (visited.has(key)) {
+    return {
+      id: exportName,
+      name: exportName,
+      kind: "external",
+      source: {
+        package: resolvedModule.packageName,
+        version: resolvedModule.packageVersion
+      }
+    };
+  }
+  visited.add(key);
+  const checker = program.getTypeChecker();
+  const sourceFile = program.getSourceFile(resolvedModule.resolvedPath);
+  if (!sourceFile) {
+    return null;
+  }
+  const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+  if (!moduleSymbol) {
+    return null;
+  }
+  const exports = checker.getExportsOfModule(moduleSymbol);
+  const targetExport = exports.find((e) => e.getName() === exportName);
+  if (!targetExport) {
+    return null;
+  }
+  let resolvedSymbol = targetExport;
+  if (targetExport.flags & ts14.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(targetExport);
+    if (aliased && aliased !== targetExport) {
+      resolvedSymbol = aliased;
+    }
+  }
+  const kind = determineExportKind(resolvedSymbol, checker);
+  const docComment = resolvedSymbol.getDocumentationComment(checker);
+  const description = docComment.length > 0 ? docComment.map((c) => c.text).join(`
+`) : undefined;
+  const specExport = {
+    id: exportName,
+    name: exportName,
+    kind,
+    ...description && { description },
+    source: {
+      package: resolvedModule.packageName,
+      version: resolvedModule.packageVersion,
+      file: resolvedModule.resolvedPath
+    }
+  };
+  if (kind === "function") {
+    const type = checker.getTypeOfSymbol(resolvedSymbol);
+    const callSignatures = type.getCallSignatures();
+    if (callSignatures.length > 0) {
+      const signatures = callSignatures.map((sig, index) => {
+        const params = extractParameters(sig, ctx);
+        const returnType = checker.getReturnTypeOfSignature(sig);
+        registerReferencedTypes(returnType, ctx);
+        const returnSchema = buildSchema(returnType, checker, ctx);
+        const sigDoc = getJSDocForSignature(sig, checker);
+        const sigTypeParams = extractTypeParametersFromSignature(sig, checker);
+        return {
+          parameters: params,
+          returns: { schema: returnSchema },
+          ...sigDoc.description && { description: sigDoc.description },
+          ...sigDoc.tags.length > 0 && { tags: sigDoc.tags },
+          ...sigDoc.examples.length > 0 && { examples: sigDoc.examples },
+          ...sigTypeParams && { typeParameters: sigTypeParams },
+          ...callSignatures.length > 1 && { overloadIndex: index }
+        };
+      });
+      specExport.signatures = signatures;
+    }
+  } else if (kind === "interface" || kind === "type" || kind === "class") {
+    const type = checker.getTypeOfSymbol(resolvedSymbol);
+    registerReferencedTypes(type, ctx);
+    const schema = buildSchema(type, checker, ctx);
+    specExport.schema = schema;
+  } else if (kind === "variable") {
+    const type = checker.getTypeOfSymbol(resolvedSymbol);
+    registerReferencedTypes(type, ctx);
+    const schema = buildSchema(type, checker, ctx);
+    specExport.schema = schema;
+  }
+  return specExport;
+}
+
 // src/builder/schema-merger.ts
 function mergeRuntimeSchemas(staticExports, runtimeSchemas) {
   let merged = 0;
@@ -5647,9 +5850,9 @@ async function extract(options) {
               break;
             }
           }
-          if (ts14.isExportSpecifier(decl)) {
+          if (ts15.isExportSpecifier(decl)) {
             const exportDecl = decl.parent?.parent;
-            if (exportDecl && ts14.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
+            if (exportDecl && ts15.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
               const moduleText = exportDecl.moduleSpecifier.getText().slice(1, -1);
               if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
                 externalPackage = moduleText;
@@ -5659,6 +5862,20 @@ async function extract(options) {
           }
         }
         if (externalPackage) {
+          const shouldResolve = matchesExternalPattern(externalPackage, options.externals?.include, options.externals?.exclude);
+          if (shouldResolve) {
+            const resolvedModule = resolveExternalModule(externalPackage, sourceFile.fileName, program.getCompilerOptions());
+            if (resolvedModule) {
+              const visitedExternals = new Set;
+              const extractedExport = extractExternalExport(exportName, resolvedModule, program, ctx, visitedExternals);
+              if (extractedExport) {
+                exports.push(extractedExport);
+                tracker.status = "success";
+                tracker.kind = extractedExport.kind;
+                continue;
+              }
+            }
+          }
           const externalExport = {
             id: exportName,
             name: exportName,
@@ -5699,7 +5916,7 @@ async function extract(options) {
   const verification = buildVerificationSummary(exportedSymbols.length, exports.length, exportTracker);
   const meta = await getPackageMeta(entryFile, baseDir);
   const types = ctx.typeRegistry.getAll();
-  const projectBaseDir = baseDir ?? path4.dirname(entryFile);
+  const projectBaseDir = baseDir ?? path6.dirname(entryFile);
   const definedTypes = new Set(types.map((t) => t.id));
   const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds, projectBaseDir, definedTypes);
   for (const forgotten of forgottenExports) {
@@ -5732,7 +5949,7 @@ async function extract(options) {
   }
   let runtimeMetadata;
   if (options.schemaExtraction === "hybrid") {
-    const projectBaseDir2 = baseDir || path4.dirname(entryFile);
+    const projectBaseDir2 = baseDir || path6.dirname(entryFile);
     const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir2, {
       target: options.schemaTarget || "draft-2020-12",
       timeout: 15000
@@ -5772,6 +5989,9 @@ async function extract(options) {
       ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {},
       ...isDtsSource && {
         limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
+      },
+      ...verification.details.skipped.length > 0 && {
+        skipped: verification.details.skipped
       }
     }
   };
@@ -5845,11 +6065,11 @@ function findTypeDefinition(typeName, program, sourceFile) {
   }
   const checker = program.getTypeChecker();
   const findInNode = (node) => {
-    if ((ts14.isInterfaceDeclaration(node) || ts14.isTypeAliasDeclaration(node) || ts14.isClassDeclaration(node) || ts14.isEnumDeclaration(node)) && node.name?.text === typeName) {
+    if ((ts15.isInterfaceDeclaration(node) || ts15.isTypeAliasDeclaration(node) || ts15.isClassDeclaration(node) || ts15.isEnumDeclaration(node)) && node.name?.text === typeName) {
       const sf = node.getSourceFile();
       return sf.fileName;
     }
-    return ts14.forEachChild(node, findInNode);
+    return ts15.forEachChild(node, findInNode);
   };
   const entryResult = findInNode(sourceFile);
   if (entryResult) {
@@ -5865,7 +6085,7 @@ function findTypeDefinition(typeName, program, sourceFile) {
       }
     }
   }
-  const symbol = checker.resolveName(typeName, sourceFile, ts14.SymbolFlags.Type, false);
+  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
   if (symbol?.declarations?.[0]) {
     const result = symbol.declarations[0].getSourceFile().fileName;
     cache.set(typeName, result);
@@ -5879,8 +6099,8 @@ function isExternalType2(definedIn, baseDir) {
     return true;
   if (definedIn.includes("node_modules"))
     return true;
-  const normalizedDefined = path4.resolve(definedIn);
-  const normalizedBase = path4.resolve(baseDir);
+  const normalizedDefined = path6.resolve(definedIn);
+  const normalizedBase = path6.resolve(baseDir);
   return !normalizedDefined.startsWith(normalizedBase);
 }
 function hasInternalTag(typeName, program, sourceFile) {
@@ -5890,7 +6110,7 @@ function hasInternalTag(typeName, program, sourceFile) {
     return cached;
   }
   const checker = program.getTypeChecker();
-  const symbol = checker.resolveName(typeName, sourceFile, ts14.SymbolFlags.Type, false);
+  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
   if (!symbol) {
     cache.set(typeName, false);
     return false;
@@ -5942,27 +6162,27 @@ function collectForgottenExports(exports, types, program, sourceFile, exportedId
 }
 function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportName, ctx, isTypeOnly = false) {
   let result = null;
-  if (ts14.isFunctionDeclaration(declaration)) {
+  if (ts15.isFunctionDeclaration(declaration)) {
     result = serializeFunctionExport(declaration, ctx);
-  } else if (ts14.isClassDeclaration(declaration)) {
+  } else if (ts15.isClassDeclaration(declaration)) {
     result = serializeClass(declaration, ctx);
-  } else if (ts14.isInterfaceDeclaration(declaration)) {
+  } else if (ts15.isInterfaceDeclaration(declaration)) {
     result = serializeInterface(declaration, ctx);
-  } else if (ts14.isTypeAliasDeclaration(declaration)) {
+  } else if (ts15.isTypeAliasDeclaration(declaration)) {
     result = serializeTypeAlias(declaration, ctx);
-  } else if (ts14.isEnumDeclaration(declaration)) {
+  } else if (ts15.isEnumDeclaration(declaration)) {
     result = serializeEnum(declaration, ctx);
-  } else if (ts14.isVariableDeclaration(declaration)) {
+  } else if (ts15.isVariableDeclaration(declaration)) {
     const varStatement = declaration.parent?.parent;
-    if (varStatement && ts14.isVariableStatement(varStatement)) {
-      if (declaration.initializer && ts14.isArrowFunction(declaration.initializer)) {
-        const varName = ts14.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
+    if (varStatement && ts15.isVariableStatement(varStatement)) {
+      if (declaration.initializer && ts15.isArrowFunction(declaration.initializer)) {
+        const varName = ts15.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
         result = serializeFunctionExport(declaration.initializer, ctx, varName);
       } else {
         result = serializeVariable(declaration, varStatement, ctx);
       }
     }
-  } else if (ts14.isNamespaceExport(declaration) || ts14.isModuleDeclaration(declaration)) {
+  } else if (ts15.isNamespaceExport(declaration) || ts15.isModuleDeclaration(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -5975,7 +6195,7 @@ function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportN
         examples: []
       };
     }
-  } else if (ts14.isNamespaceImport(declaration)) {
+  } else if (ts15.isNamespaceImport(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -5988,7 +6208,7 @@ function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportN
         examples: []
       };
     }
-  } else if (ts14.isSourceFile(declaration)) {
+  } else if (ts15.isSourceFile(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -6018,7 +6238,7 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
   const members = [];
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
-  if (symbol.flags & ts14.SymbolFlags.Alias) {
+  if (symbol.flags & ts15.SymbolFlags.Alias) {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased !== symbol) {
       targetSymbol = aliased;
@@ -6045,31 +6265,31 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
 function serializeNamespaceMember(symbol, memberName, ctx) {
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
-  if (symbol.flags & ts14.SymbolFlags.Alias) {
+  if (symbol.flags & ts15.SymbolFlags.Alias) {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased !== symbol) {
       targetSymbol = aliased;
     }
   }
   const declarations = targetSymbol.declarations ?? [];
-  const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts14.SyntaxKind.ExportSpecifier) || declarations[0];
+  const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts15.SyntaxKind.ExportSpecifier) || declarations[0];
   if (!declaration)
     return null;
   const type = checker.getTypeAtLocation(declaration);
   const callSignatures = type.getCallSignatures();
   const deprecated = isSymbolDeprecated(targetSymbol);
   let kind = "variable";
-  if (ts14.isFunctionDeclaration(declaration) || ts14.isFunctionExpression(declaration)) {
+  if (ts15.isFunctionDeclaration(declaration) || ts15.isFunctionExpression(declaration)) {
     kind = "function";
-  } else if (ts14.isClassDeclaration(declaration)) {
+  } else if (ts15.isClassDeclaration(declaration)) {
     kind = "class";
-  } else if (ts14.isInterfaceDeclaration(declaration)) {
+  } else if (ts15.isInterfaceDeclaration(declaration)) {
     kind = "interface";
-  } else if (ts14.isTypeAliasDeclaration(declaration)) {
+  } else if (ts15.isTypeAliasDeclaration(declaration)) {
     kind = "type";
-  } else if (ts14.isEnumDeclaration(declaration)) {
+  } else if (ts15.isEnumDeclaration(declaration)) {
     kind = "enum";
-  } else if (ts14.isVariableDeclaration(declaration)) {
+  } else if (ts15.isVariableDeclaration(declaration)) {
     if (callSignatures.length > 0) {
       kind = "function";
     }
@@ -6116,11 +6336,11 @@ function getJSDocFromExportSymbol(symbol) {
   const examples = [];
   const decl = symbol.declarations?.[0];
   if (decl) {
-    const exportDecl = ts14.isNamespaceExport(decl) ? decl.parent : decl;
-    if (exportDecl && ts14.isExportDeclaration(exportDecl)) {
-      const jsDocs = ts14.getJSDocCommentsAndTags(exportDecl);
+    const exportDecl = ts15.isNamespaceExport(decl) ? decl.parent : decl;
+    if (exportDecl && ts15.isExportDeclaration(exportDecl)) {
+      const jsDocs = ts15.getJSDocCommentsAndTags(exportDecl);
       for (const doc of jsDocs) {
-        if (ts14.isJSDoc(doc) && doc.comment) {
+        if (ts15.isJSDoc(doc) && doc.comment) {
           const commentText = typeof doc.comment === "string" ? doc.comment : doc.comment.map((c) => ("text" in c) ? c.text : "").join("");
           if (commentText) {
             return {
@@ -6175,14 +6395,14 @@ function withExportName(entry, exportName) {
   return {
     ...entry,
     id: exportName,
-    name: entry.name
+    name: exportName
   };
 }
 function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   return {
     ...includeSchema ? { $schema: SCHEMA_URL } : {},
     openpkg: SCHEMA_VERSION,
-    meta: { name: path4.basename(entryFile, path4.extname(entryFile)) },
+    meta: { name: path6.basename(entryFile, path6.extname(entryFile)) },
     exports: [],
     generation: {
       generator: "@openpkg-ts/sdk",
@@ -6195,19 +6415,19 @@ function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   };
 }
 async function getPackageMeta(entryFile, baseDir) {
-  const searchDir = baseDir ?? path4.dirname(entryFile);
-  const pkgPath = path4.join(searchDir, "package.json");
+  const searchDir = baseDir ?? path6.dirname(entryFile);
+  const pkgPath = path6.join(searchDir, "package.json");
   try {
-    if (fs4.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+    if (fs6.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs6.readFileSync(pkgPath, "utf-8"));
       return {
-        name: pkg.name ?? path4.basename(searchDir),
+        name: pkg.name ?? path6.basename(searchDir),
         version: pkg.version,
         description: pkg.description
       };
     }
   } catch {}
-  return { name: path4.basename(searchDir) };
+  return { name: path6.basename(searchDir) };
 }
 
 // src/primitives/spec.ts
@@ -6261,7 +6481,9 @@ export {
   normalizeSchema,
   normalizeMembers,
   normalizeExport,
+  mergeConfig,
   loadSpec,
+  loadConfig,
   listExports,
   isTypeReference,
   isTypeOnlyExport,
@@ -6323,6 +6545,7 @@ export {
   arktypeAdapter,
   analyzeSpec,
   TypeRegistry,
+  CONFIG_FILENAME,
   BUILTIN_TYPE_SCHEMAS,
   ARRAY_PROTOTYPE_METHODS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/sdk",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "TypeScript API extraction SDK - programmatic primitives for OpenPkg specs",
   "keywords": [
     "openpkg",
@@ -38,7 +38,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.32.0",
+    "@openpkg-ts/spec": "^0.33.0",
+    "picomatch": "4.0.3",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {