musubi-sdd 5.1.0 → 5.6.1

package/src/agents/schema-generator.js

@@ -1,14 +1,14 @@
 /**
  * MUSUBI Schema Generator
- * 
+ *
  * Generates JSON Schema from various sources including
  * JavaScript functions, TypeScript types, and JSDoc comments.
- * 
+ *
  * @module agents/schema-generator
  */
 
 const fs = require('fs');
-const path = require('path');
+const _path = require('path');
 
 /**
  * @typedef {Object} SchemaGeneratorOptions
@@ -29,7 +29,7 @@ class SchemaGenerator {
     this.includeExamples = options.includeExamples ?? true;
     this.defaultType = options.defaultType ?? 'string';
   }
-  
+
   /**
    * Generate schema from a function
    * @param {Function} fn
@@ -39,10 +39,10 @@ class SchemaGenerator {
     const fnString = fn.toString();
     const params = this.extractParameters(fnString);
     const jsdoc = this.extractJSDoc(fnString);
-    
+
     return this.buildSchema(params, jsdoc);
   }
-  
+
   /**
    * Generate schema from JSDoc comment
    * @param {string} jsdoc
@@ -52,7 +52,7 @@ class SchemaGenerator {
     const parsed = this.parseJSDoc(jsdoc);
     return this.buildSchemaFromParsed(parsed);
   }
-  
+
   /**
    * Generate schema from a class method
    * @param {Object} instance - Class instance
@@ -66,7 +66,7 @@ class SchemaGenerator {
     }
     return this.fromFunction(method.bind(instance));
   }
-  
+
   /**
    * Generate schema from file (extracts functions)
    * @param {string} filePath
@@ -76,14 +76,14 @@ class SchemaGenerator {
     const content = fs.readFileSync(filePath, 'utf-8');
     const functions = this.extractFunctions(content);
     const schemas = {};
-    
+
     for (const fn of functions) {
       schemas[fn.name] = this.buildSchema(fn.params, fn.jsdoc);
     }
-    
+
     return schemas;
   }
-  
+
   /**
    * Extract function parameters from function string
    * @param {string} fnString
@@ -93,13 +93,13 @@ class SchemaGenerator {
     // Match function parameters
     const paramMatch = fnString.match(/\(([^)]*)\)/);
     if (!paramMatch) return [];
-    
+
     const paramString = paramMatch[1];
     if (!paramString.trim()) return [];
-    
+
     return this.parseParameterString(paramString);
   }
-  
+
   /**
    * Parse parameter string into structured format
    * @param {string} paramString
@@ -109,35 +109,35 @@ class SchemaGenerator {
     const params = [];
     let depth = 0;
     let current = '';
-    let inDefault = false;
-    
+    let _inDefault = false;
+
     for (const char of paramString) {
       if (char === '{' || char === '[' || char === '(') depth++;
       if (char === '}' || char === ']' || char === ')') depth--;
-      
+
       if (char === '=' && depth === 0) {
-        inDefault = true;
+        _inDefault = true;
       }
-      
+
       if (char === ',' && depth === 0) {
         if (current.trim()) {
           params.push(this.parseParameter(current.trim()));
         }
         current = '';
-        inDefault = false;
+        _inDefault = false;
         continue;
       }
-      
+
       current += char;
     }
-    
+
     if (current.trim()) {
       params.push(this.parseParameter(current.trim()));
     }
-    
+
     return params;
   }
-  
+
   /**
    * Parse a single parameter
    * @param {string} param
@@ -148,34 +148,36 @@ class SchemaGenerator {
     if (param.startsWith('{')) {
       const match = param.match(/\{([^}]+)\}/);
       if (match) {
-        const destructured = match[1].split(',').map(p => p.trim().split(':')[0].split('=')[0].trim());
+        const destructured = match[1]
+          .split(',')
+          .map(p => p.trim().split(':')[0].split('=')[0].trim());
         return {
           name: 'options',
           type: 'object',
           destructured,
-          required: !param.includes('=')
+          required: !param.includes('='),
         };
       }
     }
-    
+
     // Handle default values
     const [nameWithType, defaultValue] = param.split('=').map(p => p.trim());
     const name = nameWithType.replace(/:\s*\w+$/, '').trim();
-    
+
     // Try to infer type from default value
     let type = this.defaultType;
     if (defaultValue !== undefined) {
       type = this.inferTypeFromValue(defaultValue);
     }
-    
+
     return {
       name,
       type,
       required: defaultValue === undefined,
-      default: defaultValue ? this.parseDefaultValue(defaultValue) : undefined
+      default: defaultValue ? this.parseDefaultValue(defaultValue) : undefined,
     };
   }
-  
+
   /**
    * Infer type from a default value string
    * @param {string} valueStr
@@ -183,7 +185,7 @@ class SchemaGenerator {
    */
   inferTypeFromValue(valueStr) {
     valueStr = valueStr.trim();
-    
+
     if (valueStr === 'true' || valueStr === 'false') return 'boolean';
     if (valueStr === 'null') return 'null';
     if (valueStr === '[]' || valueStr.startsWith('[')) return 'array';
@@ -191,10 +193,10 @@ class SchemaGenerator {
     if (/^['"`]/.test(valueStr)) return 'string';
     if (/^-?\d+$/.test(valueStr)) return 'integer';
     if (/^-?\d+\.\d+$/.test(valueStr)) return 'number';
-    
+
     return this.defaultType;
   }
-  
+
   /**
    * Parse default value string to actual value
    * @param {string} valueStr
@@ -211,7 +213,7 @@ class SchemaGenerator {
       return valueStr;
     }
   }
-  
+
   /**
    * Extract JSDoc comment from function string
    * @param {string} fnString
@@ -222,7 +224,7 @@ class SchemaGenerator {
     if (!match) return null;
     return this.parseJSDoc(match[0]);
   }
-  
+
   /**
    * Parse JSDoc comment
    * @param {string} jsdoc
@@ -234,16 +236,17 @@ class SchemaGenerator {
       params: [],
       returns: null,
       example: null,
-      throws: []
+      throws: [],
     };
-    
-    const lines = jsdoc.split('\n')
+
+    const lines = jsdoc
+      .split('\n')
       .map(l => l.replace(/^\s*\*\s?/, '').trim())
       .filter(l => l && !l.startsWith('/'));
-    
+
     let currentTag = null;
     let buffer = [];
-    
+
     for (const line of lines) {
       if (line.startsWith('@')) {
         // Process previous buffer
@@ -251,7 +254,7 @@ class SchemaGenerator {
           result.description = buffer.join(' ');
         }
         buffer = [];
-        
+
         if (line.startsWith('@param')) {
           currentTag = 'param';
           const parsed = this.parseParamTag(line);
@@ -281,14 +284,14 @@ class SchemaGenerator {
         }
       }
     }
-    
+
     if (currentTag === null && buffer.length) {
       result.description = buffer.join(' ');
     }
-    
+
     return result;
   }
-  
+
   /**
    * Parse @param tag
    * @param {string} line
@@ -297,16 +300,16 @@ class SchemaGenerator {
   parseParamTag(line) {
     const match = line.match(/@param\s+\{([^}]+)\}\s+(\[)?(\w+)(?:\])?(?:\s*-?\s*(.*))?/);
     if (!match) return null;
-    
+
     const [, type, optional, name, description] = match;
     return {
       name,
       type: type.toLowerCase(),
       required: !optional,
-      description: description || ''
+      description: description || '',
     };
   }
-  
+
   /**
    * Build schema from extracted params and JSDoc
    * @param {Array} params
@@ -316,14 +319,14 @@ class SchemaGenerator {
   buildSchema(params, jsdoc) {
     const properties = {};
     const required = [];
-    
+
     // Merge param info from function signature and JSDoc
     const paramMap = new Map();
-    
+
     for (const param of params) {
       paramMap.set(param.name, { ...param });
     }
-    
+
     if (jsdoc?.params) {
       for (const docParam of jsdoc.params) {
         const existing = paramMap.get(docParam.name);
@@ -331,14 +334,14 @@ class SchemaGenerator {
           Object.assign(existing, {
             type: docParam.type || existing.type,
             description: docParam.description || existing.description,
-            required: docParam.required ?? existing.required
+            required: docParam.required ?? existing.required,
           });
         } else {
           paramMap.set(docParam.name, docParam);
         }
       }
     }
-    
+
     // Build properties
     for (const [name, param] of paramMap) {
       if (param.destructured) {
@@ -346,7 +349,7 @@ class SchemaGenerator {
         for (const prop of param.destructured) {
           properties[prop] = {
             type: 'string',
-            description: `Property: ${prop}`
+            description: `Property: ${prop}`,
           };
         }
       } else {
@@ -358,28 +361,28 @@ class SchemaGenerator {
           properties[name].default = param.default;
         }
       }
-      
+
       if (param.required && !param.destructured) {
         required.push(name);
       }
     }
-    
+
     const schema = {
       type: 'object',
-      properties
+      properties,
     };
-    
+
     if (required.length > 0) {
       schema.required = required;
     }
-    
+
     if (this.strict) {
       schema.additionalProperties = false;
     }
-    
+
     return schema;
   }
-  
+
   /**
    * Build schema from parsed JSDoc
    * @param {Object} parsed
@@ -388,49 +391,49 @@ class SchemaGenerator {
   buildSchemaFromParsed(parsed) {
     return this.buildSchema([], parsed);
   }
-  
+
   /**
    * Convert type string to JSON Schema
    * @param {string} typeStr
    * @param {Object} [param]
    * @returns {Object}
    */
-  typeToSchema(typeStr, param = {}) {
+  typeToSchema(typeStr, _param = {}) {
     const type = typeStr.toLowerCase();
-    
+
     // Handle array types
     if (type.endsWith('[]')) {
       const itemType = type.slice(0, -2);
       return {
         type: 'array',
-        items: this.typeToSchema(itemType)
+        items: this.typeToSchema(itemType),
       };
     }
-    
+
     // Handle union types
     if (type.includes('|')) {
       const types = type.split('|').map(t => this.typeToSchema(t.trim()));
       return { anyOf: types };
     }
-    
+
     // Handle common types
     const typeMap = {
-      'string': { type: 'string' },
-      'number': { type: 'number' },
-      'integer': { type: 'integer' },
-      'int': { type: 'integer' },
-      'boolean': { type: 'boolean' },
-      'bool': { type: 'boolean' },
-      'object': { type: 'object' },
-      'array': { type: 'array' },
-      'any': { type: 'object' },
-      'null': { type: 'null' },
-      '*': { type: 'object' }
+      string: { type: 'string' },
+      number: { type: 'number' },
+      integer: { type: 'integer' },
+      int: { type: 'integer' },
+      boolean: { type: 'boolean' },
+      bool: { type: 'boolean' },
+      object: { type: 'object' },
+      array: { type: 'array' },
+      any: { type: 'object' },
+      null: { type: 'null' },
+      '*': { type: 'object' },
     };
-    
+
     return typeMap[type] || { type: 'string' };
   }
-  
+
   /**
    * Extract all functions from file content
    * @param {string} content
@@ -438,35 +441,36 @@ class SchemaGenerator {
    */
   extractFunctions(content) {
     const functions = [];
-    
+
     // Match function declarations with JSDoc
     const regex = /(\/\*\*[\s\S]*?\*\/)\s*(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
     let match;
-    
+
     while ((match = regex.exec(content)) !== null) {
       const [, jsdoc, name, params] = match;
       functions.push({
         name,
         params: this.parseParameterString(params),
-        jsdoc: this.parseJSDoc(jsdoc)
+        jsdoc: this.parseJSDoc(jsdoc),
       });
     }
-    
+
     // Match arrow functions with JSDoc
-    const arrowRegex = /(\/\*\*[\s\S]*?\*\/)\s*(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/g;
-    
+    const arrowRegex =
+      /(\/\*\*[\s\S]*?\*\/)\s*(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/g;
+
     while ((match = arrowRegex.exec(content)) !== null) {
       const [, jsdoc, name, params] = match;
       functions.push({
         name,
         params: this.parseParameterString(params),
-        jsdoc: this.parseJSDoc(jsdoc)
+        jsdoc: this.parseJSDoc(jsdoc),
       });
     }
-    
+
     return functions;
   }
-  
+
   /**
    * Generate OpenAI function tool schema
    * @param {string} name
@@ -480,11 +484,11 @@ class SchemaGenerator {
       function: {
         name,
         description,
-        parameters
-      }
+        parameters,
+      },
     };
   }
-  
+
   /**
    * Generate Anthropic tool schema
    * @param {string} name
@@ -496,7 +500,7 @@ class SchemaGenerator {
     return {
       name,
       description,
-      input_schema: parameters
+      input_schema: parameters,
     };
   }
 }
@@ -510,5 +514,5 @@ function createSchemaGenerator(options = {}) {
 
 module.exports = {
   SchemaGenerator,
-  createSchemaGenerator
+  createSchemaGenerator,
 };