@veraxhq/verax 0.1.0 → 0.2.1

package/src/cli/util/events.js

@@ -0,0 +1,110 @@
+/**
+ * Event emitter for run progress
+ */
+export class RunEventEmitter {
+  constructor() {
+    this.events = [];
+    this.listeners = [];
+    this.heartbeatInterval = null;
+    this.heartbeatStartTime = null;
+    this.currentPhase = null;
+    this.heartbeatIntervalMs = 2500; // 2.5 seconds
+  }
+  
+  on(event, handler) {
+    this.listeners.push({ event, handler });
+  }
+  
+  emit(type, data = {}) {
+    const event = {
+      type,
+      timestamp: new Date().toISOString(),
+      ...data,
+    };
+    
+    this.events.push(event);
+    
+    // Call registered listeners
+    this.listeners.forEach(({ event: listenEvent, handler }) => {
+      if (listenEvent === type || listenEvent === '*') {
+        handler(event);
+      }
+    });
+  }
+  
+  getEvents() {
+    return this.events;
+  }
+
+  /**
+   * Start heartbeat for a phase
+   * @param {string} phase - Current phase name
+   * @param {boolean} jsonMode - Whether in JSON output mode
+   */
+  startHeartbeat(phase, jsonMode = false) {
+    this.currentPhase = phase;
+    this.heartbeatStartTime = Date.now();
+    
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+    }
+
+    this.heartbeatInterval = setInterval(() => {
+      const elapsedMs = Date.now() - this.heartbeatStartTime;
+      const elapsedSeconds = Math.floor(elapsedMs / 1000);
+      
+      const heartbeatEvent = {
+        type: 'heartbeat',
+        phase: this.currentPhase,
+        elapsedMs,
+        elapsedSeconds,
+        timestamp: new Date().toISOString(),
+      };
+
+      // Add to events array
+      this.events.push(heartbeatEvent);
+
+      // Emit to listeners
+      this.listeners.forEach(({ event: listenEvent, handler }) => {
+        if (listenEvent === 'heartbeat' || listenEvent === '*') {
+          if (jsonMode) {
+            // In JSON mode, emit as JSON line
+            handler(heartbeatEvent);
+          } else {
+            // Human-readable format: single line, overwrite-friendly
+            process.stdout.write(`\r…still working (phase=${this.currentPhase}, elapsed=${elapsedSeconds}s)`);
+          }
+        }
+      });
+    }, this.heartbeatIntervalMs);
+    
+    // CRITICAL: Unref the interval so it doesn't keep the process alive
+    // This allows tests to exit cleanly even if stopHeartbeat() is not called
+    if (this.heartbeatInterval && this.heartbeatInterval.unref) {
+      this.heartbeatInterval.unref();
+    }
+  }
+
+  /**
+   * Stop heartbeat
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+    // Clear the progress line in human mode
+    process.stdout.write('\r' + ' '.repeat(60) + '\r');
+    this.currentPhase = null;
+    this.heartbeatStartTime = null;
+  }
+
+  /**
+   * Update current phase for heartbeat
+   * @param {string} phase - New phase name
+   */
+  updatePhase(phase) {
+    this.currentPhase = phase;
+    this.heartbeatStartTime = Date.now();
+  }
+}

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

@@ -0,0 +1,388 @@
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { expIdFromHash, compareExpectations } from './idgen.js';
+
+/**
+ * Static Expectation Extractor
+ * Extracts explicit, static expectations from source files
+ */
+
+export async function extractExpectations(projectProfile, _srcPath) {
+  const expectations = [];
+  const skipped = {
+    dynamic: 0,
+    computed: 0,
+    external: 0,
+    parseError: 0,
+    other: 0,
+  };
+  
+  const sourceRoot = resolve(projectProfile.sourceRoot);
+  const scanPaths = getScanPaths(projectProfile, sourceRoot);
+  
+  for (const scanPath of scanPaths) {
+    const fileExpectations = await scanDirectory(scanPath, sourceRoot, skipped);
+    expectations.push(...fileExpectations);
+  }
+  
+  // Sort expectations deterministically by file, line, column, kind, value
+  expectations.sort(compareExpectations);
+  
+  // Generate deterministic IDs based on content (order-independent)
+  expectations.forEach((exp) => {
+    exp.id = expIdFromHash(
+      exp.source.file,
+      exp.source.line,
+      exp.source.column,
+      exp.promise.kind,
+      exp.promise.value
+    );
+  });
+  
+  return {
+    expectations,
+    skipped,
+  };
+}
+
+/**
+ * Get directories to scan based on framework
+ */
+function getScanPaths(projectProfile, sourceRoot) {
+  const { framework, router } = projectProfile;
+  
+  if (framework === 'nextjs') {
+    if (router === 'app') {
+      return [resolve(sourceRoot, 'app')];
+    } else if (router === 'pages') {
+      return [resolve(sourceRoot, 'pages')];
+    }
+    return [];
+  }
+  
+  if (framework === 'react-vite' || framework === 'react-cra') {
+    return [resolve(sourceRoot, 'src')];
+  }
+  
+  if (framework === 'static-html') {
+    return [sourceRoot];
+  }
+  
+  // Unknown framework or no framework detected - check if it's a static HTML project
+  // (This handles cases where framework detection failed but HTML files exist)
+  if (framework === 'unknown') {
+    const htmlFiles = readdirSync(sourceRoot, { withFileTypes: true })
+      .filter(e => e.isFile() && e.name.endsWith('.html'));
+    if (htmlFiles.length > 0) {
+      return [sourceRoot];
+    }
+  }
+  
+  // Unknown framework - scan src if it exists
+  const srcPath = resolve(sourceRoot, 'src');
+  try {
+    if (statSync(srcPath).isDirectory()) {
+      return [srcPath];
+    }
+  } catch (error) {
+    // src doesn't exist
+  }
+  
+  return [];
+}
+
+/**
+ * Recursively scan directory for expectations
+ */
+async function scanDirectory(dirPath, sourceRoot, skipped) {
+  const expectations = [];
+  
+  try {
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      // Skip node_modules, .next, dist, build, etc.
+      if (shouldSkipDirectory(entry.name)) {
+        continue;
+      }
+      
+      const fullPath = join(dirPath, entry.name);
+      
+      if (entry.isDirectory()) {
+        const dirExpectations = await scanDirectory(fullPath, sourceRoot, skipped);
+        expectations.push(...dirExpectations);
+      } else if (entry.isFile() && shouldScanFile(entry.name)) {
+        const fileExpectations = scanFile(fullPath, sourceRoot, skipped);
+        expectations.push(...fileExpectations);
+      }
+    }
+  } catch (error) {
+    // Silently skip directories we can't read
+  }
+  
+  return expectations;
+}
+
+/**
+ * Check if directory should be skipped
+ */
+function shouldSkipDirectory(name) {
+  const skipPatterns = [
+    'node_modules',
+    '.next',
+    'dist',
+    'build',
+    '.git',
+    '.venv',
+    '__pycache__',
+    '.env',
+    'public',
+    '.cache',
+    'coverage',
+  ];
+  
+  return skipPatterns.includes(name) || name.startsWith('.');
+}
+
+/**
+ * Check if file should be scanned
+ */
+function shouldScanFile(name) {
+  const extensions = ['.js', '.jsx', '.ts', '.tsx', '.html', '.mjs'];
+  return extensions.some(ext => name.endsWith(ext));
+}
+
+/**
+ * Scan a single file for expectations
+ */
+function scanFile(filePath, sourceRoot, skipped) {
+  const expectations = [];
+  
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const relPath = relative(sourceRoot, filePath);
+    
+    if (filePath.endsWith('.html')) {
+      const htmlExpectations = extractHtmlExpectations(content, filePath, relPath);
+      expectations.push(...htmlExpectations);
+    } else {
+      const jsExpectations = extractJsExpectations(content, filePath, relPath, skipped);
+      expectations.push(...jsExpectations);
+    }
+  } catch (error) {
+    skipped.parseError++;
+  }
+  
+  return expectations;
+}
+
+/**
+ * Extract expectations from HTML files
+ */
+function extractHtmlExpectations(content, filePath, relPath) {
+  const expectations = [];
+  
+  // Extract <a href="/path"> links
+  const hrefRegex = /<a\s+[^>]*href=["']([^"']+)["']/gi;
+  let match;
+  
+  while ((match = hrefRegex.exec(content)) !== null) {
+    const href = match[1];
+    const lineNum = content.substring(0, match.index).split('\n').length;
+    
+    // Skip dynamic/absolute URLs
+    if (!href.startsWith('#') && !href.startsWith('http') && !href.includes('${')) {
+      expectations.push({
+        type: 'navigation',
+        promise: {
+          kind: 'navigate',
+          value: href,
+        },
+        source: {
+          file: relPath,
+          line: lineNum,
+          column: match.index - content.lastIndexOf('\n', match.index),
+        },
+        confidence: 1.0,
+      });
+    }
+  }
+  
+  return expectations;
+}
+
+/**
+ * Extract expectations from JavaScript/TypeScript files
+ */
+function extractJsExpectations(content, filePath, relPath, skipped) {
+  const expectations = [];
+  const lines = content.split('\n');
+  
+  lines.forEach((line, lineIdx) => {
+    const lineNum = lineIdx + 1;
+    
+    // Skip comments
+    if (line.trim().startsWith('//') || line.trim().startsWith('*')) {
+      return;
+    }
+    
+    // Extract Next.js <Link href="/path">
+    const linkRegex = /<Link\s+[^>]*href=["']([^"']+)["']/g;
+    let match;
+    while ((match = linkRegex.exec(line)) !== null) {
+      const href = match[1];
+      
+      // Skip dynamic hrefs
+      if (!href.includes('${') && !href.includes('+') && !href.includes('`')) {
+        expectations.push({
+          type: 'navigation',
+          promise: {
+            kind: 'navigate',
+            value: href,
+          },
+          source: {
+            file: relPath,
+            line: lineNum,
+            column: match.index,
+          },
+          confidence: 1.0,
+        });
+      } else {
+        skipped.dynamic++;
+      }
+    }
+    
+    // Extract router.push("/path")
+    const routerPushRegex = /router\.push\(["']([^"']+)["']\)/g;
+    while ((match = routerPushRegex.exec(line)) !== null) {
+      const path = match[1];
+      
+      if (!path.includes('${') && !path.includes('+') && !path.includes('`')) {
+        expectations.push({
+          type: 'navigation',
+          promise: {
+            kind: 'navigate',
+            value: path,
+          },
+          source: {
+            file: relPath,
+            line: lineNum,
+            column: match.index,
+          },
+          confidence: 1.0,
+        });
+      } else {
+        skipped.dynamic++;
+      }
+    }
+    
+    // Extract fetch("https://...")
+    const fetchRegex = /fetch\(["']([^"']+)["']\)/g;
+    while ((match = fetchRegex.exec(line)) !== null) {
+      const url = match[1];
+      
+      // Only extract absolute URLs (https://)
+      if (url.startsWith('http://') || url.startsWith('https://')) {
+        expectations.push({
+          type: 'network',
+          promise: {
+            kind: 'request',
+            value: url,
+          },
+          source: {
+            file: relPath,
+            line: lineNum,
+            column: match.index,
+          },
+          confidence: 1.0,
+        });
+      } else if (!url.includes('${') && !url.includes('+') && !url.includes('`')) {
+        skipped.external++;
+      } else {
+        skipped.dynamic++;
+      }
+    }
+    
+    // Extract axios.get/post("https://...")
+    const axiosRegex = /axios\.(get|post|put|delete|patch)\(["']([^"']+)["']\)/g;
+    while ((match = axiosRegex.exec(line)) !== null) {
+      const url = match[2];
+      
+      if (url.startsWith('http://') || url.startsWith('https://')) {
+        expectations.push({
+          type: 'network',
+          promise: {
+            kind: 'request',
+            value: url,
+          },
+          source: {
+            file: relPath,
+            line: lineNum,
+            column: match.index,
+          },
+          confidence: 1.0,
+        });
+      } else if (!url.includes('${') && !url.includes('+') && !url.includes('`')) {
+        skipped.external++;
+      } else {
+        skipped.dynamic++;
+      }
+    }
+    
+    // Extract useState setters
+    const useStateRegex = /useState\([^)]*\)/g;
+    if ((match = useStateRegex.exec(line)) !== null) {
+      expectations.push({
+        type: 'state',
+        promise: {
+          kind: 'state_mutation',
+          value: 'state management',
+        },
+        source: {
+          file: relPath,
+          line: lineNum,
+          column: match.index,
+        },
+        confidence: 0.8,
+      });
+    }
+    
+    // Extract Redux dispatch calls
+    const dispatchRegex = /dispatch\(\{/g;
+    if ((match = dispatchRegex.exec(line)) !== null) {
+      expectations.push({
+        type: 'state',
+        promise: {
+          kind: 'state_mutation',
+          value: 'state management',
+        },
+        source: {
+          file: relPath,
+          line: lineNum,
+          column: match.index,
+        },
+        confidence: 0.8,
+      });
+    }
+    
+    // Extract Zustand set() calls
+    const zustandRegex = /set\(\{/g;
+    if ((match = zustandRegex.exec(line)) !== null && line.includes('zustand') || line.includes('store')) {
+      expectations.push({
+        type: 'state',
+        promise: {
+          kind: 'state_mutation',
+          value: 'state management',
+        },
+        source: {
+          file: relPath,
+          line: lineNum,
+          column: match.index,
+        },
+        confidence: 0.8,
+      });
+    }
+  });
+  
+  return expectations;
+}

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

@@ -0,0 +1,32 @@
+import { atomicWriteJson } from './atomic-write.js';
+import { resolve } from 'path';
+import { findingIdFromExpectationId } from './idgen.js';
+
+/**
+ * Write findings.json artifact with deterministic IDs
+ */
+export function writeFindingsJson(runDir, findingsData) {
+  const findingsPath = resolve(runDir, 'findings.json');
+  
+  // Add deterministic finding IDs based on expectation IDs
+  const findingsWithIds = (findingsData.findings || []).map(finding => ({
+    ...finding,
+    findingId: findingIdFromExpectationId(finding.id),
+  }));
+  
+  const payload = {
+    findings: findingsWithIds,
+    total: findingsData.stats?.total || 0,
+    stats: {
+      total: findingsData.stats?.total || 0,
+      silentFailures: findingsData.stats?.silentFailures || 0,
+      observed: findingsData.stats?.observed || 0,
+      coverageGaps: findingsData.stats?.coverageGaps || 0,
+      unproven: findingsData.stats?.unproven || 0,
+      informational: findingsData.stats?.informational || 0,
+    },
+    detectedAt: findingsData.detectedAt || new Date().toISOString(),
+  };
+  
+  atomicWriteJson(findingsPath, payload);
+}

package/src/cli/util/idgen.js

@@ -0,0 +1,87 @@
+import crypto from 'crypto';
+
+/**
+ * Deterministic ID Generation (Phase 8.3)
+ * Generate stable, hash-based IDs independent of discovery order.
+ */
+
+/**
+ * Generate deterministic expectation ID from stable attributes
+ * ID format: exp_<6-character-hex-hash>
+ * Input order-independent: hash only depends on content, not discovery order
+ * 
+ * @param {string} file - Source file path (relative)
+ * @param {number} line - Line number
+ * @param {number} column - Column number
+ * @param {string} kind - Promise kind (e.g., 'navigate', 'click')
+ * @param {string} value - Promise value (e.g., '/products', 'button.id')
+ * @returns {string} Deterministic ID like 'exp_a1b2c3'
+ */
+export function expIdFromHash(file, line, column, kind, value) {
+  // Create stable hash input: normalize file path and combine all attributes
+  const normalizedFile = (file || '')
+    .replace(/\\/g, '/') // Convert Windows backslashes to forward slashes
+    .toLowerCase();
+  
+  const hashInput = JSON.stringify({
+    file: normalizedFile,
+    line: Number(line) || 0,
+    column: Number(column) || 0,
+    kind: String(kind || '').toLowerCase(),
+    value: String(value || ''),
+  });
+  
+  // Generate deterministic hash
+  const hash = crypto.createHash('sha256').update(hashInput).digest('hex');
+  
+  // Use first 6 characters for brevity while maintaining low collision risk
+  const hashSuffix = hash.substring(0, 6);
+  
+  return `exp_${hashSuffix}`;
+}
+
+/**
+ * Generate deterministic finding ID from expectation ID
+ * ID format: finding_<expectationId>
+ * 
+ * @param {string} expectationId - The parent expectation ID
+ * @returns {string} Finding ID like 'finding_exp_a1b2c3'
+ */
+export function findingIdFromExpectationId(expectationId) {
+  return `finding_${expectationId}`;
+}
+
+/**
+ * Comparator for stable expectation ordering
+ * Sort by: file, line, column, kind, value
+ * Returns comparable value suitable for .sort()
+ */
+export function compareExpectations(a, b) {
+  const aFile = (a.source?.file || '').toLowerCase();
+  const bFile = (b.source?.file || '').toLowerCase();
+  if (aFile !== bFile) {
+    return aFile.localeCompare(bFile);
+  }
+  
+  const aLine = a.source?.line || 0;
+  const bLine = b.source?.line || 0;
+  if (aLine !== bLine) {
+    return aLine - bLine;
+  }
+  
+  const aCol = a.source?.column || 0;
+  const bCol = b.source?.column || 0;
+  if (aCol !== bCol) {
+    return aCol - bCol;
+  }
+  
+  const aKind = (a.promise?.kind || '').toLowerCase();
+  const bKind = (b.promise?.kind || '').toLowerCase();
+  if (aKind !== bKind) {
+    return aKind.localeCompare(bKind);
+  }
+  
+  const aValue = String(a.promise?.value || '').toLowerCase();
+  const bValue = String(b.promise?.value || '').toLowerCase();
+  return aValue.localeCompare(bValue);
+}

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

@@ -0,0 +1,39 @@
+import { resolve } from 'path';
+import { atomicWriteJson } from './atomic-write.js';
+import { compareExpectations } from './idgen.js';
+
+/**
+ * Write learn.json artifact
+ * Maintains deterministic ordering for stable output
+ */
+export function writeLearnJson(runPaths, expectations, skipped) {
+  const learnJsonPath = resolve(runPaths.baseDir, 'learn.json');
+  
+  // Sort expectations deterministically for stable output
+  const sortedExpectations = [...expectations].sort(compareExpectations);
+  
+  const learnJson = {
+    expectations: sortedExpectations,
+    stats: {
+      totalExpectations: sortedExpectations.length,
+      byType: {
+        navigation: sortedExpectations.filter(e => e.type === 'navigation').length,
+        network: sortedExpectations.filter(e => e.type === 'network').length,
+        state: sortedExpectations.filter(e => e.type === 'state').length,
+      },
+    },
+    skipped: {
+      dynamic: skipped.dynamic,
+      computed: skipped.computed,
+      external: skipped.external,
+      parseError: skipped.parseError,
+      other: skipped.other,
+      total: Object.values(skipped).reduce((a, b) => a + b, 0),
+    },
+    learnedAt: new Date().toISOString(),
+  };
+  
+  atomicWriteJson(learnJsonPath, learnJson);
+  
+  return learnJsonPath;
+}