@veraxhq/verax 0.1.0 → 0.2.1

package/src/verax/cli/wizard.js

@@ -0,0 +1,109 @@
+/**
+ * Wave 3 — Interactive Wizard
+ * 
+ * Guides users through VERAX configuration with friendly prompts.
+ */
+
+/**
+ * @typedef {Object} ReadlineInterface
+ * @property {function(string): Promise<string>} question - Prompt user with question
+ * @property {function(): void} close - Close the readline interface
+ */
+
+/**
+ * Create a readline interface (can be injected for testing)
+ * @returns {Promise<ReadlineInterface>}
+ */
+async function createReadlineInterface(input = process.stdin, output = process.stdout) {
+  const readline = await import('readline/promises');
+  return readline.default.createInterface({
+    input,
+    output,
+    terminal: true
+  });
+}
+
+/**
+ * @typedef {Object} WizardOptions
+ * @property {ReadlineInterface} [readlineInterface] - Readline interface (injectable for testing)
+ */
+
+/**
+ * Run interactive wizard
+ * @param {WizardOptions} [options={}] - Options for wizard
+ * @returns {Promise<Object>} Wizard results
+ */
+export async function runWizard(options = {}) {
+  const rl = options.readlineInterface || await createReadlineInterface();
+  
+  try {
+    console.log('VERAX — Silent Failure Detection\n');
+    console.log('This wizard will guide you through setting up a VERAX scan.\n');
+    
+    // 1. Mode selection (Wave 7: add init and doctor)
+    const modeAnswer = await rl.question('Mode: (s)can, (f)low, (i)nit, or (d)octor? [s]: ');
+    const modeInput = (modeAnswer.trim().toLowerCase() || 's');
+    let mode;
+    if (modeInput.startsWith('i')) {
+      mode = 'init';
+    } else if (modeInput.startsWith('d')) {
+      mode = 'doctor';
+    } else if (modeInput.startsWith('f')) {
+      mode = 'flow';
+    } else {
+      mode = 'scan';
+    }
+    
+    // For init and doctor modes, return early
+    if (mode === 'init' || mode === 'doctor') {
+      return { mode };
+    }
+    
+    // 2. URL
+    const urlAnswer = await rl.question('URL to scan [http://localhost:3000]: ');
+    let url = urlAnswer.trim();
+    if (!url) {
+      url = 'http://localhost:3000';
+    }
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+      url = 'http://' + url;
+    }
+    
+    // 3. Project root (for scan) or flow file (for flow)
+    let projectRoot = process.cwd();
+    let flowPath = null;
+    
+    if (mode === 'scan') {
+      const projectRootAnswer = await rl.question(`Project root [${projectRoot}]: `);
+      if (projectRootAnswer.trim()) {
+        projectRoot = projectRootAnswer.trim();
+      }
+    } else {
+      const flowPathAnswer = await rl.question('Flow file path: ');
+      flowPath = flowPathAnswer.trim();
+      if (!flowPath) {
+        throw new Error('Flow file path is required');
+      }
+    }
+    
+    // 4. JSON output
+    const jsonAnswer = await rl.question('JSON output? (y/N) [N]: ');
+    const jsonOutput = (jsonAnswer.trim().toLowerCase() || 'n').startsWith('y');
+    
+    // 5. Output directory
+    const outDirAnswer = await rl.question(`Output directory [.verax/runs]: `);
+    const outDir = outDirAnswer.trim() || '.verax/runs';
+    
+    return {
+      mode,
+      url,
+      projectRoot,
+      flowPath,
+      json: jsonOutput,
+      out: outDir
+    };
+  } finally {
+    rl.close();
+  }
+}
+

package/src/verax/cli/zero-findings-explainer.js

@@ -0,0 +1,57 @@
+/**
+ * Zero Findings Explanation
+ * 
+ * Observational explanation of zero findings (not a judgment).
+ */
+
+/**
+ * Generate explanation for zero findings
+ * @param {Object} context - Context information
+ * @returns {Array<string>} Explanation lines
+ */
+export function explainZeroFindings(context = {}) {
+  const {
+    expectationsCount = 0,
+    interactionsObserved = 0,
+    discrepanciesObserved = 0
+  } = context;
+  
+  const lines = [
+    '────────────────────────────────────────────────────────────',
+    'OBSERVATION: No Discrepancies Detected',
+    '────────────────────────────────────────────────────────────',
+    '',
+    `VERAX analyzed ${expectationsCount} code-derived expectations`,
+    `Observed ${interactionsObserved} user interactions`,
+    `Discrepancies observed: ${discrepanciesObserved}`,
+    '',
+    'What this means:',
+    '  • During this scan, no discrepancies were observed between code promises and runtime behavior',
+    '  • This does NOT guarantee safety, correctness, or completeness',
+    '  • Some expectations may not have been evaluated (see gaps below)',
+    '',
+    'What was not observed:',
+  ];
+  
+  if (expectationsCount === 0) {
+    lines.push('  • No expectations found in code - no evaluation was possible');
+    lines.push('  • VERAX requires PROVEN expectations (static patterns) to observe behavior');
+  } else {
+    lines.push('  • Check coverage gaps to see what was not evaluated');
+  }
+  
+  return lines;
+}
+
+/**
+ * Print zero findings explanation
+ * @param {Object} context - Context
+ */
+export function printZeroFindingsExplanation(context = {}) {
+  const lines = explainZeroFindings(context);
+  lines.forEach(line => {
+    console.error(line);
+  });
+  console.error('');
+}
+

package/src/verax/cli/zero-interaction-explainer.js

@@ -0,0 +1,127 @@
+/**
+ * Wave 6 — Zero Interaction Explanation
+ * 
+ * Explains why no interactions were executed and what could/could not be validated.
+ */
+
+/**
+ * Explain why no interactions were executed
+ * @param {Object} context - Scan context
+ * @returns {Array<string>} Explanation lines
+ */
+export function explainZeroInteractions(context = {}) {
+  const {
+    verdict = 'UNKNOWN',
+    contextCheck = null,
+    interactionsObserved = 0,
+    expectationsTotal = 0,
+    observation = null
+  } = context;
+  
+  // If interactions were actually observed, return empty
+  if (interactionsObserved > 0) {
+    return [];
+  }
+  
+  // If no expectations, different explanation
+  if (expectationsTotal === 0) {
+    return [
+      'No interactions executed because no expectations were found.',
+      'VERAX needs code-derived expectations to know what to test.'
+    ];
+  }
+  
+  const reasons = [];
+  
+  // Context validation stopped early
+  if (verdict === 'INVALID_CONTEXT' && contextCheck && !contextCheck.forced) {
+    reasons.push([
+      '⚠️  No interactions executed because context validation failed.',
+      '',
+      'VERAX stopped the scan early to prevent analyzing the wrong site.',
+      '',
+      'What VERAX could validate:',
+      `  ✓ Discovered ${expectationsTotal} expectations from your code`,
+      '  ✗ Could not validate interactions (scan stopped)',
+      '',
+      'What to do:',
+      '  • Use --force to scan anyway, or',
+      '  • Ensure your URL matches the project being analyzed'
+    ]);
+  } else if (verdict === 'INVALID_CONTEXT_FORCED') {
+    reasons.push([
+      '⚠️  Limited interactions executed due to context mismatch.',
+      '',
+      'VERAX continued with --force but may not have found expected routes.',
+      '',
+      'What VERAX validated:',
+      `  ✓ ${expectationsTotal} expectations found`,
+      '  ⚠ Interactions may not match expectations (context mismatch)',
+      '',
+      'What to do:',
+      '  • Verify URL matches project deployment',
+      '  • Check that routes exist on the live site'
+    ]);
+  } else {
+    // No interactions discovered or executed
+    const observationDetails = observation?.observeTruth || {};
+    
+    if (observationDetails.interactionsObserved === 0) {
+      reasons.push([
+        '⚠️  No interactions executed.',
+        '',
+        'VERAX could not discover any interactive elements on the page.',
+        '',
+        'What VERAX could validate:',
+        `  ✓ Discovered ${expectationsTotal} expectations from your code`,
+        '  ✗ Could not test interactions (no discoverable elements)',
+        '',
+        'Possible reasons:',
+        '  • Page has no clickable links, buttons, or forms',
+        '  • Elements are hidden or not rendered',
+        '  • JavaScript errors prevented interaction discovery',
+        '',
+        'What to do:',
+        '  • Verify the page loads correctly',
+        '  • Check browser console for errors',
+        '  • Ensure interactive elements are visible and accessible'
+      ]);
+    } else {
+      // Interactions discovered but none executed
+      reasons.push([
+        '⚠️  No interactions executed despite discoveries.',
+        '',
+        'VERAX discovered interactions but could not execute them.',
+        '',
+        'What VERAX could validate:',
+        `  ✓ Discovered ${expectationsTotal} expectations from your code`,
+        '  ✗ Could not test interactions (execution failed)',
+        '',
+        'What to do:',
+        '  • Check network connectivity',
+        '  • Verify page is accessible',
+        '  • Review error logs for details'
+      ]);
+    }
+  }
+  
+  return reasons.flat();
+}
+
+/**
+ * Print zero interaction explanation
+ * @param {Object} context - Scan context
+ */
+export function printZeroInteractionExplanation(context) {
+  const explanation = explainZeroInteractions(context);
+  if (explanation.length > 0) {
+    console.error('\n' + '─'.repeat(60));
+    console.error('Interaction Status');
+    console.error('─'.repeat(60));
+    explanation.forEach(line => {
+      console.error(line);
+    });
+    console.error('─'.repeat(60) + '\n');
+  }
+}
+

package/src/verax/core/action-classifier.js

@@ -0,0 +1,86 @@
+/**
+ * ACTION CLASSIFIER
+ * 
+ * Classifies user interactions by safety level for misuse resistance.
+ * NO JUDGMENT SEMANTICS - only risk classification for protection.
+ * 
+ * Classifications:
+ * - SAFE_READONLY: Navigation, focus, hover, non-submitting clicks
+ * - RISKY: Destructive actions (delete/remove/clear data), logout, admin
+ * - WRITE_INTENT: State-changing actions (submit, file upload, checkout/pay)
+ * 
+ * Phase 4: Default safe mode blocks RISKY and WRITE_INTENT unless explicitly allowed.
+ */
+
+/**
+ * Classify an interaction's safety level
+ * @param {Object} interaction - Interaction object with type, text, label, selector
+ * @returns {Object} { classification: string, reason: string }
+ */
+export function classifyAction(interaction) {
+  const type = (interaction.type || '').toLowerCase();
+  const text = (interaction.text || '').toLowerCase().trim();
+  const label = (interaction.label || '').toLowerCase().trim();
+  const ariaLabel = (interaction.ariaLabel || '').toLowerCase().trim();
+  const selector = (interaction.selector || '').toLowerCase();
+  const combined = `${text} ${label} ${ariaLabel}`.trim();
+
+  // RISKY patterns - destructive/dangerous actions
+  const riskyKeywords = /\b(delete|remove|erase|wipe|destroy|drop|clear\s+(data|all|history|cache|account|database|storage)|reset\s+(account|data|database)|deactivate|terminate|uninstall|unsubscribe)\b/i;
+  const adminKeywords = /\b(admin|administrator|sudo|root|settings|config|preferences)\b/i;
+  
+  if (riskyKeywords.test(combined)) {
+    return { classification: 'RISKY', reason: 'destructive_keyword' };
+  }
+
+  // Logout/signout treated as risky (state loss)
+  if (/\b(logout|sign\s*out|log\s*out)\b/i.test(combined)) {
+    return { classification: 'RISKY', reason: 'auth_logout' };
+  }
+
+  // Admin/config actions risky
+  if (adminKeywords.test(combined) && !/view|read|show/.test(combined)) {
+    return { classification: 'RISKY', reason: 'admin_action' };
+  }
+
+  // WRITE_INTENT patterns - state-changing actions
+  const writeKeywords = /\b(submit|send|post|save|update|create|add|checkout|purchase|pay|buy|order|upload|attach|edit|modify)\b/i;
+  
+  if (writeKeywords.test(combined)) {
+    return { classification: 'WRITE_INTENT', reason: 'write_keyword' };
+  }
+
+  // Form submissions are write intent
+  if (type === 'submit' || selector.includes('type="submit"') || selector.includes('[type=submit]')) {
+    return { classification: 'WRITE_INTENT', reason: 'form_submit' };
+  }
+
+  // File inputs are write intent
+  if (type === 'file' || selector.includes('type="file"') || selector.includes('input[type=file]')) {
+    return { classification: 'WRITE_INTENT', reason: 'file_input' };
+  }
+
+  // Default: safe readonly (navigation, clicks, focus, hover)
+  return { classification: 'SAFE_READONLY', reason: 'default_safe' };
+}
+
+/**
+ * Check if action should be blocked based on safety mode and flags
+ * @param {Object} interaction - Interaction to check
+ * @param {Object} flags - Safety flags { allowWrites: boolean, allowRiskyActions: boolean }
+ * @returns {Object} { shouldBlock: boolean, classification: string, reason: string }
+ */
+export function shouldBlockAction(interaction, flags = {}) {
+  const { allowWrites = false, allowRiskyActions = false } = flags;
+  const { classification, reason } = classifyAction(interaction);
+
+  if (classification === 'RISKY' && !allowRiskyActions) {
+    return { shouldBlock: true, classification, reason };
+  }
+
+  if (classification === 'WRITE_INTENT' && !allowWrites) {
+    return { shouldBlock: true, classification, reason };
+  }
+
+  return { shouldBlock: false, classification, reason };
+}

package/src/verax/core/budget-engine.js

@@ -0,0 +1,218 @@
+/**
+ * Budget Engine
+ * Allocates adaptive interaction budgets per route/page based on:
+ * - Route criticality (has expectations or not)
+ * - Number of routes in project
+ * - Number of expectations per route
+ * 
+ * Deterministic and reproducible.
+ */
+
+export class BudgetEngine {
+  constructor(options = {}) {
+    this.baseBudgetPerRoute = options.baseBudgetPerRoute || 30;
+    this.criticalRouteMultiplier = options.criticalRouteMultiplier || 2.0;
+    this.nonCriticalRouteMultiplier = options.nonCriticalRouteMultiplier || 0.5;
+    this.expectationMultiplier = options.expectationMultiplier || 1.5;
+    this.minBudget = options.minBudget || 5;
+    this.maxBudget = options.maxBudget || 100;
+  }
+
+  /**
+   * Allocate budget for a single route
+   * @param {Object} route - Route object with url, interactions
+   * @param {Array} expectations - Expectations for this route
+   * @return {Object} Budget allocation { budget, isCritical, reason }
+   */
+  allocateBudgetForRoute(route, expectations = []) {
+    const isCritical = expectations.length > 0;
+    let budget = this.baseBudgetPerRoute;
+
+    if (isCritical) {
+      // Critical routes with expectations get higher budget
+      budget = Math.floor(budget * this.criticalRouteMultiplier);
+      
+      // Additional budget boost for routes with many expectations
+      if (expectations.length > 3) {
+        budget = Math.floor(budget * this.expectationMultiplier);
+      }
+    } else {
+      // Non-critical routes get reduced budget
+      budget = Math.floor(budget * this.nonCriticalRouteMultiplier);
+    }
+
+    // Clamp to min/max
+    budget = Math.max(this.minBudget, Math.min(this.maxBudget, budget));
+
+    return {
+      budget,
+      isCritical,
+      reason: isCritical 
+        ? `critical_route_${expectations.length}_expectations`
+        : 'non_critical_route',
+      routeUrl: route.url || route.path || 'unknown'
+    };
+  }
+
+  /**
+   * Allocate budgets for all routes deterministically
+   * @param {Array} routes - Array of route objects
+   * @param {Array} allExpectations - All expectations across routes
+   * @return {Array} Array of budget allocations sorted by URL for stability
+   */
+  allocateBudgets(routes, allExpectations = []) {
+    // Group expectations by route
+    const expectationsByRoute = new Map();
+    for (const exp of allExpectations) {
+      const routeUrl = exp.expectedRoute || exp.fromPath || '/';
+      if (!expectationsByRoute.has(routeUrl)) {
+        expectationsByRoute.set(routeUrl, []);
+      }
+      expectationsByRoute.get(routeUrl).push(exp);
+    }
+
+    // Allocate budget for each route
+    const allocations = [];
+    for (const route of routes) {
+      const routeUrl = route.url || route.path || '/';
+      const expectations = expectationsByRoute.get(routeUrl) || [];
+      const allocation = this.allocateBudgetForRoute(route, expectations);
+      allocations.push({
+        ...allocation,
+        routeUrl: routeUrl
+      });
+    }
+
+    // Sort deterministically by routeUrl for stable ordering
+    allocations.sort((a, b) => {
+      return (a.routeUrl || '').localeCompare(b.routeUrl || '');
+    });
+
+    return allocations;
+  }
+
+  /**
+   * Compute total budget across all routes
+   * @param {Array} routes - Array of route objects
+   * @param {Array} allExpectations - All expectations across routes
+   * @return {Object} Total budget stats
+   */
+  computeTotalBudget(routes, allExpectations = []) {
+    const allocations = this.allocateBudgets(routes, allExpectations);
+    
+    const totalBudget = allocations.reduce((sum, alloc) => sum + alloc.budget, 0);
+    const criticalRoutes = allocations.filter(a => a.isCritical).length;
+    const nonCriticalRoutes = allocations.filter(a => !a.isCritical).length;
+
+    return {
+      totalBudget,
+      totalRoutes: routes.length,
+      criticalRoutes,
+      nonCriticalRoutes,
+      averageBudgetPerRoute: routes.length > 0 ? Math.round(totalBudget / routes.length) : 0,
+      allocations
+    };
+  }
+
+  /**
+   * Get budget for a specific route URL
+   * @param {string} routeUrl - Route URL to query
+   * @param {Array} allocations - Pre-computed allocations
+   * @return {number|null} Budget or null if not found
+   */
+  getBudgetForRoute(routeUrl, allocations) {
+    const allocation = allocations.find(a => a.routeUrl === routeUrl);
+    return allocation ? allocation.budget : null;
+  }
+}
+
+// Legacy functional API for backwards compatibility
+export function computeRouteBudget(manifest, currentUrl, baseBudget) {
+  const routes = manifest.routes || [];
+  const expectations = manifest.staticExpectations || [];
+  const totalRoutes = routes.length;
+  // const totalExpectations = expectations.length; // Reserved for future use
+  
+  // Count expectations per route
+  const routeExpectationCount = new Map();
+  for (const exp of expectations) {
+    const routePath = exp.fromPath || '*';
+    routeExpectationCount.set(routePath, (routeExpectationCount.get(routePath) || 0) + 1);
+  }
+  
+  // Find matching route for current URL
+  const urlPath = extractPathFromUrl(currentUrl);
+  const urlPathNormalized = normalizePath(urlPath);
+  
+  // Try exact match first, then prefix match (but not root '/')
+  const matchingRoute = routes.find(r => {
+    const routePath = normalizePath(r.path);
+    if (routePath === '*' || routePath === urlPathNormalized) {
+      return true;
+    }
+    // Prefix match: only if routePath is not '/' and urlPath starts with routePath + '/'
+    if (routePath !== '/' && urlPathNormalized.startsWith(routePath + '/')) {
+      return true;
+    }
+    return false;
+  });
+  
+  const routePath = matchingRoute?.path || urlPath || '*';
+  const expectationsForRoute = routeExpectationCount.get(routePath) || 0;
+  
+  // Deterministic budget allocation:
+  // - Base: baseBudget.maxInteractionsPerPage
+  // - Critical routes (with expectations) get 1.5x budget
+  // - Non-critical routes get 0.7x budget
+  // - If total routes > 50, reduce all budgets proportionally
+  
+  let interactionBudget = baseBudget.maxInteractionsPerPage || 30;
+  
+  if (expectationsForRoute > 0) {
+    // Critical route: has expectations
+    interactionBudget = Math.floor(interactionBudget * 1.5);
+  } else if (totalRoutes > 10) {
+    // Non-critical route in large project: reduce budget
+    interactionBudget = Math.floor(interactionBudget * 0.7);
+  }
+  
+  // Scale down if project is very large
+  if (totalRoutes > 50) {
+    const scaleFactor = Math.max(0.6, 50 / totalRoutes);
+    interactionBudget = Math.floor(interactionBudget * scaleFactor);
+  }
+  
+  // Ensure minimum budget
+  interactionBudget = Math.max(5, interactionBudget);
+  
+  // Ensure maximum budget cap
+  interactionBudget = Math.min(100, interactionBudget);
+  
+  return {
+    ...baseBudget,
+    maxInteractionsPerPage: interactionBudget,
+    routePath: routePath,
+    expectationsForRoute: expectationsForRoute,
+    budgetReason: expectationsForRoute > 0 ? 'critical_route' : (totalRoutes > 10 ? 'non_critical_large_project' : 'default')
+  };
+}
+
+/**
+ * Extract path from URL
+ */
+function extractPathFromUrl(url) {
+  try {
+    const urlObj = new URL(url);
+    return urlObj.pathname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Normalize path for comparison
+ */
+function normalizePath(path) {
+  if (!path) return '/';
+  return path.replace(/\/$/, '') || '/';
+}