@portel/photon-core 2.9.4 → 2.10.0

package/src/schema-extractor.ts

@@ -140,10 +140,15 @@ export class SchemaExtractor {
         const paramDocs = this.extractParamDocs(jsdoc);
         const paramConstraints = this.extractParamConstraints(jsdoc);
 
+        // Track which paramDocs/constraints were matched for fail-safe handling
+        const matchedDocs = new Set<string>();
+        const matchedConstraints = new Set<string>();
+
         // Merge descriptions and constraints into properties
         Object.keys(properties).forEach(key => {
           if (paramDocs.has(key)) {
             properties[key].description = paramDocs.get(key);
+            matchedDocs.add(key);
           }
 
           // Apply TypeScript-extracted metadata (before JSDoc, so JSDoc can override)
@@ -156,9 +161,54 @@ export class SchemaExtractor {
           if (paramConstraints.has(key)) {
             const constraints = paramConstraints.get(key)!;
             this.applyConstraints(properties[key], constraints);
+            matchedConstraints.add(key);
           }
         });
 
+        // Fail-safe: Handle mismatched parameter names from JSDoc
+        // If a @param name doesn't match any actual parameter, try fuzzy matching
+        const unmatchedDocs = Array.from(paramDocs.entries()).filter(([name]) => !matchedDocs.has(name));
+        if (unmatchedDocs.length > 0) {
+          const propKeys = Object.keys(properties);
+
+          // If there's only one parameter and one unmatched doc, assume it belongs to that parameter
+          if (propKeys.length === 1 && unmatchedDocs.length === 1) {
+            const paramKey = propKeys[0];
+            const [docName, docValue] = unmatchedDocs[0];
+            if (!properties[paramKey].description) {
+              properties[paramKey].description = `${docName}: ${docValue}`;
+              console.warn(
+                `Parameter name mismatch in JSDoc: @param ${docName} doesn't match ` +
+                `function parameter "${paramKey}". Using description from @param ${docName}.`
+              );
+            }
+          } else if (unmatchedDocs.length > 0) {
+            // Log warning for other mismatches (multiple parameters or multiple unmatched docs)
+            unmatchedDocs.forEach(([docName]) => {
+              console.warn(
+                `Parameter name mismatch in JSDoc: @param ${docName} doesn't match any function parameter. ` +
+                `Available parameters: ${propKeys.join(', ')}. Consider updating @param tag.`
+              );
+            });
+          }
+        }
+
+        // Similar fail-safe for constraints
+        const unmatchedConstraints = Array.from(paramConstraints.entries()).filter(([name]) => !matchedConstraints.has(name));
+        if (unmatchedConstraints.length > 0) {
+          const propKeys = Object.keys(properties);
+
+          if (propKeys.length === 1 && unmatchedConstraints.length === 1) {
+            const paramKey = propKeys[0];
+            const [constraintName, constraintValue] = unmatchedConstraints[0];
+            this.applyConstraints(properties[paramKey], constraintValue);
+            console.warn(
+              `Parameter name mismatch in JSDoc: constraint tag for ${constraintName} doesn't match ` +
+              `function parameter "${paramKey}". Applying constraint to "${paramKey}".`
+            );
+          }
+        }
+
         const description = this.extractDescription(jsdoc);
         const inputSchema = {
           type: 'object' as const,
@@ -213,7 +263,7 @@ export class SchemaExtractor {
           const throttled = this.extractThrottled(jsdoc);
           const debounced = this.extractDebounced(jsdoc);
           const queued = this.extractQueued(jsdoc);
-          const validations = this.extractValidations(jsdoc);
+          const validations = this.extractValidations(jsdoc, Object.keys(properties));
           const deprecated = this.extractDeprecated(jsdoc);
 
           // Build unified middleware declarations (single source of truth for runtime)
@@ -520,6 +570,24 @@ export class SchemaExtractor {
       } else {
         properties[paramName] = { type: 'string' };
       }
+
+      // Extract default value if initializer exists
+      if (param.initializer) {
+        const defaultValue = this.extractDefaultValue(param.initializer, sourceFile);
+        if (defaultValue !== undefined) {
+          // Validate default value type matches parameter type
+          const paramType = properties[paramName].type;
+          if (!this.isDefaultValueTypeCompatible(defaultValue, paramType)) {
+            const defaultType = typeof defaultValue;
+            console.warn(
+              `Default value type mismatch: parameter "${paramName}" is type "${paramType}" ` +
+              `but default value is type "${defaultType}" (${JSON.stringify(defaultValue)}). ` +
+              `This may cause runtime errors.`
+            );
+          }
+          properties[paramName].default = defaultValue;
+        }
+      }
     }
 
     return { properties, required, simpleParams: true };
@@ -874,6 +942,30 @@ export class SchemaExtractor {
   /**
    * Extract default value from initializer
    */
+  /**
+   * Check if a default value's type is compatible with the parameter type
+   */
+  private isDefaultValueTypeCompatible(defaultValue: any, paramType: string): boolean {
+    const valueType = typeof defaultValue;
+
+    // Type must match (number → number, boolean → boolean, etc.)
+    switch (paramType) {
+      case 'string':
+        return valueType === 'string';
+      case 'number':
+        // Number params need number defaults, not strings
+        return valueType === 'number';
+      case 'boolean':
+        return valueType === 'boolean';
+      case 'array':
+        return Array.isArray(defaultValue);
+      case 'object':
+        return valueType === 'object';
+      default:
+        return true;  // Unknown types are assumed compatible
+    }
+  }
+
   private extractDefaultValue(initializer: ts.Expression, sourceFile: ts.SourceFile): any {
     // String literals
     if (ts.isStringLiteral(initializer)) {
@@ -893,8 +985,25 @@ export class SchemaExtractor {
       return false;
     }
 
-    // For complex expressions (function calls, etc.), return as string
-    return initializer.getText(sourceFile);
+    // Detect complex expressions
+    const expressionText = initializer.getText(sourceFile);
+    const isComplexExpression =
+      ts.isCallExpression(initializer) ||  // Function calls: Math.max(10, 100)
+      ts.isObjectLiteralExpression(initializer) ||  // Objects: { key: 'value' }
+      ts.isArrayLiteralExpression(initializer) ||  // Arrays: [1, 2, 3]
+      ts.isBinaryExpression(initializer) ||  // Binary ops: 10 + 20
+      ts.isConditionalExpression(initializer);  // Ternary: x ? a : b
+
+    if (isComplexExpression) {
+      console.warn(
+        `Complex default value cannot be reliably serialized: "${expressionText}". ` +
+        `Default will not be applied to schema. Consider using a simple literal value instead.`
+      );
+      return undefined;
+    }
+
+    // For other expressions, return as string
+    return expressionText;
   }
 
   // ═══════════════════════════════════════════════════════════════════════════════
@@ -1213,7 +1322,17 @@ export class SchemaExtractor {
       // Extract {@format formatName} - use lookahead to match until tag-closing }
       const formatMatch = description.match(/\{@format\s+(.+?)\}(?=\s|$|{@)/);
       if (formatMatch) {
-        paramConstraints.format = formatMatch[1].trim();
+        const format = formatMatch[1].trim();
+        // Validate format is in whitelist (JSON Schema + custom formats)
+        const validFormats = ['email', 'date', 'date-time', 'time', 'duration', 'uri', 'uri-reference', 'uuid', 'ipv4', 'ipv6', 'hostname', 'json', 'table'];
+        if (!validFormats.includes(format)) {
+          console.warn(
+            `Invalid @format value: "${format}". ` +
+            `Valid formats: ${validFormats.join(', ')}. Format not applied.`
+          );
+        } else {
+          paramConstraints.format = format;
+        }
       }
 
       // Extract {@choice value1,value2,...} - converts to enum in schema
@@ -1242,6 +1361,18 @@ export class SchemaExtractor {
         }
       }
 
+      // Extract {@minItems value} - for arrays
+      const minItemsMatch = description.match(/\{@minItems\s+(-?\d+(?:\.\d+)?)\}/);
+      if (minItemsMatch) {
+        paramConstraints.minItems = parseInt(minItemsMatch[1], 10);
+      }
+
+      // Extract {@maxItems value} - for arrays
+      const maxItemsMatch = description.match(/\{@maxItems\s+(-?\d+(?:\.\d+)?)\}/);
+      if (maxItemsMatch) {
+        paramConstraints.maxItems = parseInt(maxItemsMatch[1], 10);
+      }
+
       // Extract {@unique} or {@uniqueItems} - for arrays
       if (description.match(/\{@unique(?:Items)?\s*\}/)) {
         paramConstraints.unique = true;
@@ -1276,11 +1407,19 @@ export class SchemaExtractor {
         paramConstraints.deprecated = deprecatedMatch[1]?.trim() || true;
       }
 
-      // Extract {@readOnly} and {@writeOnly} - track which comes last
-      // They are mutually exclusive, so last one wins
+      // Extract {@readOnly} and {@writeOnly} - detect conflicts
+      // They are mutually exclusive, so warn if both present
       const readOnlyMatch = description.match(/\{@readOnly\s*\}/);
       const writeOnlyMatch = description.match(/\{@writeOnly\s*\}/);
 
+      if (readOnlyMatch && writeOnlyMatch) {
+        // Warn about conflict
+        console.warn(
+          `Conflicting constraints: @readOnly and @writeOnly cannot both be applied. ` +
+          `Keeping @${readOnlyMatch && writeOnlyMatch ? (description.lastIndexOf('@readOnly') > description.lastIndexOf('@writeOnly') ? 'readOnly' : 'writeOnly') : 'readOnly'}.`
+        );
+      }
+
       if (readOnlyMatch || writeOnlyMatch) {
         // Find positions to determine which comes last
         const readOnlyPos = readOnlyMatch ? description.indexOf(readOnlyMatch[0]) : -1;
@@ -1324,6 +1463,22 @@ export class SchemaExtractor {
         paramConstraints.accept = acceptMatch[1].trim();
       }
 
+      // Validate no unknown {@...} tags (typos in constraint names)
+      const allKnownTags = ['min', 'max', 'pattern', 'format', 'choice', 'field', 'default', 'unique', 'uniqueItems',
+                             'example', 'multipleOf', 'deprecated', 'readOnly', 'writeOnly', 'label', 'placeholder',
+                             'hint', 'hidden', 'accept', 'minItems', 'maxItems'];
+      const unknownTagRegex = /\{@([\w-]+)\s*(?:\s+[^}]*)?\}/g;
+      let unknownMatch;
+      while ((unknownMatch = unknownTagRegex.exec(description)) !== null) {
+        const tagName = unknownMatch[1];
+        if (!allKnownTags.includes(tagName)) {
+          console.warn(
+            `unknown constraint/hint: @${tagName}. ` +
+            `Valid hints: ${allKnownTags.slice(0, 8).join(', ')}, etc. This tag will be ignored.`
+          );
+        }
+      }
+
       if (Object.keys(paramConstraints).length > 0) {
         constraints.set(paramName, paramConstraints);
       }
@@ -1339,8 +1494,54 @@ export class SchemaExtractor {
    * Works with both simple types and anyOf schemas
    */
   private applyConstraints(schema: any, constraints: any) {
+    // Validate constraint values before applying (fail-safe)
+    if (constraints.min !== undefined && constraints.max !== undefined) {
+      if (constraints.min > constraints.max) {
+        console.warn(
+          `Invalid constraint: @min (${constraints.min}) > @max (${constraints.max}). ` +
+          `Using only @min. Remove @max or use a larger value.`
+        );
+        delete constraints.max;
+      }
+    }
+
     // Helper to apply constraints to a single schema based on type
     const applyToSchema = (s: any) => {
+      // Validate constraint-type compatibility
+      if (!s.enum) {
+        // Warn for incompatible constraints
+        if ((constraints.min !== undefined || constraints.max !== undefined) &&
+            s.type !== 'number' && s.type !== 'string' && s.type !== 'array') {
+          const constraintType = constraints.min !== undefined ? '@min' : '@max';
+          console.warn(
+            `Constraint ${constraintType} not applicable to type "${s.type || 'unknown'}". ` +
+            `This constraint applies to number, string, or array types only.`
+          );
+        }
+
+        if (constraints.pattern !== undefined && s.type !== 'string') {
+          console.warn(
+            `Constraint @pattern not applicable to type "${s.type || 'unknown'}". ` +
+            `Pattern only applies to string types.`
+          );
+        }
+
+        if ((constraints.minItems !== undefined || constraints.maxItems !== undefined) && s.type !== 'array') {
+          const constraintType = constraints.minItems !== undefined ? '@minItems' : '@maxItems';
+          console.warn(
+            `Constraint ${constraintType} not applicable to type "${s.type || 'unknown'}". ` +
+            `This constraint applies to array types only.`
+          );
+        }
+
+        if (constraints.multipleOf !== undefined && s.type !== 'number') {
+          console.warn(
+            `Constraint @multipleOf not applicable to type "${s.type || 'unknown'}". ` +
+            `This constraint applies to number types only.`
+          );
+        }
+      }
+
       if (s.enum) {
         // Skip enum types for most constraints (but still apply deprecated, examples, etc.)
         if (constraints.examples !== undefined) {
@@ -1352,7 +1553,7 @@ export class SchemaExtractor {
         return;
       }
 
-      // Apply min/max based on type
+      // Apply min/max based on type (skip if type is incompatible)
       if (s.type === 'number') {
         if (constraints.min !== undefined) {
           s.minimum = constraints.min;
@@ -1361,7 +1562,15 @@ export class SchemaExtractor {
           s.maximum = constraints.max;
         }
         if (constraints.multipleOf !== undefined) {
-          s.multipleOf = constraints.multipleOf;
+          // Validate multipleOf is positive (JSON schema requires > 0)
+          if (constraints.multipleOf <= 0) {
+            console.warn(
+              `Invalid @multipleOf value: ${constraints.multipleOf}. ` +
+              `Must be positive and non-zero. Constraint not applied.`
+            );
+          } else {
+            s.multipleOf = constraints.multipleOf;
+          }
         }
       } else if (s.type === 'string') {
         if (constraints.min !== undefined) {
@@ -1371,7 +1580,24 @@ export class SchemaExtractor {
           s.maxLength = constraints.max;
         }
         if (constraints.pattern !== undefined) {
-          s.pattern = constraints.pattern;
+          // Check for pattern+enum conflict
+          if (s.enum || constraints.enum) {
+            console.warn(
+              `Conflicting constraints: @pattern cannot be used with enum/choices. ` +
+              `Pattern is ignored when specific values are defined via enum or @choice.`
+            );
+          } else {
+            // Validate pattern is valid regex before applying (fail-safe)
+            try {
+              new RegExp(constraints.pattern);
+              s.pattern = constraints.pattern;
+            } catch (e) {
+              console.warn(
+                `Invalid regex in @pattern constraint: "${constraints.pattern}". ` +
+                `${e instanceof Error ? e.message : String(e)}. Pattern not applied.`
+              );
+            }
+          }
         }
       } else if (s.type === 'array') {
         if (constraints.min !== undefined) {
@@ -1380,10 +1606,27 @@ export class SchemaExtractor {
         if (constraints.max !== undefined) {
           s.maxItems = constraints.max;
         }
+        if (constraints.minItems !== undefined) {
+          s.minItems = constraints.minItems;
+        }
+        if (constraints.maxItems !== undefined) {
+          s.maxItems = constraints.maxItems;
+        }
         if (constraints.unique === true) {
           s.uniqueItems = true;
         }
+      } else if (s.type && s.type !== 'boolean' && s.type !== 'object') {
+        // For other compatible types, apply min/max as needed
+        if (['integer', 'number'].includes(s.type)) {
+          if (constraints.min !== undefined) {
+            s.minimum = constraints.min;
+          }
+          if (constraints.max !== undefined) {
+            s.maximum = constraints.max;
+          }
+        }
       }
+      // Note: For boolean and object types, we skip min/max constraints (already warned above)
 
       // Apply type-agnostic constraints
       if (constraints.format !== undefined) {
@@ -1662,10 +1905,27 @@ export class SchemaExtractor {
    * - @retryable 3 2s → 3 retries, 2s delay
    */
   private extractRetryable(jsdocContent: string): { count: number; delay: number } | undefined {
-    const match = jsdocContent.match(/@retryable(?:\s+(\d+))?(?:\s+(\d+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
+    const match = jsdocContent.match(/@retryable(?:\s+([-\d]+))?(?:\s+([-\d]+(?:ms|s|sec|m|min|h|hr|d|day)))?/i);
     if (!match) return undefined;
-    const count = match[1] ? parseInt(match[1], 10) : 3;
-    const delay = match[2] ? parseDuration(match[2]) : 1_000;
+    let count = match[1] ? parseInt(match[1], 10) : 3;
+    let delay = match[2] ? parseDuration(match[2]) : 1_000;
+
+    // Validate retryable configuration
+    if (count <= 0) {
+      console.warn(
+        `Invalid @retryable count: ${count}. ` +
+        `Count must be positive (> 0). Using default count 3.`
+      );
+      count = 3;
+    }
+    if (delay <= 0) {
+      console.warn(
+        `Invalid @retryable delay: ${delay}ms. ` +
+        `Delay must be positive (> 0). Using default delay 1000ms.`
+      );
+      delay = 1_000;
+    }
+
     return { count, delay };
   }
 
@@ -1675,9 +1935,45 @@ export class SchemaExtractor {
    * - @throttled 100/h → 100 calls per hour
    */
   private extractThrottled(jsdocContent: string): { count: number; windowMs: number } | undefined {
+    // First check if @throttled is present at all
+    const hasThrottled = /@throttled\b/i.test(jsdocContent);
     const match = jsdocContent.match(/@throttled\s+(\d+\/(?:s|sec|m|min|h|hr|d|day))/i);
-    if (!match) return undefined;
-    return parseRate(match[1]);
+
+    if (!match) {
+      if (hasThrottled) {
+        // @throttled is present but format is invalid
+        const invalidMatch = jsdocContent.match(/@throttled\s+([^\s]+)/i);
+        if (invalidMatch) {
+          console.warn(
+            `Invalid @throttled rate format: "${invalidMatch[1]}". ` +
+            `Expected format: count/unit (e.g., 10/min, 100/h). Rate not applied.`
+          );
+        }
+      }
+      return undefined;
+    }
+
+    const rateStr = match[1];
+    const rate = parseRate(rateStr);
+
+    // Validate throttled configuration
+    if (!rate) {
+      console.warn(
+        `Invalid @throttled rate format: "${rateStr}". ` +
+        `Expected format: count/unit (e.g., 10/min, 100/h). Rate not applied.`
+      );
+      return undefined;
+    }
+
+    if (rate.count <= 0) {
+      console.warn(
+        `Invalid @throttled count: ${rate.count}. ` +
+        `Count must be positive (> 0). Rate not applied.`
+      );
+      return undefined;
+    }
+
+    return rate;
   }
 
   /**
@@ -1710,13 +2006,24 @@ export class SchemaExtractor {
    * - @validate params.email must be a valid email
    * - @validate params.amount must be positive
    */
-  private extractValidations(jsdocContent: string): Array<{ field: string; rule: string }> | undefined {
+  private extractValidations(jsdocContent: string, validParamNames?: string[]): Array<{ field: string; rule: string }> | undefined {
     const validations: Array<{ field: string; rule: string }> = [];
     const regex = /@validate\s+([\w.]+)\s+(.+)/g;
     let match;
     while ((match = regex.exec(jsdocContent)) !== null) {
+      const fieldName = match[1].replace(/^params\./, ''); // strip params. prefix
+
+      // Fail-safe: Validate that referenced field exists (if validParamNames provided)
+      if (validParamNames && !validParamNames.includes(fieldName)) {
+        console.warn(
+          `@validate references non-existent parameter "${fieldName}". ` +
+          `Available parameters: ${validParamNames.join(', ')}. Validation rule ignored.`
+        );
+        continue;
+      }
+
       validations.push({
-        field: match[1].replace(/^params\./, ''), // strip params. prefix
+        field: fieldName,
         rule: match[2].trim().replace(/\*\/$/, '').trim(), // strip JSDoc closing
       });
     }