@veraxhq/verax 0.1.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@veraxhq/verax",
+  "version": "0.1.0",
+  "description": "VERAX - Silent failure detection for websites",
+  "type": "module",
+  "main": "./src/verax/index.js",
+  "bin": {
+    "verax": "bin/verax.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/verax/index.js"
+    },
+    "./learn": {
+      "import": "./src/verax/learn/index.js"
+    },
+    "./observe": {
+      "import": "./src/verax/observe/index.js"
+    },
+    "./detect": {
+      "import": "./src/verax/detect/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/learn.test.js test/observe.test.js test/detect.test.js test/static-learn.test.js test/static-detect.test.js test/observe-boundary.test.js test/static-buttons-detect.test.js test/spa-support.test.js test/scan-summary.test.js test/route-validation.test.js test/skip-reasons.test.js test/observe-stabilization.test.js test/observe-coverage.test.js test/ast-extraction.test.js test/spa-ast-integration.test.js test/wave2-human-driver.test.js test/wave4-confidence.test.js test/wave5-action-contracts.test.js test/wave6-action-contracts.test.js test/wave7-auth-flows.test.js test/wave8-state-contracts.test.js test/wave9-hardening.test.js test/wave10-ci-summary.test.js test/cli-scan.test.js test/final-gate.test.js"
+  },
+  "dependencies": {
+    "@babel/generator": "^7.28.5",
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "@babel/types": "^7.28.5",
+    "glob": "^10.3.10",
+    "inquirer": "^9.2.15",
+    "node-html-parser": "^7.0.1",
+    "playwright": "^1.40.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "testing",
+    "qa",
+    "website",
+    "silent-failures",
+    "verification"
+  ],
+  "license": "MIT"
+}

package/src/verax/detect/comparison.js

@@ -0,0 +1,69 @@
+import { resolve } from 'path';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { getUrlPath, getScreenshotHash } from './evidence-validator.js';
+
+export function hasMeaningfulUrlChange(beforeUrl, afterUrl) {
+  const beforePath = getUrlPath(beforeUrl);
+  const afterPath = getUrlPath(afterUrl);
+  
+  if (!beforePath || !afterPath) return false;
+  
+  if (beforePath === afterPath) return false;
+  
+  const beforeNormalized = beforePath.replace(/\/$/, '') || '/';
+  const afterNormalized = afterPath.replace(/\/$/, '') || '/';
+  
+  return beforeNormalized !== afterNormalized;
+}
+
+export function hasVisibleChange(beforeScreenshot, afterScreenshot, projectDir) {
+  // Screenshots are stored as relative paths like "screenshots/before-..."
+  // Try new structure first (.verax/runs/<runId>/evidence/), then legacy
+  let beforePath, afterPath;
+  const newEvidencePath = resolve(projectDir, '.verax', 'runs');
+  const legacyObservePath = resolve(projectDir, '.veraxverax', 'observe');
+  
+  // Check if new structure exists and find latest run
+  if (existsSync(newEvidencePath)) {
+    try {
+      const runs = readdirSync(newEvidencePath)
+        .map(name => ({ name, time: statSync(resolve(newEvidencePath, name)).mtimeMs }))
+        .sort((a, b) => b.time - a.time);
+      if (runs.length > 0) {
+        const runEvidencePath = resolve(newEvidencePath, runs[0].name, 'evidence', beforeScreenshot);
+        if (existsSync(runEvidencePath)) {
+          beforePath = resolve(newEvidencePath, runs[0].name, 'evidence', beforeScreenshot);
+          afterPath = resolve(newEvidencePath, runs[0].name, 'evidence', afterScreenshot);
+        } else {
+          beforePath = resolve(legacyObservePath, beforeScreenshot);
+          afterPath = resolve(legacyObservePath, afterScreenshot);
+        }
+      } else {
+        beforePath = resolve(legacyObservePath, beforeScreenshot);
+        afterPath = resolve(legacyObservePath, afterScreenshot);
+      }
+    } catch {
+      beforePath = resolve(legacyObservePath, beforeScreenshot);
+      afterPath = resolve(legacyObservePath, afterScreenshot);
+    }
+  } else {
+    beforePath = resolve(legacyObservePath, beforeScreenshot);
+    afterPath = resolve(legacyObservePath, afterScreenshot);
+  }
+  
+  const beforeHash = getScreenshotHash(beforePath);
+  const afterHash = getScreenshotHash(afterPath);
+  
+  if (!beforeHash || !afterHash) return false;
+  
+  return beforeHash !== afterHash;
+}
+
+export function hasDomChange(trace) {
+  if (!trace.dom || !trace.dom.beforeHash || !trace.dom.afterHash) {
+    return false;
+  }
+  
+  return trace.dom.beforeHash !== trace.dom.afterHash;
+}
+

package/src/verax/detect/confidence-engine.js

@@ -0,0 +1,498 @@
+/**
+ * WAVE 4: CONFIDENCE ENGINE
+ * 
+ * Evidence-based scoring for findings (0-100). No heuristics, no AI.
+ * Confidence computed strictly from:
+ * - Expectation proof strength (PROVEN_EXPECTATION required)
+ * - Runtime sensor evidence (network/console/ui-signals)
+ * - Deterministic observation signals (url/dom/screenshot changes)
+ */
+
+const BASE_SCORES = {
+  network_silent_failure: 70,
+  validation_silent_failure: 60,
+  missing_feedback_failure: 55,
+   no_effect_silent_failure: 50,
+   missing_network_action: 65,
+   missing_state_action: 60
+};
+
+const CONFIDENCE_LEVELS = {
+  HIGH: 80,
+  MEDIUM: 60
+};
+
+const LONG_ACTION_MS = 2000; // Threshold for slow requests
+
+/**
+ * Compute confidence score for a finding.
+ * 
+ * @param {Object} params
+ * @param {string} params.findingType - Type of finding
+ * @param {Object} params.expectation - Expectation with proof status
+ * @param {Object} params.sensors - Sensor data (network, console, uiSignals)
+ * @param {Object} params.comparisons - Comparison results (hasUrlChange, hasDomChange, hasVisibleChange)
+ * @param {Object} params.attemptMeta - Metadata about the interaction attempt
+ * @returns {Object} { score, level, reasons, breakdown }
+ */
+export function computeConfidence({ findingType, expectation, sensors = {}, comparisons = {}, attemptMeta = {} }) {
+  const baseScore = BASE_SCORES[findingType] || 50;
+  const points = { plus: {}, minus: {} };
+  const reasons = [];
+  
+  const networkSummary = sensors.network || {};
+  const consoleSummary = sensors.console || {};
+  const uiSignals = sensors.uiSignals || {};
+  
+  // Extract signals
+  const hasErrorFeedback = detectErrorFeedback(uiSignals);
+  const hasLoadingFeedback = detectLoadingFeedback(uiSignals);
+  const hasAnyFeedback = hasErrorFeedback || hasLoadingFeedback || detectStatusFeedback(uiSignals);
+  
+  let totalPlus = 0;
+  let totalMinus = 0;
+  
+  // Type-specific scoring
+  switch (findingType) {
+    case 'network_silent_failure':
+      totalPlus += scoreNetworkSilentFailure({
+        networkSummary,
+        consoleSummary,
+        hasErrorFeedback,
+        hasAnyFeedback,
+        points,
+        reasons
+      });
+      totalMinus += penalizeNetworkSilentFailure({
+        hasAnyFeedback,
+        points,
+        reasons
+      });
+      break;
+      
+    case 'validation_silent_failure':
+      totalPlus += scoreValidationSilentFailure({
+        networkSummary,
+        consoleSummary,
+        hasErrorFeedback,
+        attemptMeta,
+        points,
+        reasons
+      });
+      totalMinus += penalizeValidationSilentFailure({
+        hasErrorFeedback,
+        points,
+        reasons
+      });
+      break;
+      
+    case 'missing_feedback_failure':
+      totalPlus += scoreMissingFeedbackFailure({
+        networkSummary,
+        hasLoadingFeedback,
+        points,
+        reasons
+      });
+      totalMinus += penalizeMissingFeedbackFailure({
+        hasLoadingFeedback,
+        points,
+        reasons
+      });
+      break;
+      
+    case 'no_effect_silent_failure':
+      totalPlus += scoreNoEffectSilentFailure({
+        expectation,
+        comparisons,
+        networkSummary,
+        hasAnyFeedback,
+        points,
+        reasons
+      });
+      totalMinus += penalizeNoEffectSilentFailure({
+        networkSummary,
+        hasAnyFeedback,
+        points,
+        reasons
+      });
+      break;
+   
+     case 'missing_network_action':
+       totalPlus += scoreMissingNetworkAction({
+         expectation,
+         attemptMeta,
+         consoleSummary,
+         networkSummary,
+         points,
+         reasons
+       });
+       totalMinus += penalizeMissingNetworkAction({
+         networkSummary,
+         points,
+         reasons
+       });
+       break;
+
+    case 'missing_state_action':
+      totalPlus += scoreMissingStateAction({
+        expectation,
+        attemptMeta,
+        sensors,
+        comparisons,
+        points,
+        reasons
+      });
+      totalMinus += penalizeMissingStateAction({
+        sensors,
+        networkSummary,
+        points,
+        reasons
+      });
+      break;
+  }
+  
+  // Compute final score
+  let score = baseScore + totalPlus - totalMinus;
+  score = Math.max(0, Math.min(100, score)); // Cap to [0, 100]
+  
+  // Determine level
+  let level = 'LOW';
+  if (score >= CONFIDENCE_LEVELS.HIGH) {
+    level = 'HIGH';
+  } else if (score >= CONFIDENCE_LEVELS.MEDIUM) {
+    level = 'MEDIUM';
+  }
+  
+  // Limit reasons to 6 most important
+  const limitedReasons = reasons.slice(0, 6);
+  
+  return {
+    score: Math.round(score),
+    level,
+    reasons: limitedReasons,
+    breakdown: {
+      base: baseScore,
+      plus: points.plus,
+      minus: points.minus
+    }
+  };
+}
+
+// === NETWORK SILENT FAILURE SCORING ===
+
+function scoreNetworkSilentFailure({ networkSummary, consoleSummary, hasErrorFeedback, hasAnyFeedback, points, reasons }) {
+  let total = 0;
+  
+  // +15 if server error (5xx)
+  if (networkSummary.failedRequests >= 1) {
+    const has5xxError = Object.keys(networkSummary.failedByStatus || {}).some(status => parseInt(status) >= 500);
+    if (has5xxError) {
+      points.plus.serverError = 15;
+      total += 15;
+      reasons.push('Server error (5xx) detected');
+    } else {
+      // Client error (4xx)
+      points.plus.networkFailure = 10;
+      total += 10;
+      reasons.push('Network request failed');
+    }
+  }
+  
+  // +10 if request explicitly failed (requestfailed event)
+  if (networkSummary.failedRequests > 0) {
+    const hasExplicitFailure = networkSummary.topFailedUrls?.length > 0;
+    if (hasExplicitFailure) {
+      points.plus.explicitFailure = 10;
+      total += 10;
+      reasons.push('Request failure event captured');
+    }
+  }
+  
+  // +10 if console shows page error or unhandled rejection
+  if ((consoleSummary.pageErrorCount || 0) > 0 || (consoleSummary.unhandledRejectionCount || 0) > 0) {
+    points.plus.jsError = 10;
+    total += 10;
+    reasons.push('JavaScript error or unhandled rejection logged');
+  }
+  
+  // +10 if NO user feedback at all
+  if (!hasAnyFeedback) {
+    points.plus.noFeedback = 10;
+    total += 10;
+    reasons.push('No user-visible error feedback');
+  }
+  
+  return total;
+}
+
+function penalizeNetworkSilentFailure({ hasAnyFeedback, points, reasons }) {
+  let total = 0;
+  
+  // -20 if any feedback exists (shouldn't be classified as silent failure)
+  if (hasAnyFeedback) {
+    points.minus.hasFeedback = 20;
+    total += 20;
+    reasons.push('User feedback detected (reduces confidence)');
+  }
+  
+  return total;
+}
+
+// === VALIDATION SILENT FAILURE SCORING ===
+
+function scoreValidationSilentFailure({ networkSummary, consoleSummary, hasErrorFeedback, attemptMeta, points, reasons }) {
+  let total = 0;
+  
+  // +15 if invalid fields detected
+  const invalidFieldsCount = attemptMeta.invalidFieldsCount || 0;
+  if (invalidFieldsCount >= 1) {
+    points.plus.invalidFields = 15;
+    total += 15;
+    reasons.push(`${invalidFieldsCount} invalid form field(s) detected`);
+  }
+  
+  // +10 if console errors logged
+  if ((consoleSummary.consoleErrorCount || 0) >= 1) {
+    points.plus.consoleError = 10;
+    total += 10;
+    reasons.push('Validation errors logged to console');
+  }
+  
+  // +10 if no validation feedback visible
+  if (!hasErrorFeedback) {
+    points.plus.noValidationFeedback = 10;
+    total += 10;
+    reasons.push('No visible validation error message');
+  }
+  
+  return total;
+}
+
+function penalizeValidationSilentFailure({ hasErrorFeedback, points, reasons }) {
+  let total = 0;
+  
+  // -15 if error feedback exists
+  if (hasErrorFeedback) {
+    points.minus.hasErrorFeedback = 15;
+    total += 15;
+    reasons.push('Error feedback visible (reduces confidence)');
+  }
+  
+  return total;
+}
+
+// === MISSING FEEDBACK FAILURE SCORING ===
+
+function scoreMissingFeedbackFailure({ networkSummary, hasLoadingFeedback, points, reasons }) {
+  let total = 0;
+  
+  // +15 if slow requests detected
+  if ((networkSummary.slowRequestsCount || 0) >= 1) {
+    const slowestDuration = networkSummary.slowRequests?.[0]?.duration || 0;
+    points.plus.slowRequest = 15;
+    total += 15;
+    reasons.push(`Slow request detected (${slowestDuration}ms)`);
+  }
+  
+  // +10 if significant network activity
+  if ((networkSummary.totalRequests || 0) >= 1 && (networkSummary.durationMs || 0) >= LONG_ACTION_MS) {
+    points.plus.longAction = 10;
+    total += 10;
+    reasons.push('Long-running network activity');
+  }
+  
+  // +10 if no loading feedback
+  if (!hasLoadingFeedback) {
+    points.plus.noLoadingFeedback = 10;
+    total += 10;
+    reasons.push('No loading indicator shown');
+  }
+  
+  return total;
+}
+
+function penalizeMissingFeedbackFailure({ hasLoadingFeedback, points, reasons }) {
+  let total = 0;
+  
+  // -10 if loading indicator detected
+  if (hasLoadingFeedback) {
+    points.minus.hasLoadingFeedback = 10;
+    total += 10;
+    reasons.push('Loading indicator detected (reduces confidence)');
+  }
+  
+  return total;
+}
+
+// === NO EFFECT SILENT FAILURE SCORING ===
+
+function scoreNoEffectSilentFailure({ expectation, comparisons, networkSummary, hasAnyFeedback, points, reasons }) {
+  let total = 0;
+  
+  // +15 if expected navigation but no URL change
+  const expectsNavigation = expectation?.expectationType === 'navigation' || 
+                           expectation?.expectationType === 'spa_navigation' ||
+                           expectation?.expectationType === 'form_submission';
+  if (expectsNavigation && !comparisons.hasUrlChange) {
+    points.plus.expectedNavNoUrl = 15;
+    total += 15;
+    reasons.push('Expected navigation did not occur');
+  }
+  
+  // +10 if no DOM change at all
+  if (!comparisons.hasDomChange) {
+    points.plus.noDomChange = 10;
+    total += 10;
+    reasons.push('No DOM changes detected');
+  }
+  
+  // +10 if screenshot unchanged (if available)
+  if (comparisons.hasVisibleChange === false) {
+    points.plus.noVisibleChange = 10;
+    total += 10;
+    reasons.push('No visible changes in screenshot');
+  }
+  
+  return total;
+}
+
+function penalizeNoEffectSilentFailure({ networkSummary, hasAnyFeedback, points, reasons }) {
+  let total = 0;
+  
+  // -10 if network activity occurred (might be effect without visible change)
+  if ((networkSummary.totalRequests || 0) > 0) {
+    points.minus.hasNetworkActivity = 10;
+    total += 10;
+    reasons.push('Network activity detected (potential hidden effect)');
+  }
+  
+  // -10 if UI signal changed
+  if (hasAnyFeedback) {
+    points.minus.uiSignalChanged = 10;
+    total += 10;
+    reasons.push('UI signal changed (potential effect)');
+  }
+  
+  return total;
+}
+
+// === HELPER FUNCTIONS ===
+
+function detectErrorFeedback(uiSignals) {
+  const before = uiSignals.before || {};
+  const after = uiSignals.after || {};
+  const changes = uiSignals.changes || {};
+  
+  // Check if error signal appeared after interaction
+  return (after.hasErrorSignal && !before.hasErrorSignal) || 
+         (changes.changed && after.hasErrorSignal);
+}
+
+function detectLoadingFeedback(uiSignals) {
+  const before = uiSignals.before || {};
+  const after = uiSignals.after || {};
+  
+  // Check if loading indicator appeared or changed
+  return after.hasLoadingIndicator || 
+         (before.hasLoadingIndicator !== after.hasLoadingIndicator);
+}
+
+function detectStatusFeedback(uiSignals) {
+  const after = uiSignals.after || {};
+  
+  // Check for any status/live region updates
+  return after.hasStatusSignal || after.hasLiveRegion || after.hasDialog;
+}
+
+  // === MISSING NETWORK ACTION SCORING ===
+
+  function scoreMissingNetworkAction({ expectation, attemptMeta, consoleSummary, networkSummary, points, reasons }) {
+    let total = 0;
+  
+    // +15 if PROVEN expectation with source attribution (high certainty of broken promise)
+    if (expectation?.proof === 'PROVEN_EXPECTATION' && attemptMeta.sourceRef) {
+      points.plus.provenContract = 15;
+      total += 15;
+      reasons.push('Code contract proven via AST analysis');
+    }
+  
+    // +10 if console has errors (might explain why request didn't fire)
+    if ((consoleSummary.consoleErrorCount || 0) > 0 || (consoleSummary.pageErrorCount || 0) > 0) {
+      points.plus.consoleError = 10;
+      total += 10;
+      reasons.push('JavaScript errors may have prevented request');
+    }
+  
+    // +10 if absolutely zero network activity (not even unrelated requests)
+    if ((networkSummary.totalRequests || 0) === 0) {
+      points.plus.zeroNetworkActivity = 10;
+      total += 10;
+      reasons.push('Zero network activity despite code promise');
+    }
+  
+    return total;
+  }
+
+  function penalizeMissingNetworkAction({ networkSummary, points, reasons }) {
+    let total = 0;
+  
+    // -15 if there WAS network activity (maybe promise fulfilled differently)
+    if ((networkSummary.totalRequests || 0) > 0) {
+      points.minus.hadNetworkActivity = 15;
+      total += 15;
+      reasons.push('Other network requests occurred (may be fulfilling contract)');
+    }
+  
+    return total;
+  }
+
+  // === MISSING STATE ACTION SCORING ===
+
+  function scoreMissingStateAction({ expectation, attemptMeta, sensors, comparisons, points, reasons }) {
+    let total = 0;
+
+    // +15 if PROVEN expectation with handlerRef (TS cross-file proof)
+    if (expectation?.proof === 'PROVEN_EXPECTATION' && attemptMeta.handlerRef) {
+      points.plus.provenHandlerRef = 15;
+      total += 15;
+      reasons.push('State mutation proven via TS cross-file analysis');
+    }
+
+    // +10 if state UI did not change (explicit signal)
+    const stateUI = sensors.stateUI || {};
+    if (stateUI.changed === false) {
+      points.plus.noStateChange = 10;
+      total += 10;
+      reasons.push('State UI signals show no change');
+    }
+
+    // +5 if DOM did not change (supports missing state mutation theory)
+    if (comparisons.hasDomChange === false) {
+      points.plus.noDomChange = 5;
+      total += 5;
+      reasons.push('DOM unchanged despite promised state mutation');
+    }
+
+    return total;
+  }
+
+  function penalizeMissingStateAction({ sensors, networkSummary, points, reasons }) {
+    let total = 0;
+
+    // -10 if there IS network activity (may be causing state change asynchronously)
+    if ((networkSummary.totalRequests || 0) > 0) {
+      points.minus.hadNetworkActivity = 10;
+      total += 10;
+      reasons.push('Network activity may be causing deferred state update');
+    }
+
+    // -10 if UI feedback changed (may indicate state managed differently)
+    const uiSignals = sensors.uiSignals || {};
+    if (uiSignals.changes?.changed === true) {
+      points.minus.hadUIFeedback = 10;
+      total += 10;
+      reasons.push('UI feedback changed (state may be managed via feedback rather than direct mutation)');
+    }
+
+    return total;
+  }

package/src/verax/detect/evidence-validator.js

@@ -0,0 +1,33 @@
+import { readFileSync, existsSync } from 'fs';
+import { createHash } from 'crypto';
+
+export function normalizeUrl(url) {
+  try {
+    const urlObj = new URL(url);
+    return {
+      origin: urlObj.origin,
+      pathname: urlObj.pathname,
+      search: urlObj.search,
+      hash: urlObj.hash
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+export function getUrlPath(url) {
+  const normalized = normalizeUrl(url);
+  if (!normalized) return null;
+  return normalized.pathname + normalized.hash;
+}
+
+export function getScreenshotHash(screenshotPath) {
+  try {
+    if (!existsSync(screenshotPath)) return null;
+    const imageData = readFileSync(screenshotPath);
+    return createHash('md5').update(imageData).digest('hex');
+  } catch (error) {
+    return null;
+  }
+}
+