@machina.ai/openapi-contract-tester 2.1.0

package/dist/analyzers/failure-discrepancy-correlator.js

@@ -0,0 +1,202 @@
+/**
+ * Failure-Discrepancy Correlator
+ *
+ * Correlates test failures with source comparison discrepancies
+ * to provide root cause analysis and automated insights
+ *
+ * @module analyzers/failure-discrepancy-correlator
+ */
+/**
+ * Correlates test failures with source comparison discrepancies
+ *
+ * @param failures - Test failures from test execution
+ * @param discrepancies - Discrepancies from source comparison
+ * @returns Correlation result with root cause analysis
+ *
+ * @example
+ * ```typescript
+ * const correlation = correlateFailuresWithDiscrepancies(
+ *   testFailures,
+ *   comparisonResult.discrepancies
+ * );
+ *
+ * console.log(`${correlation.correlationRate} failures have known root causes`);
+ * ```
+ */
+export function correlateFailuresWithDiscrepancies(failures, discrepancies) {
+    const correlations = [];
+    for (const failure of failures) {
+        const correlation = findCorrelation(failure, discrepancies);
+        correlations.push(correlation);
+    }
+    // Calculate statistics
+    const correlatedFailures = correlations.filter(c => c.rootCause !== 'unknown').length;
+    const correlationRate = failures.length > 0
+        ? `${((correlatedFailures / failures.length) * 100).toFixed(1)}%`
+        : '0%';
+    // Summary by root cause
+    const summaryByRootCause = {
+        endpoint_not_implemented: 0,
+        endpoint_not_documented: 0,
+        auth_mismatch: 0,
+        missing_dependency: 0,
+        schema_mismatch: 0,
+        business_rule_violation: 0,
+        unknown: 0,
+    };
+    for (const corr of correlations) {
+        summaryByRootCause[corr.rootCause]++;
+    }
+    return {
+        totalFailures: failures.length,
+        correlatedFailures,
+        correlationRate,
+        correlations,
+        summaryByRootCause,
+    };
+}
+/**
+ * Finds correlation between a single failure and discrepancies
+ */
+function findCorrelation(failure, discrepancies) {
+    // Pattern 1: 404 Not Found + endpoint_in_spec_not_in_code
+    if (failure.actualStatus === 404) {
+        const relatedDisc = discrepancies.find(d => d.type === 'endpoint_in_spec_not_in_code' &&
+            d.endpoint?.method === failure.method &&
+            d.endpoint?.path === failure.path);
+        if (relatedDisc) {
+            return {
+                failure,
+                relatedDiscrepancy: relatedDisc,
+                rootCause: 'endpoint_not_implemented',
+                confidence: 0.95,
+                explanation: `Este endpoint está documentado en el OpenAPI spec pero no está implementado en el código. El 404 es esperado.`,
+                suggestedFix: `Implementar el endpoint ${failure.method} ${failure.path} en el código`,
+                autoRepairable: false,
+            };
+        }
+        // Pattern 2: 404 + missing dependency (resource needs to be created first)
+        if (failure.path.includes('{') && failure.method !== 'POST') {
+            return {
+                failure,
+                rootCause: 'missing_dependency',
+                confidence: 0.7,
+                explanation: `El recurso solicitado no existe. Este endpoint probablemente depende de que otro test cree el recurso primero.`,
+                suggestedFix: `Agregar dependencia al test que crea el recurso (POST ${failure.path.replace(/\/\{[^}]+\}.*/, '')})`,
+                autoRepairable: true,
+            };
+        }
+    }
+    // Pattern 3: 401/403 + auth_mismatch discrepancy
+    if (failure.actualStatus === 401 || failure.actualStatus === 403) {
+        const relatedDisc = discrepancies.find(d => d.type === 'auth_mismatch' &&
+            d.endpoint?.method === failure.method &&
+            d.endpoint?.path === failure.path);
+        if (relatedDisc) {
+            return {
+                failure,
+                relatedDiscrepancy: relatedDisc,
+                rootCause: 'auth_mismatch',
+                confidence: 0.9,
+                explanation: `Los requisitos de autenticación difieren entre el spec y el código. El ${failure.actualStatus} indica que el código requiere autenticación.`,
+                suggestedFix: `Actualizar el OpenAPI spec para incluir security requirements, o agregar token de autenticación al test`,
+                autoRepairable: true,
+            };
+        }
+        // Pattern 4: Auth failure without discrepancy (missing auth token)
+        return {
+            failure,
+            rootCause: 'auth_mismatch',
+            confidence: 0.6,
+            explanation: `El endpoint requiere autenticación pero el test no incluye credenciales válidas.`,
+            suggestedFix: `Agregar dependencia al test de login y usar el token resultante`,
+            autoRepairable: true,
+        };
+    }
+    // Pattern 5: endpoint_not_documented (code exists, spec doesn't)
+    const relatedNotDocumented = discrepancies.find(d => d.type === 'endpoint_in_code_not_in_spec' &&
+        d.endpoint?.method === failure.method &&
+        d.endpoint?.path === failure.path);
+    if (relatedNotDocumented) {
+        return {
+            failure,
+            relatedDiscrepancy: relatedNotDocumented,
+            rootCause: 'endpoint_not_documented',
+            confidence: 0.8,
+            explanation: `Este endpoint existe en el código pero no está documentado en el OpenAPI spec. El test puede fallar por falta de documentación de schema.`,
+            suggestedFix: `Agregar este endpoint al OpenAPI specification con su schema correcto`,
+            autoRepairable: false,
+        };
+    }
+    // Pattern 6: Schema validation failures
+    if (failure.error?.includes('schema') || failure.error?.includes('validation')) {
+        return {
+            failure,
+            rootCause: 'schema_mismatch',
+            confidence: 0.75,
+            explanation: `La respuesta del endpoint no coincide con el schema esperado en el OpenAPI spec.`,
+            suggestedFix: `Actualizar el schema en el OpenAPI spec o corregir la respuesta del código`,
+            autoRepairable: false,
+        };
+    }
+    // Pattern 7: Business rule violations from PRD
+    const relatedBusinessRule = discrepancies.find(d => d.type === 'business_rule_not_implemented' &&
+        d.prd &&
+        typeof d.prd === 'object' &&
+        'rule' in d.prd &&
+        (failure.path.includes(d.endpoint?.path || '') || failure.error?.includes(d.prd.rule)));
+    if (relatedBusinessRule) {
+        const prdRule = relatedBusinessRule.prd && typeof relatedBusinessRule.prd === 'object' && 'rule' in relatedBusinessRule.prd
+            ? relatedBusinessRule.prd.rule
+            : 'unknown rule';
+        return {
+            failure,
+            relatedDiscrepancy: relatedBusinessRule,
+            rootCause: 'business_rule_violation',
+            confidence: 0.65,
+            explanation: `Este fallo puede estar relacionado con una regla de negocio del PRD que no está implementada correctamente.`,
+            suggestedFix: `Verificar que la regla de negocio "${prdRule}" esté implementada`,
+            autoRepairable: false,
+        };
+    }
+    // Default: Unknown root cause
+    return {
+        failure,
+        rootCause: 'unknown',
+        confidence: 0,
+        explanation: `No se encontró una correlación clara con discrepancias conocidas. Este puede ser un bug genuino en el código.`,
+        suggestedFix: `Revisar manualmente el código del endpoint y los logs del servidor`,
+        autoRepairable: false,
+    };
+}
+/**
+ * Gets a human-readable description of a root cause type
+ */
+export function getRootCauseDescription(rootCause) {
+    const descriptions = {
+        endpoint_not_implemented: 'Endpoint documentado pero no implementado',
+        endpoint_not_documented: 'Endpoint implementado pero no documentado',
+        auth_mismatch: 'Desajuste en requisitos de autenticación',
+        missing_dependency: 'Falta crear recurso dependiente',
+        schema_mismatch: 'Schema de respuesta no coincide',
+        business_rule_violation: 'Regla de negocio no implementada',
+        unknown: 'Causa desconocida - requiere investigación manual',
+    };
+    return descriptions[rootCause];
+}
+/**
+ * Gets priority level for a root cause
+ */
+export function getRootCausePriority(rootCause) {
+    const priorities = {
+        endpoint_not_implemented: 'critical',
+        business_rule_violation: 'high',
+        auth_mismatch: 'high',
+        schema_mismatch: 'medium',
+        missing_dependency: 'medium',
+        endpoint_not_documented: 'low',
+        unknown: 'low',
+    };
+    return priorities[rootCause];
+}
+//# sourceMappingURL=failure-discrepancy-correlator.js.map

package/dist/analyzers/failure-discrepancy-correlator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-discrepancy-correlator.js","sourceRoot":"","sources":["../../src/analyzers/failure-discrepancy-correlator.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Analyzers Module
+ *
+ * Provides analysis tools for comparing sources and analyzing test results.
+ *
+ * @module analyzers
+ */
+export * from './source-comparator.js';
+export * from './failure-analyzer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/analyzers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyzers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}

package/dist/analyzers/index.js

@@ -0,0 +1,10 @@
+/**
+ * Analyzers Module
+ *
+ * Provides analysis tools for comparing sources and analyzing test results.
+ *
+ * @module analyzers
+ */
+export * from './source-comparator.js';
+export * from './failure-analyzer.js';
+//# sourceMappingURL=index.js.map

package/dist/analyzers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analyzers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}

package/dist/analyzers/semantic-matcher.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Semantic Matcher (AI-Powered)
+ *
+ * Detects semantic similarities between endpoints, parameters, and business rules
+ * that simple string matching cannot find.
+ *
+ * Examples:
+ * - POST /users vs POST /api/v1/register (semantically similar)
+ * - GET /products/:id vs GET /items/{productId} (parameter semantic match)
+ * - Business rule "user authentication" vs code with "login validation"
+ *
+ * @module analyzers/semantic-matcher
+ */
+import type { ParsedEndpoint } from '../types/index.js';
+import type { CodeEndpoint } from './source-comparator.js';
+import type { NormalizedPrd } from '../prd/prd-storage.js';
+/**
+ * Semantic match between endpoints
+ */
+export interface SemanticEndpointMatch {
+    /**
+     * OpenAPI endpoint
+     */
+    openApiEndpoint: ParsedEndpoint;
+    /**
+     * Code endpoint
+     */
+    codeEndpoint: CodeEndpoint;
+    /**
+     * Semantic similarity score (0-1)
+     */
+    similarity: number;
+    /**
+     * Explanation of why they match semantically
+     */
+    explanation: string;
+    /**
+     * Confidence level
+     */
+    confidence: 'high' | 'medium' | 'low';
+    /**
+     * Reasons for the match
+     */
+    reasons: string[];
+}
+/**
+ * Semantic mismatch (parameters, responses, etc.)
+ */
+export interface SemanticMismatch {
+    /**
+     * Type of mismatch
+     */
+    type: 'parameter_names' | 'response_fields' | 'business_logic';
+    /**
+     * Endpoint involved
+     */
+    endpoint: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Description
+     */
+    description: string;
+    /**
+     * Expected (from spec or PRD)
+     */
+    expected: string;
+    /**
+     * Actual (from code)
+     */
+    actual: string;
+    /**
+     * Severity
+     */
+    severity: 'error' | 'warning' | 'info';
+    /**
+     * Suggestion
+     */
+    suggestion: string;
+}
+/**
+ * Result of semantic analysis
+ */
+export interface SemanticAnalysisResult {
+    /**
+     * Endpoints that match semantically but not syntactically
+     */
+    semanticMatches: SemanticEndpointMatch[];
+    /**
+     * Semantic mismatches found
+     */
+    semanticMismatches: SemanticMismatch[];
+    /**
+     * Business rules mapped to implementation
+     */
+    businessRuleMappings: Array<{
+        rule: string;
+        mappedTo: string[];
+        confidence: number;
+    }>;
+}
+/**
+ * Performs semantic analysis using AI to find non-obvious matches and mismatches
+ *
+ * @param openApiEndpoints - Endpoints from OpenAPI spec
+ * @param codeEndpoints - Endpoints from code
+ * @param prd - PRD with business rules (optional)
+ * @returns Semantic analysis result
+ *
+ * @example
+ * ```typescript
+ * const semantic = await performSemanticAnalysis(
+ *   openApiEndpoints,
+ *   codeEndpoints,
+ *   normalizedPrd
+ * );
+ *
+ * console.log(`Found ${semantic.semanticMatches.length} semantic matches`);
+ * ```
+ */
+export declare function performSemanticAnalysis(openApiEndpoints: ParsedEndpoint[], codeEndpoints: CodeEndpoint[], prd?: NormalizedPrd): Promise<SemanticAnalysisResult>;
+//# sourceMappingURL=semantic-matcher.d.ts.map

package/dist/analyzers/semantic-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-matcher.d.ts","sourceRoot":"","sources":["../../src/analyzers/semantic-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAM3D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,eAAe,EAAE,cAAc,CAAC;IAEhC;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAEtC;;OAEG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAE/D;;OAEG;IACH,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IAEF;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IAEvC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,eAAe,EAAE,qBAAqB,EAAE,CAAC;IAEzC;;OAEG;IACH,kBAAkB,EAAE,gBAAgB,EAAE,CAAC;IAEvC;;OAEG;IACH,oBAAoB,EAAE,KAAK,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,uBAAuB,CAC3C,gBAAgB,EAAE,cAAc,EAAE,EAClC,aAAa,EAAE,YAAY,EAAE,EAC7B,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAAC,sBAAsB,CAAC,CAiFjC"}

package/dist/analyzers/semantic-matcher.js

@@ -0,0 +1,297 @@
+/**
+ * Semantic Matcher (AI-Powered)
+ *
+ * Detects semantic similarities between endpoints, parameters, and business rules
+ * that simple string matching cannot find.
+ *
+ * Examples:
+ * - POST /users vs POST /api/v1/register (semantically similar)
+ * - GET /products/:id vs GET /items/{productId} (parameter semantic match)
+ * - Business rule "user authentication" vs code with "login validation"
+ *
+ * @module analyzers/semantic-matcher
+ */
+import { createLogger } from '../utils/logger.js';
+import { callLLM } from '../llm/ai-client.js';
+const log = createLogger('semantic-matcher');
+/**
+ * Performs semantic analysis using AI to find non-obvious matches and mismatches
+ *
+ * @param openApiEndpoints - Endpoints from OpenAPI spec
+ * @param codeEndpoints - Endpoints from code
+ * @param prd - PRD with business rules (optional)
+ * @returns Semantic analysis result
+ *
+ * @example
+ * ```typescript
+ * const semantic = await performSemanticAnalysis(
+ *   openApiEndpoints,
+ *   codeEndpoints,
+ *   normalizedPrd
+ * );
+ *
+ * console.log(`Found ${semantic.semanticMatches.length} semantic matches`);
+ * ```
+ */
+export async function performSemanticAnalysis(openApiEndpoints, codeEndpoints, prd) {
+    log.info('Starting semantic analysis with AI');
+    const semanticMatches = [];
+    const semanticMismatches = [];
+    const businessRuleMappings = [];
+    // Phase 1: Find semantic endpoint matches
+    const unmatchedOpenApi = openApiEndpoints.filter(oaEndpoint => {
+        // Check if there's no exact match in code
+        return !codeEndpoints.some(ce => ce.method === oaEndpoint.method && normalizePath(ce.path) === normalizePath(oaEndpoint.path));
+    });
+    const unmatchedCode = codeEndpoints.filter(codeEndpoint => {
+        // Check if there's no exact match in spec
+        return !openApiEndpoints.some(oa => oa.method === codeEndpoint.method && normalizePath(oa.path) === normalizePath(codeEndpoint.path));
+    });
+    if (unmatchedOpenApi.length > 0 && unmatchedCode.length > 0) {
+        log.info('Finding semantic matches for unmatched endpoints', {
+            unmatchedOpenApi: unmatchedOpenApi.length,
+            unmatchedCode: unmatchedCode.length
+        });
+        const matches = await findSemanticEndpointMatches(unmatchedOpenApi, unmatchedCode);
+        semanticMatches.push(...matches);
+    }
+    // Phase 2: Find semantic parameter mismatches in matched endpoints
+    const matchedEndpoints = openApiEndpoints.filter(oaEndpoint => {
+        return codeEndpoints.some(ce => ce.method === oaEndpoint.method && normalizePath(ce.path) === normalizePath(oaEndpoint.path));
+    });
+    if (matchedEndpoints.length > 0) {
+        log.info('Analyzing semantic parameter mismatches', {
+            matchedEndpoints: matchedEndpoints.length
+        });
+        for (const oaEndpoint of matchedEndpoints) {
+            const codeEndpoint = codeEndpoints.find(ce => ce.method === oaEndpoint.method && normalizePath(ce.path) === normalizePath(oaEndpoint.path));
+            if (codeEndpoint) {
+                const paramMismatches = await findParameterSemanticMismatches(oaEndpoint, codeEndpoint);
+                semanticMismatches.push(...paramMismatches);
+            }
+        }
+    }
+    // Phase 3: Map business rules to implementation (if PRD available)
+    if (prd && prd.businessRules.length > 0) {
+        log.info('Mapping business rules to implementation', {
+            businessRules: prd.businessRules.length
+        });
+        const mappings = await mapBusinessRulesToImplementation(prd, codeEndpoints);
+        businessRuleMappings.push(...mappings);
+    }
+    log.info('Semantic analysis complete', {
+        semanticMatches: semanticMatches.length,
+        semanticMismatches: semanticMismatches.length,
+        businessRuleMappings: businessRuleMappings.length
+    });
+    return {
+        semanticMatches,
+        semanticMismatches,
+        businessRuleMappings
+    };
+}
+/**
+ * Finds semantic matches between unmatched endpoints using AI
+ */
+async function findSemanticEndpointMatches(openApiEndpoints, codeEndpoints) {
+    // Limit to avoid expensive LLM calls
+    const maxToAnalyze = Math.min(10, openApiEndpoints.length);
+    const matches = [];
+    for (let i = 0; i < maxToAnalyze; i++) {
+        const oaEndpoint = openApiEndpoints[i];
+        const prompt = `You are an API semantic analyzer. Find if any code endpoint semantically matches this OpenAPI endpoint.
+
+OpenAPI Endpoint:
+- Method: ${oaEndpoint.method}
+- Path: ${oaEndpoint.path}
+- Description: ${oaEndpoint.operation?.summary || oaEndpoint.operation?.description || 'none'}
+- Operation ID: ${oaEndpoint.operation?.operationId || 'none'}
+
+Code Endpoints (candidates):
+${codeEndpoints.slice(0, 20).map((ce, idx) => `${idx + 1}. ${ce.method} ${ce.path}${ce.handlerName ? ` (${ce.handlerName})` : ''}`).join('\n')}
+
+Task: Determine if any code endpoint is semantically equivalent to the OpenAPI endpoint.
+
+Examples of semantic matches:
+- POST /users ≈ POST /api/v1/register (both create users)
+- GET /products/:id ≈ GET /items/{productId} (same resource, different naming)
+- DELETE /sessions ≈ POST /logout (both end user session)
+
+Respond in JSON format:
+{
+  "hasMatch": true/false,
+  "matchIndex": <1-based index from candidates list, or null>,
+  "similarity": <0.0-1.0, or null>,
+  "confidence": "high|medium|low",
+  "explanation": "Brief explanation of why they match",
+  "reasons": ["reason1", "reason2"]
+}
+
+If no semantic match found, set hasMatch to false.`;
+        try {
+            const result = await callLLM(prompt, { maxTokens: 512, temperature: 0.2 });
+            if (result.success && result.text) {
+                const jsonMatch = result.text.match(/\{[\s\S]*\}/);
+                if (jsonMatch) {
+                    const parsed = JSON.parse(jsonMatch[0]);
+                    if (parsed.hasMatch && parsed.matchIndex && parsed.matchIndex > 0 && parsed.matchIndex <= codeEndpoints.length) {
+                        const codeEndpoint = codeEndpoints[parsed.matchIndex - 1];
+                        matches.push({
+                            openApiEndpoint: oaEndpoint,
+                            codeEndpoint,
+                            similarity: parsed.similarity || 0.7,
+                            explanation: parsed.explanation || 'Semantic match detected by AI',
+                            confidence: parsed.confidence || 'medium',
+                            reasons: parsed.reasons || []
+                        });
+                        log.info('Semantic match found', {
+                            openApi: `${oaEndpoint.method} ${oaEndpoint.path}`,
+                            code: `${codeEndpoint.method} ${codeEndpoint.path}`,
+                            similarity: parsed.similarity
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            log.warn('Semantic matching failed for endpoint', {
+                endpoint: `${oaEndpoint.method} ${oaEndpoint.path}`,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return matches;
+}
+/**
+ * Finds semantic parameter mismatches using AI
+ */
+async function findParameterSemanticMismatches(openApiEndpoint, codeEndpoint) {
+    const mismatches = [];
+    // Get parameter names from OpenAPI (combine path, query, and header params)
+    const allSpecParams = [
+        ...(openApiEndpoint.pathParams || []),
+        ...(openApiEndpoint.queryParams || []),
+        ...(openApiEndpoint.headerParams || [])
+    ];
+    const specParams = allSpecParams.map((p) => p.name);
+    const codeParams = codeEndpoint.parameters || [];
+    if (specParams.length === 0 || codeParams.length === 0) {
+        return mismatches; // No parameters to compare
+    }
+    const prompt = `Compare parameter names between API spec and code implementation.
+
+Endpoint: ${openApiEndpoint.method} ${openApiEndpoint.path}
+
+Spec Parameters: ${specParams.join(', ')}
+Code Parameters: ${codeParams.join(', ')}
+
+Task: Find semantic mismatches where parameter names differ but likely refer to the same thing.
+
+Examples:
+- "userId" in spec vs "user_id" in code → Same thing, different naming convention
+- "productId" in spec vs "itemId" in code → Might be semantic mismatch if product ≠ item
+
+Respond in JSON array format (max 3 mismatches):
+[
+  {
+    "type": "parameter_names",
+    "specParam": "userId",
+    "codeParam": "user_id",
+    "severity": "warning",
+    "description": "Parameter name differs in naming convention",
+    "suggestion": "Use consistent naming: either camelCase or snake_case"
+  }
+]
+
+Return empty array [] if no mismatches.`;
+    try {
+        const result = await callLLM(prompt, { maxTokens: 512, temperature: 0.3 });
+        if (result.success && result.text) {
+            const jsonMatch = result.text.match(/\[[\s\S]*\]/);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
+                for (const item of parsed) {
+                    mismatches.push({
+                        type: 'parameter_names',
+                        endpoint: {
+                            method: openApiEndpoint.method,
+                            path: openApiEndpoint.path
+                        },
+                        description: item.description,
+                        expected: item.specParam,
+                        actual: item.codeParam,
+                        severity: item.severity || 'warning',
+                        suggestion: item.suggestion
+                    });
+                }
+            }
+        }
+    }
+    catch (error) {
+        log.warn('Parameter semantic analysis failed', {
+            endpoint: `${openApiEndpoint.method} ${openApiEndpoint.path}`,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+    return mismatches;
+}
+/**
+ * Maps business rules from PRD to code implementation using AI
+ */
+async function mapBusinessRulesToImplementation(prd, codeEndpoints) {
+    const mappings = [];
+    // Limit to top 5 business rules
+    const rulesToAnalyze = prd.businessRules.slice(0, 5);
+    for (const rule of rulesToAnalyze) {
+        const prompt = `Map this business rule to code endpoints.
+
+Business Rule: "${rule.name}"
+Condition: ${rule.condition || 'none'}
+Expected Outcome: ${rule.expectedOutcome || 'none'}
+
+Available Endpoints:
+${codeEndpoints.slice(0, 20).map((ce, idx) => `${idx + 1}. ${ce.method} ${ce.path}${ce.handlerName ? ` (${ce.handlerName})` : ''}`).join('\n')}
+
+Task: Identify which endpoints likely implement this business rule.
+
+Respond in JSON:
+{
+  "mappedEndpoints": [1, 3, 5],  // 1-based indices, or empty array
+  "confidence": 0.8,  // 0.0-1.0
+  "explanation": "Brief explanation"
+}`;
+        try {
+            const result = await callLLM(prompt, { maxTokens: 256, temperature: 0.3 });
+            if (result.success && result.text) {
+                const jsonMatch = result.text.match(/\{[\s\S]*\}/);
+                if (jsonMatch) {
+                    const parsed = JSON.parse(jsonMatch[0]);
+                    const mappedTo = (parsed.mappedEndpoints || [])
+                        .filter((idx) => idx > 0 && idx <= codeEndpoints.length)
+                        .map((idx) => `${codeEndpoints[idx - 1].method} ${codeEndpoints[idx - 1].path}`);
+                    if (mappedTo.length > 0) {
+                        mappings.push({
+                            rule: rule.name,
+                            mappedTo,
+                            confidence: parsed.confidence || 0.5
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            log.warn('Business rule mapping failed', {
+                rule: rule.name,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return mappings;
+}
+/**
+ * Normalizes path for comparison (converts :param to {param})
+ */
+function normalizePath(path) {
+    return path.replace(/:([\w]+)/g, '{$1}').replace(/\/$/, '');
+}
+//# sourceMappingURL=semantic-matcher.js.map