@arcteninc/core 0.0.45 → 0.0.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcteninc/core",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -46,6 +46,7 @@
     "ajv": "^8.17.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "ts-json-schema-generator": "^2.4.0",
     "typescript": "^5.9.3",
     "vite": "^7.1.12",
     "vite-plugin-dts": "^4.5.4"

package/scripts/cli-extract-types-auto.ts

@@ -9,6 +9,25 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
 
+// Lazy import for ts-json-schema-generator (optional - falls back to custom serializer if not available)
+let tsJsonSchemaGeneratorModule: any = null;
+let generatorAvailable = false;
+
+async function ensureGeneratorLoaded(): Promise<boolean> {
+  if (generatorAvailable) return true;
+  if (tsJsonSchemaGeneratorModule !== null) return false; // Already tried and failed
+  
+  try {
+    // @ts-ignore - ts-json-schema-generator is optional
+    tsJsonSchemaGeneratorModule = await import('ts-json-schema-generator');
+    generatorAvailable = true;
+    return true;
+  } catch (error) {
+    tsJsonSchemaGeneratorModule = false; // Mark as failed
+    return false;
+  }
+}
+
 // JSON Schema compatible format
 interface JsonSchemaProperty {
   type?: string | string[]; // Can be string, array of strings, or omitted for anyOf/oneOf/$ref
@@ -33,6 +52,7 @@ interface FunctionMetadata {
     type: 'object';
     properties: Record<string, JsonSchemaProperty>;
     required?: string[]; // Array of required parameter names
+    $defs?: Record<string, JsonSchemaProperty>; // Type definitions for recursive types
   };
   returnType?: string;
   isAsync?: boolean;
@@ -552,195 +572,36 @@ function resolveImportPath(
   return null;
 }
 
-// Constants for JSON Schema validation
-// These are actual constants from the JSON Schema specification
-const VALID_JSON_SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array', 'null']);
-
-// Safety limit for serialization depth (only used as a last resort)
-// Note: Cycle detection via 'visited' Set is the primary protection against infinite recursion
-// This is only a fallback safety net for edge cases
-const MAX_SERIALIZATION_DEPTH = 50; // Increased from 10 - legitimate types can be deeply nested
-
-// Note: MAX_TOOL_NAME_LENGTH was removed - we now use proper AST node type checks
-// instead of string length heuristics for better accuracy
-
-/**
- * Type-safe accessors for TypeScript internal APIs
- * These use type guards to safely access properties that aren't in the public API
- */
-
-interface BooleanLiteralType extends ts.Type {
-  intrinsicName: 'true' | 'false';
-}
-
-interface NumberLiteralType extends ts.Type {
-  value: number;
-}
-
-interface StringLiteralType extends ts.Type {
-  value: string;
-}
-
-/**
- * Get boolean literal value from a TypeScript type
- */
-function getBooleanLiteralValue(type: ts.Type): boolean | null {
-  if (type.flags & ts.TypeFlags.BooleanLiteral) {
-    const boolType = type as BooleanLiteralType;
-    return boolType.intrinsicName === 'true';
-  }
-  return null;
-}
-
-/**
- * Get number literal value from a TypeScript type
- */
-function getNumberLiteralValue(type: ts.Type): number | null {
-  if (type.flags & ts.TypeFlags.NumberLiteral) {
-    const numType = type as NumberLiteralType;
-    return numType.value;
-  }
-  return null;
-}
-
-/**
- * Get string literal value from a TypeScript type
- */
-function getStringLiteralValue(type: ts.Type): string | null {
-  if (type.flags & ts.TypeFlags.StringLiteral) {
-    const strType = type as StringLiteralType;
-    return strType.value;
-  }
-  return null;
-}
-
-/**
- * Get type ID safely (for cycle detection)
- * Uses TypeScript's internal API - this is necessary for cycle detection
- * but we wrap it in a function to centralize the unsafe access
- */
-function getTypeId(type: ts.Type): number | undefined {
-  // TypeScript's Type interface doesn't expose 'id' in public API,
-  // but it's available internally and needed for cycle detection.
-  // This is a known limitation when working with TypeScript's compiler API.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return (type as any).id;
-}
-
 /**
- * Serialize a literal type (boolean, number, or string literal) to JSON Schema
- * Returns null if the type is not a literal
+ * Try to get type name and source file for use with ts-json-schema-generator
  */
-function serializeLiteralType(type: ts.Type): JsonSchemaProperty | null {
-  const boolValue = getBooleanLiteralValue(type);
-  if (boolValue !== null) {
-    return { type: 'boolean', const: boolValue };
-  }
-  
-  const numValue = getNumberLiteralValue(type);
-  if (numValue !== null) {
-    return { type: 'number', const: numValue };
-  }
-  
-  const strValue = getStringLiteralValue(type);
-  if (strValue !== null) {
-    return { type: 'string', const: strValue };
-  }
-  
-  return null;
-}
-
-/**
- * Check if a type is a type reference (named type like FilterTreeNode)
- * Uses TypeScript API to determine if it's a named type reference
- */
-function isTypeReference(type: ts.Type, checker: ts.TypeChecker): boolean {
-  const symbol = type.getSymbol();
-  if (!symbol) return false;
-  
-  const name = symbol.getName();
-  if (name.length === 0) return false;
-  
-  // Check if it's a primitive JSON Schema type (should not be treated as type reference)
-  if (VALID_JSON_SCHEMA_TYPES.has(name.toLowerCase())) {
-    return false;
-  }
-  
-  // Check if it's a named type (has declarations and is not a primitive)
-  const declarations = symbol.getDeclarations();
-  if (!declarations || declarations.length === 0) return false;
-  
-  // Check if any declaration is a type alias, interface, or class
-  // This is more reliable than regex pattern matching
-  for (const decl of declarations) {
-    if (
-      ts.isTypeAliasDeclaration(decl) ||
-      ts.isInterfaceDeclaration(decl) ||
-      ts.isClassDeclaration(decl) ||
-      ts.isEnumDeclaration(decl)
-    ) {
-      // Additional check: PascalCase convention (first letter uppercase)
-      // This helps distinguish type references from variables/functions
-      const firstChar = name.charAt(0);
-      return firstChar >= 'A' && firstChar <= 'Z';
-    }
-  }
-  
-  return false;
-}
-
-/**
- * Check if a schema is a fallback 'any' (not a real schema)
- * Uses type checking instead of string length heuristics
- */
-function isFallbackAnySchema(
-  schema: JsonSchemaProperty, 
+function getTypeInfoForGenerator(
   type: ts.Type,
   checker: ts.TypeChecker
-): boolean {
-  // Empty schema {} means "any value" in JSON Schema draft 2020-12
-  // If schema is empty (no keys), it's a fallback "any" schema
-  if (Object.keys(schema).length === 0) {
-    return true;
-  }
-  
-  // If it has properties, anyOf, or items, it's a real schema
-  if (schema.properties || schema.anyOf || schema.items) {
-    return false;
-  }
-  
-  // If it has a type property (and it's not 'any'), it's a real schema
-  if (schema.type && schema.type !== 'any') {
-    return false;
-  }
-  
-  // Check if it's actually a type reference we couldn't resolve
-  // (not a primitive, not an object we processed, etc.)
-  return isTypeReference(type, checker);
-}
-
-/**
- * Resolve type references (type aliases, interfaces) to their actual types
- */
-function resolveTypeReference(
-  type: ts.Type,
-  checker: ts.TypeChecker
-): ts.Type | null {
+): { typeName: string; sourceFile: string } | null {
   const symbol = type.getSymbol();
   if (!symbol) return null;
 
+  const name = symbol.getName();
+  if (!name || name.length === 0) return null;
+
   const declarations = symbol.getDeclarations();
   if (!declarations || declarations.length === 0) return null;
 
-  // Try to get the actual type from the declaration
+  // Find the first declaration that's a type alias, interface, or class
   for (const decl of declarations) {
-    if (ts.isTypeAliasDeclaration(decl) && decl.type) {
-      // Resolve the type alias
-      return checker.getTypeFromTypeNode(decl.type);
-    }
-    if (ts.isInterfaceDeclaration(decl)) {
-      // Get the interface type
-      return checker.getTypeAtLocation(decl);
+    if (
+      ts.isTypeAliasDeclaration(decl) ||
+      ts.isInterfaceDeclaration(decl) ||
+      ts.isClassDeclaration(decl)
+    ) {
+      const sourceFile = decl.getSourceFile();
+      if (sourceFile) {
+        return {
+          typeName: name,
+          sourceFile: sourceFile.fileName,
+        };
+      }
     }
   }
 
@@ -748,406 +609,104 @@ function resolveTypeReference(
 }
 
 /**
- * Serialize a TypeScript type to JSON Schema format
- * Returns: { isOptional, schema }
+ * Serialize a TypeScript type to JSON Schema format using ts-json-schema-generator
+ * Returns: { isOptional, schema } or null if generator not available
+ * Note: This is async and should only be called at top level
  */
-function serializeType(
+async function serializeTypeWithGenerator(
   type: ts.Type,
   checker: ts.TypeChecker,
-  visited = new Set<number>(),
-  depth = 0
-): { isOptional: boolean; schema: JsonSchemaProperty } {
-  const typeString = checker.typeToString(type);
-  
-  if (depth > MAX_SERIALIZATION_DEPTH) {
-    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
-  }
-
-  const typeId = getTypeId(type);
-  if (typeId !== undefined && visited.has(typeId)) {
-    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
-  }
-
-  // Handle primitives
-  if (type.flags & ts.TypeFlags.String) {
-    return { isOptional: false, schema: { type: 'string' } };
-  }
-  if (type.flags & ts.TypeFlags.Number) {
-    return { isOptional: false, schema: { type: 'number' } };
-  }
-  if (type.flags & ts.TypeFlags.Boolean) {
-    return { isOptional: false, schema: { type: 'boolean' } };
-  }
-  
-  // Handle literals using helper function
-  const literalSchema = serializeLiteralType(type);
-  if (literalSchema) {
-    return { isOptional: false, schema: literalSchema };
-  }
-  
-  if (type.flags & ts.TypeFlags.Undefined || type.flags & ts.TypeFlags.Void) {
-    return { isOptional: true, schema: { type: 'null' } };
+  program: ts.Program,
+  configPath: string | undefined,
+  defs?: Record<string, JsonSchemaProperty>
+): Promise<{ isOptional: boolean; schema: JsonSchemaProperty } | null> {
+  // Try to load generator if not already loaded
+  const generatorLoaded = await ensureGeneratorLoaded();
+  if (!generatorLoaded || !tsJsonSchemaGeneratorModule) {
+    return null;
   }
 
-  // Handle union types
-  if (type.isUnion()) {
-    const types = type.types;
-
-    // Separate null, undefined, and other types
-    const hasNull = types.some(t => t.flags & ts.TypeFlags.Null);
-    const hasUndefined = types.some(t => t.flags & ts.TypeFlags.Undefined);
-    const nonNullUndefinedTypes = types.filter(
-      t => !(t.flags & ts.TypeFlags.Null) && !(t.flags & ts.TypeFlags.Undefined)
-    );
-
-    // Check if it's a string literal union (enum) - possibly with null/undefined
-    const stringLiterals = nonNullUndefinedTypes
-      .map(t => getStringLiteralValue(t))
-      .filter((v): v is string => v !== null);
-
-    // If all non-null/undefined types are string literals, use enum
-    if (stringLiterals.length > 0 && stringLiterals.length === nonNullUndefinedTypes.length) {
-      const enumSchema: JsonSchemaProperty = { type: 'string', enum: stringLiterals };
-      
-      // If null or undefined is also present, wrap in anyOf
-      if (hasNull || hasUndefined) {
-        return {
-          isOptional: false,
-          schema: { anyOf: [enumSchema, { type: 'null' }] }
-        };
-      }
-      
-      return {
-        isOptional: false,
-        schema: enumSchema
-      };
-    }
-
-    // Handle optional (T | undefined) - make it optional instead of union
-    if (hasUndefined && nonNullUndefinedTypes.length === 1 && !hasNull) {
-      const result = serializeType(nonNullUndefinedTypes[0], checker, visited, depth + 1);
-      return { isOptional: true, schema: result.schema };
-    }
+  const typeInfo = getTypeInfoForGenerator(type, checker);
+  if (!typeInfo) return null;
+
+  try {
+    // Create generator config
+    const generatorConfig: any = {
+      path: typeInfo.sourceFile,
+      tsconfig: configPath || 'tsconfig.json',
+      type: typeInfo.typeName,
+      expose: 'all',
+      jsDoc: 'extended',
+      topRef: true,
+      skipTypeCheck: true,
+      additionalProperties: false,
+    };
 
-    // Build anyOf array for proper JSON Schema union
-    const anyOf: JsonSchemaProperty[] = [];
+    const generator = tsJsonSchemaGeneratorModule.createGenerator(generatorConfig);
+    const schema = generator.createSchema(typeInfo.typeName);
 
-    // Add null if present
-    if (hasNull) {
-      anyOf.push({ type: 'null' });
+    // Extract $defs if present and merge into our defs
+    if (schema.$defs && defs) {
+      Object.assign(defs, schema.$defs);
     }
 
-    // Add undefined as null (JSON doesn't have undefined)
-    if (hasUndefined) {
-      anyOf.push({ type: 'null' });
-    }
+    // Remove $defs from the schema itself (we'll add it at the top level)
+    const { $defs, ...schemaWithoutDefs } = schema as any;
 
-    // Process non-null/undefined types
-    for (const unionType of nonNullUndefinedTypes) {
-      // Check if it's a primitive type
-      if (unionType.flags & ts.TypeFlags.String) {
-        anyOf.push({ type: 'string' });
-      } else if (unionType.flags & ts.TypeFlags.Number) {
-        anyOf.push({ type: 'number' });
-      } else if (unionType.flags & ts.TypeFlags.Boolean) {
-        anyOf.push({ type: 'boolean' });
-      } else {
-        // Try literal types first (using helper function)
-        const literalSchema = serializeLiteralType(unionType);
-        if (literalSchema) {
-          anyOf.push(literalSchema);
-        } else if (checker.isArrayType(unionType)) {
-        // Handle array types
-        const typeArgs = (unionType as ts.TypeReference).typeArguments;
-        if (typeArgs && typeArgs.length > 0) {
-          const itemResult = serializeType(typeArgs[0], checker, visited, depth + 1);
-          anyOf.push({ type: 'array', items: itemResult.schema });
-        } else {
-          anyOf.push({ type: 'array' });
-        }
-        } else {
-          // Try to serialize the type (handles objects, type references, etc.)
-          // This will recursively resolve type aliases and interfaces
-          try {
-            const refResult = serializeType(unionType, checker, visited, depth + 1);
-            
-            // Check if we got a valid schema (not just 'any' fallback)
-            if (!isFallbackAnySchema(refResult.schema, unionType, checker)) {
-              anyOf.push(refResult.schema);
-            } else {
-              // Try to resolve type reference before giving up
-              const resolvedType = resolveTypeReference(unionType, checker);
-              if (resolvedType) {
-                try {
-                  const resolvedResult = serializeType(resolvedType, checker, visited, depth + 1);
-                  if (!isFallbackAnySchema(resolvedResult.schema, resolvedType, checker)) {
-                    anyOf.push(resolvedResult.schema);
-                  } else {
-                    anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
-                  }
-                } catch (error) {
-                  anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
-                }
-              } else {
-                // It's a type reference we couldn't fully resolve - use empty schema (any value)
-                anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
-              }
-            }
-          } catch (error) {
-            // Fallback for unresolvable types
-            const unionTypeString = checker.typeToString(unionType);
-            console.warn(`Warning: Could not serialize union type: ${unionTypeString}`, error);
-            anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
-          }
-        }
-      }
-    }
-
-    // If we only have one type (plus null/undefined), simplify
-    if (anyOf.length === 1) {
-      return { isOptional: hasNull || hasUndefined, schema: anyOf[0] };
-    }
-
-    // If we have multiple types, use anyOf
-    if (anyOf.length > 1) {
-      // Remove duplicate null entries
-      const uniqueAnyOf = anyOf.filter((schema, index, self) => {
-        if (schema.type === 'null') {
-          return index === self.findIndex(s => s.type === 'null');
-        }
-        return true;
-      });
-
-      return {
-        isOptional: false,
-        schema: { anyOf: uniqueAnyOf }
-      };
-    }
+    // Handle optional (check if type includes undefined)
+    const isOptional = type.flags & ts.TypeFlags.Undefined || 
+      (type.isUnion() && type.types.some(t => t.flags & ts.TypeFlags.Undefined));
 
-    // Fallback
     return {
-      isOptional: false,
-      schema: {} // Empty schema = any value (JSON Schema draft 2020-12)
+      isOptional: !!isOptional,
+      schema: schemaWithoutDefs as JsonSchemaProperty,
     };
+  } catch (error) {
+    // If generator fails, return null (will result in empty schema)
+    return null;
   }
+}
 
-  // Handle intersection types (A & B)
-  if (type.isIntersection()) {
-    const types = type.types;
-    const allProperties: Record<string, JsonSchemaProperty> = {};
-    const allRequired: string[] = [];
-
-    for (const intersectionType of types) {
-      const result = serializeType(intersectionType, checker, visited, depth + 1);
-      if (result.schema.type === 'object' && result.schema.properties) {
-        Object.assign(allProperties, result.schema.properties);
-        if (result.schema.required) {
-          allRequired.push(...result.schema.required);
-        }
-      }
-    }
-
-    if (Object.keys(allProperties).length > 0) {
-      return {
-        isOptional: false,
-        schema: {
-          type: 'object',
-          properties: allProperties,
-          required: Array.from(new Set(allRequired))
-        }
-      };
-    }
-  }
+// Cache for generator results to avoid repeated calls
+const generatorCache = new Map<string, { isOptional: boolean; schema: JsonSchemaProperty }>();
 
-  // Handle arrays
-  if (checker.isArrayType(type)) {
-    const typeArgs = (type as ts.TypeReference).typeArguments;
-    if (typeArgs && typeArgs.length > 0) {
-      const itemResult = serializeType(typeArgs[0], checker, visited, depth + 1);
-      return {
-        isOptional: false,
-        schema: { type: 'array', items: itemResult.schema }
-      };
-    }
-    return { isOptional: false, schema: { type: 'array' } };
+/**
+ * Serialize a TypeScript type to JSON Schema format using ts-json-schema-generator
+ * Only works for named types (interfaces, type aliases, classes)
+ * Returns empty schema for anonymous types
+ */
+async function serializeType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  program: ts.Program | undefined,
+  configPath: string | undefined,
+  defs?: Record<string, JsonSchemaProperty>
+): Promise<{ isOptional: boolean; schema: JsonSchemaProperty }> {
+  if (!program || !configPath) {
+    return { isOptional: false, schema: {} }; // Empty schema = any value
   }
 
-  // Handle objects
-  if (type.flags & ts.TypeFlags.Object) {
-    if (typeId !== undefined) {
-      visited.add(typeId);
-    }
-
-    const properties: Record<string, JsonSchemaProperty> = {};
-    const required: string[] = [];
-    const props = checker.getPropertiesOfType(type);
-
-    if (props.length > 0) {
-      for (const prop of props) {
-        try {
-          const propDeclaration = prop.valueDeclaration || prop.declarations?.[0];
-
-          if (!propDeclaration) {
-            // Skip properties without declarations
-            continue;
-          }
-
-          const propType = checker.getTypeOfSymbolAtLocation(prop, propDeclaration);
-          const isOptional = (prop.flags & ts.SymbolFlags.Optional) !== 0;
-
-          const propResult = serializeType(propType, checker, visited, depth + 1);
-          properties[prop.name] = propResult.schema;
-
-          // Track required properties
-          if (!isOptional && !propResult.isOptional) {
-            required.push(prop.name);
-          }
-        } catch (error) {
-          // Skip properties that can't be serialized
-          console.warn(`Warning: Could not serialize property ${prop.name}`, error);
-        }
-      }
-
-      // Extract index signatures ([key: string]: T)
-      const indexSignatures = checker.getIndexInfosOfType(type);
-      if (indexSignatures && indexSignatures.length > 0) {
-        try {
-          const indexInfo = indexSignatures[0];
-          if (indexInfo.declaration) {
-            const indexType = checker.getTypeAtLocation(indexInfo.declaration);
-            const indexResult = serializeType(indexType, checker, visited, depth + 1);
-            // JSON Schema uses additionalProperties for index signatures
-            if (indexResult.schema.type !== 'any' || indexResult.schema.properties) {
-              // Only set if it's a meaningful type (not just 'any' fallback)
-              if (!isFallbackAnySchema(indexResult.schema, indexType, checker)) {
-                properties['[key: string]'] = indexResult.schema;
-              }
-            }
-          }
-        } catch (error) {
-          // Index signature extraction failed, continue without it
-          console.warn(`Warning: Could not extract index signature`, error);
-        }
-      }
-
-      const schema: JsonSchemaProperty = {
-        type: 'object',
-        properties
-      };
-
-      if (required.length > 0) {
-        schema.required = required;
-      }
-
-      return { isOptional: false, schema };
-    }
+  const typeInfo = getTypeInfoForGenerator(type, checker);
+  if (!typeInfo) {
+    // Anonymous/inline type - can't serialize with generator
+    return { isOptional: false, schema: {} }; // Empty schema = any value
   }
 
-  // Fallback - check type flags to determine if it's a valid JSON Schema type
-  // Valid JSON Schema types: string, number, integer, boolean, object, array, null
-  
-  // Check if it's an enum type (TypeScript enum)
-  if (type.flags & ts.TypeFlags.Enum) {
-    try {
-      const symbol = type.getSymbol();
-      if (symbol) {
-        const enumMembers = checker.getPropertiesOfType(type);
-        if (enumMembers.length > 0) {
-          // Extract enum values - enum members are typically string or number literals
-          const values: (string | number)[] = [];
-          for (const member of enumMembers) {
-            const memberDeclaration = member.valueDeclaration || member.declarations?.[0];
-            if (memberDeclaration) {
-              const memberType = checker.getTypeOfSymbolAtLocation(member, memberDeclaration);
-              const strValue = getStringLiteralValue(memberType);
-              if (strValue !== null) {
-                values.push(strValue);
-              } else {
-                const numValue = getNumberLiteralValue(memberType);
-                if (numValue !== null) {
-                  values.push(numValue);
-                }
-              }
-            }
-          }
-          if (values.length > 0) {
-            // Check if all values are strings or all are numbers
-            const allStrings = values.every(v => typeof v === 'string');
-            const allNumbers = values.every(v => typeof v === 'number');
-            if (allStrings) {
-              return { isOptional: false, schema: { type: 'string', enum: values.filter((v): v is string => typeof v === 'string') } };
-            } else if (allNumbers) {
-              const numberValues = values.filter((v): v is number => typeof v === 'number');
-              return { isOptional: false, schema: { type: 'number', enum: numberValues } };
-            }
-          }
-        }
-      }
-    } catch (error) {
-      console.warn(`Warning: Could not extract enum values for type: ${typeString}`, error);
-    }
-    // If we can't extract enum values, use empty schema (any value)
-    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
-  }
-  
-  // Check if it's a type reference (like InternalFilterType.StringFilter)
-  // Type references that aren't objects/arrays/primitives should use 'any'
-  if (type.flags & ts.TypeFlags.Object) {
-    // Already handled above, but check if it's an empty object type
-    const props = checker.getPropertiesOfType(type);
-    if (props.length === 0) {
-      // Empty object or type reference we can't resolve
-      // Check if typeString suggests it's a named type reference
-      if (typeString && typeString.includes('.')) {
-        return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
-      }
-    }
-  }
-  
-  // Check if typeString is a valid JSON Schema primitive type
-  const lowerTypeString = typeString?.toLowerCase();
-  
-  // If it's a valid JSON Schema type, use it (shouldn't happen here, but safety check)
-  if (lowerTypeString && VALID_JSON_SCHEMA_TYPES.has(lowerTypeString)) {
-    // Type assertion is safe here because VALID_JSON_SCHEMA_TYPES validates the value
-    const validType = lowerTypeString as 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
-    return {
-      isOptional: false,
-      schema: { type: validType }
-    };
-  }
-  
-  // Try to resolve type references before giving up
-  const resolvedType = resolveTypeReference(type, checker);
-  if (resolvedType) {
-    try {
-      const resolvedResult = serializeType(resolvedType, checker, visited, depth + 1);
-      if (!isFallbackAnySchema(resolvedResult.schema, resolvedType, checker)) {
-        return resolvedResult;
-      }
-    } catch (error) {
-      // Resolution failed, continue to fallback
-    }
+  // Check cache first
+  const cacheKey = `${typeInfo.sourceFile}:${typeInfo.typeName}`;
+  if (generatorCache.has(cacheKey)) {
+    return generatorCache.get(cacheKey)!;
   }
 
-  // Handle special type flags
-  if (type.flags & ts.TypeFlags.Never) {
-    return { isOptional: false, schema: { type: 'null' } };
-  }
-  if (type.flags & ts.TypeFlags.Unknown) {
-    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
-  }
-  if (type.flags & ts.TypeFlags.Any) {
-    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
+  // Use generator
+  const result = await serializeTypeWithGenerator(type, checker, program, configPath, defs);
+  if (result) {
+    generatorCache.set(cacheKey, result);
+    return result;
   }
 
-  // For any other unrecognized type, use empty schema instead of invalid type strings
-  // This prevents errors like "type": "InternalFilterType.StringFilter"
-  // Empty schema {} means "allow any value" in JSON Schema draft 2020-12
-  return {
-    isOptional: false,
-    schema: {} // Empty schema = any value (JSON Schema draft 2020-12)
-  };
+  // Generator failed - return empty schema
+  return { isOptional: false, schema: {} }; // Empty schema = any value
 }
 
 /**
@@ -1219,11 +778,13 @@ function extractDefaultValue(
 /**
  * Extract metadata from a function
  */
-function extractFunctionMetadata(
+async function extractFunctionMetadata(
   node: ts.FunctionDeclaration | ts.VariableDeclaration,
   checker: ts.TypeChecker,
-  sourceFile: ts.SourceFile
-): FunctionMetadata | null {
+  sourceFile: ts.SourceFile,
+  program?: ts.Program,
+  configPath?: string
+): Promise<FunctionMetadata | null> {
   let functionNode: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression | null = null;
   let functionName: string;
 
@@ -1286,6 +847,7 @@ function extractFunctionMetadata(
 
   const properties: Record<string, JsonSchemaProperty> = {};
   const required: string[] = [];
+  const defs: Record<string, JsonSchemaProperty> = {}; // Type definitions for recursive types (shared across all parameters)
   
   // Check if async - works for both function declarations and arrow functions
   const isAsync = 
@@ -1317,6 +879,9 @@ function extractFunctionMetadata(
     }
   }
 
+  // Shared defsVisited across all parameters (tracks which definitions we're currently building)
+  const defsVisited = new Set<number>();
+
   for (const param of parameters) {
     const paramName = param.name.getText(sourceFile);
     const hasDefault = param.initializer !== undefined;
@@ -1340,7 +905,9 @@ function extractFunctionMetadata(
         }
       }
       
-      const result = serializeType(type, checker);
+      // Use ts-json-schema-generator for named types only
+      // Anonymous types are not supported - agents can't use them anyway
+      const result = await serializeType(type, checker, program, configPath, defs);
       propSchema = result.schema;
       isOptional = result.isOptional;
     } else {
@@ -1398,14 +965,21 @@ function extractFunctionMetadata(
     }
   }
 
+  const parametersSchema: FunctionMetadata['parameters'] = {
+    type: 'object',
+    properties,
+    required: required.length > 0 ? required : undefined
+  };
+  
+  // Add $defs if we have any type definitions
+  if (Object.keys(defs).length > 0) {
+    parametersSchema.$defs = defs;
+  }
+  
   return {
     name: functionName,
     description,
-    parameters: {
-      type: 'object',
-      properties,
-      required: required.length > 0 ? required : undefined
-    },
+    parameters: parametersSchema,
     returnType,
     isAsync,
   };
@@ -1474,7 +1048,7 @@ async function autoDiscoverAndExtract(projectRoot: string, outputPath: string) {
       if (sourceFile) {
         const result = findFunctionDefinition(toolName, sourceFile, program);
         if (result) {
-          const metadata = extractFunctionMetadata(result.node, checker, result.sourceFile);
+          const metadata = await extractFunctionMetadata(result.node, checker, result.sourceFile, program, configPath);
           if (metadata) {
             functionsMap[toolName] = metadata;
             discoveredFrom.push(path.relative(projectRoot, result.sourceFile.fileName));