@openpkg-ts/sdk 0.30.1 → 0.31.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,77 @@
+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";
+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: OpenPkg2): SpecDiagnostics;
 import { SpecMember } from "@openpkg-ts/spec";
 /**
 * Extract badge strings from a member's visibility and flags.
@@ -9,8 +82,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 OpenPkg8, SpecExport as SpecExport3, SpecExportKind as SpecExportKind5, SpecType } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg3 } from "@openpkg-ts/spec";
 interface HTMLOptions {
 	/** Page title override */
 	title?: string;
@@ -24,6 +97,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 +121,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: OpenPkg3, options?: HTMLOptions): string;
+import { OpenPkg as OpenPkg4, SpecExportKind as SpecExportKind2 } 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 */
@@ -93,7 +170,7 @@ interface SimplifiedExample {
 interface SimplifiedExport {
 	id: string;
 	name: string;
-	kind: SpecExportKind;
+	kind: SpecExportKind2;
 	signature: string;
 	description?: string;
 	deprecated: boolean;
@@ -115,7 +192,7 @@ interface SimplifiedSpec {
 	version?: string;
 	description?: string;
 	exports: SimplifiedExport[];
-	byKind: Record<SpecExportKind, SimplifiedExport[]>;
+	byKind: Record<SpecExportKind2, SimplifiedExport[]>;
 	totalExports: number;
 }
 /**
@@ -139,7 +216,7 @@ interface SimplifiedSpec {
 * // { id, name, kind, signature, parameters, returns, ... }
 * ```
 */
-declare function toJSON2(spec: OpenPkg2, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
+declare function toJSON2(spec: OpenPkg4, options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
 /**
 * Serialize to JSON string with formatting.
 *
@@ -147,10 +224,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: OpenPkg4, options?: JSONOptions & {
 	pretty?: boolean;
 }): string;
-import { OpenPkg as OpenPkg3, SpecExport } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg5, SpecExport as SpecExport2 } from "@openpkg-ts/spec";
 interface MarkdownOptions {
 	/** Include frontmatter in output */
 	frontmatter?: boolean;
@@ -173,8 +250,10 @@ interface MarkdownOptions {
 	headingOffset?: 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 +271,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 +291,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: OpenPkg5, options?: ExportMarkdownOptions): string;
+import { OpenPkg as OpenPkg6, SpecExportKind as SpecExportKind3 } from "@openpkg-ts/spec";
 type NavFormat = "fumadocs" | "docusaurus" | "generic";
 type GroupBy = "kind" | "module" | "tag" | "none";
 interface NavOptions {
@@ -228,7 +307,7 @@ interface NavOptions {
 	/** Include index pages for groups */
 	includeGroupIndex?: boolean;
 	/** Custom kind labels */
-	kindLabels?: Partial<Record<SpecExportKind2, string>>;
+	kindLabels?: Partial<Record<SpecExportKind3, string>>;
 	/** Sort exports alphabetically */
 	sortAlphabetically?: boolean;
 }
@@ -288,7 +367,7 @@ type DocusaurusSidebar = DocusaurusSidebarItem[];
 * const sidebar = docs.toNavigation({ format: 'docusaurus' })
 * ```
 */
-declare function toNavigation2(spec: OpenPkg4, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
+declare function toNavigation2(spec: OpenPkg6, options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
 /**
 * Generate Fumadocs meta.json file content.
 *
@@ -302,7 +381,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: OpenPkg6, options?: Omit<NavOptions, "format">): string;
 /**
 * Generate Docusaurus sidebar config.
 *
@@ -316,8 +395,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: OpenPkg6, options?: Omit<NavOptions, "format">): string;
+import { OpenPkg as OpenPkg7, SpecExportKind as SpecExportKind4 } from "@openpkg-ts/spec";
 interface SearchOptions {
 	/** Base URL for search result links */
 	baseUrl?: string;
@@ -361,7 +440,7 @@ interface PagefindRecord {
 interface AlgoliaRecord {
 	objectID: string;
 	name: string;
-	kind: SpecExportKind3;
+	kind: SpecExportKind4;
 	description?: string;
 	signature: string;
 	content: string;
@@ -381,7 +460,7 @@ interface AlgoliaRecord {
 interface SearchRecord {
 	id: string;
 	name: string;
-	kind: SpecExportKind3;
+	kind: SpecExportKind4;
 	signature: string;
 	description?: string;
 	content: string;
@@ -410,7 +489,7 @@ interface SearchIndex {
 * // { records: [...], version: '1.0.0', packageName: 'my-lib' }
 * ```
 */
-declare function toSearchIndex2(spec: OpenPkg5, options?: SearchOptions): SearchIndex;
+declare function toSearchIndex2(spec: OpenPkg7, options?: SearchOptions): SearchIndex;
 /**
 * Generate Pagefind-compatible records.
 *
@@ -426,7 +505,7 @@ declare function toSearchIndex2(spec: OpenPkg5, options?: SearchOptions): Search
 * })
 * ```
 */
-declare function toPagefindRecords2(spec: OpenPkg5, options?: SearchOptions): PagefindRecord[];
+declare function toPagefindRecords2(spec: OpenPkg7, options?: SearchOptions): PagefindRecord[];
 /**
 * Generate Algolia-compatible records.
 *
@@ -440,7 +519,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: OpenPkg7, options?: SearchOptions): AlgoliaRecord[];
 /**
 * Serialize search index to JSON string.
 *
@@ -454,36 +533,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: OpenPkg7, options?: SearchOptions & {
 	pretty?: boolean;
 }): string;
 interface LoadOptions {
 	/** Path to openpkg.json file or the spec object directly */
-	input: string | OpenPkg6;
+	input: string | OpenPkg8;
 }
 interface DocsInstance {
 	/** The parsed OpenPkg spec */
-	spec: OpenPkg6;
+	spec: OpenPkg8;
 	/** 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: SpecExportKind5): 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<SpecExportKind5, SpecExport3[]>;
 	/** Render spec or single to MDX */
 	toMarkdown(options?: ExportMarkdownOptions): string;
 	/** Render spec or single to HTML */
@@ -511,7 +590,7 @@ interface DocsInstance {
 * const docs = loadSpec(spec)
 * ```
 */
-declare function loadSpec(spec: OpenPkg6): DocsInstance;
+declare function loadSpec(spec: OpenPkg8): DocsInstance;
 /**
 * Creates a docs instance for querying and rendering API documentation.
 *
@@ -533,8 +612,8 @@ 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 | 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;
@@ -613,7 +692,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 +706,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: OpenPkg9): SpecType2 | undefined;
 /**
 * Check if a member is a method (has signatures).
 *
@@ -742,7 +821,7 @@ declare function formatConditionalType(condType: SpecConditionalType): string;
 * ```
 */
 declare function formatMappedType(mappedType: SpecMappedType): string;
-import { SpecExport as SpecExport4, SpecType as SpecType3 } from "@openpkg-ts/spec";
+import { SpecExport as SpecExport5, SpecType as SpecType3 } from "@openpkg-ts/spec";
 interface GetExportOptions {
 	/** Entry point file path */
 	entryFile: string;
@@ -757,7 +836,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 +877,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;
@@ -821,7 +900,7 @@ interface ExtractOptions {
 	isDtsSource?: boolean;
 }
 interface ExtractResult {
-	spec: OpenPkg8;
+	spec: OpenPkg10;
 	diagnostics: Diagnostic[];
 	forgottenExports?: ForgottenExport[];
 	/** Metadata about runtime schema extraction (when schemaExtraction: 'hybrid') */
@@ -1227,24 +1306,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 +1400,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 +1431,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 +1465,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

@@ -1,3 +1,72 @@
+// 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,
@@ -6,6 +75,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 && 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 = [];
@@ -519,10 +664,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 +815,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])
@@ -1018,6 +1173,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 +1206,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);
@@ -4593,6 +4755,15 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
   const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts12.SyntaxKind.ExportSpecifier) || declarations[0];
   if (!declaration)
     return null;
+  if (ts12.isSourceFile(declaration)) {
+    return {
+      name,
+      kind: "namespace",
+      file: path2.relative(path2.dirname(entryFile), declaration.fileName),
+      line: 1,
+      reexport: true
+    };
+  }
   const kind = getExportKind(declaration, checker.getTypeAtLocation(declaration));
   const sourceFile = declaration.getSourceFile();
   const { line } = sourceFile.getLineAndCharacterOfPosition(declaration.getStart());
@@ -4610,6 +4781,9 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
   };
 }
 function getExportKind(declaration, type) {
+  if (ts12.isSourceFile(declaration)) {
+    return "namespace";
+  }
   if (ts12.isFunctionDeclaration(declaration) || ts12.isFunctionExpression(declaration)) {
     return "function";
   }
@@ -5987,6 +6161,7 @@ export {
   isExported,
   isBuiltinGeneric,
   isAnonymous,
+  hasDeprecatedTag,
   groupByVisibility,
   getTypeOrigin,
   getSourceLocation,
@@ -5998,6 +6173,7 @@ export {
   getMemberBadges,
   getJSDocComment,
   getExport,
+  getDeprecationMessage,
   toMarkdown as generateDocs,
   formatTypeParameters,
   formatSchema,
@@ -6006,8 +6182,10 @@ export {
   formatMappedType,
   formatConditionalType,
   formatBadges,
+  findMissingParamDocs,
   findDiscriminatorProperty,
   findAdapter,
+  filterSpec,
   extractTypeParameters,
   extractStandardSchemasFromTs,
   extractStandardSchemasFromProject,
@@ -6029,6 +6207,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.1",
+  "version": "0.31.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.31.0",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {