@openpkg-ts/extract 0.13.0 → 0.14.1

package/dist/src/index.d.ts

@@ -8,24 +8,17 @@ declare class TypeRegistry {
 	has(id: string): boolean;
 	getAll(): SpecType[];
 	/**
-	* Register a type from a ts.Type, extracting its structure.
+	* Register a type from a ts.Type (lightweight stub).
 	* Returns the type ID if registered, undefined if skipped.
 	*/
 	registerType(type: ts.Type, checker: ts.TypeChecker, exportedIds: Set<string>): string | undefined;
-	private buildSpecType;
 	/**
-	* Build a shallow schema for registry types (no deep recursion).
-	* Only captures top-level structure with $refs.
+	* Build a lightweight stub type (no deep schema extraction).
 	*/
-	private buildShallowSchema;
-	/**
-	* Extract shallow members for classes/interfaces.
-	* Only captures property names and simple type info.
-	*/
-	private extractShallowMembers;
+	private buildStubType;
 	registerFromSymbol(symbol: ts.Symbol, checker: ts.TypeChecker): SpecType | undefined;
 }
-import { SpecExample, SpecSource, SpecTag } from "@openpkg-ts/spec";
+import { SpecExample, SpecSource, SpecTag, SpecTypeParameter } from "@openpkg-ts/spec";
 import ts2 from "typescript";
 declare function getJSDocComment(node: ts2.Node): {
 	description?: string;
@@ -33,6 +26,23 @@ declare function getJSDocComment(node: ts2.Node): {
 	examples: SpecExample[];
 };
 declare function getSourceLocation(node: ts2.Node, sourceFile: ts2.SourceFile): SpecSource;
+/**
+* Get description for a destructured parameter property from JSDoc @param tags.
+* Matches patterns like:
+* - @param paramName - exact match
+* - @param opts.paramName - dotted notation with alias
+* - @param {type} paramName - type annotation format
+*/
+declare function getParamDescription(propertyName: string, jsdocTags: readonly ts2.JSDocTag[], inferredAlias?: string): string | undefined;
+type DeclarationWithTypeParams = ts2.FunctionDeclaration | ts2.ClassDeclaration | ts2.InterfaceDeclaration | ts2.TypeAliasDeclaration | ts2.MethodDeclaration | ts2.ArrowFunction;
+/**
+* Extract type parameters from declarations like `<T extends Base, K = Default>`
+*/
+declare function extractTypeParameters(node: DeclarationWithTypeParams, checker: ts2.TypeChecker): SpecTypeParameter[] | undefined;
+/**
+* Check if a symbol is marked as deprecated via @deprecated JSDoc tag.
+*/
+declare function isSymbolDeprecated(symbol: ts2.Symbol | undefined): boolean;
 import { OpenPkg } from "@openpkg-ts/spec";
 interface ExtractOptions {
 	entryFile: string;
@@ -42,6 +52,8 @@ interface ExtractOptions {
 	maxExternalTypeDepth?: number;
 	resolveExternalTypes?: boolean;
 	schemaExtraction?: "static" | "hybrid";
+	/** Include $schema URL in output */
+	includeSchema?: boolean;
 }
 interface ExtractResult {
 	spec: OpenPkg;
@@ -50,6 +62,8 @@ interface ExtractResult {
 interface Diagnostic {
 	message: string;
 	severity: "error" | "warning" | "info";
+	code?: string;
+	suggestion?: string;
 	location?: {
 		file?: string;
 		line?: number;
@@ -71,35 +85,135 @@ interface ProgramResult {
 	configPath?: string;
 }
 declare function createProgram({ entryFile, baseDir, content }: ProgramOptions): ProgramResult;
-import { SpecSchema } from "@openpkg-ts/spec";
-import ts4 from "typescript";
-type SchemaAdapter = {
-	name: string;
-	detect: (node: ts4.Node, checker: ts4.TypeChecker) => boolean;
-	extract: (node: ts4.Node, checker: ts4.TypeChecker) => SpecSchema | null;
-};
+import * as TS from "typescript";
+/**
+* A schema adapter can detect and extract output types from a specific
+* schema validation library.
+*/
+interface SchemaAdapter {
+	/** Unique identifier for this adapter */
+	readonly id: string;
+	/** npm package name(s) this adapter handles */
+	readonly packages: readonly string[];
+	/**
+	* Check if a type matches this adapter's schema library.
+	* Should be fast - called for every export.
+	*/
+	matches(type: TS.Type, checker: TS.TypeChecker): boolean;
+	/**
+	* Extract the output type from a schema type.
+	* Returns null if extraction fails.
+	*/
+	extractOutputType(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
+	/**
+	* Extract the input type from a schema type (optional).
+	* Useful for transforms where input differs from output.
+	*/
+	extractInputType?(type: TS.Type, checker: TS.TypeChecker): TS.Type | null;
+}
+/**
+* Result of schema type extraction
+*/
+interface SchemaExtractionResult {
+	/** The adapter that matched */
+	adapter: SchemaAdapter;
+	/** The extracted output type */
+	outputType: TS.Type;
+	/** The extracted input type (if different from output) */
+	inputType?: TS.Type;
+}
+/**
+* Utility: Check if type is an object type reference (has type arguments)
+*/
+declare function isTypeReference(type: TS.Type): type is TS.TypeReference;
+/**
+* Utility: Remove undefined/null from a union type
+*/
+declare function getNonNullableType(type: TS.Type): TS.Type;
 declare function registerAdapter(adapter: SchemaAdapter): void;
-declare function findAdapter(node: ts4.Node, checker: ts4.TypeChecker): SchemaAdapter | undefined;
-declare function isSchemaType(node: ts4.Node, checker: ts4.TypeChecker): boolean;
-declare function extractSchemaType(node: ts4.Node, checker: ts4.TypeChecker): SpecSchema | null;
+declare function findAdapter(type: TS.Type, checker: TS.TypeChecker): SchemaAdapter | undefined;
+declare function isSchemaType(type: TS.Type, checker: TS.TypeChecker): boolean;
+declare function extractSchemaType(type: TS.Type, checker: TS.TypeChecker): SchemaExtractionResult | null;
 declare const arktypeAdapter: SchemaAdapter;
 declare const typeboxAdapter: SchemaAdapter;
 declare const valibotAdapter: SchemaAdapter;
 declare const zodAdapter: SchemaAdapter;
-import { SpecSchema as SpecSchema2 } from "@openpkg-ts/spec";
-import ts5 from "typescript";
-interface StandardSchemaResult {
-	schema: SpecSchema2;
+/**
+* Standard JSON Schema v1 interface (minimal for detection).
+*/
+interface StandardJSONSchemaV1 {
+	"~standard": {
+		version: number;
+		vendor: string;
+		jsonSchema?: {
+			output: (target?: string) => Record<string, unknown>;
+			input?: (target?: string) => Record<string, unknown>;
+		};
+	};
+}
+/**
+* Result of extracting Standard Schema from an export.
+*/
+interface StandardSchemaExtractionResult {
+	exportName: string;
 	vendor: string;
+	outputSchema: Record<string, unknown>;
+	inputSchema?: Record<string, unknown>;
+}
+/**
+* Options for runtime Standard Schema extraction.
+*/
+interface ExtractStandardSchemasOptions {
+	/** Timeout in milliseconds (default: 10000) */
+	timeout?: number;
+	/** JSON Schema target version (default: 'draft-2020-12') */
+	target?: "draft-2020-12" | "draft-07" | "openapi-3.0";
 }
-declare function extractStandardSchemas(_program: ts5.Program, _entryFile: string): StandardSchemaResult[];
+/**
+* Result of Standard Schema extraction.
+*/
+interface StandardSchemaExtractionOutput {
+	schemas: Map<string, StandardSchemaExtractionResult>;
+	errors: string[];
+}
+/**
+* Check if an object implements StandardJSONSchemaV1.
+* This is a static type guard - doesn't require runtime.
+*/
+declare function isStandardJSONSchema(obj: unknown): obj is StandardJSONSchemaV1;
+/**
+* Resolve compiled JS path from TypeScript source.
+* Tries common output locations: dist/, build/, lib/, same dir.
+*/
+declare function resolveCompiledPath(tsPath: string, baseDir: string): string | null;
+/**
+* Extract Standard Schema JSON Schemas from a compiled JS module.
+*
+* **Security Note**: This executes the module in a subprocess.
+* Only use with trusted code (user's own packages).
+*
+* @param compiledJsPath - Path to compiled .js file
+* @param options - Extraction options
+* @returns Extraction results with schemas and any errors
+*/
+declare function extractStandardSchemas(compiledJsPath: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
+/**
+* Extract Standard Schema from a TypeScript project.
+*
+* Convenience function that resolves compiled JS and extracts schemas.
+*
+* @param entryFile - TypeScript entry file path
+* @param baseDir - Project base directory
+* @param options - Extraction options
+*/
+declare function extractStandardSchemasFromProject(entryFile: string, baseDir: string, options?: ExtractStandardSchemasOptions): Promise<StandardSchemaExtractionOutput>;
 import { SpecExport } from "@openpkg-ts/spec";
-import ts7 from "typescript";
-import ts6 from "typescript";
+import ts5 from "typescript";
+import ts4 from "typescript";
 interface SerializerContext {
-	typeChecker: ts6.TypeChecker;
-	program: ts6.Program;
-	sourceFile: ts6.SourceFile;
+	typeChecker: ts4.TypeChecker;
+	program: ts4.Program;
+	sourceFile: ts4.SourceFile;
 	maxTypeDepth: number;
 	maxExternalTypeDepth: number;
 	currentDepth: number;
@@ -107,37 +221,39 @@ interface SerializerContext {
 	typeRegistry: TypeRegistry;
 	exportedIds: Set<string>;
 	/** Track visited types to prevent infinite recursion */
-	visitedTypes: Set<ts6.Type>;
+	visitedTypes: Set<ts4.Type>;
 }
-declare function serializeClass(node: ts7.ClassDeclaration, ctx: SerializerContext): SpecExport | null;
+declare function serializeClass(node: ts5.ClassDeclaration, ctx: SerializerContext): SpecExport | null;
 import { SpecExport as SpecExport2 } from "@openpkg-ts/spec";
-import ts8 from "typescript";
-declare function serializeEnum(node: ts8.EnumDeclaration, ctx: SerializerContext): SpecExport2 | null;
+import ts6 from "typescript";
+declare function serializeEnum(node: ts6.EnumDeclaration, ctx: SerializerContext): SpecExport2 | null;
 import { SpecExport as SpecExport3 } from "@openpkg-ts/spec";
-import ts9 from "typescript";
-declare function serializeFunctionExport(node: ts9.FunctionDeclaration | ts9.ArrowFunction, ctx: SerializerContext): SpecExport3 | null;
+import ts7 from "typescript";
+declare function serializeFunctionExport(node: ts7.FunctionDeclaration | ts7.ArrowFunction, ctx: SerializerContext): SpecExport3 | null;
 import { SpecExport as SpecExport4 } from "@openpkg-ts/spec";
-import ts10 from "typescript";
-declare function serializeInterface(node: ts10.InterfaceDeclaration, ctx: SerializerContext): SpecExport4 | null;
+import ts8 from "typescript";
+declare function serializeInterface(node: ts8.InterfaceDeclaration, ctx: SerializerContext): SpecExport4 | null;
 import { SpecExport as SpecExport5 } from "@openpkg-ts/spec";
-import ts11 from "typescript";
-declare function serializeTypeAlias(node: ts11.TypeAliasDeclaration, ctx: SerializerContext): SpecExport5 | null;
+import ts9 from "typescript";
+declare function serializeTypeAlias(node: ts9.TypeAliasDeclaration, ctx: SerializerContext): SpecExport5 | null;
 import { SpecExport as SpecExport6 } from "@openpkg-ts/spec";
-import ts12 from "typescript";
-declare function serializeVariable(node: ts12.VariableDeclaration, statement: ts12.VariableStatement, ctx: SerializerContext): SpecExport6 | null;
-import ts13 from "typescript";
-declare function formatTypeReference(type: ts13.Type, checker: ts13.TypeChecker): string;
-declare function collectReferencedTypes(type: ts13.Type, checker: ts13.TypeChecker, visited?: Set<string>): string[];
+import ts10 from "typescript";
+declare function serializeVariable(node: ts10.VariableDeclaration, statement: ts10.VariableStatement, ctx: SerializerContext): SpecExport6 | null;
 import { SpecSignatureParameter } from "@openpkg-ts/spec";
-import ts14 from "typescript";
-declare function extractParameters(signature: ts14.Signature, ctx: SerializerContext): SpecSignatureParameter[];
+import ts11 from "typescript";
+declare function extractParameters(signature: ts11.Signature, ctx: SerializerContext): SpecSignatureParameter[];
 /**
 * Recursively register types referenced by a ts.Type.
 * Uses ctx.visitedTypes to prevent infinite recursion on circular types.
 */
-declare function registerReferencedTypes(type: ts14.Type, ctx: SerializerContext): void;
-import { SpecSchema as SpecSchema3 } from "@openpkg-ts/spec";
-import ts15 from "typescript";
+declare function registerReferencedTypes(type: ts11.Type, ctx: SerializerContext, depth?: number): void;
+import { SpecSchema } from "@openpkg-ts/spec";
+import ts12 from "typescript";
+/**
+* Built-in type schemas with JSON Schema format hints.
+* Used for types that have specific serialization formats.
+*/
+declare const BUILTIN_TYPE_SCHEMAS: Record<string, SpecSchema>;
 /**
 * Check if a name is a primitive type
 */
@@ -149,13 +265,41 @@ declare function isBuiltinGeneric(name: string): boolean;
 /**
 * Check if a type is anonymous (no meaningful symbol name)
 */
-declare function isAnonymous(type: ts15.Type): boolean;
+declare function isAnonymous(type: ts12.Type): boolean;
 /**
 * Build a structured SpecSchema from a TypeScript type.
 * Uses $ref for named types and typeArguments for generics.
 */
-declare function buildSchema(type: ts15.Type, checker: ts15.TypeChecker, ctx?: SerializerContext, _depth?: number): SpecSchema3;
-import ts16 from "typescript";
-declare function isExported(node: ts16.Node): boolean;
-declare function getNodeName(node: ts16.Node): string | undefined;
-export { zodAdapter, valibotAdapter, typeboxAdapter, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, registerReferencedTypes, registerAdapter, isSchemaType, isPrimitiveName, isExported, isBuiltinGeneric, isAnonymous, getSourceLocation, getNodeName, getJSDocComment, formatTypeReference, findAdapter, extractStandardSchemas, extractSchemaType, extractParameters, extract, createProgram, collectReferencedTypes, buildSchema, arktypeAdapter, TypeRegistry, StandardSchemaResult, SerializerContext, SchemaAdapter, ProgramResult, ProgramOptions, ExtractResult, ExtractOptions, Diagnostic };
+declare function buildSchema(type: ts12.Type, checker: ts12.TypeChecker, ctx?: SerializerContext, _depth?: number): SpecSchema;
+/**
+* Check if a schema is a pure $ref (only has $ref property)
+*/
+declare function isPureRefSchema(schema: SpecSchema): schema is {
+	$ref: string;
+};
+/**
+* Add description to a schema, handling $ref properly.
+* For pure $ref schemas, wraps in allOf to preserve the reference.
+*/
+declare function withDescription(schema: SpecSchema, description: string): SpecSchema;
+/**
+* Check if a schema represents the 'any' type
+*/
+declare function schemaIsAny(schema: SpecSchema): boolean;
+/**
+* Deep equality comparison for schemas
+*/
+declare function schemasAreEqual(left: SpecSchema, right: SpecSchema): boolean;
+/**
+* Remove duplicate schemas from an array while preserving order.
+*/
+declare function deduplicateSchemas(schemas: SpecSchema[]): SpecSchema[];
+/**
+* Find a discriminator property in a union of object types (tagged union pattern).
+* A valid discriminator has a unique literal value in each union member.
+*/
+declare function findDiscriminatorProperty(unionTypes: ts12.Type[], checker: ts12.TypeChecker): string | undefined;
+import ts13 from "typescript";
+declare function isExported(node: ts13.Node): boolean;
+declare function getNodeName(node: ts13.Node): string | undefined;
+export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveCompiledPath, registerReferencedTypes, registerAdapter, isTypeReference, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isPrimitiveName, isExported, isBuiltinGeneric, isAnonymous, getSourceLocation, getParamDescription, getNonNullableType, getNodeName, getJSDocComment, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromProject, extractStandardSchemas, extractSchemaType, extractParameters, extract, deduplicateSchemas, createProgram, buildSchema, arktypeAdapter, TypeRegistry, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SerializerContext, SchemaExtractionResult, SchemaAdapter, ProgramResult, ProgramOptions, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, Diagnostic, BUILTIN_TYPE_SCHEMAS };