@veraxhq/verax 0.2.0 → 0.3.0

package/src/cli/util/runtime-budget.js

@@ -0,0 +1,147 @@
+/**
+ * Runtime Budget Model
+ * Computes timeouts based on project size, execution mode, and framework
+ * Ensures deterministic, bounded execution times
+ */
+
+/**
+ * @typedef {Object} RuntimeBudgetOptions
+ * @property {number} [expectationsCount=0] - Number of expectations to process
+ * @property {string} [mode='default'] - Execution mode: 'default', 'run', 'ci'
+ * @property {string} [framework='unknown'] - Detected framework (optional)
+ * @property {number|null} [fileCount=null] - Number of files scanned (optional, fallback to expectationsCount)
+ */
+
+/**
+ * Compute runtime budgets for a VERAX run
+ * @param {RuntimeBudgetOptions} [options={}] - Budget computation options
+ * @returns {Object} Budget object with phase timeouts
+ */
+export function computeRuntimeBudget(options = {}) {
+  const {
+    expectationsCount = 0,
+    mode = 'default',
+    framework = 'unknown',
+    fileCount = null,
+  } = options;
+
+  // TEST MODE OVERRIDE: Fixed deterministic budgets for integration tests
+  if (process.env.VERAX_TEST_MODE === '1') {
+    return {
+      totalMaxMs: 30000,          // Hard cap per run
+      learnMaxMs: 5000,           // Keep learn bounded
+      observeMaxMs: 20000,        // Deterministic observe budget
+      detectMaxMs: 5000,          // Bounded detect
+      perExpectationMaxMs: 5000,  // Deterministic per-expectation guard
+      mode: 'test',
+      framework,
+      expectationsCount,
+      projectSize: fileCount !== null ? fileCount : expectationsCount,
+      frameworkMultiplier: 1.0,
+    };
+  }
+
+  // Use file count if available, otherwise use expectations count as proxy
+  const projectSize = fileCount !== null ? fileCount : expectationsCount;
+
+  // Base timeouts (milliseconds)
+  // Small project: < 10 expectations/files
+  // Medium project: 10-50 expectations/files
+  // Large project: > 50 expectations/files
+
+  // Learn phase: file scanning and AST parsing
+  const learnBaseMs = mode === 'ci' ? 30000 : 60000; // CI: 30s, default: 60s
+  const learnPerFileMs = 50; // 50ms per file
+  const learnMaxMs = mode === 'ci' ? 120000 : 300000; // CI: 2min, default: 5min
+
+  // Observe phase: browser automation
+  const observeBaseMs = mode === 'ci' ? 60000 : 120000; // CI: 1min, default: 2min
+  const observePerExpectationMs = mode === 'ci' ? 2000 : 5000; // CI: 2s, default: 5s per expectation
+  const observeMaxMs = mode === 'ci' ? 600000 : 1800000; // CI: 10min, default: 30min
+
+  // Detect phase: analysis and comparison
+  const detectBaseMs = mode === 'ci' ? 15000 : 30000; // CI: 15s, default: 30s
+  const detectPerExpectationMs = 100; // 100ms per expectation
+  const detectMaxMs = mode === 'ci' ? 120000 : 300000; // CI: 2min, default: 5min
+
+  // Per-expectation timeout during observe phase
+  const perExpectationBaseMs = mode === 'ci' ? 10000 : 30000; // CI: 10s, default: 30s
+  const perExpectationMaxMs = 120000; // 2min max per expectation
+
+  // Framework weighting (some frameworks may need more time)
+  let frameworkMultiplier = 1.0;
+  if (framework === 'nextjs' || framework === 'remix') {
+    frameworkMultiplier = 1.2; // SSR frameworks may need slightly more time
+  } else if (framework === 'react' || framework === 'vue') {
+    frameworkMultiplier = 1.1; // SPA frameworks
+  }
+
+  // Compute phase budgets
+  const computedLearnMaxMs = Math.min(
+    learnBaseMs + (projectSize * learnPerFileMs * frameworkMultiplier),
+    learnMaxMs
+  );
+
+  const computedObserveMaxMs = Math.min(
+    observeBaseMs + (expectationsCount * observePerExpectationMs * frameworkMultiplier),
+    observeMaxMs
+  );
+
+  const computedDetectMaxMs = Math.min(
+    detectBaseMs + (expectationsCount * detectPerExpectationMs * frameworkMultiplier),
+    detectMaxMs
+  );
+
+  const computedPerExpectationMaxMs = Math.min(
+    perExpectationBaseMs * frameworkMultiplier,
+    perExpectationMaxMs
+  );
+
+  // Global watchdog timeout (must be >= sum of all phases + buffer)
+  // Add 30s buffer for finalization
+  const totalMaxMs = Math.max(
+    computedLearnMaxMs + computedObserveMaxMs + computedDetectMaxMs + 30000,
+    mode === 'ci' ? 900000 : 2400000 // CI: 15min minimum, default: 40min minimum
+  );
+
+  // Cap global timeout
+  const totalMaxMsCap = mode === 'ci' ? 1800000 : 3600000; // CI: 30min, default: 60min
+  const finalTotalMaxMs = Math.min(totalMaxMs, totalMaxMsCap);
+
+  // Ensure minimums are met
+  const finalLearnMaxMs = Math.max(computedLearnMaxMs, 10000); // At least 10s
+  const finalObserveMaxMs = Math.max(computedObserveMaxMs, 30000); // At least 30s
+  const finalDetectMaxMs = Math.max(computedDetectMaxMs, 5000); // At least 5s
+  const finalPerExpectationMaxMs = Math.max(computedPerExpectationMaxMs, 5000); // At least 5s
+
+  return {
+    totalMaxMs: finalTotalMaxMs,
+    learnMaxMs: finalLearnMaxMs,
+    observeMaxMs: finalObserveMaxMs,
+    detectMaxMs: finalDetectMaxMs,
+    perExpectationMaxMs: finalPerExpectationMaxMs,
+    mode,
+    framework,
+    expectationsCount,
+    projectSize,
+  };
+}
+
+/**
+ * Create a timeout wrapper that rejects after specified milliseconds
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @param {Promise} promise - Promise to wrap
+ * @param {string} phase - Phase name for error messages
+ * @returns {Promise} Promise that rejects on timeout
+ */
+export function withTimeout(timeoutMs, promise, phase = 'unknown') {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Phase timeout: ${phase} exceeded ${timeoutMs}ms`));
+      }, timeoutMs);
+    }),
+  ]);
+}
+

package/src/cli/util/source-requirement.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, statSync } from 'fs';
+import { extname, join, resolve } from 'path';
+import { DataError } from './errors.js';
+import { getSourceCodeRequirementBanner } from '../../verax/core/product-definition.js';
+
+const CODE_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.html']);
+
+function safeReaddir(dirPath) {
+  try {
+    return readdirSync(dirPath);
+  } catch {
+    return [];
+  }
+}
+
+function directoryHasCode(dirPath) {
+  const entries = safeReaddir(dirPath);
+  for (const entry of entries) {
+    const fullPath = join(dirPath, entry);
+    let stats;
+    try {
+      stats = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stats.isFile() && CODE_EXTS.has(extname(entry).toLowerCase())) {
+      return true;
+    }
+
+    if (stats.isDirectory() && (entry === 'src' || entry === 'app')) {
+      const nested = safeReaddir(fullPath).slice(0, 50);
+      if (nested.some((name) => CODE_EXTS.has(extname(name).toLowerCase()))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function assertHasLocalSource(srcPath) {
+  const resolved = resolve(srcPath);
+  const hasPackageJson = existsSync(join(resolved, 'package.json'));
+  const hasIndexHtml = existsSync(join(resolved, 'index.html'));
+  const hasCodeFiles = directoryHasCode(resolved);
+
+  if (!hasPackageJson && !hasIndexHtml && !hasCodeFiles) {
+    const banner = getSourceCodeRequirementBanner();
+    throw new DataError(
+      `${banner} Provide --src pointing to your repository so VERAX can analyze expectations. See docs/README.md for the canonical product contract.`
+    );
+  }
+
+  return { hasPackageJson, hasIndexHtml, hasCodeFiles };
+}

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

@@ -1,5 +1,4 @@
 import { atomicWriteJson } from './atomic-write.js';
-import { resolve } from 'path';
 
 /**
  * Write summary.json with deterministic digest
@@ -8,6 +7,7 @@ import { resolve } from 'path';
  */
 export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
   const payload = {
+    contractVersion: 1,
     runId: summaryData.runId,
     status: summaryData.status,
     startedAt: summaryData.startedAt,
@@ -15,6 +15,18 @@ export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
     command: summaryData.command,
     url: summaryData.url,
     notes: summaryData.notes,
+    metrics: summaryData.metrics || {
+      learnMs: stats.learnMs || 0,
+      observeMs: stats.observeMs || 0,
+      detectMs: stats.detectMs || 0,
+      totalMs: stats.totalMs || 0,
+    },
+    findingsCounts: summaryData.findingsCounts || {
+      HIGH: stats.HIGH || 0,
+      MEDIUM: stats.MEDIUM || 0,
+      LOW: stats.LOW || 0,
+      UNKNOWN: stats.UNKNOWN || 0,
+    },
     
     // Stable digest that should be identical across repeated runs on same input
     digest: {

package/src/cli/util/svelte-navigation-detector.js

@@ -0,0 +1,163 @@
+/**
+ * PHASE 20 — Svelte Navigation Detector
+ * 
+ * Detects navigation promises in Svelte applications:
+ * - <a href="/path"> links
+ * - goto() calls from SvelteKit
+ * - programmatic navigation
+ */
+
+import { extractSvelteSFC, extractTemplateBindings, mapTemplateHandlersToScript } from './svelte-sfc-extractor.js';
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+
+/**
+ * Detect navigation promises in Svelte SFC
+ * 
+ * @param {string} filePath - Path to .svelte file
+ * @param {string} content - Full file content
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array} Array of navigation expectations
+ */
+export function detectSvelteNavigation(filePath, content, projectRoot) {
+  const expectations = [];
+  
+  try {
+    const sfc = extractSvelteSFC(content);
+    const { scriptBlocks, markup } = sfc;
+    
+    // Extract navigation from markup (links)
+    if (markup && markup.content) {
+      const linkRegex = /<a\s+[^>]*href=["']([^"']+)["'][^>]*>/gi;
+      let linkMatch;
+      while ((linkMatch = linkRegex.exec(markup.content)) !== null) {
+        const href = linkMatch[1];
+        // Skip external links and hash-only links
+        if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('#')) {
+          continue;
+        }
+        
+        const beforeMatch = markup.content.substring(0, linkMatch.index);
+        const line = markup.startLine + (beforeMatch.match(/\n/g) || []).length;
+        
+        expectations.push({
+          type: 'navigation',
+          target: href,
+          context: 'markup',
+          sourceRef: {
+            file: filePath,
+            line,
+            snippet: linkMatch[0],
+          },
+          proof: 'PROVEN_EXPECTATION',
+          metadata: {
+            navigationType: 'link',
+          },
+        });
+      }
+    }
+    
+    // Extract navigation from script blocks (goto, navigate, etc.)
+    for (const scriptBlock of scriptBlocks) {
+      if (!scriptBlock.content) continue;
+      
+      try {
+        const ast = parse(scriptBlock.content, {
+          sourceType: 'module',
+          plugins: ['typescript', 'jsx'],
+        });
+        
+        traverse.default(ast, {
+          CallExpression(path) {
+            const { node } = path;
+            
+            // Detect goto() calls (SvelteKit)
+            if (
+              node.callee.type === 'Identifier' &&
+              node.callee.name === 'goto' &&
+              node.arguments.length > 0
+            ) {
+              const arg = node.arguments[0];
+              let target = null;
+              
+              if (arg.type === 'StringLiteral') {
+                target = arg.value;
+              } else if (arg.type === 'TemplateLiteral' && arg.quasis.length === 1) {
+                target = arg.quasis[0].value.raw;
+              }
+              
+              if (target && !target.startsWith('http://') && !target.startsWith('https://') && !target.startsWith('#')) {
+                const location = node.loc;
+                const line = scriptBlock.startLine + (location ? location.start.line - 1 : 0);
+                
+                expectations.push({
+                  type: 'navigation',
+                  target,
+                  context: 'goto',
+                  sourceRef: {
+                    file: filePath,
+                    line,
+                    snippet: scriptBlock.content.substring(
+                      node.start - (ast.program.body[0]?.start || 0),
+                      node.end - (ast.program.body[0]?.start || 0)
+                    ),
+                  },
+                  proof: arg.type === 'StringLiteral' ? 'PROVEN_EXPECTATION' : 'LIKELY_EXPECTATION',
+                  metadata: {
+                    navigationType: 'goto',
+                  },
+                });
+              }
+            }
+            
+            // Detect navigate() calls (if imported)
+            if (
+              node.callee.type === 'MemberExpression' &&
+              node.callee.property.name === 'navigate' &&
+              node.arguments.length > 0
+            ) {
+              const arg = node.arguments[0];
+              let target = null;
+              
+              if (arg.type === 'StringLiteral') {
+                target = arg.value;
+              } else if (arg.type === 'TemplateLiteral' && arg.quasis.length === 1) {
+                target = arg.quasis[0].value.raw;
+              }
+              
+              if (target && !target.startsWith('http://') && !target.startsWith('https://') && !target.startsWith('#')) {
+                const location = node.loc;
+                const line = scriptBlock.startLine + (location ? location.start.line - 1 : 0);
+                
+                expectations.push({
+                  type: 'navigation',
+                  target,
+                  context: 'navigate',
+                  sourceRef: {
+                    file: filePath,
+                    line,
+                    snippet: scriptBlock.content.substring(
+                      node.start - (ast.program.body[0]?.start || 0),
+                      node.end - (ast.program.body[0]?.start || 0)
+                    ),
+                  },
+                  proof: arg.type === 'StringLiteral' ? 'PROVEN_EXPECTATION' : 'LIKELY_EXPECTATION',
+                  metadata: {
+                    navigationType: 'navigate',
+                  },
+                });
+              }
+            }
+          },
+        });
+      } catch (parseError) {
+        // Skip if parsing fails
+      }
+    }
+  } catch (error) {
+    // Skip if extraction fails
+  }
+  
+  return expectations;
+}
+

package/src/cli/util/svelte-network-detector.js

@@ -0,0 +1,80 @@
+/**
+ * PHASE 20 — Svelte Network Detector
+ * 
+ * Detects network calls (fetch, axios) in Svelte component handlers and lifecycle functions.
+ * Reuses AST network detector but ensures it works with Svelte SFC script blocks.
+ */
+
+import { extractSvelteSFC, extractTemplateBindings, mapTemplateHandlersToScript } from './svelte-sfc-extractor.js';
+import { detectNetworkCallsAST } from './ast-network-detector.js';
+import { relative } from 'path';
+
+/**
+ * Detect network promises in Svelte SFC
+ * 
+ * @param {string} filePath - Path to .svelte file
+ * @param {string} content - Full file content
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array} Array of network expectations
+ */
+export function detectSvelteNetwork(filePath, content, projectRoot) {
+  const expectations = [];
+  
+  try {
+    const sfc = extractSvelteSFC(content);
+    const { scriptBlocks, markup } = sfc;
+    
+    // Extract event handlers from markup to identify UI-bound handlers
+    const templateBindings = markup ? extractTemplateBindings(markup.content) : { eventHandlers: [] };
+    const mappedHandlers = scriptBlocks.length > 0 && templateBindings.eventHandlers.length > 0
+      ? mapTemplateHandlersToScript(templateBindings.eventHandlers, scriptBlocks[0].content)
+      : [];
+    
+    const uiBoundHandlers = new Set(mappedHandlers.map(h => h.handler));
+    
+    // Process each script block
+    for (const scriptBlock of scriptBlocks) {
+      if (!scriptBlock.content) continue;
+      
+      // Use AST network detector on script content
+      const networkCalls = detectNetworkCallsAST(scriptBlock.content, filePath, relative(projectRoot, filePath));
+      
+      // Filter and enhance network calls
+      for (const networkCall of networkCalls) {
+        // Check if this is in a UI-bound handler
+        const isUIBound = networkCall.context && uiBoundHandlers.has(networkCall.context);
+        
+        // Skip analytics-only calls (filtered by guardrails later)
+        if (networkCall.target && (
+          networkCall.target.includes('/api/analytics') ||
+          networkCall.target.includes('/api/track') ||
+          networkCall.target.includes('/api/beacon')
+        )) {
+          continue;
+        }
+        
+        expectations.push({
+          type: 'network',
+          target: networkCall.target,
+          method: networkCall.method || 'GET',
+          context: networkCall.context || 'component',
+          sourceRef: {
+            file: filePath,
+            line: networkCall.line || scriptBlock.startLine,
+            snippet: networkCall.snippet || '',
+          },
+          proof: networkCall.proof || 'LIKELY_EXPECTATION',
+          metadata: {
+            isUIBound,
+            handlerContext: networkCall.context,
+          },
+        });
+      }
+    }
+  } catch (error) {
+    // Skip if extraction fails
+  }
+  
+  return expectations;
+}
+

package/src/cli/util/svelte-sfc-extractor.js

@@ -0,0 +1,147 @@
+/**
+ * PHASE 20 — Svelte SFC (Single File Component) Extractor
+ * 
+ * Extracts <script>, <script context="module">, and markup content from .svelte files.
+ * Deterministic and robust (no external runtime execution).
+ */
+
+/**
+ * PHASE 20: Extract Svelte SFC blocks
+ * 
+ * @param {string} content - Full .svelte file content
+ * @param {string} filePath - Path to the .svelte file (for context)
+ * @returns {Object} { scriptBlocks: [{content, lang, startLine, isModule}], markup: {content, startLine} }
+ */
+export function extractSvelteSFC(content) {
+  const scriptBlocks = [];
+  let markup = null;
+  
+  // Extract <script> blocks (including <script context="module">)
+  const scriptRegex = /<script(?:\s+context=["']module["'])?(?:\s+lang=["']([^"']+)["'])?[^>]*>([\s\S]*?)<\/script>/gi;
+  let scriptMatch;
+  
+  while ((scriptMatch = scriptRegex.exec(content)) !== null) {
+    const isModule = scriptMatch[0].includes('context="module"') || scriptMatch[0].includes("context='module'");
+    const lang = scriptMatch[1] || 'js';
+    const scriptContent = scriptMatch[2];
+    
+    // Calculate start line
+    const beforeMatch = content.substring(0, scriptMatch.index);
+    const startLine = (beforeMatch.match(/\n/g) || []).length + 1;
+    
+    scriptBlocks.push({
+      content: scriptContent.trim(),
+      lang: lang.toLowerCase(),
+      startLine,
+      isModule,
+    });
+  }
+  
+  // Extract markup (everything outside script/style tags)
+  // Svelte markup is the template content
+  const styleRegex = /<style[^>]*>[\s\S]*?<\/style>/gi;
+  const allScriptRegex = /<script[^>]*>[\s\S]*?<\/script>/gi;
+  
+  let markupContent = content;
+  // Remove style blocks
+  markupContent = markupContent.replace(styleRegex, '');
+  // Remove script blocks
+  markupContent = markupContent.replace(allScriptRegex, '');
+  
+  // Find first non-whitespace line for markup
+  const lines = content.split('\n');
+  let markupStartLine = 1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() && !line.trim().startsWith('<script') && !line.trim().startsWith('<style')) {
+      markupStartLine = i + 1;
+      break;
+    }
+  }
+  
+  if (markupContent.trim()) {
+    markup = {
+      content: markupContent.trim(),
+      startLine: markupStartLine,
+    };
+  }
+  
+  return {
+    scriptBlocks,
+    markup,
+  };
+}
+
+/**
+ * Extract template bindings from Svelte markup
+ * Detects reactive statements, event handlers, and bindings
+ * 
+ * @param {string} markupContent - Svelte markup content
+ * @returns {Object} { reactiveStatements: [], eventHandlers: [], bindings: [] }
+ */
+export function extractTemplateBindings(markupContent) {
+  const reactiveStatements = [];
+  const eventHandlers = [];
+  const bindings = [];
+  
+  // Extract reactive statements: $: statements
+  const reactiveRegex = /\$:\s*([^;]+);/g;
+  let reactiveMatch;
+  while ((reactiveMatch = reactiveRegex.exec(markupContent)) !== null) {
+    reactiveStatements.push({
+      statement: reactiveMatch[1].trim(),
+      line: (markupContent.substring(0, reactiveMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  // Extract event handlers: on:click, on:submit, etc.
+  const eventHandlerRegex = /on:(\w+)=["']([^"']+)["']/g;
+  let handlerMatch;
+  while ((handlerMatch = eventHandlerRegex.exec(markupContent)) !== null) {
+    eventHandlers.push({
+      event: handlerMatch[1],
+      handler: handlerMatch[2],
+      line: (markupContent.substring(0, handlerMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  // Extract bindings: bind:value, bind:checked, etc.
+  const bindingRegex = /bind:(\w+)=["']([^"']+)["']/g;
+  let bindingMatch;
+  while ((bindingMatch = bindingRegex.exec(markupContent)) !== null) {
+    bindings.push({
+      property: bindingMatch[1],
+      variable: bindingMatch[2],
+      line: (markupContent.substring(0, bindingMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  return {
+    reactiveStatements,
+    eventHandlers,
+    bindings,
+  };
+}
+
+/**
+ * Map template handlers to script functions
+ * Helps identify which handlers are UI-bound
+ * 
+ * @param {Array} eventHandlers - Event handlers from template
+ * @param {string} scriptContent - Script block content
+ * @returns {Array} Mapped handlers with function references
+ */
+export function mapTemplateHandlersToScript(eventHandlers, scriptContent) {
+  return eventHandlers.map(handler => {
+    // Try to find function definition in script
+    const functionRegex = new RegExp(`(?:function\\s+${handler.handler}|const\\s+${handler.handler}\\s*=\\s*[^(]*\\(|${handler.handler}\\s*=\\s*[^(]*\\(|export\\s+function\\s+${handler.handler})`, 'g');
+    const functionMatch = functionRegex.exec(scriptContent);
+    
+    return {
+      ...handler,
+      functionFound: !!functionMatch,
+      functionLine: functionMatch ? (scriptContent.substring(0, functionMatch.index).match(/\n/g) || []).length + 1 : null,
+    };
+  });
+}
+