@veraxhq/verax 0.1.0 → 0.2.1

package/src/verax/detect/expectation-model.js

@@ -1,204 +1,277 @@
 import { getUrlPath } from './evidence-validator.js';
-import { ExpectationProof } from '../shared/expectation-proof.js';
+
+function routeMatchesUrl(routePath, url) {
+  const urlPath = getUrlPath(url);
+  if (!urlPath) return false;
+  
+  const normalizedRoute = routePath.replace(/\/$/, '') || '/';
+  const normalizedUrl = urlPath.replace(/\/$/, '') || '/';
+  
+  if (normalizedRoute === normalizedUrl) return true;
+  
+  if (normalizedRoute.includes(':')) {
+    const routeParts = normalizedRoute.split('/');
+    const urlParts = normalizedUrl.split('/');
+    
+    if (routeParts.length !== urlParts.length) return false;
+    
+    for (let i = 0; i < routeParts.length; i++) {
+      if (routeParts[i].startsWith(':')) continue;
+      if (routeParts[i] !== urlParts[i]) return false;
+    }
+    return true;
+  }
+  
+  return false;
+}
+
+function normalizeExpectationType(expectationType) {
+  if (expectationType === 'spa_navigation') {
+    return 'navigation';
+  }
+  return expectationType;
+}
+
+/**
+ * Normalize selector for comparison.
+ * Removes brackets, parentheses, and normalizes whitespace.
+ */
+function normalizeSelector(selector) {
+  if (!selector) return '';
+  return selector.replace(/[[\]()]/g, '').trim();
+}
 
 /**
- * Extracts href value from interaction selector.
- * Used to match SPA expectations by href attribute.
+ * Check if two selectors match.
+ * Returns true if:
+ * - Exact match, OR
+ * - One contains the other (after normalization)
  */
-function extractHrefFromSelector(selector) {
-  if (!selector) return null;
+function selectorsMatch(selector1, selector2) {
+  if (!selector1 || !selector2) return false;
   
-  // Match href="/about" or href='/about' in selector
-  const hrefMatch = selector.match(/href=["']([^"']+)["']/);
-  if (hrefMatch) {
-    return hrefMatch[1];
-  }
+  const norm1 = normalizeSelector(selector1);
+  const norm2 = normalizeSelector(selector2);
   
-  return null;
+  if (selector1 === selector2) return true;
+  if (norm1 === norm2) return true;
+  if (selector1.includes(selector2)) return true;
+  if (selector2.includes(selector1)) return true;
+  if (norm1.includes(norm2)) return true;
+  if (norm2.includes(norm1)) return true;
+  
+  return false;
 }
 
 /**
- * Returns expectation info for an interaction at a given URL.
- * Wave 0: PROVEN expectations from staticExpectations (HTML-derived)
- * Wave 1: PROVEN expectations from spaExpectations (AST-derived JSX contracts)
- * Wave 5: PROVEN expectations from actionContracts (AST-derived network actions)
- * Wave 8: PROVEN expectations from actionContracts (AST-derived state actions)
- * 
- * @returns {{ hasExpectation: boolean, proof: string, expectedTargetPath?: string, expectationType?: string, method?: string, urlPath?: string, stateKind?: string }}
+ * Check if interaction type is compatible with expectation type.
  */
-export function getExpectation(manifest, interaction, beforeUrl, attemptMeta = {}) {
-  // Wave 5/6/8 - ACTION CONTRACTS: Check network and state action expectations
-  if (manifest.actionContracts && manifest.actionContracts.length > 0) {
-    // Priority: handlerRef (cross-file) → sourceRef (inline)
-    const handlerMatch = attemptMeta.handlerRef
-      ? manifest.actionContracts.find(
-          (contract) => contract.handlerRef === attemptMeta.handlerRef
-        )
-      : null;
-    if (handlerMatch) {
-      if (handlerMatch.kind === 'NETWORK_ACTION') {
-        return {
-          hasExpectation: true,
-          proof: ExpectationProof.PROVEN_EXPECTATION,
-          expectationType: 'network_action',
-          method: handlerMatch.method,
-          urlPath: handlerMatch.urlPath
-        };
-      } else if (handlerMatch.kind === 'STATE_ACTION') {
-        return {
-          hasExpectation: true,
-          proof: ExpectationProof.PROVEN_EXPECTATION,
-          expectationType: 'state_action',
-          stateKind: handlerMatch.stateKind
-        };
-      }
+function typesCompatible(expectationType, interactionType) {
+  const normalizedType = normalizeExpectationType(expectationType);
+  if (normalizedType === 'navigation') {
+    return interactionType === 'link' || interactionType === 'button';
+  }
+  if (normalizedType === 'form_submission') {
+    return interactionType === 'form';
+  }
+  // VALIDATION INTELLIGENCE v1: Validation blocks are triggered by forms
+  if (normalizedType === 'validation_block') {
+    return interactionType === 'form';
+  }
+  if (normalizedType === 'network_action') {
+    return interactionType === 'button' || interactionType === 'form';
+  }
+  return false;
+}
+
+/**
+ * Match expectation to interaction.
+ * Returns the matched expectation or null.
+ */
+export function matchExpectation(expectation, interaction, beforeUrl) {
+  const beforePath = getUrlPath(beforeUrl);
+  if (!beforePath) return null;
+  
+  const normalizedBefore = beforePath.replace(/\/$/, '') || '/';
+  const normalizedFrom = expectation.fromPath.replace(/\/$/, '') || '/';
+  const normalizedType = normalizeExpectationType(expectation.type);
+  
+  if (normalizedFrom !== normalizedBefore) return null;
+  
+  if (!typesCompatible(normalizedType, interaction.type)) return null;
+  
+  const selectorHint = expectation.evidence?.selectorHint || '';
+  const interactionSelector = interaction.selector || '';
+  
+  if (selectorHint && interactionSelector) {
+    if (selectorsMatch(selectorHint, interactionSelector)) {
+      return { ...expectation, type: normalizedType };
     }
+  } else if (!selectorHint && !interactionSelector) {
+    return { ...expectation, type: normalizedType };
+  }
+  
+  return null;
+}
 
-    const sourceMatch = attemptMeta.sourceRef
-      ? manifest.actionContracts.find(
-          (contract) => contract.source === attemptMeta.sourceRef
-        )
-      : null;
-    if (sourceMatch) {
-      if (sourceMatch.kind === 'NETWORK_ACTION') {
-        return {
-          hasExpectation: true,
-          proof: ExpectationProof.PROVEN_EXPECTATION,
-          expectationType: 'network_action',
-          method: sourceMatch.method,
-          urlPath: sourceMatch.urlPath
-        };
-      } else if (sourceMatch.kind === 'STATE_ACTION') {
-        return {
-          hasExpectation: true,
-          proof: ExpectationProof.PROVEN_EXPECTATION,
-          expectationType: 'state_action',
-          stateKind: sourceMatch.stateKind
-        };
+function _matchesStaticExpectation(expectation, interaction, afterUrl) {
+  if (interaction.type !== 'link') return false;
+  
+  const afterPath = getUrlPath(afterUrl);
+  if (!afterPath) return false;
+  
+  const normalizedTarget = expectation.targetPath.replace(/\/$/, '') || '/';
+  const normalizedAfter = afterPath.replace(/\/$/, '') || '/';
+  
+  if (normalizedAfter === normalizedTarget) {
+    return true;
+  }
+  
+  const selectorHint = expectation.evidence.selectorHint || '';
+  const interactionSelector = interaction.selector || '';
+  const _interactionLabel = (interaction.label || '').toLowerCase().trim();
+  
+  if (selectorHint && interactionSelector) {
+    if (selectorHint.includes(interactionSelector) || interactionSelector.includes(selectorHint.replace(/[\]()]/g, ''))) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+export function expectsNavigation(manifest, interaction, beforeUrl) {
+  if (manifest.staticExpectations && manifest.staticExpectations.length > 0) {
+    for (const expectation of manifest.staticExpectations) {
+      const matched = matchExpectation(expectation, interaction, beforeUrl);
+      if (matched) {
+        return true;
       }
     }
   }
   
-  // Wave 1 - CODE TRUTH ENGINE: Check SPA expectations (AST-derived contracts)
-  if (manifest.spaExpectations && manifest.spaExpectations.length > 0) {
-    // For link interactions, extract href and match against expectations
-    if (interaction.type === 'link') {
-      const href = extractHrefFromSelector(interaction.selector);
-      
-      if (href) {
-        // Normalize href (remove trailing slash, ensure leading slash)
-        const normalizedHref = (href.startsWith('/') ? href : '/' + href).replace(/\/$/, '') || '/';
-        
-        for (const expectation of manifest.spaExpectations) {
-          if (expectation.proof !== ExpectationProof.PROVEN_EXPECTATION) {
-            continue;
-          }
-          
-          const normalizedTarget = expectation.targetPath.replace(/\/$/, '') || '/';
-          
-          // Match by href attribute value
-          if (expectation.matchAttribute === 'href' && normalizedHref === normalizedTarget) {
-            return {
-              hasExpectation: true,
-              proof: ExpectationProof.PROVEN_EXPECTATION,
-              expectedTargetPath: expectation.targetPath,
-              expectationType: 'spa_navigation'
-            };
-          }
+  if (manifest.projectType === 'react_spa' && interaction.type === 'link') {
+    const beforePath = getUrlPath(beforeUrl);
+    if (beforePath) {
+      const href = interaction.selector ? interaction.selector.match(/href=["']([^"']+)["']/) : null;
+      if (!href) {
+        for (const route of (manifest.routes || [])) {
+          if (!route.public) continue;
+          const routePath = route.path.toLowerCase();
+          const routeName = routePath.split('/').pop() || 'home';
+          const interactionLabel = (interaction.label || '').toLowerCase().trim();
           
-          // Also match 'to' attribute for React Router
-          if (expectation.matchAttribute === 'to' && normalizedHref === normalizedTarget) {
-            return {
-              hasExpectation: true,
-              proof: ExpectationProof.PROVEN_EXPECTATION,
-              expectedTargetPath: expectation.targetPath,
-              expectationType: 'spa_navigation'
-            };
+          if (interactionLabel.includes(routeName) || routeName.includes(interactionLabel)) {
+            return true;
           }
         }
       }
     }
   }
   
-  // Wave 0: Static HTML expectations
-  if (manifest.staticExpectations && manifest.staticExpectations.length > 0) {
-    const beforePath = getUrlPath(beforeUrl);
-    if (beforePath) {
-      const normalizedBefore = beforePath.replace(/\/$/, '') || '/';
+  if (interaction.type === 'link') {
+    const label = (interaction.label || '').toLowerCase().trim();
+    
+    for (const route of (manifest.routes || [])) {
+      if (!route.public) continue;
+      
+      const routePath = route.path.toLowerCase();
+      const routeName = routePath.split('/').pop() || 'home';
       
-      for (const expectation of manifest.staticExpectations) {
-        if (expectation.proof !== ExpectationProof.PROVEN_EXPECTATION) {
-          continue; // Only consider proven expectations
+      if (label.includes(routeName) || routeName.includes(label)) {
+        return true;
+      }
+      
+      if (routeMatchesUrl(route.path, beforeUrl + route.path)) {
+        return true;
+      }
+    }
+  }
+  
+  if (interaction.type === 'button' || interaction.type === 'form') {
+    const label = (interaction.label || '').toLowerCase().trim();
+    
+    const navigationKeywords = ['go', 'navigate', 'next', 'continue', 'submit', 'save'];
+    const hasNavKeyword = navigationKeywords.some(keyword => label.includes(keyword));
+    
+    if (hasNavKeyword) {
+      for (const route of (manifest.routes || [])) {
+        if (!route.public) continue;
+        if (route.path === '/' && label.includes('home')) {
+          return true;
         }
-        
-        if (expectation.type === 'navigation') {
-          const normalizedFrom = expectation.fromPath.replace(/\/$/, '') || '/';
-          
-          if (normalizedFrom === normalizedBefore) {
-            if (interaction.type === 'link' || interaction.type === 'button') {
-              const selectorHint = expectation.evidence.selectorHint || '';
-              const interactionSelector = interaction.selector || '';
-              
-              if (selectorHint && interactionSelector) {
-                const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
-                const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
-                
-                if (selectorHint === interactionSelector || 
-                    selectorHint.includes(interactionSelector) || 
-                    interactionSelector.includes(normalizedSelectorHint) ||
-                    normalizedSelectorHint === normalizedInteractionSelector) {
-                  return {
-                    hasExpectation: true,
-                    proof: ExpectationProof.PROVEN_EXPECTATION,
-                    expectedTargetPath: expectation.targetPath,
-                    expectationType: 'navigation'
-                  };
-                }
-              }
-            }
-          }
-        } else if (expectation.type === 'form_submission') {
-          const normalizedFrom = expectation.fromPath.replace(/\/$/, '') || '/';
-          
-          if (normalizedFrom === normalizedBefore && interaction.type === 'form') {
-            const selectorHint = expectation.evidence.selectorHint || '';
-            const interactionSelector = interaction.selector || '';
-            
-            if (selectorHint && interactionSelector) {
-              const normalizedSelectorHint = selectorHint.replace(/[\[\]()]/g, '');
-              const normalizedInteractionSelector = interactionSelector.replace(/[\[\]()]/g, '');
-              
-              if (selectorHint === interactionSelector || 
-                  selectorHint.includes(interactionSelector) || 
-                  interactionSelector.includes(normalizedSelectorHint) ||
-                  normalizedSelectorHint === normalizedInteractionSelector) {
-                return {
-                  hasExpectation: true,
-                  proof: ExpectationProof.PROVEN_EXPECTATION,
-                  expectedTargetPath: expectation.targetPath,
-                  expectationType: 'form_submission'
-                };
-              }
-            }
-          }
+        if (route.path !== '/') {
+          return true;
         }
       }
     }
+    
+    for (const route of (manifest.routes || [])) {
+      if (!route.public) continue;
+      const routePath = route.path.toLowerCase();
+      const routeName = routePath.split('/').pop() || 'home';
+      
+      if (routeName === 'home' && (label.includes('home') || label.includes('main') || label.includes('index'))) {
+        return true;
+      }
+      
+      if (label.includes(routeName) || routeName.includes(label)) {
+        return true;
+      }
+    }
   }
   
-  // No proven expectation found - all heuristic matching removed
-  return {
-    hasExpectation: false,
-    proof: ExpectationProof.UNKNOWN_EXPECTATION
-  };
+  return false;
 }
 
 /**
- * Legacy function for backward compatibility.
- * Now delegates to getExpectation and returns boolean.
+ * Get expectation for interaction from manifest (unified API for static and action contracts)
+ * @param {Object} manifest - Project manifest
+ * @param {Object} interaction - Interaction object
+ * @param {string} beforeUrl - URL before interaction
+ * @param {Object} [attemptMeta] - Optional metadata about the interaction attempt
+ * @returns {Object} { hasExpectation: boolean, proof: string, ...expectationData }
  */
-export function expectsNavigation(manifest, interaction, beforeUrl) {
-  const expectation = getExpectation(manifest, interaction, beforeUrl);
-  return expectation.hasExpectation && expectation.proof === ExpectationProof.PROVEN_EXPECTATION;
+export function getExpectation(manifest, interaction, beforeUrl, attemptMeta = {}) {
+  // Check static expectations first (for static sites)
+  if (manifest.staticExpectations && manifest.staticExpectations.length > 0) {
+    for (const expectation of manifest.staticExpectations) {
+      const matched = matchExpectation(expectation, interaction, beforeUrl);
+      if (matched) {
+        return {
+          hasExpectation: true,
+          proof: expectation.proof || 'PROVEN_EXPECTATION',
+          expectationType: expectation.type,
+          expectedTargetPath: expectation.targetPath,
+          ...expectation
+        };
+      }
+    }
+  }
+  
+  // Check action contracts (for apps with source-level contracts)
+  if (manifest.actionContracts && manifest.actionContracts.length > 0) {
+    const sourceRef = attemptMeta?.sourceRef;
+    if (sourceRef) {
+      for (const contract of manifest.actionContracts) {
+        if (contract.source === sourceRef) {
+          const expectationType = contract.kind === 'NETWORK_ACTION' ? 'network_action' : 'action';
+          return {
+            hasExpectation: true,
+            proof: 'PROVEN_EXPECTATION',
+            expectationType,
+            method: contract.method,
+            urlPath: contract.urlPath,
+            ...contract
+          };
+        }
+      }
+    }
+  }
+  
+  return {
+    hasExpectation: false,
+    proof: 'UNKNOWN_EXPECTATION'
+  };
 }
 

package/src/verax/detect/explanation-helpers.js

@@ -0,0 +1,187 @@
+/**
+ * PHASE 9: Reality Confidence & Explanation Layer
+ * 
+ * Helper functions to generate human-readable explanations for findings.
+ */
+
+/**
+ * Generate a human summary - one short sentence describing what the USER experienced.
+ * NO technical jargon.
+ */
+export function generateHumanSummary(finding, _trace) {
+  const findingType = finding.type || '';
+  const interaction = finding.interaction || {};
+  const label = interaction.label || interaction.text || 'the button';
+  const evidence = finding.evidence || {};
+  
+  switch (findingType) {
+    case 'navigation_silent_failure':
+      if (evidence.urlChanged) {
+        return `The ${label} changed the page URL, but the visible content did not change.`;
+      }
+      return `Clicking ${label} should have navigated to a different page, but nothing happened.`;
+      
+    case 'network_silent_failure':
+      return `The ${label} was clicked, but the expected network request was not sent.`;
+      
+    case 'validation_silent_failure':
+      return `Submitting the form did not show any validation feedback, even though validation should have occurred.`;
+      
+    case 'state_silent_failure':
+      return `The ${label} was clicked, but the expected state change did not happen.`;
+      
+    case 'reality_dead_interaction':
+      return `The ${label} was clickable, but nothing happened after clicking it.`;
+      
+    case 'partial_navigation_failure':
+      return `The ${label} started navigating, but did not reach the expected destination.`;
+      
+    case 'silent_failure':
+    case 'flow_silent_failure':
+      return `The ${label} was clicked, but the expected result did not occur.`;
+      
+    case 'observed_break':
+      return `The ${label} behaved differently than expected based on previous observations.`;
+      
+    default:
+      return `An unexpected issue occurred with ${label}.`;
+  }
+}
+
+/**
+ * Generate action hint for a finding.
+ * Returns: { recommendedAction: 'FIX' | 'REVIEW' | 'IGNORE', reason, suggestedNextStep }
+ */
+export function generateActionHint(finding, confidence) {
+  const findingType = finding.type || '';
+  // Handle both full confidence object and simple confidence object
+  const confidenceLevel = confidence?.level || finding.confidence?.level || 'UNKNOWN';
+  const expectationStrength = confidence?.factors?.expectationStrength || 
+                              finding.confidence?.factors?.expectationStrength || 
+                              'UNKNOWN';
+  
+  // Rules:
+  // - PROVEN silent_failure (MEDIUM/HIGH) → FIX
+  // - reality_dead_interaction → REVIEW
+  // - coverage_gap → IGNORE
+  // - LOW confidence findings → REVIEW
+  // - HIGH confidence findings → FIX
+  
+  if (findingType === 'reality_dead_interaction') {
+    return {
+      recommendedAction: 'REVIEW',
+      reason: 'This is a dead interaction that may be intentional or a design issue',
+      suggestedNextStep: 'Check if this button is supposed to do something. If yes, add a handler. If no, remove it or disable it.'
+    };
+  }
+  
+  // Coverage gaps are informational only
+  if (findingType.includes('coverage') || findingType === 'coverage_gap') {
+    return {
+      recommendedAction: 'IGNORE',
+      reason: 'This is a coverage gap, not a user-facing failure',
+      suggestedNextStep: 'No action needed - this indicates incomplete test coverage, not a broken feature'
+    };
+  }
+  
+  // PROVEN expectations with MEDIUM/HIGH confidence → FIX
+  if (expectationStrength === 'PROVEN' && (confidenceLevel === 'HIGH' || confidenceLevel === 'MEDIUM')) {
+    return {
+      recommendedAction: 'FIX',
+      reason: 'Your code explicitly promises this behavior, and evidence shows it failed',
+      suggestedNextStep: 'Fix the implementation to match what your code promises, or update the code if the promise changed'
+    };
+  }
+  
+  // HIGH confidence (even if not PROVEN) → FIX
+  if (confidenceLevel === 'HIGH') {
+    return {
+      recommendedAction: 'FIX',
+      reason: 'Strong evidence indicates this is a real failure',
+      suggestedNextStep: 'Investigate and fix the issue'
+    };
+  }
+  
+  // MEDIUM confidence → REVIEW
+  if (confidenceLevel === 'MEDIUM') {
+    return {
+      recommendedAction: 'REVIEW',
+      reason: 'Evidence suggests a failure, but some uncertainty remains',
+      suggestedNextStep: 'Review the finding and evidence to determine if this is a real issue or a false positive'
+    };
+  }
+  
+  // LOW confidence → REVIEW
+  if (confidenceLevel === 'LOW') {
+    return {
+      recommendedAction: 'REVIEW',
+      reason: 'Limited evidence - this may be a false positive',
+      suggestedNextStep: 'Review manually to confirm if this is a real issue'
+    };
+  }
+  
+  // Default for unknown
+  return {
+    recommendedAction: 'REVIEW',
+    reason: 'Insufficient information to determine action',
+    suggestedNextStep: 'Review the finding and evidence manually'
+  };
+}
+
+/**
+ * Derive a confidence explanation structure for findings.
+ * Ensures required fields exist even if upstream confidence missed them.
+ */
+export function deriveConfidenceExplanation(confidence = {}, findingType = 'unknown') {
+  const base = confidence.confidenceExplanation || {};
+  const factors = confidence.factors || {};
+  const expectationStrength = factors.expectationStrength || 'UNKNOWN';
+  const sensorsPresent = factors.sensorsPresent || {};
+
+  const why = Array.isArray(base.whyThisConfidence) && base.whyThisConfidence.length > 0
+    ? base.whyThisConfidence
+    : [
+        expectationStrength === 'PROVEN'
+          ? 'Expectation is proven and failed in practice'
+          : `Expectation strength is ${expectationStrength}, adding uncertainty`,
+        sensorsPresent.network || sensorsPresent.console || sensorsPresent.ui
+          ? 'Some evidence was captured from available sensors'
+          : 'Limited evidence captured from sensors'
+      ];
+
+  const whatIncrease = Array.isArray(base.whatWouldIncreaseConfidence) && base.whatWouldIncreaseConfidence.length > 0
+    ? base.whatWouldIncreaseConfidence
+    : [
+        expectationStrength === 'PROVEN'
+          ? 'Capture more sensor evidence (network/console/UI) for this interaction'
+          : 'Make this expectation PROVEN or capture more evidence to remove uncertainty'
+      ];
+
+  const whatReduce = Array.isArray(base.whatWouldReduceConfidence) && base.whatWouldReduceConfidence.length > 0
+    ? base.whatWouldReduceConfidence
+    : ['Confidence would drop if sensors were missing or expectation weakened'];
+
+  return {
+    whyThisConfidence: dedupeStrings(why),
+    whatWouldIncreaseConfidence: dedupeStrings(whatIncrease),
+    whatWouldReduceConfidence: dedupeStrings(whatReduce),
+    expectationStrength,
+    sensorsPresent,
+    findingType
+  };
+}
+
+function dedupeStrings(list = []) {
+  const seen = new Set();
+  const output = [];
+  for (const item of list) {
+    const val = String(item || '').trim();
+    if (!val) continue;
+    if (!seen.has(val)) {
+      seen.add(val);
+      output.push(val);
+    }
+  }
+  return output;
+}
+