@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/detect/problem-aggregator.js

@@ -0,0 +1,361 @@
+/**
+ * Problem Aggregator
+ * 
+ * Groups raw findings into decision-level problems for executive review.
+ * 
+ * RULES:
+ * - Deterministic grouping (no ML, no heuristics)
+ * - Every problem references underlying findings
+ * - Raw findings are preserved (never hidden)
+ * - Evidence is deduplicated across group
+ */
+
+import { basename } from 'path';
+
+/**
+ * Aggregate findings into decision-level problems
+ * 
+ * @param {Array} findings - Raw findings from detection
+ * @param {Object} manifest - Project manifest
+ * @returns {Array} Array of ProblemGroup objects
+ */
+export function aggregateProblems(findings, manifest) {
+  if (!findings || findings.length === 0) {
+    return [];
+  }
+
+  // Group findings by page/route
+  const byPage = groupByPage(findings);
+  
+  // Within each page, group by user intent
+  const problems = [];
+  
+  for (const [page, pageFindings] of Object.entries(byPage)) {
+    const intentGroups = groupByIntent(pageFindings);
+    
+    for (const [intent, intentFindings] of Object.entries(intentGroups)) {
+      // Create a problem group
+      const problem = createProblemGroup(page, intent, intentFindings, manifest);
+      if (problem) {
+        problems.push(problem);
+      }
+    }
+  }
+  
+  // Sort by impact (HIGH > MEDIUM > LOW) then confidence (HIGH > LOW)
+  problems.sort((a, b) => {
+    const impactOrder = { HIGH: 3, MEDIUM: 2, LOW: 1, UNKNOWN: 0 };
+    const impactDiff = impactOrder[b.impact] - impactOrder[a.impact];
+    if (impactDiff !== 0) return impactDiff;
+    return b.confidence - a.confidence;
+  });
+  
+  return problems;
+}
+
+/**
+ * Group findings by page/route
+ */
+function groupByPage(findings) {
+  const groups = {};
+  
+  for (const finding of findings) {
+    const page = extractPage(finding);
+    if (!groups[page]) {
+      groups[page] = [];
+    }
+    groups[page].push(finding);
+  }
+  
+  return groups;
+}
+
+/**
+ * Extract page identifier from finding
+ */
+function extractPage(finding) {
+  if (!finding.source || !finding.source.file) {
+    return 'unknown';
+  }
+  
+  // Extract filename without extension
+  const file = finding.source.file;
+  const filename = basename(file, '.jsx').replace(/\.js$/, '');
+  
+  // Map common patterns to routes
+  if (filename.match(/dashboard/i)) return 'dashboard';
+  if (filename.match(/profile/i)) return 'profile';
+  if (filename.match(/settings/i)) return 'settings';
+  if (filename.match(/home|index/i)) return 'home';
+  if (filename.match(/login|auth/i)) return 'auth';
+  
+  return filename.toLowerCase();
+}
+
+/**
+ * Group findings by user intent
+ */
+function groupByIntent(findings) {
+  const groups = {};
+  
+  for (const finding of findings) {
+    const intent = inferIntent(finding);
+    if (!groups[intent]) {
+      groups[intent] = [];
+    }
+    groups[intent].push(finding);
+  }
+  
+  return groups;
+}
+
+/**
+ * Infer user intent from finding
+ */
+function inferIntent(finding) {
+  const promise = finding.promise || {};
+  const type = finding.type;
+  const source = finding.source || {};
+  const file = source.file || '';
+  
+  // Form submission
+  if (type === 'form' || promise.kind === 'submit') {
+    return 'save';
+  }
+  
+  // Navigation
+  if (type === 'navigation' || promise.kind === 'navigate') {
+    return 'navigate';
+  }
+  
+  // Auth actions - explicit button clicks
+  if (promise.kind === 'click' && promise.value && promise.value.match(/login|logout|signin|signout/i)) {
+    return 'auth';
+  }
+  
+  // State changes - be more specific about what kind
+  if (type === 'state' || promise.kind === 'state_mutation') {
+    const value = promise.value || '';
+    
+    // Loading/saving state - usually indicates stuck loading indicator
+    if (value.match(/loading|saving|submitting/i) || file.match(/dashboard/i)) {
+      return 'loading_feedback';
+    }
+    
+    // Auth-related state
+    if (value.match(/auth|user|login/i) || file.match(/auth|profile/i)) {
+      // If in Profile.jsx specifically, it's conditional UI bug
+      if (file.match(/profile/i)) {
+        return 'conditional_ui';
+      }
+      return 'auth_state';
+    }
+    
+    // Generic state update
+    return 'state_update';
+  }
+  
+  // Feedback/validation
+  if (type === 'feedback' || promise.kind === 'validation') {
+    return 'validation';
+  }
+  
+  // Button clicks
+  if (promise.kind === 'click') {
+    return 'interact';
+  }
+  
+  return 'other';
+}
+
+/**
+ * Create a problem group from findings
+ */
+function createProblemGroup(page, intent, findings, _manifest) {
+  if (findings.length === 0) {
+    return null;
+  }
+  
+  // Generate problem ID
+  const id = `problem_${page}_${intent}`;
+  
+  // Determine title based on intent
+  const title = generateTitle(page, intent, findings);
+  
+  // Aggregate impact (highest wins)
+  const impact = aggregateImpact(findings);
+  
+  // Aggregate confidence (average)
+  const confidence = aggregateConfidence(findings);
+  
+  // Deduplicate evidence
+  const evidence = deduplicateEvidence(findings);
+  
+  // Extract finding IDs
+  const findingIds = findings.map(f => f.id);
+  
+  // Generate explanation
+  const explanation = generateExplanation(page, intent, findings);
+  
+  return {
+    id,
+    title,
+    page,
+    userIntent: intent,
+    impact,
+    confidence,
+    findings: findingIds,
+    findingCount: findings.length,
+    evidence,
+    whatUserTried: explanation.whatUserTried,
+    whatWasExpected: explanation.whatWasExpected,
+    whatActuallyHappened: explanation.whatActuallyHappened,
+    whyItMatters: explanation.whyItMatters
+  };
+}
+
+/**
+ * Generate human-readable title for problem
+ */
+function generateTitle(page, intent, findings) {
+  const pageName = page.charAt(0).toUpperCase() + page.slice(1);
+  
+  const intentMap = {
+    navigate: `${pageName} page doesn't load`,
+    save: `${pageName} form submission fails silently`,
+    auth: `${pageName} authentication fails silently`,
+    auth_state: `${pageName} authentication state doesn't update UI`,
+    conditional_ui: `${pageName} conditional UI doesn't update after state change`,
+    loading_feedback: `${pageName} loading state never resolves`,
+    state_update: `${pageName} state changes don't update UI`,
+    validation: `${pageName} validation feedback missing`,
+    interact: `${pageName} interactive elements don't work`,
+    other: `${pageName} has broken functionality`
+  };
+  
+  return intentMap[intent] || `${pageName} has ${findings.length} silent failures`;
+}
+
+/**
+ * Aggregate impact across findings (highest wins)
+ */
+function aggregateImpact(findings) {
+  const impactOrder = { HIGH: 3, MEDIUM: 2, LOW: 1, UNKNOWN: 0 };
+  let maxImpact = 'UNKNOWN';
+  let maxValue = 0;
+  
+  for (const finding of findings) {
+    const impact = finding.impact || 'UNKNOWN';
+    const value = impactOrder[impact] || 0;
+    if (value > maxValue) {
+      maxValue = value;
+      maxImpact = impact;
+    }
+  }
+  
+  return maxImpact;
+}
+
+/**
+ * Aggregate confidence across findings (average)
+ */
+function aggregateConfidence(findings) {
+  if (findings.length === 0) return 0;
+  
+  const sum = findings.reduce((acc, f) => acc + (f.confidence || 0.5), 0);
+  return Math.round((sum / findings.length) * 100) / 100;
+}
+
+/**
+ * Deduplicate evidence across findings
+ */
+function deduplicateEvidence(findings) {
+  const evidenceMap = new Map();
+  
+  for (const finding of findings) {
+    if (!finding.evidence) continue;
+    
+    for (const ev of finding.evidence) {
+      const key = `${ev.type}:${ev.path || 'none'}`;
+      if (!evidenceMap.has(key)) {
+        evidenceMap.set(key, ev);
+      }
+    }
+  }
+  
+  return Array.from(evidenceMap.values());
+}
+
+/**
+ * Generate explanation for problem
+ */
+function generateExplanation(page, intent, findings) {
+  const pageName = page.charAt(0).toUpperCase() + page.slice(1);
+  const count = findings.length;
+  
+  // Build explanation based on intent
+  const explanations = {
+    navigate: {
+      whatUserTried: `Navigate to ${pageName} page`,
+      whatWasExpected: 'Page content loads and displays',
+      whatActuallyHappened: `URL changed but page content did not render (${count} state mutations stuck)`,
+      whyItMatters: 'Users cannot access the intended page or see its content'
+    },
+    save: {
+      whatUserTried: `Submit form on ${pageName} page`,
+      whatWasExpected: 'Form submits and shows success feedback (message, redirect, or toast)',
+      whatActuallyHappened: `Form submitted but no feedback was provided to user (${count} related issues)`,
+      whyItMatters: 'Users don\'t know if their data was saved or if they should retry'
+    },
+    auth: {
+      whatUserTried: `Log in or log out using ${pageName} page buttons`,
+      whatWasExpected: 'Button click triggers authentication action with visual feedback',
+      whatActuallyHappened: `Button clicks produced no observable effect (${count} buttons don't work)`,
+      whyItMatters: 'Users cannot complete authentication workflows'
+    },
+    auth_state: {
+      whatUserTried: `Authenticate using ${pageName} page`,
+      whatWasExpected: 'Authentication state changes update UI accordingly',
+      whatActuallyHappened: `Auth state changed but UI did not reflect changes (${count} state mutations)`,
+      whyItMatters: 'Users cannot tell their authentication status'
+    },
+    conditional_ui: {
+      whatUserTried: `Interact with conditional UI on ${pageName} page`,
+      whatWasExpected: 'UI elements appear/disappear based on state (e.g., Login button hides after login)',
+      whatActuallyHappened: `State changed but conditional UI did not update (${count} stale elements)`,
+      whyItMatters: 'Users see UI elements that should be hidden or vice versa, causing confusion'
+    },
+    loading_feedback: {
+      whatUserTried: `Interact with ${pageName} page`,
+      whatWasExpected: 'Loading indicator appears then resolves when content is ready',
+      whatActuallyHappened: `Loading states were set but never cleared (${count} stuck states)`,
+      whyItMatters: 'Users see perpetual loading spinners or incomplete UI'
+    },
+    state_update: {
+      whatUserTried: `Interact with ${pageName} page elements`,
+      whatWasExpected: 'UI updates to reflect new state',
+      whatActuallyHappened: `State changed but UI did not update (${count} stale UI elements)`,
+      whyItMatters: 'Users see outdated information that doesn\'t match actual state'
+    },
+    validation: {
+      whatUserTried: `Submit invalid data on ${pageName} form`,
+      whatWasExpected: 'Validation errors display clearly',
+      whatActuallyHappened: `Validation feedback elements missing (${count} issues)`,
+      whyItMatters: 'Users cannot correct their mistakes or understand what went wrong'
+    },
+    interact: {
+      whatUserTried: `Click buttons or interact with elements on ${pageName}`,
+      whatWasExpected: 'Interactive elements respond with visible feedback',
+      whatActuallyHappened: `${count} interactive elements produced no observable effect`,
+      whyItMatters: 'Users cannot complete intended actions or workflows'
+    },
+    other: {
+      whatUserTried: `Use ${pageName} page functionality`,
+      whatWasExpected: 'Actions produce visible results',
+      whatActuallyHappened: `${count} actions failed silently with no user feedback`,
+      whyItMatters: 'Core functionality is broken but fails without error messages'
+    }
+  };
+  
+  return explanations[intent] || explanations.other;
+}

package/src/verax/detect/route-findings.js

@@ -0,0 +1,219 @@
+/**
+ * PHASE 12 — Route Intelligence Findings Detector
+ * 
+ * Detects route-related silent failures by correlating navigation promises
+ * with route definitions and evaluating outcomes.
+ */
+
+import {
+  buildRouteModels,
+  correlateNavigationWithRoute,
+  evaluateRouteNavigation,
+  buildRouteEvidence,
+  isRouteChangeFalsePositive,
+} from '../core/route-intelligence.js';
+import { computeConfidenceForFinding } from '../core/confidence-engine.js';
+import { buildAndEnforceEvidencePackage } from '../core/evidence-builder.js';
+import { applyGuardrails } from '../core/guardrails-engine.js';
+
+/**
+ * PHASE 12: Detect route-related findings
+ * 
+ * @param {Array} traces - Interaction traces
+ * @param {Object} manifest - Project manifest with routes and expectations
+ * @param {Array} _findings - Findings array to append to
+ * @ts-expect-error - JSDoc param documented but unused
+ * @returns {Array} Route-related findings
+ */
+export function detectRouteFindings(traces, manifest, _findings) {
+  const routeFindings = [];
+  
+  // Build route models from manifest routes
+  const routeModels = buildRouteModels(manifest.routes || []);
+  
+  // Process each trace
+  for (const trace of traces) {
+    const interaction = trace.interaction || {};
+    const beforeUrl = trace.before?.url || trace.sensors?.navigation?.beforeUrl || '';
+    const afterUrl = trace.after?.url || trace.sensors?.navigation?.afterUrl || '';
+    
+    // Find navigation expectations for this interaction
+    const navigationExpectations = findNavigationExpectations(manifest, interaction, beforeUrl);
+    
+    for (const expectation of navigationExpectations) {
+      const navigationTarget = expectation.targetPath || expectation.expectedTarget || '';
+      
+      if (!navigationTarget) continue;
+      
+      // Correlate navigation promise with route
+      const correlation = correlateNavigationWithRoute(navigationTarget, routeModels);
+      
+      // Check for false positives
+      if (isRouteChangeFalsePositive(trace, correlation)) {
+        continue;
+      }
+      
+      // Evaluate route navigation outcome
+      const evaluation = evaluateRouteNavigation(correlation, trace, beforeUrl, afterUrl);
+      
+      // Generate finding if needed
+      if (evaluation.outcome === 'SILENT_FAILURE' || 
+          evaluation.outcome === 'ROUTE_MISMATCH' ||
+          (evaluation.outcome === 'SUSPECTED' && evaluation.confidence >= 0.6)) {
+        
+        // Build evidence
+        const evidence = buildRouteEvidence(correlation, expectation, evaluation, trace);
+        
+        // Determine finding type
+        let findingType = 'route_silent_failure';
+        let reason = evaluation.reason || 'Route navigation promise not fulfilled';
+        
+        if (evaluation.outcome === 'ROUTE_MISMATCH') {
+          findingType = 'route_mismatch';
+          reason = `Navigation occurred but target route does not match. Expected: ${correlation?.route?.path}, Actual: ${evidence.beforeAfter.afterUrl}`;
+        } else if (evaluation.outcome === 'SUSPECTED') {
+          findingType = 'route_ambiguous';
+          reason = 'Dynamic route cannot be deterministically validated';
+        }
+        
+        // PHASE 15: Compute unified confidence
+        const unifiedConfidence = computeConfidenceForFinding({
+          findingType: findingType,
+          expectation,
+          sensors: trace.sensors || {},
+          comparisons: {
+            urlChanged: evidence.signals.urlChanged,
+            domChanged: evidence.signals.domChanged,
+          },
+          evidence,
+          options: {}
+        });
+        
+        // PHASE 12: Evidence Law - require sufficient evidence for CONFIRMED
+        const hasSufficientEvidence = evidence.beforeAfter.beforeUrl && 
+                                      evidence.beforeAfter.afterUrl &&
+                                      (evidence.signals.urlChanged || 
+                                       evidence.signals.routerStateChanged || 
+                                       evidence.signals.uiChanged || 
+                                       evidence.signals.domChanged);
+        
+        const severity = hasSufficientEvidence && (unifiedConfidence.score01 || unifiedConfidence.score || 0) >= 0.8 ? 'CONFIRMED' : 'SUSPECTED';
+        
+        const finding = {
+          type: findingType,
+          severity,
+          confidence: unifiedConfidence.score01 || unifiedConfidence.score || 0, // Contract v1: score01 canonical
+          confidenceLevel: unifiedConfidence.level, // PHASE 15: Add confidence level
+          confidenceReasons: unifiedConfidence.topReasons || unifiedConfidence.reasons || [], // Contract v1: topReasons
+          interaction: {
+            type: interaction.type,
+            selector: interaction.selector,
+            label: interaction.label,
+          },
+          reason,
+          evidence,
+          source: {
+            file: expectation.source?.file || null,
+            line: expectation.source?.line || null,
+            column: expectation.source?.column || null,
+            context: expectation.source?.context || null,
+            astSource: expectation.source?.astSource || expectation.metadata?.astSource || null,
+          },
+        };
+        
+        // PHASE 16: Build and enforce evidence package
+        const findingWithEvidence = buildAndEnforceEvidencePackage(finding, {
+          expectation,
+          trace,
+          evidence,
+          confidence: unifiedConfidence,
+        });
+        
+        // PHASE 17: Apply guardrails (AFTER evidence builder)
+        const context = {
+          evidencePackage: findingWithEvidence.evidencePackage,
+          signals: findingWithEvidence.evidencePackage?.signals || evidence.signals || {},
+          confidenceReasons: unifiedConfidence.reasons || [],
+          promiseType: expectation?.type || null,
+        };
+        const { finding: findingWithGuardrails } = applyGuardrails(findingWithEvidence, context);
+        
+        routeFindings.push(findingWithGuardrails);
+      }
+    }
+  }
+  
+  return routeFindings;
+}
+
+/**
+ * Find navigation expectations matching the interaction
+ */
+function findNavigationExpectations(manifest, interaction, beforeUrl) {
+  const expectations = [];
+  
+  // Check static expectations
+  if (manifest.staticExpectations) {
+    const beforePath = extractPathFromUrl(beforeUrl);
+    if (beforePath) {
+      const normalizedBefore = beforePath.replace(/\/$/, '') || '/';
+      
+      for (const expectation of manifest.staticExpectations) {
+        if (expectation.type !== 'navigation' && expectation.type !== 'spa_navigation') {
+          continue;
+        }
+        
+        const normalizedFrom = (expectation.fromPath || '').replace(/\/$/, '') || '/';
+        if (normalizedFrom === normalizedBefore) {
+          // Check selector match
+          const selectorHint = expectation.selectorHint || '';
+          const interactionSelector = interaction.selector || '';
+          
+          if (!selectorHint || !interactionSelector || 
+              selectorHint === interactionSelector ||
+              selectorHint.includes(interactionSelector) ||
+              interactionSelector.includes(selectorHint)) {
+            expectations.push(expectation);
+          }
+        }
+      }
+    }
+  }
+  
+  // Check expectations from intel (AST-based)
+  if (manifest.expectations) {
+    for (const expectation of manifest.expectations) {
+      if (expectation.type === 'navigation' || expectation.type === 'spa_navigation') {
+        // Match by selector or label
+        const selectorHint = expectation.selectorHint || '';
+        const interactionSelector = interaction.selector || '';
+        const interactionLabel = (interaction.label || '').toLowerCase();
+        const expectationLabel = (expectation.promise?.value || '').toLowerCase();
+        
+        if (selectorHint === interactionSelector ||
+            (expectationLabel && interactionLabel && expectationLabel.includes(interactionLabel))) {
+          expectations.push(expectation);
+        }
+      }
+    }
+  }
+  
+  return expectations;
+}
+
+/**
+ * Extract path from URL
+ */
+function extractPathFromUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  
+  try {
+    const urlObj = new URL(url);
+    return urlObj.pathname;
+  } catch {
+    // Relative URL
+    const pathMatch = url.match(/^([^?#]+)/);
+    return pathMatch ? pathMatch[1] : url;
+  }
+}
+