@openpkg-ts/sdk 0.30.2 → 0.32.0

package/README.md

@@ -75,6 +75,55 @@ import { diffSpecs } from '@openpkg-ts/sdk';
 
 const diff = diffSpecs(oldSpec, newSpec);
 console.log(`Breaking: ${diff.breaking.length}`);
+
+// With options
+const diff = diffSpecs(oldSpec, newSpec, {
+  includeDocsOnly: false,  // exclude docs-only changes
+  kinds: ['function', 'class'],  // filter by kind
+});
+```
+
+### filterSpec
+
+Immutable spec filtering by criteria.
+
+```typescript
+import { filterSpec } from '@openpkg-ts/sdk';
+
+// Filter by kind
+const { spec, matched, total } = filterSpec(fullSpec, {
+  kinds: ['function', 'class'],
+});
+
+// Filter by tags
+filterSpec(spec, { tags: ['public'] });
+
+// Filter deprecated exports
+filterSpec(spec, { deprecated: true });
+
+// Search by name/description
+filterSpec(spec, { search: 'client' });
+
+// Combine criteria (AND logic)
+filterSpec(spec, {
+  kinds: ['function'],
+  hasDescription: true,
+  deprecated: false,
+});
+```
+
+### analyzeSpec
+
+Analyze spec for quality issues.
+
+```typescript
+import { analyzeSpec } from '@openpkg-ts/sdk';
+
+const diagnostics = analyzeSpec(spec);
+
+console.log(`Missing descriptions: ${diagnostics.missingDescriptions.length}`);
+console.log(`Deprecated without reason: ${diagnostics.deprecatedNoReason.length}`);
+console.log(`Missing param docs: ${diagnostics.missingParamDocs.length}`);
 ```
 
 ## Documentation Generation
@@ -144,6 +193,10 @@ import type {
   ExtractResult,
   DocsInstance,
   SimplifiedSpec,
+  FilterCriteria,
+  FilterResult,
+  SpecDiagnostics,
+  DiffOptions,
 } from '@openpkg-ts/sdk';
 ```
 

package/dist/index.d.ts

@@ -1,4 +1,39 @@
 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";
+interface DiagnosticItem {
+	exportId: string;
+	exportName: string;
+	issue: string;
+	/** Member name if issue is on a member */
+	member?: string;
+	/** Parameter name if issue is on a parameter */
+	param?: string;
+}
+interface SpecDiagnostics {
+	/** Exports/members without descriptions */
+	missingDescriptions: DiagnosticItem[];
+	/** Exports marked @deprecated but no reason provided */
+	deprecatedNoReason: DiagnosticItem[];
+	/** Function params without descriptions in JSDoc */
+	missingParamDocs: DiagnosticItem[];
+}
+/**
+* Check if has @deprecated tag.
+*/
+declare function hasDeprecatedTag(exp: SpecExport): boolean;
+/**
+* Get deprecation message from @deprecated tag.
+* Returns undefined if no reason provided.
+*/
+declare function getDeprecationMessage(exp: SpecExport): string | undefined;
+/**
+* Find params without descriptions in JSDoc.
+*/
+declare function findMissingParamDocs(exp: SpecExport): string[];
+/**
+* Analyze a spec for quality issues.
+*/
+declare function analyzeSpec(spec: OpenPkg): SpecDiagnostics;
 import { SpecMember } from "@openpkg-ts/spec";
 /**
 * Extract badge strings from a member's visibility and flags.
@@ -9,8 +44,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 OpenPkg6, SpecExport as SpecExport2, SpecExportKind as SpecExportKind4, SpecType } from "@openpkg-ts/spec";
-import { OpenPkg } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg7, SpecExport as SpecExport3, SpecExportKind as SpecExportKind4, SpecType } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg2 } from "@openpkg-ts/spec";
 interface HTMLOptions {
 	/** Page title override */
 	title?: string;
@@ -24,6 +59,8 @@ interface HTMLOptions {
 	fullDocument?: boolean;
 	/** Export to render (single mode) */
 	export?: string;
+	/** Exports to render (multi-mode) - overridden by `export` if both provided */
+	exports?: string[];
 }
 /**
 * Render spec to standalone HTML page.
@@ -46,13 +83,15 @@ interface HTMLOptions {
 * const fragment = docs.toHTML({ export: 'greet', fullDocument: false })
 * ```
 */
-declare function toHTML2(spec: OpenPkg, options?: HTMLOptions): string;
-import { OpenPkg as OpenPkg2, SpecExportKind } from "@openpkg-ts/spec";
+declare function toHTML2(spec: OpenPkg2, options?: HTMLOptions): string;
+import { OpenPkg as OpenPkg3, SpecExportKind } from "@openpkg-ts/spec";
 interface JSONOptions {
 	/** Include raw spec data alongside simplified data */
 	includeRaw?: boolean;
 	/** Export to render (single mode) */
 	export?: string;
+	/** Exports to render (multi-mode) - overridden by `export` if both provided */
+	exports?: string[];
 	/** Include computed fields (signatures, formatted types) */
 	computed?: boolean;
 	/** Flatten nested structures */
@@ -139,7 +178,7 @@ interface SimplifiedSpec {
 * // { id, name, kind, signature, parameters, returns, ... }
 * ```
 */
-declare function toJSON2(spec: OpenPkg2, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+declare function toJSON2(spec: OpenPkg3, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
 /**
 * Serialize to JSON string with formatting.
 *
@@ -147,10 +186,10 @@ declare function toJSON2(spec: OpenPkg2, options?: JSONOptions): SimplifiedSpec
 * @param options - JSON options plus pretty formatting option
 * @returns JSON string
 */
-declare function toJSONString(spec: OpenPkg2, options?: JSONOptions & {
+declare function toJSONString(spec: OpenPkg3, options?: JSONOptions & {
 	pretty?: boolean;
 }): string;
-import { OpenPkg as OpenPkg3, SpecExport } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg4, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
 interface MarkdownOptions {
 	/** Include frontmatter in output */
 	frontmatter?: boolean;
@@ -171,10 +210,14 @@ interface MarkdownOptions {
 	codeSignatures?: boolean;
 	/** Heading level offset (0 = starts at h1, 1 = starts at h2) */
 	headingOffset?: number;
+	/** Collapse unions with more than N members (default: no collapse) */
+	collapseUnionThreshold?: number;
 }
 interface ExportMarkdownOptions extends MarkdownOptions {
-	/** Export to render */
+	/** Export to render (single mode) */
 	export?: string;
+	/** Exports to render (multi-mode) - overridden by `export` if both provided */
+	exports?: string[];
 }
 /**
 * Render a single to MDX.
@@ -192,7 +235,7 @@ interface ExportMarkdownOptions extends MarkdownOptions {
 * })
 * ```
 */
-declare function exportToMarkdown(exp: SpecExport, options?: MarkdownOptions): string;
+declare function exportToMarkdown(exp: SpecExport2, options?: MarkdownOptions): string;
 /**
 * Render entire spec to MDX.
 *
@@ -212,8 +255,8 @@ declare function exportToMarkdown(exp: SpecExport, options?: MarkdownOptions): s
 * // Single * const fnMdx = docs.toMarkdown({ export: 'greet' })
 * ```
 */
-declare function toMarkdown2(spec: OpenPkg3, options?: ExportMarkdownOptions): string;
-import { OpenPkg as OpenPkg4, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
+declare function toMarkdown2(spec: OpenPkg4, options?: ExportMarkdownOptions): string;
+import { OpenPkg as OpenPkg5, SpecExportKind as SpecExportKind2 } from "@openpkg-ts/spec";
 type NavFormat = "fumadocs" | "docusaurus" | "generic";
 type GroupBy = "kind" | "module" | "tag" | "none";
 interface NavOptions {
@@ -288,7 +331,7 @@ type DocusaurusSidebar = DocusaurusSidebarItem[];
 * const sidebar = docs.toNavigation({ format: 'docusaurus' })
 * ```
 */
-declare function toNavigation2(spec: OpenPkg4, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+declare function toNavigation2(spec: OpenPkg5, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
 /**
 * Generate Fumadocs meta.json file content.
 *
@@ -302,7 +345,7 @@ declare function toNavigation2(spec: OpenPkg4, options?: NavOptions): GenericNav
 * fs.writeFileSync('docs/api/meta.json', meta)
 * ```
 */
-declare function toFumadocsMetaJSON(spec: OpenPkg4, options?: Omit<NavOptions, "format">): string;
+declare function toFumadocsMetaJSON(spec: OpenPkg5, options?: Omit<NavOptions, "format">): string;
 /**
 * Generate Docusaurus sidebar config.
 *
@@ -316,8 +359,8 @@ declare function toFumadocsMetaJSON(spec: OpenPkg4, options?: Omit<NavOptions, "
 * fs.writeFileSync('sidebars.js', sidebar)
 * ```
 */
-declare function toDocusaurusSidebarJS(spec: OpenPkg4, options?: Omit<NavOptions, "format">): string;
-import { OpenPkg as OpenPkg5, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
+declare function toDocusaurusSidebarJS(spec: OpenPkg5, options?: Omit<NavOptions, "format">): string;
+import { OpenPkg as OpenPkg6, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
 interface SearchOptions {
 	/** Base URL for search result links */
 	baseUrl?: string;
@@ -410,7 +453,7 @@ interface SearchIndex {
 * // { records: [...], version: '1.0.0', packageName: 'my-lib' }
 * ```
 */
-declare function toSearchIndex2(spec: OpenPkg5, options?: SearchOptions): SearchIndex;
+declare function toSearchIndex2(spec: OpenPkg6, options?: SearchOptions): SearchIndex;
 /**
 * Generate Pagefind-compatible records.
 *
@@ -426,7 +469,7 @@ declare function toSearchIndex2(spec: OpenPkg5, options?: SearchOptions): Search
 * })
 * ```
 */
-declare function toPagefindRecords2(spec: OpenPkg5, options?: SearchOptions): PagefindRecord[];
+declare function toPagefindRecords2(spec: OpenPkg6, options?: SearchOptions): PagefindRecord[];
 /**
 * Generate Algolia-compatible records.
 *
@@ -440,7 +483,7 @@ declare function toPagefindRecords2(spec: OpenPkg5, options?: SearchOptions): Pa
 * // Upload to Algolia index
 * ```
 */
-declare function toAlgoliaRecords2(spec: OpenPkg5, options?: SearchOptions): AlgoliaRecord[];
+declare function toAlgoliaRecords2(spec: OpenPkg6, options?: SearchOptions): AlgoliaRecord[];
 /**
 * Serialize search index to JSON string.
 *
@@ -454,36 +497,36 @@ declare function toAlgoliaRecords2(spec: OpenPkg5, options?: SearchOptions): Alg
 * fs.writeFileSync('search-index.json', json)
 * ```
 */
-declare function toSearchIndexJSON(spec: OpenPkg5, options?: SearchOptions & {
+declare function toSearchIndexJSON(spec: OpenPkg6, options?: SearchOptions & {
 	pretty?: boolean;
 }): string;
 interface LoadOptions {
 	/** Path to openpkg.json file or the spec object directly */
-	input: string | OpenPkg6;
+	input: string | OpenPkg7;
 }
 interface DocsInstance {
 	/** The parsed OpenPkg spec */
-	spec: OpenPkg6;
+	spec: OpenPkg7;
 	/** Get an by its ID */
-	getExport(id: string): SpecExport2 | undefined;
+	getExport(id: string): SpecExport3 | undefined;
 	/** Get a type definition by its ID */
 	getType(id: string): SpecType | undefined;
 	/** Get all exports of a specific kind */
-	getExportsByKind(kind: SpecExportKind4): SpecExport2[];
+	getExportsByKind(kind: SpecExportKind4): SpecExport3[];
 	/** Get all exports */
-	getAllExports(): SpecExport2[];
+	getAllExports(): SpecExport3[];
 	/** Get all type definitions */
 	getAllTypes(): SpecType[];
 	/** Get exports by JSDoc tag (e.g., '@beta', '@internal') */
-	getExportsByTag(tagName: string): SpecExport2[];
+	getExportsByTag(tagName: string): SpecExport3[];
 	/** Search exports by name or description */
-	search(query: string): SpecExport2[];
+	search(query: string): SpecExport3[];
 	/** Get exports belonging to a specific module/namespace */
-	getModule(moduleName: string): SpecExport2[];
+	getModule(moduleName: string): SpecExport3[];
 	/** Get deprecated exports */
-	getDeprecated(): SpecExport2[];
+	getDeprecated(): SpecExport3[];
 	/** Get exports grouped by kind */
-	groupByKind(): Record<SpecExportKind4, SpecExport2[]>;
+	groupByKind(): Record<SpecExportKind4, SpecExport3[]>;
 	/** Render spec or single to MDX */
 	toMarkdown(options?: ExportMarkdownOptions): string;
 	/** Render spec or single to HTML */
@@ -511,7 +554,7 @@ interface DocsInstance {
 * const docs = loadSpec(spec)
 * ```
 */
-declare function loadSpec(spec: OpenPkg6): DocsInstance;
+declare function loadSpec(spec: OpenPkg7): DocsInstance;
 /**
 * Creates a docs instance for querying and rendering API documentation.
 *
@@ -533,11 +576,13 @@ declare function loadSpec(spec: OpenPkg6): DocsInstance;
 * docs.search('hook')
 * ```
 */
-declare function createDocs(input: string | OpenPkg6): DocsInstance;
-import { OpenPkg as OpenPkg7, SpecExport as SpecExport3, SpecMember as SpecMember2, SpecSchema, SpecSignature, SpecType as SpecType2, SpecTypeParameter } from "@openpkg-ts/spec";
+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";
 interface FormatSchemaOptions {
 	/** Include package attribution for external types */
 	includePackage?: boolean;
+	/** Collapse unions with more than N members (default: no collapse) */
+	collapseUnionThreshold?: number;
 }
 /**
 * Format a schema to a human-readable type string.
@@ -613,7 +658,7 @@ declare function formatReturnType(sig?: SpecSignature): string;
 * // 'class Logger extends EventEmitter'
 * ```
 */
-declare function buildSignatureString(exp: SpecExport3, sigIndex?: number): string;
+declare function buildSignatureString(exp: SpecExport4, sigIndex?: number): string;
 /**
 * Resolve a type reference to its definition.
 *
@@ -627,7 +672,7 @@ declare function buildSignatureString(exp: SpecExport3, sigIndex?: number): stri
 * // { id: 'User', name: 'User', kind: 'interface', ... }
 * ```
 */
-declare function resolveTypeRef(ref: string, spec: OpenPkg7): SpecType2 | undefined;
+declare function resolveTypeRef(ref: string, spec: OpenPkg8): SpecType2 | undefined;
 /**
 * Check if a member is a method (has signatures).
 *
@@ -742,7 +787,49 @@ declare function formatConditionalType(condType: SpecConditionalType): string;
 * ```
 */
 declare function formatMappedType(mappedType: SpecMappedType): string;
-import { SpecExport as SpecExport4, SpecType as SpecType3 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg9, SpecExportKind as SpecExportKind5 } from "@openpkg-ts/spec";
+type FilterCriteria = {
+	/** Filter by kinds */
+	kinds?: SpecExportKind5[];
+	/** Filter by names (exact match) */
+	names?: string[];
+	/** Filter by IDs */
+	ids?: string[];
+	/** Filter by tags (must have at least one matching tag) */
+	tags?: string[];
+	/** Filter by deprecation status */
+	deprecated?: boolean;
+	/** Filter by whether has a description */
+	hasDescription?: boolean;
+	/** Search term (matches name or description, case-insensitive) */
+	search?: string;
+	/** Filter by module path (source.file contains this) */
+	module?: string;
+	/** Also search member names/descriptions (requires search) */
+	searchMembers?: boolean;
+	/** Also search docs: param descriptions, return descriptions, examples (requires search) */
+	searchDocs?: boolean;
+};
+type FilterResult = {
+	/** New spec with only matched exports (immutable) */
+	spec: OpenPkg9;
+	/** Number of exports that matched */
+	matched: number;
+	/** Total number of exports in original spec */
+	total: number;
+};
+/**
+* Filter a spec by various criteria.
+* Returns a new spec with only matched exports (never mutates input).
+* Uses AND logic: all specified criteria must match.
+* Types are always preserved (no pruning).
+*
+* @param spec - The spec to filter
+* @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;
+import { SpecExport as SpecExport5, SpecType as SpecType3 } from "@openpkg-ts/spec";
 interface GetExportOptions {
 	/** Entry point file path */
 	entryFile: string;
@@ -757,7 +844,7 @@ interface GetExportOptions {
 }
 interface GetExportResult {
 	/** The spec, or null if not found */
-	export: SpecExport4 | null;
+	export: SpecExport5 | null;
 	/** Related types referenced by the */
 	types: SpecType3[];
 	/** Errors encountered */
@@ -798,7 +885,7 @@ interface ListExportsResult {
 * List all exports from a TypeScript entry point
 */
 declare function listExports(options: ListExportsOptions): Promise<ListExportsResult>;
-import { OpenPkg as OpenPkg8 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg10 } from "@openpkg-ts/spec";
 interface ExtractOptions {
 	entryFile: string;
 	baseDir?: string;
@@ -819,9 +906,11 @@ interface ExtractOptions {
 	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: OpenPkg8;
+	spec: OpenPkg10;
 	diagnostics: Diagnostic[];
 	forgottenExports?: ForgottenExport[];
 	/** Metadata about runtime schema extraction (when schemaExtraction: 'hybrid') */
@@ -939,6 +1028,8 @@ interface SerializerContext {
 	visitedTypes: Set<ts.Type>;
 	/** Flag to indicate we're processing tuple elements - skip Array prototype methods */
 	inTupleElement?: boolean;
+	/** Include private/protected class members (default: false) */
+	includePrivate?: boolean;
 }
 declare class TypeRegistry {
 	private types;
@@ -1002,8 +1093,12 @@ type DeclarationWithTypeParams = ts4.FunctionDeclaration | ts4.ClassDeclaration
 declare function extractTypeParameters(node: DeclarationWithTypeParams, checker: ts4.TypeChecker): SpecTypeParameter2[] | undefined;
 /**
 * Check if a symbol is marked as deprecated via @deprecated JSDoc tag.
+* Returns deprecation status and optional reason text.
 */
-declare function isSymbolDeprecated(symbol: ts4.Symbol | undefined): boolean;
+declare function isSymbolDeprecated(symbol: ts4.Symbol | undefined): {
+	deprecated: boolean;
+	reason?: string;
+};
 /**
 * Target version for JSON Schema generation.
 * @see https://standardschema.dev/json-schema
@@ -1227,24 +1322,24 @@ declare const arktypeAdapter: SchemaAdapter;
 declare const typeboxAdapter: SchemaAdapter;
 declare const valibotAdapter: SchemaAdapter;
 declare const zodAdapter: SchemaAdapter;
-import { SpecExport as SpecExport6 } from "@openpkg-ts/spec";
-import ts6 from "typescript";
-declare function serializeClass(node: ts6.ClassDeclaration, ctx: SerializerContext): SpecExport6 | null;
 import { SpecExport as SpecExport7 } from "@openpkg-ts/spec";
-import ts7 from "typescript";
-declare function serializeEnum(node: ts7.EnumDeclaration, ctx: SerializerContext): SpecExport7 | null;
+import ts6 from "typescript";
+declare function serializeClass(node: ts6.ClassDeclaration, ctx: SerializerContext): SpecExport7 | null;
 import { SpecExport as SpecExport8 } from "@openpkg-ts/spec";
-import ts8 from "typescript";
-declare function serializeFunctionExport(node: ts8.FunctionDeclaration | ts8.ArrowFunction, ctx: SerializerContext): SpecExport8 | null;
+import ts7 from "typescript";
+declare function serializeEnum(node: ts7.EnumDeclaration, ctx: SerializerContext): SpecExport8 | null;
 import { SpecExport as SpecExport9 } from "@openpkg-ts/spec";
-import ts9 from "typescript";
-declare function serializeInterface(node: ts9.InterfaceDeclaration, ctx: SerializerContext): SpecExport9 | null;
+import ts8 from "typescript";
+declare function serializeFunctionExport(node: ts8.FunctionDeclaration | ts8.ArrowFunction, ctx: SerializerContext): SpecExport9 | null;
 import { SpecExport as SpecExport10 } from "@openpkg-ts/spec";
-import ts10 from "typescript";
-declare function serializeTypeAlias(node: ts10.TypeAliasDeclaration, ctx: SerializerContext): SpecExport10 | null;
+import ts9 from "typescript";
+declare function serializeInterface(node: ts9.InterfaceDeclaration, ctx: SerializerContext): SpecExport10 | null;
 import { SpecExport as SpecExport11 } from "@openpkg-ts/spec";
+import ts10 from "typescript";
+declare function serializeTypeAlias(node: ts10.TypeAliasDeclaration, ctx: SerializerContext): SpecExport11 | null;
+import { SpecExport as SpecExport12 } from "@openpkg-ts/spec";
 import ts11 from "typescript";
-declare function serializeVariable(node: ts11.VariableDeclaration, statement: ts11.VariableStatement, ctx: SerializerContext): SpecExport11 | null;
+declare function serializeVariable(node: ts11.VariableDeclaration, statement: ts11.VariableStatement, ctx: SerializerContext): SpecExport12 | null;
 import { SpecSignatureParameter } from "@openpkg-ts/spec";
 import ts12 from "typescript";
 declare function extractParameters(signature: ts12.Signature, ctx: SerializerContext): SpecSignatureParameter[];
@@ -1321,7 +1416,7 @@ declare function deduplicateSchemas(schemas: SpecSchema2[]): SpecSchema2[];
 * A valid discriminator has a unique literal value in each union member.
 */
 declare function findDiscriminatorProperty(unionTypes: ts13.Type[], checker: ts13.TypeChecker): string | undefined;
-import { SpecExport as SpecExport12, SpecMember as SpecMember3, SpecSchema as SpecSchema3, SpecType as SpecType5 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport13, SpecMember as SpecMember3, SpecSchema as SpecSchema3, SpecType as SpecType5 } from "@openpkg-ts/spec";
 /**
 * Options for schema normalization
 */
@@ -1352,7 +1447,7 @@ declare function normalizeSchema(schema: SpecSchema3, options?: NormalizeOptions
 * 2. Normalize member schemas
 * 3. Generate a JSON Schema from members if members exist (populates `schema` field)
 */
-declare function normalizeExport(exp: SpecExport12, options?: NormalizeOptions): SpecExport12;
+declare function normalizeExport(exp: SpecExport13, options?: NormalizeOptions): SpecExport13;
 /**
 * Normalize a SpecType, normalizing its schema and nested schemas.
 *
@@ -1386,4 +1481,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, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExport2 as getExport, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, 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, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, 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, 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 };

package/dist/index.js

@@ -6,6 +6,82 @@ import {
   diffSpec as diffSpec2,
   recommendSemverBump
 } from "@openpkg-ts/spec";
+// src/core/diagnostics.ts
+function hasDeprecatedTag(exp) {
+  if (exp.deprecated === true)
+    return true;
+  return exp.tags?.some((t) => t.name === "deprecated" || t.name === "@deprecated") ?? false;
+}
+function getDeprecationMessage(exp) {
+  const tag = exp.tags?.find((t) => t.name === "deprecated" || t.name === "@deprecated");
+  if (tag?.text.trim()) {
+    return tag.text.trim();
+  }
+  return;
+}
+function findMissingParamDocs(exp) {
+  const missing = [];
+  for (const sig of exp.signatures ?? []) {
+    for (const param of sig.parameters ?? []) {
+      if (!param.description?.trim()) {
+        missing.push(param.name);
+      }
+    }
+  }
+  return missing;
+}
+function checkMemberDescriptions(exp, members) {
+  const items = [];
+  for (const member of members) {
+    if (!member.description?.trim() && member.name) {
+      items.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "member missing description",
+        member: member.name
+      });
+    }
+  }
+  return items;
+}
+function analyzeSpec(spec) {
+  const missingDescriptions = [];
+  const deprecatedNoReason = [];
+  const missingParamDocs = [];
+  for (const exp of spec.exports) {
+    if (!exp.description?.trim()) {
+      missingDescriptions.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "missing description"
+      });
+    }
+    if (exp.members) {
+      missingDescriptions.push(...checkMemberDescriptions(exp, exp.members));
+    }
+    if (hasDeprecatedTag(exp) && !getDeprecationMessage(exp)) {
+      deprecatedNoReason.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "deprecated without reason"
+      });
+    }
+    const missingParams = findMissingParamDocs(exp);
+    for (const param of missingParams) {
+      missingParamDocs.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "param missing description",
+        param
+      });
+    }
+  }
+  return {
+    missingDescriptions,
+    deprecatedNoReason,
+    missingParamDocs
+  };
+}
 // src/core/format.ts
 function getMemberBadges(member) {
   const badges = [];
@@ -76,7 +152,15 @@ function formatSchema(schema, options) {
       return withPackage(baseName);
     }
     if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
-      return schema.anyOf.map((s) => formatSchema(s, options)).join(" | ");
+      const threshold = options?.collapseUnionThreshold;
+      const members = schema.anyOf;
+      if (threshold && members.length > threshold) {
+        const shown = members.slice(0, 3);
+        const remaining = members.length - 3;
+        const shownStr = shown.map((s) => formatSchema(s, options)).join(" | ");
+        return `${shownStr} | ... (${remaining} more)`;
+      }
+      return members.map((s) => formatSchema(s, options)).join(" | ");
     }
     if ("allOf" in schema && Array.isArray(schema.allOf)) {
       return schema.allOf.map((s) => formatSchema(s, options)).join(" & ");
@@ -519,10 +603,15 @@ function toHTML(spec, options = {}) {
 </body>
 </html>`;
   }
+  let specExports = spec.exports;
+  if (options.exports?.length) {
+    const ids = new Set(options.exports);
+    specExports = spec.exports.filter((e) => ids.has(e.name) || ids.has(e.id));
+  }
   const title = options.title || `${spec.meta.name} API Reference`;
   const description = spec.meta.description ? `<p>${escapeHTML(spec.meta.description)}</p>` : "";
   const byKind = {};
-  for (const exp of spec.exports) {
+  for (const exp of specExports) {
     if (!byKind[exp.kind])
       byKind[exp.kind] = [];
     byKind[exp.kind].push(exp);
@@ -665,7 +754,12 @@ function toJSON(spec, options = {}) {
     }
     return simplifyExport(exp);
   }
-  const exports = spec.exports.map(simplifyExport);
+  let specExports = spec.exports;
+  if (options.exports?.length) {
+    const ids = new Set(options.exports);
+    specExports = spec.exports.filter((e) => ids.has(e.name) || ids.has(e.id));
+  }
+  const exports = specExports.map(simplifyExport);
   const byKind = {};
   for (const exp of exports) {
     if (!byKind[exp.kind])
@@ -739,12 +833,12 @@ function heading(level, text, offset = 0) {
   const actualLevel = Math.min(level + offset, 6);
   return `${"#".repeat(actualLevel)} ${text}`;
 }
-function renderParameters2(sig, offset = 0) {
+function renderParameters2(sig, offset = 0, schemaOpts) {
   if (!sig?.parameters?.length)
     return "";
   const lines = [heading(2, "Parameters", offset), ""];
   for (const param of sig.parameters) {
-    const type = formatSchema(param.schema);
+    const type = formatSchema(param.schema, schemaOpts);
     const required = param.required !== false ? "" : "?";
     const rest = param.rest ? "..." : "";
     lines.push(`### \`${rest}${param.name}${required}\``);
@@ -763,11 +857,11 @@ function renderParameters2(sig, offset = 0) {
   return lines.join(`
 `);
 }
-function renderReturns2(sig, offset = 0) {
+function renderReturns2(sig, offset = 0, schemaOpts) {
   if (!sig?.returns)
     return "";
   const lines = [heading(2, "Returns", offset), ""];
-  const type = formatSchema(sig.returns.schema);
+  const type = formatSchema(sig.returns.schema, schemaOpts);
   lines.push(`**Type:** \`${type}\``);
   if (sig.returns.description) {
     lines.push("");
@@ -819,13 +913,13 @@ function renderExamples2(examples, offset = 0) {
   return lines.join(`
 `);
 }
-function renderProperties2(members, offset = 0) {
+function renderProperties2(members, offset = 0, schemaOpts) {
   const props = getProperties(members);
   if (!props.length)
     return "";
   const lines = [heading(2, "Properties", offset), ""];
   for (const prop of props) {
-    const type = formatSchema(prop.schema);
+    const type = formatSchema(prop.schema, schemaOpts);
     lines.push(`### \`${prop.name}\``);
     lines.push("");
     if (prop.decorators?.length) {
@@ -858,7 +952,7 @@ function renderProperties2(members, offset = 0) {
   return lines.join(`
 `);
 }
-function renderMethods2(members, offset = 0) {
+function renderMethods2(members, offset = 0, schemaOpts) {
   const methods = getMethods(members);
   if (!methods.length)
     return "";
@@ -895,14 +989,14 @@ function renderMethods2(members, offset = 0) {
       lines.push("**Parameters:**");
       lines.push("");
       for (const param of sig.parameters) {
-        const paramType = formatSchema(param.schema);
+        const paramType = formatSchema(param.schema, schemaOpts);
         const desc = param.description ? ` - ${param.description}` : "";
         lines.push(`- \`${param.name}\`: \`${paramType}\`${desc}`);
       }
       lines.push("");
     }
     if (sig?.returns) {
-      const retType = formatSchema(sig.returns.schema);
+      const retType = formatSchema(sig.returns.schema, schemaOpts);
       const desc = sig.returns.description ? ` - ${sig.returns.description}` : "";
       lines.push(`**Returns:** \`${retType}\`${desc}`);
       lines.push("");
@@ -929,6 +1023,7 @@ function renderEnumMembers2(members, offset = 0) {
 function exportToMarkdown(exp, options = {}) {
   const sections = { ...defaultSections, ...options.sections };
   const offset = options.headingOffset ?? 0;
+  const schemaOpts = options.collapseUnionThreshold ? { collapseUnionThreshold: options.collapseUnionThreshold } : undefined;
   const parts = [];
   if (options.frontmatter !== false) {
     parts.push(generateFrontmatter(exp, options.customFrontmatter));
@@ -976,24 +1071,25 @@ function exportToMarkdown(exp, options = {}) {
     parts.push("");
   }
   if (exp.deprecated) {
-    parts.push("> **Deprecated**");
+    const reason = "deprecationReason" in exp && exp.deprecationReason ? `: ${exp.deprecationReason}` : "";
+    parts.push(`> **Deprecated**${reason}`);
     parts.push("");
   }
   const primarySig = exp.signatures?.[0];
   switch (exp.kind) {
     case "function":
       if (sections.parameters)
-        parts.push(renderParameters2(primarySig, offset));
+        parts.push(renderParameters2(primarySig, offset, schemaOpts));
       if (sections.returns)
-        parts.push(renderReturns2(primarySig, offset));
+        parts.push(renderReturns2(primarySig, offset, schemaOpts));
       parts.push(renderThrows2(primarySig, offset));
       break;
     case "class":
     case "interface":
       if (sections.properties)
-        parts.push(renderProperties2(exp.members, offset));
+        parts.push(renderProperties2(exp.members, offset, schemaOpts));
       if (sections.methods)
-        parts.push(renderMethods2(exp.members, offset));
+        parts.push(renderMethods2(exp.members, offset, schemaOpts));
       break;
     case "enum":
       if (sections.members)
@@ -1018,6 +1114,13 @@ function toMarkdown(spec, options = {}) {
     }
     return exportToMarkdown(exp, options);
   }
+  let specExports = spec.exports;
+  if (options.exports?.length) {
+    const ids = new Set(options.exports);
+    specExports = spec.exports.filter((e) => ids.has(e.name) || ids.has(e.id));
+    if (specExports.length === 0)
+      return "";
+  }
   const parts = [];
   if (options.frontmatter !== false) {
     const frontmatter = {
@@ -1044,7 +1147,7 @@ function toMarkdown(spec, options = {}) {
     parts.push("");
   }
   const byKind = {};
-  for (const exp of spec.exports) {
+  for (const exp of specExports) {
     if (!byKind[exp.kind])
       byKind[exp.kind] = [];
     byKind[exp.kind].push(exp);
@@ -1515,6 +1618,109 @@ function extractModuleName(exp) {
   }
   return;
 }
+// src/primitives/filter.ts
+function matchesExport(exp, criteria) {
+  if (criteria.kinds && criteria.kinds.length > 0) {
+    if (!criteria.kinds.includes(exp.kind))
+      return false;
+  }
+  if (criteria.names && criteria.names.length > 0) {
+    if (!criteria.names.includes(exp.name))
+      return false;
+  }
+  if (criteria.ids && criteria.ids.length > 0) {
+    if (!criteria.ids.includes(exp.id))
+      return false;
+  }
+  if (criteria.tags && criteria.tags.length > 0) {
+    const expTags = exp.tags?.map((t) => t.name) ?? [];
+    if (!criteria.tags.some((tag) => expTags.includes(tag)))
+      return false;
+  }
+  if (criteria.deprecated !== undefined) {
+    if ((exp.deprecated ?? false) !== criteria.deprecated)
+      return false;
+  }
+  if (criteria.hasDescription !== undefined) {
+    const has = Boolean(exp.description && exp.description.trim().length > 0);
+    if (has !== criteria.hasDescription)
+      return false;
+  }
+  if (criteria.search) {
+    const term = criteria.search.toLowerCase();
+    const nameMatch = exp.name.toLowerCase().includes(term);
+    const descMatch = exp.description?.toLowerCase().includes(term) ?? false;
+    let memberMatch = false;
+    if (criteria.searchMembers && exp.members) {
+      memberMatch = exp.members.some((m) => m.name?.toLowerCase().includes(term) || m.description?.toLowerCase().includes(term));
+    }
+    let docsMatch = false;
+    if (criteria.searchDocs) {
+      for (const sig of exp.signatures ?? []) {
+        for (const param of sig.parameters ?? []) {
+          if (param.description?.toLowerCase().includes(term)) {
+            docsMatch = true;
+            break;
+          }
+        }
+        if (docsMatch)
+          break;
+        if (sig.returns?.description?.toLowerCase().includes(term)) {
+          docsMatch = true;
+          break;
+        }
+      }
+      if (!docsMatch && exp.examples) {
+        for (const ex of exp.examples) {
+          const exText = typeof ex === "string" ? ex : ex.code + (ex.description ?? "");
+          if (exText.toLowerCase().includes(term)) {
+            docsMatch = true;
+            break;
+          }
+        }
+      }
+    }
+    if (!nameMatch && !descMatch && !memberMatch && !docsMatch)
+      return false;
+  }
+  if (criteria.module) {
+    const file = exp.source?.file ?? "";
+    if (!file.includes(criteria.module))
+      return false;
+  }
+  return true;
+}
+function filterSpec(spec, criteria) {
+  const total = spec.exports.length;
+  const isEmpty = Object.keys(criteria).length === 0;
+  if (isEmpty) {
+    return {
+      spec: {
+        ...spec,
+        exports: [...spec.exports],
+        types: spec.types ? [...spec.types] : undefined
+      },
+      matched: total,
+      total
+    };
+  }
+  const matched = [];
+  for (const exp of spec.exports) {
+    if (matchesExport(exp, criteria)) {
+      matched.push(exp);
+    }
+  }
+  const newSpec = {
+    ...spec,
+    exports: matched,
+    types: spec.types ? [...spec.types] : undefined
+  };
+  return {
+    spec: newSpec,
+    matched: matched.length,
+    total
+  };
+}
 // src/primitives/get.ts
 import ts11 from "typescript";
 
@@ -1934,18 +2140,27 @@ function extractTypeParameters(node, checker) {
 }
 function isSymbolDeprecated(symbol) {
   if (!symbol) {
-    return false;
+    return { deprecated: false };
   }
   const jsDocTags = symbol.getJsDocTags();
-  if (jsDocTags.some((tag) => tag.name.toLowerCase() === "deprecated")) {
-    return true;
+  const deprecatedTag = jsDocTags.find((tag) => tag.name.toLowerCase() === "deprecated");
+  if (deprecatedTag) {
+    const reason = deprecatedTag.text?.map((t) => t.text).join("") || undefined;
+    return { deprecated: true, reason };
   }
   for (const declaration of symbol.getDeclarations() ?? []) {
-    if (ts2.getJSDocDeprecatedTag(declaration)) {
-      return true;
+    const tag = ts2.getJSDocDeprecatedTag(declaration);
+    if (tag) {
+      let reason;
+      if (typeof tag.comment === "string") {
+        reason = tag.comment;
+      } else if (Array.isArray(tag.comment)) {
+        reason = tag.comment.map((c) => typeof c === "string" ? c : c.text).join("");
+      }
+      return { deprecated: true, reason };
     }
   }
-  return false;
+  return { deprecated: false };
 }
 function getJSDocForSignature(signature, checker) {
   const decl = signature.getDeclaration();
@@ -3044,7 +3259,8 @@ function createContext(program, sourceFile, options = {}) {
     resolveExternalTypes: options.resolveExternalTypes ?? true,
     typeRegistry: new TypeRegistry,
     exportedIds: new Set,
-    visitedTypes: new Set
+    visitedTypes: new Set,
+    includePrivate: options.includePrivate ?? false
   };
 }
 function getInheritedMembers(classType, ownMemberNames, ctx, isStatic = false) {
@@ -3180,7 +3396,7 @@ function serializeClass(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const deprecated = isSymbolDeprecated(symbol);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
   const { description, tags, examples } = getJSDocComment(node, symbol, checker);
   const source = getSourceLocation(node, declSourceFile);
@@ -3252,7 +3468,7 @@ function serializeClass(node, ctx) {
     signatures: signatures.length > 0 ? signatures : undefined,
     extends: extendsClause,
     implements: implementsClause?.length ? implementsClause : undefined,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {},
     ...Object.keys(classFlags).length > 0 ? { flags: classFlags } : {}
   };
@@ -3297,8 +3513,9 @@ function serializeProperty(node, ctx) {
     return null;
   const { description, tags } = getJSDocComment(node);
   const visibility = getVisibility(node);
-  if (visibility === "private")
+  if (!ctx.includePrivate && (visibility === "private" || visibility === "protected")) {
     return null;
+  }
   const type = checker.getTypeAtLocation(node);
   registerReferencedTypes(type, ctx);
   const schema = buildSchema(type, checker, ctx);
@@ -3326,6 +3543,9 @@ function serializeMethod(node, ctx) {
     return null;
   const { description, tags } = getJSDocComment(node);
   const visibility = getVisibility(node);
+  if (!ctx.includePrivate && (visibility === "private" || visibility === "protected")) {
+    return null;
+  }
   const type = checker.getTypeAtLocation(node);
   const callSignatures = type.getCallSignatures();
   const signatures = callSignatures.map((sig, index) => {
@@ -3387,6 +3607,9 @@ function serializeAccessor(node, ctx) {
     return null;
   const { description, tags } = getJSDocComment(node);
   const visibility = getVisibility(node);
+  if (!ctx.includePrivate && (visibility === "private" || visibility === "protected")) {
+    return null;
+  }
   const type = checker.getTypeAtLocation(node);
   const schema = buildSchema(type, checker, ctx);
   registerReferencedTypes(type, ctx);
@@ -3460,7 +3683,7 @@ function serializeEnum(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const deprecated = isSymbolDeprecated(symbol);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
   const { description, tags, examples } = getJSDocComment(node, symbol, checker);
   const source = getSourceLocation(node, declSourceFile);
@@ -3493,7 +3716,7 @@ function serializeEnum(node, ctx) {
     tags,
     source,
     members,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -3533,7 +3756,7 @@ function serializeFunctionExport(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const deprecated = isSymbolDeprecated(symbol);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
   const { description, tags, examples } = getJSDocComment(node, symbol, ctx.typeChecker);
   const source = getSourceLocation(node, declSourceFile);
@@ -3563,7 +3786,7 @@ function serializeFunctionExport(node, ctx) {
     source,
     typeParameters,
     signatures,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -3576,7 +3799,7 @@ function serializeInterface(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const deprecated = isSymbolDeprecated(symbol);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
   const { description, tags, examples } = getJSDocComment(node, symbol, checker);
   const source = getSourceLocation(node, declSourceFile);
@@ -3656,7 +3879,7 @@ function serializeInterface(node, ctx) {
     members: members.length > 0 ? members : undefined,
     signatures: exportSignatures,
     extends: extendsClause,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -3797,7 +4020,7 @@ function serializeTypeAlias(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const deprecated = isSymbolDeprecated(symbol);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
   const { description, tags, examples } = getJSDocComment(node, symbol, ctx.typeChecker);
   const source = getSourceLocation(node, declSourceFile);
@@ -3819,7 +4042,7 @@ function serializeTypeAlias(node, ctx) {
     source,
     typeParameters,
     schema,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -3993,7 +4216,7 @@ function serializeVariable(node, statement, ctx) {
   const name = symbol?.getName() ?? node.name.getText();
   if (!name)
     return null;
-  const deprecated = isSymbolDeprecated(symbol);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
   const { description, tags, examples } = getJSDocComment(statement, symbol, ctx.typeChecker);
   const source = getSourceLocation(node, declSourceFile);
@@ -4015,7 +4238,7 @@ function serializeVariable(node, statement, ctx) {
     source,
     schema,
     ...flags ? { flags } : {},
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -5346,7 +5569,8 @@ async function extract(options) {
     only,
     ignore,
     onProgress,
-    isDtsSource
+    isDtsSource,
+    includePrivate
   } = options;
   const diagnostics = [];
   let exports = [];
@@ -5385,7 +5609,8 @@ async function extract(options) {
   const ctx = createContext(program, sourceFile, {
     maxTypeDepth,
     maxExternalTypeDepth,
-    resolveExternalTypes
+    resolveExternalTypes,
+    includePrivate
   });
   ctx.exportedIds = exportedIds;
   const filteredSymbols = exportedSymbols.filter((s) => shouldIncludeExport(s.getName(), only, ignore));
@@ -5401,8 +5626,47 @@ async function extract(options) {
     try {
       const { declaration, targetSymbol, isTypeOnly } = resolveExportTarget2(symbol, typeChecker);
       if (!declaration) {
-        tracker.status = "skipped";
-        tracker.skipReason = "no-declaration";
+        let externalPackage;
+        const allDecls = [
+          ...targetSymbol.declarations ?? [],
+          ...symbol.declarations ?? []
+        ];
+        for (const decl of allDecls) {
+          const sf = decl.getSourceFile();
+          if (sf?.fileName.includes("node_modules")) {
+            const match = sf.fileName.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+            if (match) {
+              externalPackage = match[1];
+              break;
+            }
+          }
+          if (ts14.isExportSpecifier(decl)) {
+            const exportDecl = decl.parent?.parent;
+            if (exportDecl && ts14.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
+              const moduleText = exportDecl.moduleSpecifier.getText().slice(1, -1);
+              if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
+                externalPackage = moduleText;
+                break;
+              }
+            }
+          }
+        }
+        if (externalPackage) {
+          const externalExport = {
+            id: exportName,
+            name: exportName,
+            kind: "external",
+            source: {
+              package: externalPackage
+            }
+          };
+          exports.push(externalExport);
+          tracker.status = "success";
+          tracker.kind = "external";
+        } else {
+          tracker.status = "skipped";
+          tracker.skipReason = "no-declaration";
+        }
         continue;
       }
       const exp = serializeDeclaration2(declaration, symbol, targetSymbol, exportName, ctx, isTypeOnly);
@@ -5999,6 +6263,7 @@ export {
   isExported,
   isBuiltinGeneric,
   isAnonymous,
+  hasDeprecatedTag,
   groupByVisibility,
   getTypeOrigin,
   getSourceLocation,
@@ -6010,6 +6275,7 @@ export {
   getMemberBadges,
   getJSDocComment,
   getExport,
+  getDeprecationMessage,
   toMarkdown as generateDocs,
   formatTypeParameters,
   formatSchema,
@@ -6018,8 +6284,10 @@ export {
   formatMappedType,
   formatConditionalType,
   formatBadges,
+  findMissingParamDocs,
   findDiscriminatorProperty,
   findAdapter,
+  filterSpec,
   extractTypeParameters,
   extractStandardSchemasFromTs,
   extractStandardSchemasFromProject,
@@ -6041,6 +6309,7 @@ export {
   buildSignatureString,
   buildSchema,
   arktypeAdapter,
+  analyzeSpec,
   TypeRegistry,
   BUILTIN_TYPE_SCHEMAS,
   ARRAY_PROTOTYPE_METHODS

package/package.json

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