@arcteninc/core 0.0.45 → 0.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcteninc/core",
-  "version": "0.0.45",
+  "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
@@ -755,7 +798,9 @@ 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);
   
@@ -764,7 +809,24 @@ function serializeType(
   }
 
   const typeId = getTypeId(type);
+  
+  // Handle recursive types with $defs support
   if (typeId !== undefined && visited.has(typeId)) {
+    // 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)
   }
 
@@ -825,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 };
     }
 
@@ -860,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' });
@@ -869,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)) {
@@ -879,7 +941,7 @@ 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 {
@@ -938,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) {
@@ -963,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 }
@@ -981,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) {
@@ -995,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
@@ -1015,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)
@@ -1039,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 };
     }
   }
@@ -1121,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;
       }
@@ -1286,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 = 
@@ -1317,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;
@@ -1340,7 +1435,10 @@ 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 {
@@ -1398,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,
   };