@veraxhq/verax 0.2.1 → 0.3.0

package/src/verax/core/report/human-summary.js

@@ -0,0 +1,222 @@
+/**
+ * PHASE 21.10 — Human Summary
+ * 
+ * Generates human-readable summary for Enterprise UX.
+ * Clear, direct, no marketing.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Load artifact JSON
+ */
+function loadArtifact(runDir, filename) {
+  const path = resolve(runDir, filename);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate human summary
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object} Human summary
+ */
+export async function generateHumanSummary(projectDir, runId) {
+  const runDir = resolve(projectDir, '.verax', 'runs', runId);
+  
+  if (!existsSync(runDir)) {
+    return null;
+  }
+  
+  const summary = loadArtifact(runDir, 'summary.json');
+  const findings = loadArtifact(runDir, 'findings.json');
+  const determinism = loadArtifact(runDir, 'decisions.json');
+  const performanceReport = loadArtifact(runDir, 'performance.report.json');
+  
+  // Security reports are in release/ directory (project root)
+  // Use projectDir parameter directly (already resolved)
+  const releaseDir = resolve(projectDir, 'release');
+  const securitySecrets = loadArtifact(releaseDir, 'security.secrets.report.json');
+  const securityVuln = loadArtifact(releaseDir, 'security.vuln.report.json');
+  
+  const gaStatus = loadArtifact(runDir, 'ga.status.json');
+  
+  if (!summary) {
+    return null;
+  }
+  
+  const findingsArray = Array.isArray(findings?.findings) ? findings.findings : [];
+  const confirmedFindings = findingsArray.filter(f => (f.severity || f.status) === 'CONFIRMED');
+  const suspectedFindings = findingsArray.filter(f => (f.severity || f.status) === 'SUSPECTED');
+  
+  // What VERAX is confident about
+  const confident = {
+    findings: confirmedFindings.length,
+    message: confirmedFindings.length > 0 
+      ? `${confirmedFindings.length} finding(s) with complete evidence`
+      : 'No findings with complete evidence',
+    details: confirmedFindings.map(f => ({
+      type: f.type,
+      outcome: f.outcome,
+      confidence: f.confidenceLevel || 'UNKNOWN'
+    }))
+  };
+  
+  // What VERAX is NOT confident about
+  const notConfident = {
+    findings: suspectedFindings.length,
+    message: suspectedFindings.length > 0
+      ? `${suspectedFindings.length} finding(s) with incomplete evidence (SUSPECTED)`
+      : 'No findings with incomplete evidence',
+    details: suspectedFindings.map(f => ({
+      type: f.type,
+      outcome: f.outcome,
+      confidence: f.confidenceLevel || 'UNKNOWN',
+      missingEvidence: f.evidencePackage?.isComplete === false
+    }))
+  };
+  
+  // Why some things were skipped
+  const skips = [];
+  if (summary.truth?.observe?.skips) {
+    for (const skip of summary.truth.observe.skips) {
+      skips.push({
+        reason: skip.reason || skip.code || 'UNKNOWN',
+        count: skip.count || 1,
+        message: skip.message || `Skipped: ${skip.reason || skip.code}`
+      });
+    }
+  }
+  
+  // Determinism verdict
+  let determinismVerdict = 'UNKNOWN';
+  if (determinism) {
+    try {
+      const { DecisionRecorder } = await import('../../../core/determinism-model.js');
+      const recorder = DecisionRecorder.fromExport(determinism);
+      const { computeDeterminismVerdict } = await import('../../../core/determinism/contract.js');
+      const verdict = computeDeterminismVerdict(recorder);
+      determinismVerdict = verdict.verdict;
+    } catch {
+      determinismVerdict = summary.determinism?.verdict || 'UNKNOWN';
+    }
+  } else if (summary.determinism) {
+    determinismVerdict = summary.determinism.verdict || 'UNKNOWN';
+  }
+  
+  // Performance verdict
+  const performanceVerdict = performanceReport?.verdict || 'UNKNOWN';
+  const performanceOk = performanceReport?.ok !== false;
+  
+  // Security verdict
+  const securityOk = !securitySecrets?.hasSecrets && 
+                     !securityVuln?.blocking &&
+                     (securitySecrets !== null || securityVuln !== null); // At least one report exists
+  
+  // GA verdict
+  const gaReady = gaStatus?.gaReady === true;
+  const gaVerdict = gaReady ? 'GA-READY' : (gaStatus ? 'GA-BLOCKED' : 'UNKNOWN');
+  
+  return {
+    runId,
+    whatWeKnow: {
+      confident: confident,
+      notConfident: notConfident,
+      skips: skips.length > 0 ? {
+        total: skips.reduce((sum, s) => sum + s.count, 0),
+        reasons: skips
+      } : null
+    },
+    verdicts: {
+      determinism: {
+        verdict: determinismVerdict,
+        message: determinismVerdict === 'DETERMINISTIC' 
+          ? 'Run was reproducible (same inputs = same outputs)'
+          : determinismVerdict === 'NON_DETERMINISTIC'
+          ? 'Run was not reproducible (adaptive events detected)'
+          : 'Determinism not evaluated'
+      },
+      performance: {
+        verdict: performanceVerdict,
+        ok: performanceOk,
+        message: performanceOk
+          ? 'Performance within budget'
+          : performanceReport?.violations?.length > 0
+          ? `${performanceReport.violations.length} BLOCKING performance violation(s)`
+          : 'Performance not evaluated'
+      },
+      security: {
+        ok: securityOk,
+        message: securityOk
+          ? 'Security baseline passed'
+          : securitySecrets?.hasSecrets
+          ? 'Secrets detected'
+          : securityVuln?.blocking
+          ? 'Critical vulnerabilities detected'
+          : 'Security not evaluated'
+      },
+      ga: {
+        verdict: gaVerdict,
+        ready: gaReady,
+        message: gaReady
+          ? 'GA-READY: All gates passed'
+          : gaStatus
+          ? `GA-BLOCKED: ${gaStatus.blockers?.length || 0} blocker(s)`
+          : 'GA not evaluated'
+      }
+    },
+    generatedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Format human summary for CLI display
+ * 
+ * @param {Object} summary - Human summary
+ * @returns {string} Formatted string
+ */
+export function formatHumanSummary(summary) {
+  if (!summary) {
+    return 'Summary: Not available';
+  }
+  
+  const lines = [];
+  lines.push('\n' + '='.repeat(80));
+  lines.push('HUMAN SUMMARY');
+  lines.push('='.repeat(80));
+  
+  // What we know
+  lines.push('\nWhat VERAX is confident about:');
+  lines.push(`  ${summary.whatWeKnow.confident.message}`);
+  
+  lines.push('\nWhat VERAX is NOT confident about:');
+  lines.push(`  ${summary.whatWeKnow.notConfident.message}`);
+  
+  if (summary.whatWeKnow.skips) {
+    lines.push('\nWhy some things were skipped:');
+    for (const skip of summary.whatWeKnow.skips.reasons) {
+      lines.push(`  - ${skip.message} (${skip.count}x)`);
+    }
+  }
+  
+  // Verdicts
+  lines.push('\nVerdicts:');
+  lines.push(`  Determinism: ${summary.verdicts.determinism.verdict} - ${summary.verdicts.determinism.message}`);
+  lines.push(`  Performance: ${summary.verdicts.performance.verdict} - ${summary.verdicts.performance.message}`);
+  lines.push(`  Security: ${summary.verdicts.security.ok ? 'OK' : 'BLOCKED'} - ${summary.verdicts.security.message}`);
+  lines.push(`  GA: ${summary.verdicts.ga.verdict} - ${summary.verdicts.ga.message}`);
+  
+  lines.push('='.repeat(80) + '\n');
+  
+  return lines.join('\n');
+}
+

package/src/verax/core/route-intelligence.js

@@ -0,0 +1,419 @@
+/**
+ * PHASE 12 — Route Intelligence & Deep Route Detection
+ * 
+ * Unified route model and intelligence layer that:
+ * - Defines route taxonomy (static, dynamic, ambiguous)
+ * - Correlates navigation promises with routes
+ * - Handles dynamic routes honestly
+ * - Provides evidence for route-related findings
+ */
+
+import { normalizeDynamicRoute, isDynamicPath, normalizeNavigationTarget } from '../shared/dynamic-route-utils.js';
+
+/**
+ * Route Taxonomy
+ */
+export const ROUTE_TYPE = {
+  STATIC: 'static',
+  DYNAMIC: 'dynamic',
+  AMBIGUOUS: 'ambiguous',
+  PROGRAMMATIC: 'programmatic'
+};
+
+export const ROUTE_STABILITY = {
+  STATIC: 'static',      // Fully static route
+  DYNAMIC: 'dynamic',    // Dynamic but can be normalized
+  AMBIGUOUS: 'ambiguous' // Cannot be deterministically validated
+};
+
+export const ROUTE_SOURCE = {
+  FILE_SYSTEM: 'file_system',  // Next.js pages/app router
+  JSX: 'jsx',                  // React Router <Route>
+  CONFIG: 'config',            // Vue Router config
+  PROGRAMMATIC: 'programmatic' // navigate(), router.push()
+};
+
+/**
+ * PHASE 12: Unified Route Model
+ * 
+ * @typedef {Object} RouteModel
+ * @property {string} path - Normalized route path
+ * @property {string} type - ROUTE_TYPE (static, dynamic, ambiguous, programmatic)
+ * @property {string} stability - ROUTE_STABILITY (static, dynamic, ambiguous)
+ * @property {string} source - ROUTE_SOURCE (file_system, jsx, config, programmatic)
+ * @property {string} framework - Framework identifier
+ * @property {string} sourceRef - Source reference (file:line:col)
+ * @property {string} file - Source file path
+ * @property {number} line - Source line number
+ * @property {string} [originalPattern] - Original dynamic pattern (if dynamic)
+ * @property {string[]} [parameters] - Dynamic parameters (if dynamic)
+ * @property {boolean} [isDynamic] - Whether route is dynamic
+ * @property {boolean} [exampleExecution] - Whether example path was generated
+ */
+
+/**
+ * Build unified route model from extracted routes
+ * 
+ * @param {Array} extractedRoutes - Routes from route extractors
+ * @returns {Array<RouteModel>} Unified route models
+ */
+export function buildRouteModels(extractedRoutes) {
+  const routeModels = [];
+  
+  for (const route of extractedRoutes) {
+    const path = route.path || '';
+    const isDynamicRoute = route.isDynamic || isDynamicPath(path);
+    
+    // Determine route type
+    let type = ROUTE_TYPE.STATIC;
+    let stability = ROUTE_STABILITY.STATIC;
+    
+    if (isDynamicRoute) {
+      type = ROUTE_TYPE.DYNAMIC;
+      
+      // Check if dynamic route can be normalized
+      if (route.originalPattern || route.exampleExecution) {
+        stability = ROUTE_STABILITY.DYNAMIC; // Can be normalized
+      } else {
+        stability = ROUTE_STABILITY.AMBIGUOUS; // Cannot be deterministically validated
+      }
+    }
+    
+    // Determine source
+    let source = ROUTE_SOURCE.PROGRAMMATIC;
+    if (route.framework === 'next-pages' || route.framework === 'next-app') {
+      source = ROUTE_SOURCE.FILE_SYSTEM;
+    } else if (route.framework === 'react-router') {
+      source = ROUTE_SOURCE.JSX;
+    } else if (route.framework === 'vue-router') {
+      source = ROUTE_SOURCE.CONFIG;
+    }
+    
+    const routeModel = {
+      path,
+      type,
+      stability,
+      source,
+      framework: route.framework || 'unknown',
+      sourceRef: route.sourceRef || `${route.file || 'unknown'}:${route.line || 1}`,
+      file: route.file || null,
+      line: route.line || null,
+    };
+    
+    // Add dynamic route metadata
+    if (isDynamicRoute) {
+      routeModel.originalPattern = route.originalPattern || path;
+      routeModel.isDynamic = true;
+      routeModel.exampleExecution = route.exampleExecution || false;
+      routeModel.parameters = route.parameters || extractParameters(path);
+    }
+    
+    routeModels.push(routeModel);
+  }
+  
+  return routeModels;
+}
+
+/**
+ * Extract parameter names from dynamic route path
+ */
+function extractParameters(path) {
+  const parameters = [];
+  
+  // React/Vue Router :param
+  const reactMatches = path.matchAll(/:(\w+)/g);
+  for (const match of reactMatches) {
+    parameters.push(match[1]);
+  }
+  
+  // Next.js [param]
+  const nextMatches = path.matchAll(/\[(\w+)\]/g);
+  for (const match of nextMatches) {
+    parameters.push(match[1]);
+  }
+  
+  return parameters;
+}
+
+/**
+ * PHASE 12: Correlate navigation promise with route
+ * 
+ * @param {string} navigationTarget - Navigation target from promise
+ * @param {Array<RouteModel>} routeModels - Available route models
+ * @returns {Object|null} Correlation result or null
+ */
+export function correlateNavigationWithRoute(navigationTarget, routeModels) {
+  if (!navigationTarget || typeof navigationTarget !== 'string') {
+    return null;
+  }
+  
+  // Normalize navigation target (handle dynamic targets)
+  const normalized = normalizeNavigationTarget(navigationTarget);
+  const targetToMatch = normalized.exampleTarget || navigationTarget;
+  
+  // Try exact match first
+  let matchedRoute = routeModels.find(r => r.path === targetToMatch);
+  
+  if (matchedRoute) {
+    return {
+      route: matchedRoute,
+      matchType: 'exact',
+      confidence: 1.0,
+      normalizedTarget: targetToMatch,
+      originalTarget: navigationTarget,
+      isDynamic: normalized.isDynamic,
+    };
+  }
+  
+  // Try prefix match for dynamic routes
+  for (const route of routeModels) {
+    if (route.isDynamic && route.originalPattern) {
+      // Check if target matches dynamic pattern
+      const patternMatch = matchDynamicPattern(targetToMatch, route.originalPattern);
+      if (patternMatch) {
+        return {
+          route: route,
+          matchType: 'pattern',
+          confidence: 0.9,
+          normalizedTarget: targetToMatch,
+          originalTarget: navigationTarget,
+          isDynamic: true,
+          patternMatch: patternMatch,
+        };
+      }
+    }
+  }
+  
+  // No match found
+  return null;
+}
+
+/**
+ * Match a target path against a dynamic route pattern
+ */
+function matchDynamicPattern(target, pattern) {
+  // Convert pattern to regex
+  // React Router: /users/:id -> /users/(\w+)
+  // Next.js: /users/[id] -> /users/(\w+)
+  
+  let regexPattern = pattern;
+  
+  // Replace :param with (\w+)
+  regexPattern = regexPattern.replace(/:(\w+)/g, '(\\w+)');
+  
+  // Replace [param] with (\w+)
+  regexPattern = regexPattern.replace(/\[(\w+)\]/g, '(\\w+)');
+  
+  // Escape other special characters
+  regexPattern = regexPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  
+  // Restore the capture groups
+  regexPattern = regexPattern.replace(/\\\(\\\\w\+\\\)/g, '(\\w+)');
+  
+  const regex = new RegExp(`^${regexPattern}$`);
+  const match = target.match(regex);
+  
+  return match ? { matched: true, groups: match.slice(1) } : null;
+}
+
+/**
+ * PHASE 12: Evaluate route navigation outcome
+ * 
+ * @param {Object} correlation - Route correlation result
+ * @param {Object} trace - Interaction trace
+ * @param {string} beforeUrl - URL before interaction
+ * @param {string} afterUrl - URL after interaction
+ * @returns {Object} Evaluation result
+ */
+export function evaluateRouteNavigation(correlation, trace, beforeUrl, afterUrl) {
+  if (!correlation) {
+    return {
+      outcome: 'NO_ROUTE_MATCH',
+      confidence: 0.0,
+      reason: 'Navigation target does not match any known route',
+    };
+  }
+  
+  const { route, normalizedTarget } = correlation;
+  const sensors = trace.sensors || {};
+  const navSensor = sensors.navigation || {};
+  
+  // Check URL change
+  const urlChanged = navSensor.urlChanged === true || 
+                     (beforeUrl && afterUrl && beforeUrl !== afterUrl);
+  
+  // Check if URL matches route
+  const afterPath = extractPathFromUrl(afterUrl);
+  const routeMatched = afterPath === route.path || 
+                       afterPath === normalizedTarget ||
+                       (route.isDynamic && matchDynamicPattern(afterPath, route.originalPattern));
+  
+  // Check router state change (for SPAs)
+  const routerStateChanged = navSensor.routerStateChanged === true ||
+                            navSensor.routeChanged === true ||
+                            (navSensor.routerEvents && navSensor.routerEvents.length > 0);
+  
+  // Check UI change
+  const uiChanged = sensors.uiSignals?.diff?.changed === true;
+  const domChanged = trace.after?.dom !== trace.before?.dom;
+  
+  // PHASE 12: Evidence Law - require before/after + supporting signal
+  const hasEvidence = (beforeUrl && afterUrl) && 
+                      (urlChanged || routerStateChanged || uiChanged || domChanged);
+  
+  if (routeMatched && hasEvidence) {
+    return {
+      outcome: 'VERIFIED',
+      confidence: route.stability === ROUTE_STABILITY.STATIC ? 1.0 : 0.9,
+      reason: null,
+      evidence: {
+        urlChanged,
+        routerStateChanged,
+        uiChanged,
+        domChanged,
+        routeMatched: true,
+      },
+    };
+  }
+  
+  if (!routeMatched && urlChanged) {
+    return {
+      outcome: 'ROUTE_MISMATCH',
+      confidence: 0.8,
+      reason: 'Navigation occurred but target route does not match',
+      evidence: {
+        urlChanged: true,
+        expectedRoute: route.path,
+        actualPath: afterPath,
+      },
+    };
+  }
+  
+  if (!hasEvidence) {
+    return {
+      outcome: 'SILENT_FAILURE',
+      confidence: correlation.confidence,
+      reason: 'Navigation promise not fulfilled - no URL change, router state change, or UI change',
+      evidence: {
+        urlChanged: false,
+        routerStateChanged: false,
+        uiChanged: false,
+        domChanged: false,
+      },
+    };
+  }
+  
+  // Ambiguous case
+  if (route.stability === ROUTE_STABILITY.AMBIGUOUS) {
+    return {
+      outcome: 'SUSPECTED',
+      confidence: 0.6,
+      reason: 'Dynamic route cannot be deterministically validated',
+      evidence: {
+        routeStability: 'ambiguous',
+        urlChanged,
+        routerStateChanged,
+        uiChanged,
+      },
+    };
+  }
+  
+  return {
+    outcome: 'UNKNOWN',
+    confidence: 0.5,
+    reason: 'Route navigation outcome unclear',
+  };
+}
+
+/**
+ * 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;
+  }
+}
+
+/**
+ * PHASE 12: Build evidence for route-related finding
+ * 
+ * @param {Object} correlation - Route correlation
+ * @param {Object} navigationPromise - Navigation promise from expectation
+ * @param {Object} evaluation - Route evaluation result
+ * @param {Object} trace - Interaction trace
+ * @returns {Object} Evidence object
+ */
+export function buildRouteEvidence(correlation, navigationPromise, evaluation, trace) {
+  const evidence = {
+    routeDefinition: {
+      path: correlation?.route?.path || null,
+      type: correlation?.route?.type || null,
+      stability: correlation?.route?.stability || null,
+      source: correlation?.route?.source || null,
+      sourceRef: correlation?.route?.sourceRef || null,
+    },
+    navigationTrigger: {
+      target: navigationPromise?.target || null,
+      method: navigationPromise?.method || null,
+      astSource: navigationPromise?.astSource || null,
+      context: navigationPromise?.context || null,
+    },
+    beforeAfter: {
+      beforeUrl: trace.before?.url || null,
+      afterUrl: trace.after?.url || null,
+      beforeScreenshot: trace.before?.screenshot || null,
+      afterScreenshot: trace.after?.screenshot || null,
+    },
+    signals: {
+      urlChanged: evaluation.evidence?.urlChanged || false,
+      routerStateChanged: evaluation.evidence?.routerStateChanged || false,
+      uiChanged: evaluation.evidence?.uiChanged || false,
+      domChanged: evaluation.evidence?.domChanged || false,
+      routeMatched: evaluation.evidence?.routeMatched || false,
+    },
+    evaluation: {
+      outcome: evaluation.outcome,
+      confidence: evaluation.confidence,
+      reason: evaluation.reason,
+    },
+  };
+  
+  return evidence;
+}
+
+/**
+ * PHASE 12: Check if route change is false positive
+ * 
+ * @param {Object} trace - Interaction trace
+ * @param {Object} correlation - Route correlation
+ * @returns {boolean} True if should be ignored (false positive)
+ */
+export function isRouteChangeFalsePositive(trace, correlation) {
+  const sensors = trace.sensors || {};
+  const navSensor = sensors.navigation || {};
+  
+  // Internal state-only route changes (shallow routing)
+  if (navSensor.shallowRouting === true && !navSensor.urlChanged) {
+    return true;
+  }
+  
+  // Analytics-only navigation
+  const networkSensor = sensors.network || {};
+  const hasAnalyticsRequest = networkSensor.observedRequestUrls?.some(url => 
+    url && typeof url === 'string' && url.includes('/api/analytics')
+  );
+  
+  if (hasAnalyticsRequest && !navSensor.urlChanged && !sensors.uiSignals?.diff?.changed) {
+    return true;
+  }
+  
+  return false;
+}
+