@portel/photon-core 2.9.4 → 2.10.0

package/dist/schema-extractor.js

@@ -103,10 +103,14 @@ export class SchemaExtractor {
                 // Extract descriptions from JSDoc
                 const paramDocs = this.extractParamDocs(jsdoc);
                 const paramConstraints = this.extractParamConstraints(jsdoc);
+                // Track which paramDocs/constraints were matched for fail-safe handling
+                const matchedDocs = new Set();
+                const matchedConstraints = new Set();
                 // 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)
                     if (properties[key]._tsReadOnly) {
@@ -117,8 +121,44 @@ 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',
@@ -169,7 +209,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)
                     const middleware = this.buildMiddlewareDeclarations(jsdoc);
@@ -450,6 +490,21 @@ 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 };
     }
@@ -756,6 +811,28 @@ export class SchemaExtractor {
     /**
      * Extract default value from initializer
      */
+    /**
+     * Check if a default value's type is compatible with the parameter type
+     */
+    isDefaultValueTypeCompatible(defaultValue, paramType) {
+        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
+        }
+    }
     extractDefaultValue(initializer, sourceFile) {
         // String literals
         if (ts.isStringLiteral(initializer)) {
@@ -772,8 +849,20 @@ export class SchemaExtractor {
         if (initializer.kind === ts.SyntaxKind.FalseKeyword) {
             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;
     }
     // ═══════════════════════════════════════════════════════════════════════════════
     // INLINE CONFIG + @use PARSING
@@ -1061,7 +1150,16 @@ 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
             const choiceMatch = description.match(/\{@choice\s+([^}]+)\}/);
@@ -1087,6 +1185,16 @@ export class SchemaExtractor {
                     paramConstraints.default = defaultValue;
                 }
             }
+            // 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;
@@ -1118,10 +1226,15 @@ export class SchemaExtractor {
             if (deprecatedMatch) {
                 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;
@@ -1159,6 +1272,19 @@ export class SchemaExtractor {
             if (acceptMatch) {
                 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);
             }
@@ -1172,8 +1298,39 @@ export class SchemaExtractor {
      * Works with both simple types and anyOf schemas
      */
     applyConstraints(schema, constraints) {
+        // 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) => {
+            // 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) {
@@ -1184,7 +1341,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;
@@ -1193,7 +1350,14 @@ 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') {
@@ -1204,7 +1368,22 @@ 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') {
@@ -1214,10 +1393,28 @@ 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) {
                 s.format = constraints.format;
@@ -1471,11 +1668,22 @@ export class SchemaExtractor {
      * - @retryable 3 2s → 3 retries, 2s delay
      */
     extractRetryable(jsdocContent) {
-        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 };
     }
     /**
@@ -1484,10 +1692,34 @@ export class SchemaExtractor {
      * - @throttled 100/h → 100 calls per hour
      */
     extractThrottled(jsdocContent) {
+        // 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)
+        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;
-        return parseRate(match[1]);
+        }
+        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;
     }
     /**
      * Extract debounce configuration from @debounced tag
@@ -1519,13 +1751,20 @@ export class SchemaExtractor {
      * - @validate params.email must be a valid email
      * - @validate params.amount must be positive
      */
-    extractValidations(jsdocContent) {
+    extractValidations(jsdocContent, validParamNames) {
         const validations = [];
         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
             });
         }