@veraxhq/verax 0.2.1 → 0.4.0

package/src/verax/core/determinism/run-fingerprint.js

@@ -0,0 +1,123 @@
+/**
+ * PHASE 25 — Run Fingerprint
+ * 
+ * Computes stable run fingerprint from deterministic inputs.
+ * Used to verify that repeated runs have identical inputs.
+ */
+
+import { createHash } from 'crypto';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname as _dirname } from 'path';
+import { getVeraxVersion } from '../run-id.js';
+
+/**
+ * Compute run fingerprint from deterministic inputs
+ * 
+ * @param {Object} params - Run parameters
+ * @param {string} params.url - Target URL
+ * @param {string} params.projectDir - Project directory
+ * @param {string} params.manifestPath - Manifest path (optional)
+ * @param {Object} params.policyHash - Policy hash (optional)
+ * @param {string} params.fixtureId - Fixture ID (optional)
+ * @returns {string} Run fingerprint (hex hash)
+ */
+export function computeRunFingerprint(params) {
+  const {
+    url,
+    projectDir,
+    // @ts-expect-error - Private field documented but not in type
+    _manifestPath = null,
+    policyHash = null,
+    fixtureId = null
+  } = params;
+  
+  // Compute source hash (hash of all source files)
+  const srcHash = computeSourceHash(projectDir);
+  
+  // Compute policy hash if not provided
+  const computedPolicyHash = policyHash || computePolicyHash(projectDir);
+  
+  // Get VERAX version
+  const veraxVersion = getVeraxVersion();
+  
+  // Build fingerprint input
+  const fingerprintInput = {
+    url: normalizeUrl(url),
+    srcHash,
+    policyHash: computedPolicyHash,
+    veraxVersion,
+    fixtureId: fixtureId || null
+  };
+  
+  // Generate stable hash
+  const configString = JSON.stringify(fingerprintInput, Object.keys(fingerprintInput).sort());
+  const hash = createHash('sha256').update(configString).digest('hex');
+  
+  // @ts-expect-error - digest returns string
+  return hash.substring(0, 32); // 32 chars for readability
+}
+
+/**
+ * Compute source hash (hash of all source files in project)
+ */
+function computeSourceHash(projectDir) {
+  try {
+    // For now, use a simple approach: hash package.json + src directory structure
+    // In production, this should hash all source files
+    const packagePath = resolve(projectDir, 'package.json');
+    if (existsSync(packagePath)) {
+      const pkgContent = readFileSync(packagePath, 'utf-8');
+      // @ts-expect-error - digest returns string
+      return createHash('sha256').update(pkgContent).digest('hex').substring(0, 16);
+    }
+    return 'no-source';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Compute policy hash (hash of guardrails/confidence policies)
+ */
+function computePolicyHash(projectDir) {
+  try {
+    // Hash default policies (in production, should hash all policy files)
+    const policyPaths = [
+      resolve(projectDir, '.verax', 'guardrails.policy.json'),
+      resolve(projectDir, '.verax', 'confidence.policy.json')
+    ];
+    
+    const hashes = [];
+    for (const path of policyPaths) {
+      if (existsSync(path)) {
+        const content = readFileSync(path, 'utf-8');
+        // @ts-expect-error - digest returns string
+        hashes.push(createHash('sha256').update(content).digest('hex').substring(0, 8));
+      }
+    }
+    
+    if (hashes.length > 0) {
+      // @ts-expect-error - digest returns string
+      return createHash('sha256').update(hashes.join('|')).digest('hex').substring(0, 16);
+    }
+    
+    return 'default-policy';
+  } catch {
+    return 'unknown-policy';
+  }
+}
+
+/**
+ * Normalize URL for fingerprint
+ */
+function normalizeUrl(url) {
+  if (!url || typeof url !== 'string') return '';
+  try {
+    const urlObj = new URL(url);
+    // Normalize: remove trailing slash, lowercase host
+    return `${urlObj.protocol}//${urlObj.host.toLowerCase()}${urlObj.pathname.replace(/\/$/, '') || '/'}`;
+  } catch {
+    return url;
+  }
+}
+

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

@@ -0,0 +1,529 @@
+/**
+ * PHASE 14 — Dynamic Routes: Truth, Intent & Safe Support
+ * 
+ * Dynamic route intelligence layer that:
+ * - Classifies dynamic routes by verifiability
+ * - Correlates navigation promises with route definitions and UI outcomes
+ * - Produces evidence-backed findings or explicit ambiguity
+ * - Prevents false positives and false promises
+ */
+
+import { isDynamicPath, normalizeDynamicRoute, normalizeNavigationTarget } from '../shared/dynamic-route-utils.js';
+import { correlateNavigationWithRoute, evaluateRouteNavigation } from './route-intelligence.js';
+import { scoreUIFeedback, detectUIFeedbackSignals } from './ui-feedback-intelligence.js';
+
+/**
+ * PHASE 14: Dynamic Route Verifiability Classification
+ */
+export const DYNAMIC_ROUTE_VERIFIABILITY = {
+  STATIC: 'STATIC',
+  VERIFIED_DYNAMIC: 'VERIFIED_DYNAMIC',
+  AMBIGUOUS_DYNAMIC: 'AMBIGUOUS_DYNAMIC',
+  UNVERIFIABLE_DYNAMIC: 'UNVERIFIABLE_DYNAMIC',
+};
+
+/**
+ * PHASE 14: Route Verdict
+ */
+export const ROUTE_VERDICT = {
+  VERIFIED: 'VERIFIED',
+  SILENT_FAILURE: 'SILENT_FAILURE',
+  ROUTE_MISMATCH: 'ROUTE_MISMATCH',
+  AMBIGUOUS: 'AMBIGUOUS',
+};
+
+/**
+ * PHASE 14: Classify dynamic route by verifiability
+ * 
+ * @param {Object} routeModel - Route model from route intelligence
+ * @param {Object} trace - Interaction trace (optional, for runtime analysis)
+ * @returns {Object} Classification result
+ */
+export function classifyDynamicRoute(routeModel, trace = null) {
+  const path = routeModel.path || '';
+  const originalPattern = routeModel.originalPattern || path;
+  
+  // STATIC: No dynamic parameters
+  if (!isDynamicPath(path) && !isDynamicPath(originalPattern)) {
+    return {
+      verifiability: DYNAMIC_ROUTE_VERIFIABILITY.STATIC,
+      reason: 'Route contains no dynamic parameters',
+      confidence: 1.0,
+    };
+  }
+  
+  // Check if route can be normalized
+  const normalized = normalizeDynamicRoute(originalPattern);
+  if (!normalized || !normalized.examplePath) {
+    return {
+      verifiability: DYNAMIC_ROUTE_VERIFIABILITY.UNVERIFIABLE_DYNAMIC,
+      reason: 'Dynamic route pattern cannot be normalized to example path',
+      confidence: 0.9,
+    };
+  }
+  
+  // Check route characteristics that affect verifiability
+  const isAuthGated = isAuthGatedRoute(routeModel, trace);
+  const isSSROnly = isSSROnlyRoute(routeModel, trace);
+  const isRuntimeOnly = isRuntimeOnlyRoute(routeModel, trace);
+  // @ts-expect-error - Function hoisting
+  const hasObservableSignals = hasObservableSignals(routeModel, trace);
+  
+  // UNVERIFIABLE: Auth-gated, SSR-only, or runtime-only without observable signals
+  if (isAuthGated || isSSROnly || (isRuntimeOnly && !hasObservableSignals)) {
+    return {
+      verifiability: DYNAMIC_ROUTE_VERIFIABILITY.UNVERIFIABLE_DYNAMIC,
+      reason: buildUnverifiableReason(isAuthGated, isSSROnly, isRuntimeOnly, hasObservableSignals),
+      confidence: 0.9,
+    };
+  }
+  
+  // Check if we can verify the outcome
+  if (trace) {
+    const canVerify = canVerifyRouteOutcome(routeModel, trace);
+    
+    if (canVerify.verifiable) {
+      return {
+        verifiability: DYNAMIC_ROUTE_VERIFIABILITY.VERIFIED_DYNAMIC,
+        reason: canVerify.reason,
+        confidence: canVerify.confidence,
+      };
+    } else {
+      return {
+        verifiability: DYNAMIC_ROUTE_VERIFIABILITY.AMBIGUOUS_DYNAMIC,
+        reason: canVerify.reason || 'Route pattern known but outcome unclear',
+        confidence: 0.6,
+      };
+    }
+  }
+  
+  // Default: AMBIGUOUS if pattern is known but we can't verify yet
+  return {
+    verifiability: DYNAMIC_ROUTE_VERIFIABILITY.AMBIGUOUS_DYNAMIC,
+    reason: 'Route pattern known but outcome cannot be verified without trace data',
+    confidence: 0.6,
+  };
+}
+
+/**
+ * Check if route is auth-gated
+ */
+function isAuthGatedRoute(routeModel, _trace) {
+  // Check route path patterns
+  const path = routeModel.path || '';
+  const authPatterns = ['/admin', '/dashboard', '/account', '/settings', '/profile', '/user'];
+  
+  if (authPatterns.some(pattern => path.includes(pattern))) {
+    return true;
+  }
+  
+  // Check trace for auth-related signals
+  if (_trace) {
+    const sensors = _trace.sensors || {};
+    const navSensor = sensors.navigation || {};
+    
+    // If navigation was blocked or redirected to login
+    if (navSensor.blockedNavigations?.length > 0) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Check if route is SSR-only
+ */
+function isSSROnlyRoute(routeModel, _trace) {
+  // Next.js app router with dynamic segments might be SSR-only
+  if (routeModel.framework === 'next-app' && routeModel.isDynamic) {
+    // Check if route has getServerSideProps or similar indicators
+    // For now, we'll be conservative and not mark as SSR-only without evidence
+    return false;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if route is runtime-only (no static analysis possible)
+ */
+function isRuntimeOnlyRoute(routeModel, _trace) {
+  // Routes with complex template literals or runtime variables
+  const originalPattern = routeModel.originalPattern || '';
+  
+  // Pure variable references like ${path} or ${id} without pattern
+  if (originalPattern.includes('${') && !originalPattern.match(/\/[^$]+\$\{[^}]+\}/)) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if route has observable signals
+ */
+function _hasObservableSignals(routeModel, trace) {
+  if (!trace) return false;
+  
+  const sensors = trace.sensors || {};
+  const navSensor = sensors.navigation || {};
+  const uiSignals = sensors.uiSignals || {};
+  const uiFeedback = sensors.uiFeedback || {};
+  
+  // Check for URL change
+  if (navSensor.urlChanged === true) {
+    return true;
+  }
+  
+  // Check for UI feedback
+  if (uiSignals.diff?.changed === true || uiFeedback.overallUiFeedbackScore > 0.3) {
+    return true;
+  }
+  
+  // Check for DOM change
+  if (trace.dom?.beforeHash !== trace.dom?.afterHash) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if route outcome can be verified
+ */
+function canVerifyRouteOutcome(routeModel, trace) {
+  const sensors = trace.sensors || {};
+  const navSensor = sensors.navigation || {};
+  const beforeUrl = trace.before?.url || navSensor.beforeUrl || '';
+  const afterUrl = trace.after?.url || navSensor.afterUrl || '';
+  
+  // Check URL change
+  const urlChanged = navSensor.urlChanged === true || (beforeUrl && afterUrl && beforeUrl !== afterUrl);
+  
+  // Check if URL matches route pattern
+  const afterPath = extractPathFromUrl(afterUrl);
+  const routeMatched = matchDynamicPattern(afterPath, routeModel.originalPattern || routeModel.path);
+  
+  // Check UI feedback
+  const uiSignals = detectUIFeedbackSignals(trace);
+  const hasUIFeedback = uiSignals.length > 0;
+  
+  // Check DOM change
+  const domChanged = trace.dom?.beforeHash !== trace.dom?.afterHash;
+  
+  if (urlChanged && routeMatched && (hasUIFeedback || domChanged)) {
+    return {
+      verifiable: true,
+      reason: 'URL changed, route pattern matched, and UI feedback or DOM change observed',
+      confidence: 0.9,
+    };
+  }
+  
+  if (urlChanged && routeMatched) {
+    return {
+      verifiable: true,
+      reason: 'URL changed and route pattern matched',
+      confidence: 0.8,
+    };
+  }
+  
+  if (urlChanged && !routeMatched) {
+    return {
+      verifiable: false,
+      reason: 'URL changed but does not match route pattern',
+      confidence: 0.7,
+    };
+  }
+  
+  return {
+    verifiable: false,
+    reason: 'No URL change or observable signals',
+    confidence: 0.5,
+  };
+}
+
+/**
+ * Build reason for unverifiable route
+ */
+function buildUnverifiableReason(isAuthGated, isSSROnly, isRuntimeOnly, hasObservableSignals) {
+  const reasons = [];
+  
+  if (isAuthGated) {
+    reasons.push('auth-gated');
+  }
+  if (isSSROnly) {
+    reasons.push('SSR-only');
+  }
+  if (isRuntimeOnly) {
+    reasons.push('runtime-only');
+  }
+  if (!hasObservableSignals) {
+    reasons.push('no observable signals');
+  }
+  
+  return `Route is ${reasons.join(', ')}`;
+}
+
+/**
+ * Match dynamic pattern against actual path
+ */
+function matchDynamicPattern(actualPath, pattern) {
+  if (!actualPath || !pattern) return false;
+  
+  // Convert pattern to regex
+  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}$`);
+  return regex.test(actualPath);
+}
+
+/**
+ * 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 14: Correlate navigation promise with dynamic route and UI feedback
+ * 
+ * @param {Object} expectation - Navigation expectation
+ * @param {Object} routeModel - Route model
+ * @param {Object} trace - Interaction trace
+ * @returns {Object} Correlation result with verdict
+ */
+export function correlateDynamicRouteNavigation(expectation, routeModel, trace) {
+  const classification = classifyDynamicRoute(routeModel, trace);
+  
+  // If route is UNVERIFIABLE, return skip
+  if (classification.verifiability === DYNAMIC_ROUTE_VERIFIABILITY.UNVERIFIABLE_DYNAMIC) {
+    return {
+      verdict: null,
+      skip: true,
+      skipReason: classification.reason,
+      confidence: classification.confidence,
+    };
+  }
+  
+  // Normalize navigation target
+  const navigationTarget = expectation.targetPath || expectation.expectedTarget || '';
+  const normalized = normalizeNavigationTarget(navigationTarget);
+  const targetToMatch = normalized.exampleTarget || navigationTarget;
+  
+  // Match route pattern
+  const routeMatched = matchDynamicPattern(targetToMatch, routeModel.originalPattern || routeModel.path);
+  
+  // Get route evaluation from route intelligence
+  const correlation = correlateNavigationWithRoute(navigationTarget, [routeModel]);
+  const _routeEvaluation = correlation ? evaluateRouteNavigation(correlation, trace, trace.before?.url || '', trace.after?.url || '') : null;
+  
+  // Get UI feedback score
+  const uiSignals = detectUIFeedbackSignals(trace);
+  const feedbackScore = scoreUIFeedback(uiSignals, expectation, trace);
+  
+  // Determine verdict
+  const sensors = trace.sensors || {};
+  const navSensor = sensors.navigation || {};
+  const urlChanged = navSensor.urlChanged === true;
+  const afterPath = extractPathFromUrl(trace.after?.url || navSensor.afterUrl || '');
+  
+  // VERIFIED: URL changed, route matched, and UI feedback present
+  if (urlChanged && routeMatched && feedbackScore.score === 'FEEDBACK_CONFIRMED') {
+    return {
+      verdict: ROUTE_VERDICT.VERIFIED,
+      skip: false,
+      confidence: 0.9,
+      reason: 'Navigation successful: URL changed, route matched, and UI feedback confirmed',
+      evidence: {
+        urlChanged: true,
+        routeMatched: true,
+        uiFeedback: feedbackScore.score,
+        afterPath,
+      },
+    };
+  }
+  
+  // VERIFIED: URL changed and route matched (even without explicit UI feedback)
+  if (urlChanged && routeMatched) {
+    return {
+      verdict: ROUTE_VERDICT.VERIFIED,
+      skip: false,
+      confidence: 0.85,
+      reason: 'Navigation successful: URL changed and route matched',
+      evidence: {
+        urlChanged: true,
+        routeMatched: true,
+        afterPath,
+      },
+    };
+  }
+  
+  // ROUTE_MISMATCH: URL changed but doesn't match route
+  if (urlChanged && !routeMatched) {
+    return {
+      verdict: ROUTE_VERDICT.ROUTE_MISMATCH,
+      skip: false,
+      confidence: 0.8,
+      reason: `Navigation occurred but target route does not match. Expected pattern: ${routeModel.originalPattern}, Actual: ${afterPath}`,
+      evidence: {
+        urlChanged: true,
+        routeMatched: false,
+        expectedPattern: routeModel.originalPattern,
+        actualPath: afterPath,
+      },
+    };
+  }
+  
+  // SILENT_FAILURE: No URL change, no route match, no UI feedback
+  if (!urlChanged && !routeMatched && feedbackScore.score === 'FEEDBACK_MISSING') {
+    return {
+      verdict: ROUTE_VERDICT.SILENT_FAILURE,
+      skip: false,
+      confidence: 0.85,
+      reason: 'Navigation promise not fulfilled: no URL change, route mismatch, and no UI feedback',
+      evidence: {
+        urlChanged: false,
+        routeMatched: false,
+        uiFeedback: feedbackScore.score,
+      },
+    };
+  }
+  
+  // AMBIGUOUS: Unclear outcome
+  if (classification.verifiability === DYNAMIC_ROUTE_VERIFIABILITY.AMBIGUOUS_DYNAMIC) {
+    return {
+      verdict: ROUTE_VERDICT.AMBIGUOUS,
+      skip: false,
+      confidence: 0.6,
+      reason: classification.reason || 'Dynamic route outcome is ambiguous',
+      evidence: {
+        classification: classification.verifiability,
+        urlChanged,
+        routeMatched,
+        uiFeedback: feedbackScore.score,
+      },
+    };
+  }
+  
+  // Default: AMBIGUOUS
+  return {
+    verdict: ROUTE_VERDICT.AMBIGUOUS,
+    skip: false,
+    confidence: 0.5,
+    reason: 'Route navigation outcome unclear',
+    evidence: {
+      urlChanged,
+      routeMatched,
+      uiFeedback: feedbackScore.score,
+    },
+  };
+}
+
+/**
+ * PHASE 14: Build evidence for dynamic route finding
+ * 
+ * @param {Object} expectation - Navigation expectation
+ * @param {Object} routeModel - Route model
+ * @param {Object} correlation - Correlation result
+ * @param {Object} trace - Interaction trace
+ * @returns {Object} Evidence object
+ */
+export function buildDynamicRouteEvidence(expectation, routeModel, correlation, trace) {
+  const classification = classifyDynamicRoute(routeModel, trace);
+  const uiSignals = detectUIFeedbackSignals(trace);
+  const feedbackScore = scoreUIFeedback(uiSignals, expectation, trace);
+  
+  const evidence = {
+    routeDefinition: {
+      path: routeModel.path,
+      originalPattern: routeModel.originalPattern || routeModel.path,
+      type: routeModel.type,
+      stability: routeModel.stability,
+      source: routeModel.source,
+      sourceRef: routeModel.sourceRef,
+      verifiability: classification.verifiability,
+      verifiabilityReason: classification.reason,
+    },
+    navigationTrigger: {
+      target: expectation.targetPath || expectation.expectedTarget || null,
+      method: expectation.promise?.method || null,
+      astSource: expectation.source?.astSource || null,
+      context: expectation.source?.context || null,
+    },
+    beforeAfter: {
+      beforeUrl: trace.before?.url || trace.sensors?.navigation?.beforeUrl || null,
+      afterUrl: trace.after?.url || trace.sensors?.navigation?.afterUrl || null,
+      beforeScreenshot: trace.before?.screenshot || null,
+      afterScreenshot: trace.after?.screenshot || null,
+      beforeDomHash: trace.dom?.beforeHash || null,
+      afterDomHash: trace.dom?.afterHash || null,
+    },
+    signals: {
+      urlChanged: correlation.evidence?.urlChanged || false,
+      routeMatched: correlation.evidence?.routeMatched || false,
+      uiFeedback: feedbackScore.score,
+      uiFeedbackSignals: uiSignals.map(s => ({
+        type: s.type,
+        confidence: s.confidence,
+      })),
+      domChanged: trace.dom?.beforeHash !== trace.dom?.afterHash,
+    },
+    correlation: {
+      verdict: correlation.verdict,
+      confidence: correlation.confidence,
+      reason: correlation.reason,
+      skip: correlation.skip || false,
+      skipReason: correlation.skipReason || null,
+    },
+  };
+  
+  return evidence;
+}
+
+/**
+ * PHASE 14: Check if route should be skipped (unverifiable)
+ * 
+ * @param {Object} routeModel - Route model
+ * @param {Object} trace - Interaction trace
+ * @returns {Object} Skip decision
+ */
+export function shouldSkipDynamicRoute(routeModel, trace) {
+  const classification = classifyDynamicRoute(routeModel, trace);
+  
+  if (classification.verifiability === DYNAMIC_ROUTE_VERIFIABILITY.UNVERIFIABLE_DYNAMIC) {
+    return {
+      skip: true,
+      reason: classification.reason,
+      confidence: classification.confidence,
+    };
+  }
+  
+  return {
+    skip: false,
+    reason: null,
+    confidence: 0,
+  };
+}
+