@veraxhq/verax 0.1.0 → 0.2.0

package/src/verax/shared/expectation-tracker.js

@@ -0,0 +1,201 @@
+/**
+ * Wave 2 — Expectation Tracker
+ * 
+ * Generates stable expectation IDs and tracks expectation usage.
+ */
+
+import { createHash } from 'crypto';
+
+/**
+ * Generate stable expectation ID from expectation data
+ * @param {Object} expectation - Expectation object
+ * @param {string} type - Expectation type (navigation, network_action, state_action)
+ * @returns {string} Stable ID (8-char hex hash)
+ */
+export function generateExpectationId(expectation, type) {
+  // Create deterministic hash from type + source + target
+  const source = expectation.source || expectation.sourceFile || expectation.evidence?.source || '';
+  const target = expectation.targetPath || expectation.urlPath || '';
+  const method = expectation.method || '';
+  const stateKind = expectation.stateKind || '';
+  const handlerRef = expectation.handlerRef || '';
+  const sourceRef = expectation.source || '';
+  
+  // Build hash input string
+  const hashInput = `${type}|${source}|${target}|${method}|${stateKind}|${handlerRef}|${sourceRef}`;
+  
+  // Generate stable 8-character hex hash
+  const hash = createHash('sha256').update(hashInput).digest('hex');
+  return hash.substring(0, 8);
+}
+
+/**
+ * Normalize expectation for tracking
+ * @param {Object} expectation - Raw expectation from manifest
+ * @param {string} type - Expectation type
+ * @returns {Object} Normalized expectation with ID
+ */
+export function normalizeExpectation(expectation, type) {
+  const id = generateExpectationId(expectation, type);
+  
+  // Extract source location
+  let sourceFile = null;
+  let sourceLine = null;
+  let sourceColumn = null;
+  
+  if (expectation.evidence?.source) {
+    sourceFile = expectation.evidence.source;
+  } else if (expectation.sourceFile) {
+    sourceFile = expectation.sourceFile;
+  } else if (expectation.source) {
+    // sourceRef format: "file:line:col"
+    const sourceMatch = expectation.source.match(/^(.+):(\d+):(\d+)$/);
+    if (sourceMatch) {
+      sourceFile = sourceMatch[1];
+      sourceLine = parseInt(sourceMatch[2], 10);
+      sourceColumn = parseInt(sourceMatch[3], 10);
+    } else {
+      sourceFile = expectation.source;
+    }
+  }
+  
+  if (expectation.line !== undefined && expectation.line !== null) {
+    sourceLine = expectation.line;
+  }
+  
+  // Determine reason for PROVEN vs UNKNOWN
+  let reason = 'unknown';
+  if (expectation.proof === 'PROVEN_EXPECTATION') {
+    if (type === 'navigation') {
+      if (expectation.evidence) {
+        reason = 'static route literal';
+      } else if (expectation.matchAttribute) {
+        reason = 'ast-derived jsx contract';
+      }
+    } else if (type === 'network_action') {
+      if (expectation.source || expectation.handlerRef) {
+        reason = 'ast-derived network contract';
+      }
+    } else if (type === 'state_action') {
+      if (expectation.source || expectation.handlerRef) {
+        reason = 'ast-derived state contract';
+      }
+    } else if (type === 'validation_block') {
+      if (expectation.source || expectation.handlerRef) {
+        reason = 'ast-derived validation contract';
+      }
+    }
+  } else {
+    reason = 'unproven expectation';
+  }
+  
+  return {
+    id,
+    type,
+    proof: expectation.proof || 'UNKNOWN_EXPECTATION',
+    reason,
+    source: {
+      file: sourceFile,
+      line: sourceLine,
+      column: sourceColumn
+    },
+    used: false,
+    usedReason: null,
+    raw: expectation // Keep raw data for reference
+  };
+}
+
+/**
+ * Track all expectations from manifest
+ * @param {Object} manifest - Manifest object
+ * @returns {Array} Array of normalized expectations
+ */
+export function trackExpectations(manifest) {
+  const expectations = [];
+  
+  // Track static expectations
+  if (manifest.staticExpectations && manifest.staticExpectations.length > 0) {
+    for (const exp of manifest.staticExpectations) {
+      const type = exp.type === 'form_submission' ? 'network_action' : 'navigation';
+      expectations.push(normalizeExpectation(exp, type));
+    }
+  }
+  
+  // Track SPA expectations
+  if (manifest.spaExpectations && manifest.spaExpectations.length > 0) {
+    for (const exp of manifest.spaExpectations) {
+      expectations.push(normalizeExpectation(exp, 'navigation'));
+    }
+  }
+  
+  // Track action contracts (network, state, and validation)
+  if (manifest.actionContracts && manifest.actionContracts.length > 0) {
+    for (const contract of manifest.actionContracts) {
+      if (contract.kind === 'NETWORK_ACTION' || contract.kind === 'network') {
+        expectations.push(normalizeExpectation(contract, 'network_action'));
+      } else if (contract.kind === 'STATE_ACTION' || contract.kind === 'state') {
+        expectations.push(normalizeExpectation(contract, 'state_action'));
+      } else if (contract.kind === 'VALIDATION_BLOCK') {
+        expectations.push(normalizeExpectation(contract, 'validation_block'));
+      }
+    }
+  }
+  
+  return expectations;
+}
+
+/**
+ * Find expectation by ID
+ * @param {Array} expectations - Tracked expectations
+ * @param {string} expectationId - ID to find
+ * @returns {Object|null} Matching expectation or null
+ */
+export function findExpectationById(expectations, expectationId) {
+  return expectations.find(e => e.id === expectationId) || null;
+}
+
+/**
+ * Find expectation by matching criteria (for detect phase)
+ * @param {Array} expectations - Tracked expectations
+ * @param {Object} criteria - Matching criteria
+ * @returns {Object|null} Matching expectation or null
+ */
+export function findExpectationByCriteria(expectations, criteria) {
+  const { type, source, target, method, stateKind, handlerRef } = criteria;
+  
+  for (const exp of expectations) {
+    if (exp.type !== type) continue;
+    
+    // Match by source
+    const expSource = exp.raw.source || exp.raw.sourceFile || exp.raw.evidence?.source;
+    if (source && expSource && expSource.includes(source)) {
+      // Check target for navigation
+      if (type === 'navigation') {
+        const expTarget = exp.raw.targetPath;
+        if (expTarget === target) {
+          return exp;
+        }
+      }
+      // Check method/urlPath for network_action
+      else if (type === 'network_action') {
+        if (method && exp.raw.method === method && exp.raw.urlPath === target) {
+          return exp;
+        }
+      }
+      // Check stateKind for state_action
+      else if (type === 'state_action') {
+        if (stateKind && exp.raw.stateKind === stateKind) {
+          return exp;
+        }
+      }
+    }
+    
+    // Match by handlerRef
+    if (handlerRef && exp.raw.handlerRef === handlerRef) {
+      return exp;
+    }
+  }
+  
+  return null;
+}
+

package/src/verax/shared/expectations-writer.js

@@ -0,0 +1,60 @@
+/**
+ * Wave 2 — Expectations Writer
+ * 
+ * Writes expectations.json artifact with full explainability.
+ */
+
+import { writeFileSync } from 'fs';
+
+/**
+ * Write expectations.json artifact
+ * @param {Object} paths - Artifact paths
+ * @param {Array} expectations - Tracked expectations
+ */
+export function writeExpectations(paths, expectations) {
+  // Count by type
+  const byType = {
+    navigation: 0,
+    network_action: 0,
+    state_action: 0
+  };
+  
+  let skipped = 0;
+  
+  const expectationsList = expectations.map(exp => {
+    byType[exp.type] = (byType[exp.type] || 0) + 1;
+    
+    if (!exp.used) {
+      skipped++;
+    }
+    
+    return {
+      id: exp.id,
+      type: exp.type,
+      proof: exp.proof,
+      reason: exp.reason,
+      source: {
+        file: exp.source.file,
+        line: exp.source.line,
+        column: exp.source.column
+      },
+      used: exp.used,
+      usedReason: exp.usedReason || null
+    };
+  });
+  
+  const data = {
+    summary: {
+      total: expectations.length,
+      byType: byType,
+      skipped: skipped
+    },
+    expectations: expectationsList
+  };
+  
+  const expectationsPath = paths.expectations || paths.summary.replace('summary.json', 'expectations.json');
+  writeFileSync(expectationsPath, JSON.stringify(data, null, 2) + '\n');
+  
+  return expectationsPath;
+}
+

package/src/verax/shared/first-run.js

@@ -0,0 +1,44 @@
+/**
+ * Wave 9 — First-Run Detection
+ * 
+ * Detects and tracks first-ever CLI run.
+ */
+
+import { existsSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+/**
+ * Get first-run marker path
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Marker file path
+ */
+function getMarkerPath(projectRoot) {
+  const veraxDir = resolve(projectRoot, '.verax');
+  return resolve(veraxDir, '.first-run-complete');
+}
+
+/**
+ * Check if this is the first run
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean} True if first run
+ */
+export function isFirstRun(projectRoot) {
+  const markerPath = getMarkerPath(projectRoot);
+  return !existsSync(markerPath);
+}
+
+/**
+ * Mark first run as complete
+ * @param {string} projectRoot - Project root directory
+ */
+export function markFirstRunComplete(projectRoot) {
+  const markerPath = getMarkerPath(projectRoot);
+  const veraxDir = dirname(markerPath);
+  
+  // Ensure .verax directory exists
+  mkdirSync(veraxDir, { recursive: true });
+  
+  // Write marker file (empty file is sufficient)
+  writeFileSync(markerPath, '', 'utf-8');
+}
+

package/src/verax/shared/progress-reporter.js

@@ -0,0 +1,171 @@
+/**
+ * Wave 4 — Progress Reporter
+ * 
+ * Reports real-time progress during scan phases with actual counts.
+ */
+
+/**
+ * Progress reporter that tracks real progress metrics
+ */
+export class ProgressReporter {
+  constructor(options = {}) {
+    this.output = options.output || process.stderr;
+    this.silent = options.silent || false;
+    this.explain = options.explain || false;
+    
+    // Phase tracking
+    this.currentPhase = null;
+    this.phaseProgress = {
+      learn: { current: 0, total: 0, details: [] },
+      validate: { current: 0, total: 0, details: [] },
+      observe: { current: 0, total: 0, details: [] },
+      detect: { current: 0, total: 0, details: [] }
+    };
+    
+    // Interaction stats
+    this.interactionStats = {
+      discovered: 0,
+      executed: 0,
+      skipped: 0,
+      skippedByReason: {}
+    };
+    
+    // Expectation stats
+    this.expectationStats = {
+      total: 0,
+      used: 0,
+      unused: 0,
+      unusedByReason: {}
+    };
+  }
+  
+  /**
+   * Report phase start
+   */
+  startPhase(phase, message) {
+    this.currentPhase = phase;
+    if (!this.silent) {
+      this.output.write(`[VERAX] [${phase}] ${message}\n`);
+    }
+  }
+  
+  /**
+   * Report learn phase progress
+   */
+  reportLearnProgress(current, total, details = []) {
+    this.phaseProgress.learn.current = current;
+    this.phaseProgress.learn.total = total;
+    this.phaseProgress.learn.details = details;
+    
+    if (!this.silent && total > 0) {
+      this.output.write(`[VERAX] [1/4] Learn: ${current}/${total} expectations discovered\n`);
+    }
+  }
+  
+  /**
+   * Report validate phase progress
+   */
+  reportValidateProgress(current, total) {
+    this.phaseProgress.validate.current = current;
+    this.phaseProgress.validate.total = total;
+    
+    if (!this.silent && total > 0) {
+      this.output.write(`[VERAX] [2/4] Validate: ${current}/${total} routes checked\n`);
+    }
+  }
+  
+  /**
+   * Report observe phase progress
+   */
+  reportObserveProgress(discovered, executed, skipped = 0, skippedByReason = {}) {
+    this.interactionStats.discovered = discovered;
+    this.interactionStats.executed = executed;
+    this.interactionStats.skipped = skipped;
+    this.interactionStats.skippedByReason = skippedByReason;
+    
+    if (!this.silent) {
+      this.output.write(`[VERAX] [3/4] Observe: ${executed}/${discovered} interactions executed`);
+      if (skipped > 0) {
+        const reasons = Object.entries(skippedByReason)
+          .map(([reason, count]) => `${reason}=${count}`)
+          .join(', ');
+        this.output.write(` (skipped: ${skipped} [${reasons}])\n`);
+      } else {
+        this.output.write('\n');
+      }
+    }
+  }
+  
+  /**
+   * Report detect phase progress
+   */
+  reportDetectProgress(evaluated, total, used = 0, unused = 0, unusedByReason = {}) {
+    this.phaseProgress.detect.current = evaluated;
+    this.phaseProgress.detect.total = total;
+    this.expectationStats.total = total;
+    this.expectationStats.used = used;
+    this.expectationStats.unused = unused;
+    this.expectationStats.unusedByReason = unusedByReason;
+    
+    if (!this.silent && total > 0) {
+      this.output.write(`[VERAX] [4/4] Detect: ${evaluated}/${total} expectations evaluated`);
+      if (unused > 0) {
+        const reasons = Object.entries(unusedByReason)
+          .map(([reason, count]) => `${reason}=${count}`)
+          .join(', ');
+        this.output.write(` (unused: ${unused} [${reasons}])\n`);
+      } else {
+        this.output.write('\n');
+      }
+    }
+  }
+  
+  /**
+   * Get progress statistics
+   */
+  getProgressStats() {
+    return {
+      learn: {
+        current: this.phaseProgress.learn.current,
+        total: this.phaseProgress.learn.total
+      },
+      validate: {
+        current: this.phaseProgress.validate.current,
+        total: this.phaseProgress.validate.total
+      },
+      observe: {
+        current: this.interactionStats.executed,
+        total: this.interactionStats.discovered
+      },
+      detect: {
+        current: this.phaseProgress.detect.current,
+        total: this.phaseProgress.detect.total
+      }
+    };
+  }
+  
+  /**
+   * Get interaction statistics
+   */
+  getInteractionStats() {
+    return {
+      discovered: this.interactionStats.discovered,
+      executed: this.interactionStats.executed,
+      skipped: this.interactionStats.skipped,
+      skippedByReason: this.interactionStats.skippedByReason
+    };
+  }
+  
+  /**
+   * Get expectation usage statistics
+   */
+  getExpectationUsageStats() {
+    return {
+      total: this.expectationStats.total,
+      used: this.expectationStats.used,
+      unused: this.expectationStats.unused,
+      unusedByReason: this.expectationStats.unusedByReason
+    };
+  }
+}
+

package/src/verax/shared/retry-policy.js

@@ -42,9 +42,10 @@ export function isRetryableError(error) {
  * Retry an operation with exponential backoff.
  * @param {Function} fn - Async function to retry
  * @param {string} operationName - For logging
+ * @param {Object} decisionRecorder - Optional DecisionRecorder for Phase 6 determinism tracking
  * @returns {Promise<{result: *, retriesUsed: number}>}
  */
-export async function retryOperation(fn, operationName = 'operation') {
+export async function retryOperation(fn, operationName = 'operation', decisionRecorder = null) {
   let lastError = null;
   let retriesUsed = 0;
 
@@ -59,6 +60,18 @@ export async function retryOperation(fn, operationName = 'operation') {
       if (attempt < MAX_RETRIES && isRetryableError(error)) {
         retriesUsed++;
         const delayMs = RETRY_DELAYS[attempt];
+        
+        // PHASE 6: Record retry decision for determinism tracking
+        if (decisionRecorder && decisionRecorder.record) {
+          const { recordRetryAttempt } = await import('../core/determinism-model.js');
+          recordRetryAttempt(decisionRecorder, {
+            attempt: attempt + 1,
+            errorType: lastError.message,
+            backoffMs: delayMs,
+            operationName
+          });
+        }
+        
         await new Promise(resolve => setTimeout(resolve, delayMs));
         // Continue to next attempt
       } else {

package/src/verax/shared/root-artifacts.js

@@ -0,0 +1,49 @@
+/**
+ * Root-level artifacts helper
+ * Enforces strict routing of outputs to artifacts/* subdirectories.
+ */
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+
+const BASE = 'artifacts';
+const TYPE_DIRS = {
+  'test-runs': 'test-runs',
+  'tmp': 'tmp',
+  'debug': 'debug',
+  'logs': 'logs',
+  'legacy': 'legacy',
+};
+
+/**
+ * Ensure directory exists
+ */
+function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Get an absolute path for an artifact output, enforcing isolation.
+ * @param {('test-runs'|'tmp'|'debug'|'logs'|'legacy')} type
+ * @param {string} name - filename or subpath (no leading slashes)
+ * @returns {string} absolute path to write into
+ */
+export function getArtifactPath(type, name) {
+  const subDir = TYPE_DIRS[type];
+  if (!subDir) throw new Error(`Unknown artifact type: ${type}`);
+  const dir = resolve(BASE, subDir);
+  ensureDir(dir);
+  return resolve(dir, name);
+}
+
+/**
+ * Get directory for a given artifact type.
+ */
+export function getArtifactDir(type) {
+  const subDir = TYPE_DIRS[type];
+  if (!subDir) throw new Error(`Unknown artifact type: ${type}`);
+  const dir = resolve(BASE, subDir);
+  ensureDir(dir);
+  return dir;
+}

package/src/verax/shared/scan-budget.js

@@ -0,0 +1,86 @@
+/**
+ * ScanBudget - Single source of truth for all execution limits
+ * 
+ * All execution-related limits are controlled through this object.
+ * No hardcoded limits should exist in execution code paths.
+ */
+
+/**
+ * @typedef {Object} ScanBudget
+ * @property {number} maxTotalInteractions - Maximum total interactions across all pages
+ * @property {number} maxInteractionsPerPage - Maximum interactions to discover/execute per page
+ * @property {number} maxPages - Maximum pages to visit (currently not used, but reserved for future)
+ * @property {number} maxFlows - Maximum flows to execute per run
+ * @property {number} maxFlowSteps - Maximum steps per flow
+ * @property {number} maxScanDurationMs - Maximum total scan duration in milliseconds
+ * @property {number} interactionTimeoutMs - Timeout for individual interaction execution
+ * @property {number} navigationTimeoutMs - Timeout for navigation waits
+ * @property {number} stabilizationWindowMs - Total stabilization window (mid + end + network wait)
+ * @property {number} stabilizationSampleMidMs - First stabilization sample delay
+ * @property {number} stabilizationSampleEndMs - Second stabilization sample delay
+ * @property {number} networkWaitMs - Additional wait for slow network requests
+ * @property {number} navigationStableWaitMs - Wait after navigation before interaction
+ * @property {number} initialNavigationTimeoutMs - Timeout for initial page.goto() navigation
+ * @property {number} settleTimeoutMs - Timeout for settle operations
+ * @property {number} settleIdleMs - Network idle threshold for settle
+ * @property {number} settleDomStableMs - DOM stability window for settle
+ * @property {number} maxUniqueUrls - Maximum unique normalized URLs (frontier cap)
+ * @property {boolean} adaptiveStabilization - Enable adaptive settle extension in THOROUGH/EXHAUSTIVE
+ */
+
+/**
+ * Default scan budget that reproduces current behavior exactly.
+ * 
+ * Current values:
+ * - maxInteractionsPerPage: 30 (from interaction-discovery.js)
+ * - maxScanDurationMs: 60000 (60 seconds, from observe/index.js)
+ * - maxFlowSteps: 5 (from observe/index.js)
+ * - maxFlows: 3 (from observe/index.js)
+ * - interactionTimeoutMs: 10000 (10 seconds, from interaction-runner.js)
+ * - navigationTimeoutMs: 15000 (15 seconds, from interaction-runner.js)
+ * - stabilizationSampleMidMs: 500 (from interaction-runner.js)
+ * - stabilizationSampleEndMs: 1500 (from interaction-runner.js)
+ * - networkWaitMs: 1000 (from interaction-runner.js line 49)
+ * - navigationStableWaitMs: 2000 (from browser.js STABLE_WAIT_MS)
+ * - initialNavigationTimeoutMs: 30000 (from browser.js page.goto timeout)
+ * - settleTimeoutMs: 30000 (from settle.js default)
+ * - settleIdleMs: 1500 (from settle.js default)
+ * - settleDomStableMs: 2000 (from settle.js default)
+ * - stabilizationWindowMs: 3000 (500 + 1000 + 1000 + 500 = total stabilization time)
+ * - maxTotalInteractions: unlimited (controlled by maxScanDurationMs)
+ * - maxPages: 1 (current implementation only scans starting page)
+ */
+export const DEFAULT_SCAN_BUDGET = {
+  maxTotalInteractions: Infinity, // Controlled by maxScanDurationMs in practice
+  maxInteractionsPerPage: 30,
+    maxPages: 50, // Allow multi-page traversal by default
+  maxFlows: 3,
+  maxFlowSteps: 5,
+  maxScanDurationMs: 60000,
+  interactionTimeoutMs: 10000,
+  navigationTimeoutMs: 15000,
+  stabilizationWindowMs: 3000, // Total: 500 + 1000 + 1000 + 500
+  stabilizationSampleMidMs: 500,
+  stabilizationSampleEndMs: 1500,
+  networkWaitMs: 1000,
+  navigationStableWaitMs: 2000,
+  initialNavigationTimeoutMs: 30000,
+  settleTimeoutMs: 30000,
+  settleIdleMs: 1500,
+  settleDomStableMs: 2000,
+  maxUniqueUrls: 500, // Prevent infinite frontier growth on large sites
+  adaptiveStabilization: false // Disabled by default, enabled in THOROUGH/EXHAUSTIVE
+};
+
+/**
+ * Create a scan budget with custom values, falling back to defaults.
+ * @param {Partial<ScanBudget>} overrides - Partial budget to override defaults
+ * @returns {ScanBudget} Complete scan budget
+ */
+export function createScanBudget(overrides = {}) {
+  return {
+    ...DEFAULT_SCAN_BUDGET,
+    ...overrides
+  };
+}
+