@veraxhq/verax 0.2.1 → 0.4.0

package/src/cli/util/evidence-engine.js

@@ -0,0 +1,287 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { computeDOMDiff, hasFeedbackElements as _hasFeedbackElements, hasValidationErrors as _hasValidationErrors } from './dom-diff.js';
+
+/**
+ * Evidence Engine
+ * Captures and bundles evidence for each interaction attempt
+ */
+
+export class EvidenceBundle {
+  constructor(promiseId, expNum, evidencePath) {
+    this.promiseId = promiseId;
+    this.expNum = expNum;
+    this.evidencePath = evidencePath;
+    this.beforeScreenshot = null;
+    this.afterScreenshot = null;
+    this.beforeHTML = null;
+    this.afterHTML = null;
+    this.domDiff = null;
+    this.networkEvents = [];
+    this.networkEventsByTime = new Map(); // For correlation
+    this.consoleErrors = [];
+    this.actionStartTime = null; // When action was executed
+    this.timing = {
+      startedAt: null,
+      endedAt: null,
+    };
+    this.signals = {
+      navigationChanged: false,
+      domChanged: false,
+      feedbackSeen: false,
+      networkActivity: false,
+      consoleErrors: false,
+      meaningfulDomChange: false, // NEW: tracks only meaningful changes
+      correlatedNetworkActivity: false, // NEW: tracks network within action window
+    };
+    this.files = [];
+    this.correlatedRequests = []; // Network requests correlated to this action
+  }
+  
+  /**
+   * Capture before state
+   */
+  async captureBeforeState(page, suffix = '') {
+    try {
+      this.beforeScreenshot = `exp_${this.expNum}_before${suffix}.png`;
+      const screenshotPath = resolve(this.evidencePath, this.beforeScreenshot);
+      await page.screenshot({ path: screenshotPath });
+      this.files.push(this.beforeScreenshot);
+    } catch (e) {
+      this.beforeScreenshot = null;
+    }
+    
+    try {
+      this.beforeHTML = await page.content();
+    } catch (e) {
+      this.beforeHTML = null;
+    }
+  }
+  
+  /**
+   * Capture after state
+   */
+  async captureAfterState(page, suffix = '') {
+    try {
+      this.afterScreenshot = `exp_${this.expNum}_after${suffix}.png`;
+      const screenshotPath = resolve(this.evidencePath, this.afterScreenshot);
+      await page.screenshot({ path: screenshotPath });
+      this.files.push(this.afterScreenshot);
+    } catch (e) {
+      this.afterScreenshot = null;
+    }
+    
+    try {
+      this.afterHTML = await page.content();
+    } catch (e) {
+      this.afterHTML = null;
+    }
+  }
+  
+  /**
+   * Analyze changes between before and after
+   */
+  analyzeChanges(urlBefore, urlAfter) {
+    // Navigation change
+    if (urlBefore && urlAfter && urlBefore !== urlAfter) {
+      this.signals.navigationChanged = true;
+    }
+    
+    // DOM change
+    if (this.beforeHTML && this.afterHTML) {
+      this.domDiff = computeDOMDiff(this.beforeHTML, this.afterHTML);
+      if (this.domDiff.changed) {
+        this.signals.domChanged = true;
+      }
+      
+      // Track meaningful changes separately
+      if (this.domDiff.isMeaningful) {
+        this.signals.meaningfulDomChange = true;
+      }
+      
+      // Check for feedback elements visibility change
+      if (detectNewFeedback(this.beforeHTML, this.afterHTML)) {
+        this.signals.feedbackSeen = true;
+      }
+      
+      // Check for validation error appearance
+      if (detectNewValidationError(this.beforeHTML, this.afterHTML)) {
+        this.signals.feedbackSeen = true;
+      }
+    }
+  }
+  
+  /**
+   * Record network events that occurred during this action
+   */
+  recordNetworkEvent(networkLog) {
+    this.networkEvents.push(networkLog);
+    
+    // Track event time for correlation
+    if (networkLog.startTime) {
+      this.networkEventsByTime.set(networkLog.startTime, networkLog);
+    }
+    
+    if (this.networkEvents.length > 0) {
+      this.signals.networkActivity = true;
+    }
+  }
+  
+  /**
+   * Correlate network events to this action
+   * Captures requests that started within correlation window after action
+   * Window: 0-2500ms after action starts
+   */
+  correlateNetworkRequests() {
+    if (!this.actionStartTime || this.networkEvents.length === 0) {
+      return;
+    }
+    
+    const actionTime = new Date(this.actionStartTime).getTime();
+    const correlationWindow = 2500; // milliseconds
+    
+    for (const event of this.networkEvents) {
+      if (event.startTime) {
+        const eventTime = new Date(event.startTime).getTime();
+        if (eventTime >= actionTime && eventTime <= actionTime + correlationWindow) {
+          this.correlatedRequests.push(event);
+          this.signals.correlatedNetworkActivity = true;
+        }
+      }
+    }
+  }
+  
+  /**
+   * Record console errors
+   */
+  recordConsoleError(error) {
+    this.consoleErrors.push(error);
+    if (this.consoleErrors.length > 0) {
+      this.signals.consoleErrors = true;
+    }
+  }
+  
+  /**
+   * Finalize evidence bundle
+   */
+  finalize(_page) {
+    this.timing.endedAt = new Date().toISOString();
+    
+    // Persist evidence files
+    try {
+      mkdirSync(this.evidencePath, { recursive: true });
+      
+      // Save DOM diff if available
+      if (this.domDiff) {
+        const diffFile = `exp_${this.expNum}_dom_diff.json`;
+        writeFileSync(
+          resolve(this.evidencePath, diffFile),
+          JSON.stringify(this.domDiff, null, 2),
+          'utf-8'
+        );
+        this.files.push(diffFile);
+      }
+      
+      // Save network events if any
+      if (this.networkEvents.length > 0) {
+        const netFile = `exp_${this.expNum}_network.json`;
+        writeFileSync(
+          resolve(this.evidencePath, netFile),
+          JSON.stringify(this.networkEvents, null, 2),
+          'utf-8'
+        );
+        this.files.push(netFile);
+      }
+      
+      // Save console errors if any
+      if (this.consoleErrors.length > 0) {
+        const errFile = `exp_${this.expNum}_console_errors.json`;
+        writeFileSync(
+          resolve(this.evidencePath, errFile),
+          JSON.stringify(this.consoleErrors, null, 2),
+          'utf-8'
+        );
+        this.files.push(errFile);
+      }
+    } catch (e) {
+      // Best effort
+    }
+  }
+  
+  /**
+   * Check if we have meaningful evidence
+   */
+  hasEvidence() {
+    return (
+      this.beforeScreenshot ||
+      this.afterScreenshot ||
+      this.domDiff?.changed ||
+      this.networkEvents.length > 0 ||
+      this.consoleErrors.length > 0 ||
+      Object.values(this.signals).some(v => v === true)
+    );
+  }
+  
+  /**
+   * Summarize signals for observation
+   */
+  getSummary() {
+    return {
+      files: this.files,
+      timing: this.timing,
+      signals: this.signals,
+      hasEvidence: this.hasEvidence(),
+    };
+  }
+}
+
+/**
+ * Create a bundle for a promise
+ */
+export function createEvidenceBundle(promise, expNum, evidencePath) {
+  return new EvidenceBundle(promise.id, expNum, evidencePath);
+}
+
+/**
+ * Detect if new feedback elements appeared
+ */
+function detectNewFeedback(htmlBefore, htmlAfter) {
+  const feedbackPatterns = [
+    'role="alert"',
+    'role="status"',
+    'aria-live="polite"',
+    'aria-live="assertive"',
+    'class="toast"',
+    'class="modal"',
+    'class="dialog"',
+  ];
+  
+  for (const pattern of feedbackPatterns) {
+    if (!htmlBefore.includes(pattern) && htmlAfter.includes(pattern)) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Detect if new validation errors appeared
+ */
+function detectNewValidationError(htmlBefore, htmlAfter) {
+  const errorPatterns = [
+    'aria-invalid="true"',
+    'aria-invalid=\'true\'',
+    'class="error"',
+    'class="invalid"',
+    '[data-error]',
+  ];
+  
+  for (const pattern of errorPatterns) {
+    if (!htmlBefore.includes(pattern) && htmlAfter.includes(pattern)) {
+      return true;
+    }
+  }
+  
+  return false;
+}

package/src/cli/util/expectation-extractor.js

@@ -1,10 +1,12 @@
 import { readdirSync, readFileSync, statSync } from 'fs';
 import { join, relative, resolve } from 'path';
 import { expIdFromHash, compareExpectations } from './idgen.js';
+import { extractPromisesFromAST } from './ast-promise-extractor.js';
 
 /**
  * Static Expectation Extractor
- * Extracts explicit, static expectations from source files
+ * PHASE H2/M2: AST-based promise extraction
+ * Extracts explicit, static expectations from source files using AST parsing
  */
 
 export async function extractExpectations(projectProfile, _srcPath) {
@@ -61,7 +63,16 @@ function getScanPaths(projectProfile, sourceRoot) {
   }
   
   if (framework === 'react-vite' || framework === 'react-cra') {
-    return [resolve(sourceRoot, 'src')];
+    const srcPath = resolve(sourceRoot, 'src');
+    try {
+      if (statSync(srcPath).isDirectory()) {
+        return [srcPath];
+      }
+    } catch (error) {
+      // src doesn't exist - scan root for React files
+    }
+    // Fallback: scan root directory for React files
+    return [sourceRoot];
   }
   
   if (framework === 'static-html') {
@@ -78,7 +89,7 @@ function getScanPaths(projectProfile, sourceRoot) {
     }
   }
   
-  // Unknown framework - scan src if it exists
+  // Unknown framework - scan src if it exists, otherwise scan root
   const srcPath = resolve(sourceRoot, 'src');
   try {
     if (statSync(srcPath).isDirectory()) {
@@ -88,7 +99,8 @@ function getScanPaths(projectProfile, sourceRoot) {
     // src doesn't exist
   }
   
-  return [];
+  // Fallback: scan root directory
+  return [sourceRoot];
 }
 
 /**
@@ -163,9 +175,15 @@ function scanFile(filePath, sourceRoot, skipped) {
     const relPath = relative(sourceRoot, filePath);
     
     if (filePath.endsWith('.html')) {
+      // HTML files: Use regex-based extraction (static HTML fallback)
       const htmlExpectations = extractHtmlExpectations(content, filePath, relPath);
       expectations.push(...htmlExpectations);
     } else {
+      // JS/JSX/TS/TSX files: Use AST-based extraction (PHASE H2)
+      const astPromises = extractPromisesFromAST(content, filePath, relPath);
+      expectations.push(...astPromises);
+      
+      // Legacy regex-based extraction (preserved for navigation/network/state)
       const jsExpectations = extractJsExpectations(content, filePath, relPath, skipped);
       expectations.push(...jsExpectations);
     }
@@ -178,11 +196,12 @@ function scanFile(filePath, sourceRoot, skipped) {
 
 /**
  * Extract expectations from HTML files
+ * PHASE H2: Enhanced with button, form, and validation detection
  */
 function extractHtmlExpectations(content, filePath, relPath) {
   const expectations = [];
   
-  // Extract <a href="/path"> links
+  // Extract <a href="/path"> links (navigation)
   const hrefRegex = /<a\s+[^>]*href=["']([^"']+)["']/gi;
   let match;
   
@@ -208,9 +227,136 @@ function extractHtmlExpectations(content, filePath, relPath) {
     }
   }
   
+  // Extract <button> elements (interaction promise)
+  const buttonRegex = /<button\s+[^>]*>/gi;
+  while ((match = buttonRegex.exec(content)) !== null) {
+    const lineNum = content.substring(0, match.index).split('\n').length;
+    const buttonText = extractTextFromTag(content, match.index, 'button');
+    
+    expectations.push({
+      category: 'button',
+      type: 'interaction',
+      promise: {
+        kind: 'click',
+        value: buttonText || 'button click',
+      },
+      source: {
+        file: relPath,
+        line: lineNum,
+        column: match.index - content.lastIndexOf('\n', match.index),
+      },
+      selector: buttonText ? `button:contains("${buttonText}")` : 'button',
+      action: 'click',
+      expectedOutcome: 'ui-change',
+      confidenceHint: 'low',
+    });
+  }
+  
+  // Extract <form> elements (submission promise)
+  const formRegex = /<form\s+[^>]*>/gi;
+  while ((match = formRegex.exec(content)) !== null) {
+    const lineNum = content.substring(0, match.index).split('\n').length;
+    const formTag = match[0];
+    
+    // Check for action attribute
+    const actionMatch = /action=["']([^"']+)["']/.exec(formTag);
+    const hasAction = actionMatch && actionMatch[1];
+    
+    expectations.push({
+      category: 'form',
+      type: 'interaction',
+      promise: {
+        kind: 'submit',
+        value: hasAction ? `form submit to ${actionMatch[1]}` : 'form submission',
+      },
+      source: {
+        file: relPath,
+        line: lineNum,
+        column: match.index - content.lastIndexOf('\n', match.index),
+      },
+      selector: hasAction ? `form[action="${actionMatch[1]}"]` : 'form',
+      action: 'submit',
+      expectedOutcome: hasAction ? 'navigation' : 'ui-change',
+      confidenceHint: hasAction ? 'medium' : 'low',
+    });
+  }
+  
+  // Extract required input fields (validation promise)
+  const requiredRegex = /<input\s+[^>]*required[^>]*>/gi;
+  while ((match = requiredRegex.exec(content)) !== null) {
+    const lineNum = content.substring(0, match.index).split('\n').length;
+    const inputTag = match[0];
+    
+    // Extract name or id for selector
+    const nameMatch = /name=["']([^"']+)["']/.exec(inputTag);
+    const idMatch = /id=["']([^"']+)["']/.exec(inputTag);
+    const selector = nameMatch ? `input[name="${nameMatch[1]}"]` : 
+                     idMatch ? `input#${idMatch[1]}` : 'input[required]';
+    
+    expectations.push({
+      category: 'validation',
+      type: 'feedback',
+      promise: {
+        kind: 'validation',
+        value: 'required field validation',
+      },
+      source: {
+        file: relPath,
+        line: lineNum,
+        column: match.index - content.lastIndexOf('\n', match.index),
+      },
+      selector,
+      action: 'observe',
+      expectedOutcome: 'feedback',
+      confidenceHint: 'medium',
+    });
+  }
+  
+  // Extract aria-live regions (feedback promise)
+  const ariaLiveRegex = /<[^>]+aria-live=["']([^"']+)["'][^>]*>/gi;
+  while ((match = ariaLiveRegex.exec(content)) !== null) {
+    const lineNum = content.substring(0, match.index).split('\n').length;
+    
+    expectations.push({
+      category: 'feedback',
+      type: 'feedback',
+      promise: {
+        kind: 'ui-feedback',
+        value: 'live region update',
+      },
+      source: {
+        file: relPath,
+        line: lineNum,
+        column: match.index - content.lastIndexOf('\n', match.index),
+      },
+      selector: '[aria-live]',
+      action: 'observe',
+      expectedOutcome: 'feedback',
+      confidenceHint: 'medium',
+    });
+  }
+  
   return expectations;
 }
 
+/**
+ * Extract text content from HTML tag
+ */
+function extractTextFromTag(content, startIndex, tagName) {
+  const closeTagRegex = new RegExp(`</${tagName}>`, 'i');
+  const closeMatch = closeTagRegex.exec(content.substring(startIndex));
+  
+  if (!closeMatch) return '';
+  
+  const endOfOpenTag = content.indexOf('>', startIndex);
+  if (endOfOpenTag === -1) return '';
+  
+  const textContent = content.substring(endOfOpenTag + 1, startIndex + closeMatch.index);
+  
+  // Strip HTML tags and trim
+  return textContent.replace(/<[^>]+>/g, '').trim();
+}
+
 /**
  * Extract expectations from JavaScript/TypeScript files
  */

package/src/cli/util/findings-writer.js

@@ -1,6 +1,7 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
 import { findingIdFromExpectationId } from './idgen.js';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write findings.json artifact with deterministic IDs
@@ -15,6 +16,7 @@ export function writeFindingsJson(runDir, findingsData) {
   }));
   
   const payload = {
+    contractVersion: ARTIFACT_REGISTRY.findings.contractVersion,
     findings: findingsWithIds,
     total: findingsData.stats?.total || 0,
     stats: {
@@ -26,6 +28,7 @@ export function writeFindingsJson(runDir, findingsData) {
       informational: findingsData.stats?.informational || 0,
     },
     detectedAt: findingsData.detectedAt || new Date().toISOString(),
+    enforcement: findingsData.enforcement || null,
   };
   
   atomicWriteJson(findingsPath, payload);