@arcteninc/core 0.0.44 → 0.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcteninc/core",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

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

@@ -33,6 +33,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;
@@ -627,6 +628,48 @@ function getTypeId(type: ts.Type): number | undefined {
   return (type as any).id;
 }
 
+/**
+ * Get a stable name for a type to use in $defs
+ * Returns the type name if it's a named type (interface, type alias, class)
+ * Otherwise returns a generated name based on type ID
+ */
+function getTypeNameForDefs(
+  type: ts.Type,
+  checker: ts.TypeChecker
+): string | null {
+  const symbol = type.getSymbol();
+  if (symbol) {
+    const name = symbol.getName();
+    if (name && name.length > 0) {
+      // Check if it's a named type (not a primitive)
+      const declarations = symbol.getDeclarations();
+      if (declarations && declarations.length > 0) {
+        // Check if it's a type alias, interface, or class
+        for (const decl of declarations) {
+          if (
+            ts.isTypeAliasDeclaration(decl) ||
+            ts.isInterfaceDeclaration(decl) ||
+            ts.isClassDeclaration(decl)
+          ) {
+            return name;
+          }
+        }
+      }
+    }
+  }
+  
+  // Fallback: try to get a name from typeToString
+  const typeString = checker.typeToString(type);
+  // If it's a simple type name (not a complex expression), use it
+  if (typeString && !typeString.includes('|') && !typeString.includes('&') && 
+      !typeString.includes('<') && !typeString.includes('(') &&
+      typeString.length < 50 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(typeString)) {
+    return typeString;
+  }
+  
+  return null;
+}
+
 /**
  * Serialize a literal type (boolean, number, or string literal) to JSON Schema
  * Returns null if the type is not a literal
@@ -698,9 +741,10 @@ function isFallbackAnySchema(
   type: ts.Type,
   checker: ts.TypeChecker
 ): boolean {
-  // If it's not 'any', it's a real schema
-  if (schema.type !== 'any') {
-    return false;
+  // 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
@@ -708,6 +752,11 @@ function isFallbackAnySchema(
     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);
@@ -749,17 +798,36 @@ function serializeType(
   type: ts.Type,
   checker: ts.TypeChecker,
   visited = new Set<number>(),
-  depth = 0
+  depth = 0,
+  defs?: Record<string, JsonSchemaProperty>,
+  defsVisited = new Set<number>()
 ): { isOptional: boolean; schema: JsonSchemaProperty } {
   const typeString = checker.typeToString(type);
   
   if (depth > MAX_SERIALIZATION_DEPTH) {
-    return { isOptional: false, schema: { type: 'any' } };
+    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
   }
 
   const typeId = getTypeId(type);
+  
+  // Handle recursive types with $defs support
   if (typeId !== undefined && visited.has(typeId)) {
-    return { isOptional: false, schema: { type: 'any' } };
+    // Check if this is a named type that we can reference
+    if (defs) {
+      const typeName = getTypeNameForDefs(type, checker);
+      if (typeName) {
+        // If the definition already exists, use $ref
+        if (defs[typeName]) {
+          return { isOptional: false, schema: { $ref: `#/$defs/${typeName}` } };
+        }
+        // If we're currently building this definition, use $ref (circular reference)
+        if (defsVisited.has(typeId)) {
+          return { isOptional: false, schema: { $ref: `#/$defs/${typeName}` } };
+        }
+      }
+    }
+    // Fallback: empty schema for anonymous recursive types
+    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
   }
 
   // Handle primitives
@@ -819,7 +887,7 @@ function serializeType(
 
     // 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);
+      const result = serializeType(nonNullUndefinedTypes[0], checker, visited, depth + 1, defs, defsVisited);
       return { isOptional: true, schema: result.schema };
     }
 
@@ -854,7 +922,7 @@ function serializeType(
         // Handle array types
         const typeArgs = (unionType as ts.TypeReference).typeArguments;
         if (typeArgs && typeArgs.length > 0) {
-          const itemResult = serializeType(typeArgs[0], checker, visited, depth + 1);
+          const itemResult = serializeType(typeArgs[0], checker, visited, depth + 1, defs, defsVisited);
           anyOf.push({ type: 'array', items: itemResult.schema });
         } else {
           anyOf.push({ type: 'array' });
@@ -863,7 +931,7 @@ function serializeType(
           // 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);
+            const refResult = serializeType(unionType, checker, visited, depth + 1, defs, defsVisited);
             
             // Check if we got a valid schema (not just 'any' fallback)
             if (!isFallbackAnySchema(refResult.schema, unionType, checker)) {
@@ -873,25 +941,25 @@ function serializeType(
               const resolvedType = resolveTypeReference(unionType, checker);
               if (resolvedType) {
                 try {
-                  const resolvedResult = serializeType(resolvedType, checker, visited, depth + 1);
+                  const resolvedResult = serializeType(resolvedType, checker, visited, depth + 1, defs, defsVisited);
                   if (!isFallbackAnySchema(resolvedResult.schema, resolvedType, checker)) {
                     anyOf.push(resolvedResult.schema);
                   } else {
-                    anyOf.push({ type: 'any' });
+                    anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
                   }
                 } catch (error) {
-                  anyOf.push({ type: 'any' });
+                  anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
                 }
               } else {
-                // It's a type reference we couldn't fully resolve - use 'any'
-                anyOf.push({ type: 'any' });
+                // 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({ type: 'any' });
+            anyOf.push({}); // Empty schema = any value (JSON Schema draft 2020-12)
           }
         }
       }
@@ -921,7 +989,7 @@ function serializeType(
     // Fallback
     return {
       isOptional: false,
-      schema: { type: 'any' }
+      schema: {} // Empty schema = any value (JSON Schema draft 2020-12)
     };
   }
 
@@ -932,7 +1000,7 @@ function serializeType(
     const allRequired: string[] = [];
 
     for (const intersectionType of types) {
-      const result = serializeType(intersectionType, checker, visited, depth + 1);
+      const result = serializeType(intersectionType, checker, visited, depth + 1, defs, defsVisited);
       if (result.schema.type === 'object' && result.schema.properties) {
         Object.assign(allProperties, result.schema.properties);
         if (result.schema.required) {
@@ -957,7 +1025,7 @@ function serializeType(
   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);
+      const itemResult = serializeType(typeArgs[0], checker, visited, depth + 1, defs, defsVisited);
       return {
         isOptional: false,
         schema: { type: 'array', items: itemResult.schema }
@@ -975,6 +1043,28 @@ function serializeType(
     const properties: Record<string, JsonSchemaProperty> = {};
     const required: string[] = [];
     const props = checker.getPropertiesOfType(type);
+    
+    // Check if this is a named type that should go in $defs
+    const typeName = defs ? getTypeNameForDefs(type, checker) : null;
+    const shouldUseDefs = defs && typeName && props.length > 0;
+    
+    if (shouldUseDefs && typeId !== undefined) {
+      // Check if we're already building this definition
+      if (defsVisited.has(typeId)) {
+        // Circular reference - return $ref
+        return { isOptional: false, schema: { $ref: `#/$defs/${typeName}` } };
+      }
+      
+      // Check if definition already exists
+      if (defs[typeName]) {
+        return { isOptional: false, schema: { $ref: `#/$defs/${typeName}` } };
+      }
+      
+      // Start building the definition
+      defsVisited.add(typeId);
+      // Create placeholder in defs (will be filled below)
+      defs[typeName] = { type: 'object', properties: {}, required: [] };
+    }
 
     if (props.length > 0) {
       for (const prop of props) {
@@ -989,7 +1079,7 @@ function serializeType(
           const propType = checker.getTypeOfSymbolAtLocation(prop, propDeclaration);
           const isOptional = (prop.flags & ts.SymbolFlags.Optional) !== 0;
 
-          const propResult = serializeType(propType, checker, visited, depth + 1);
+          const propResult = serializeType(propType, checker, visited, depth + 1, defs, defsVisited);
           properties[prop.name] = propResult.schema;
 
           // Track required properties
@@ -1009,7 +1099,7 @@ function serializeType(
           const indexInfo = indexSignatures[0];
           if (indexInfo.declaration) {
             const indexType = checker.getTypeAtLocation(indexInfo.declaration);
-            const indexResult = serializeType(indexType, checker, visited, depth + 1);
+            const indexResult = serializeType(indexType, checker, visited, depth + 1, defs, defsVisited);
             // 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)
@@ -1033,6 +1123,13 @@ function serializeType(
         schema.required = required;
       }
 
+      // If we're building a definition, update it and return $ref
+      if (shouldUseDefs && typeName && defs) {
+        defs[typeName] = schema;
+        defsVisited.delete(typeId!);
+        return { isOptional: false, schema: { $ref: `#/$defs/${typeName}` } };
+      }
+
       return { isOptional: false, schema };
     }
   }
@@ -1080,8 +1177,8 @@ function serializeType(
     } catch (error) {
       console.warn(`Warning: Could not extract enum values for type: ${typeString}`, error);
     }
-    // If we can't extract enum values, use 'any'
-    return { isOptional: false, schema: { type: 'any' } };
+    // 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)
@@ -1093,7 +1190,7 @@ function serializeType(
       // 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: { type: 'any' } };
+        return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
       }
     }
   }
@@ -1115,7 +1212,7 @@ function serializeType(
   const resolvedType = resolveTypeReference(type, checker);
   if (resolvedType) {
     try {
-      const resolvedResult = serializeType(resolvedType, checker, visited, depth + 1);
+      const resolvedResult = serializeType(resolvedType, checker, visited, depth + 1, defs, defsVisited);
       if (!isFallbackAnySchema(resolvedResult.schema, resolvedType, checker)) {
         return resolvedResult;
       }
@@ -1129,17 +1226,18 @@ function serializeType(
     return { isOptional: false, schema: { type: 'null' } };
   }
   if (type.flags & ts.TypeFlags.Unknown) {
-    return { isOptional: false, schema: { type: 'any' } };
+    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
   }
   if (type.flags & ts.TypeFlags.Any) {
-    return { isOptional: false, schema: { type: 'any' } };
+    return { isOptional: false, schema: {} }; // Empty schema = any value (JSON Schema draft 2020-12)
   }
 
-  // For any other unrecognized type, use 'any' instead of invalid type strings
+  // 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: { type: 'any' }
+    schema: {} // Empty schema = any value (JSON Schema draft 2020-12)
   };
 }
 
@@ -1279,6 +1377,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 = 
@@ -1310,6 +1409,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;
@@ -1333,11 +1435,14 @@ function extractFunctionMetadata(
         }
       }
       
-      const result = serializeType(type, checker);
+      // Use a fresh visited set for each parameter to avoid false cycle detection
+      // but share defs and defsVisited so recursive types are defined once
+      const visited = new Set<number>();
+      const result = serializeType(type, checker, visited, 0, defs, defsVisited);
       propSchema = result.schema;
       isOptional = result.isOptional;
     } else {
-      propSchema = { type: 'any' };
+      propSchema = {}; // Empty schema = any value (JSON Schema draft 2020-12)
     }
 
     // Check if parameter has default value or question mark
@@ -1391,14 +1496,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,
   };