@openpkg-ts/sdk 0.31.0 → 0.32.0

package/dist/index.d.ts

@@ -1,43 +1,5 @@
-import { OpenPkg, SpecExportKind } from "@openpkg-ts/spec";
-type FilterCriteria = {
-	/** Filter by kinds */
-	kinds?: SpecExportKind[];
-	/** 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;
-};
-type FilterResult = {
-	/** New spec with only matched exports (immutable) */
-	spec: OpenPkg;
-	/** 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: OpenPkg, criteria: FilterCriteria): FilterResult;
 import { BreakingSeverity, CategorizedBreaking, calculateNextVersion, categorizeBreakingChanges, diffSpec, diffSpec as diffSpec2, MemberChangeInfo, recommendSemverBump, SemverBump, SemverRecommendation, SpecDiff } from "@openpkg-ts/spec";
-import { OpenPkg as OpenPkg2, SpecExport } from "@openpkg-ts/spec";
+import { OpenPkg, SpecExport } from "@openpkg-ts/spec";
 interface DiagnosticItem {
 	exportId: string;
 	exportName: string;
@@ -71,7 +33,7 @@ declare function findMissingParamDocs(exp: SpecExport): string[];
 /**
 * Analyze a spec for quality issues.
 */
-declare function analyzeSpec(spec: OpenPkg2): SpecDiagnostics;
+declare function analyzeSpec(spec: OpenPkg): SpecDiagnostics;
 import { SpecMember } from "@openpkg-ts/spec";
 /**
 * Extract badge strings from a member's visibility and flags.
@@ -82,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 OpenPkg8, SpecExport as SpecExport3, SpecExportKind as SpecExportKind5, SpecType } from "@openpkg-ts/spec";
-import { OpenPkg as OpenPkg3 } 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;
@@ -121,8 +83,8 @@ interface HTMLOptions {
 * const fragment = docs.toHTML({ export: 'greet', fullDocument: false })
 * ```
 */
-declare function toHTML2(spec: OpenPkg3, options?: HTMLOptions): string;
-import { OpenPkg as OpenPkg4, SpecExportKind as SpecExportKind2 } 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;
@@ -170,7 +132,7 @@ interface SimplifiedExample {
 interface SimplifiedExport {
 	id: string;
 	name: string;
-	kind: SpecExportKind2;
+	kind: SpecExportKind;
 	signature: string;
 	description?: string;
 	deprecated: boolean;
@@ -192,7 +154,7 @@ interface SimplifiedSpec {
 	version?: string;
 	description?: string;
 	exports: SimplifiedExport[];
-	byKind: Record<SpecExportKind2, SimplifiedExport[]>;
+	byKind: Record<SpecExportKind, SimplifiedExport[]>;
 	totalExports: number;
 }
 /**
@@ -216,7 +178,7 @@ interface SimplifiedSpec {
 * // { id, name, kind, signature, parameters, returns, ... }
 * ```
 */
-declare function toJSON2(spec: OpenPkg4, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+declare function toJSON2(spec: OpenPkg3, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
 /**
 * Serialize to JSON string with formatting.
 *
@@ -224,10 +186,10 @@ declare function toJSON2(spec: OpenPkg4, options?: JSONOptions): SimplifiedSpec
 * @param options - JSON options plus pretty formatting option
 * @returns JSON string
 */
-declare function toJSONString(spec: OpenPkg4, options?: JSONOptions & {
+declare function toJSONString(spec: OpenPkg3, options?: JSONOptions & {
 	pretty?: boolean;
 }): string;
-import { OpenPkg as OpenPkg5, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg4, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
 interface MarkdownOptions {
 	/** Include frontmatter in output */
 	frontmatter?: boolean;
@@ -248,6 +210,8 @@ 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 (single mode) */
@@ -291,8 +255,8 @@ declare function exportToMarkdown(exp: SpecExport2, options?: MarkdownOptions):
 * // Single * const fnMdx = docs.toMarkdown({ export: 'greet' })
 * ```
 */
-declare function toMarkdown2(spec: OpenPkg5, options?: ExportMarkdownOptions): string;
-import { OpenPkg as OpenPkg6, SpecExportKind as SpecExportKind3 } 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 {
@@ -307,7 +271,7 @@ interface NavOptions {
 	/** Include index pages for groups */
 	includeGroupIndex?: boolean;
 	/** Custom kind labels */
-	kindLabels?: Partial<Record<SpecExportKind3, string>>;
+	kindLabels?: Partial<Record<SpecExportKind2, string>>;
 	/** Sort exports alphabetically */
 	sortAlphabetically?: boolean;
 }
@@ -367,7 +331,7 @@ type DocusaurusSidebar = DocusaurusSidebarItem[];
 * const sidebar = docs.toNavigation({ format: 'docusaurus' })
 * ```
 */
-declare function toNavigation2(spec: OpenPkg6, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+declare function toNavigation2(spec: OpenPkg5, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
 /**
 * Generate Fumadocs meta.json file content.
 *
@@ -381,7 +345,7 @@ declare function toNavigation2(spec: OpenPkg6, options?: NavOptions): GenericNav
 * fs.writeFileSync('docs/api/meta.json', meta)
 * ```
 */
-declare function toFumadocsMetaJSON(spec: OpenPkg6, options?: Omit<NavOptions, "format">): string;
+declare function toFumadocsMetaJSON(spec: OpenPkg5, options?: Omit<NavOptions, "format">): string;
 /**
 * Generate Docusaurus sidebar config.
 *
@@ -395,8 +359,8 @@ declare function toFumadocsMetaJSON(spec: OpenPkg6, options?: Omit<NavOptions, "
 * fs.writeFileSync('sidebars.js', sidebar)
 * ```
 */
-declare function toDocusaurusSidebarJS(spec: OpenPkg6, options?: Omit<NavOptions, "format">): string;
-import { OpenPkg as OpenPkg7, SpecExportKind as SpecExportKind4 } 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;
@@ -440,7 +404,7 @@ interface PagefindRecord {
 interface AlgoliaRecord {
 	objectID: string;
 	name: string;
-	kind: SpecExportKind4;
+	kind: SpecExportKind3;
 	description?: string;
 	signature: string;
 	content: string;
@@ -460,7 +424,7 @@ interface AlgoliaRecord {
 interface SearchRecord {
 	id: string;
 	name: string;
-	kind: SpecExportKind4;
+	kind: SpecExportKind3;
 	signature: string;
 	description?: string;
 	content: string;
@@ -489,7 +453,7 @@ interface SearchIndex {
 * // { records: [...], version: '1.0.0', packageName: 'my-lib' }
 * ```
 */
-declare function toSearchIndex2(spec: OpenPkg7, options?: SearchOptions): SearchIndex;
+declare function toSearchIndex2(spec: OpenPkg6, options?: SearchOptions): SearchIndex;
 /**
 * Generate Pagefind-compatible records.
 *
@@ -505,7 +469,7 @@ declare function toSearchIndex2(spec: OpenPkg7, options?: SearchOptions): Search
 * })
 * ```
 */
-declare function toPagefindRecords2(spec: OpenPkg7, options?: SearchOptions): PagefindRecord[];
+declare function toPagefindRecords2(spec: OpenPkg6, options?: SearchOptions): PagefindRecord[];
 /**
 * Generate Algolia-compatible records.
 *
@@ -519,7 +483,7 @@ declare function toPagefindRecords2(spec: OpenPkg7, options?: SearchOptions): Pa
 * // Upload to Algolia index
 * ```
 */
-declare function toAlgoliaRecords2(spec: OpenPkg7, options?: SearchOptions): AlgoliaRecord[];
+declare function toAlgoliaRecords2(spec: OpenPkg6, options?: SearchOptions): AlgoliaRecord[];
 /**
 * Serialize search index to JSON string.
 *
@@ -533,22 +497,22 @@ declare function toAlgoliaRecords2(spec: OpenPkg7, options?: SearchOptions): Alg
 * fs.writeFileSync('search-index.json', json)
 * ```
 */
-declare function toSearchIndexJSON(spec: OpenPkg7, 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 | OpenPkg8;
+	input: string | OpenPkg7;
 }
 interface DocsInstance {
 	/** The parsed OpenPkg spec */
-	spec: OpenPkg8;
+	spec: OpenPkg7;
 	/** Get an by its ID */
 	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: SpecExportKind5): SpecExport3[];
+	getExportsByKind(kind: SpecExportKind4): SpecExport3[];
 	/** Get all exports */
 	getAllExports(): SpecExport3[];
 	/** Get all type definitions */
@@ -562,7 +526,7 @@ interface DocsInstance {
 	/** Get deprecated exports */
 	getDeprecated(): SpecExport3[];
 	/** Get exports grouped by kind */
-	groupByKind(): Record<SpecExportKind5, SpecExport3[]>;
+	groupByKind(): Record<SpecExportKind4, SpecExport3[]>;
 	/** Render spec or single to MDX */
 	toMarkdown(options?: ExportMarkdownOptions): string;
 	/** Render spec or single to HTML */
@@ -590,7 +554,7 @@ interface DocsInstance {
 * const docs = loadSpec(spec)
 * ```
 */
-declare function loadSpec(spec: OpenPkg8): DocsInstance;
+declare function loadSpec(spec: OpenPkg7): DocsInstance;
 /**
 * Creates a docs instance for querying and rendering API documentation.
 *
@@ -612,11 +576,13 @@ declare function loadSpec(spec: OpenPkg8): DocsInstance;
 * docs.search('hook')
 * ```
 */
-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";
+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.
@@ -706,7 +672,7 @@ declare function buildSignatureString(exp: SpecExport4, sigIndex?: number): stri
 * // { id: 'User', name: 'User', kind: 'interface', ... }
 * ```
 */
-declare function resolveTypeRef(ref: string, spec: OpenPkg9): SpecType2 | undefined;
+declare function resolveTypeRef(ref: string, spec: OpenPkg8): SpecType2 | undefined;
 /**
 * Check if a member is a method (has signatures).
 *
@@ -821,6 +787,48 @@ declare function formatConditionalType(condType: SpecConditionalType): string;
 * ```
 */
 declare function formatMappedType(mappedType: SpecMappedType): string;
+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 */
@@ -898,6 +906,8 @@ 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: OpenPkg10;
@@ -1018,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;
@@ -1081,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

package/dist/index.js

@@ -1,72 +1,3 @@
-// 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;
-    if (!nameMatch && !descMatch)
-      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/diff.ts
 import {
   calculateNextVersion,
@@ -83,7 +14,7 @@ function hasDeprecatedTag(exp) {
 }
 function getDeprecationMessage(exp) {
   const tag = exp.tags?.find((t) => t.name === "deprecated" || t.name === "@deprecated");
-  if (tag && tag.text.trim()) {
+  if (tag?.text.trim()) {
     return tag.text.trim();
   }
   return;
@@ -221,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(" & ");
@@ -894,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}\``);
@@ -918,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("");
@@ -974,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) {
@@ -1013,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 "";
@@ -1050,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("");
@@ -1084,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));
@@ -1131,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)
@@ -1677,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";
 
@@ -2096,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();
@@ -3206,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) {
@@ -3342,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);
@@ -3414,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 } : {}
   };
@@ -3459,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);
@@ -3488,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) => {
@@ -3549,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);
@@ -3622,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);
@@ -3655,7 +3716,7 @@ function serializeEnum(node, ctx) {
     tags,
     source,
     members,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -3695,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);
@@ -3725,7 +3786,7 @@ function serializeFunctionExport(node, ctx) {
     source,
     typeParameters,
     signatures,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -3738,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);
@@ -3818,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 } : {}
   };
 }
@@ -3959,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);
@@ -3981,7 +4042,7 @@ function serializeTypeAlias(node, ctx) {
     source,
     typeParameters,
     schema,
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -4155,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);
@@ -4177,7 +4238,7 @@ function serializeVariable(node, statement, ctx) {
     source,
     schema,
     ...flags ? { flags } : {},
-    ...deprecated ? { deprecated: true } : {},
+    ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -5508,7 +5569,8 @@ async function extract(options) {
     only,
     ignore,
     onProgress,
-    isDtsSource
+    isDtsSource,
+    includePrivate
   } = options;
   const diagnostics = [];
   let exports = [];
@@ -5547,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));
@@ -5563,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/sdk",
-  "version": "0.31.0",
+  "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.31.0",
+    "@openpkg-ts/spec": "^0.32.0",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {