@veraxhq/verax 0.1.0 → 0.2.1

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

@@ -0,0 +1,136 @@
+/**
+ * BUDGET PROFILES
+ *
+ * Predefined scan budgets for different use cases.
+ * Select using VERAX_BUDGET_PROFILE environment variable.
+ *
+ * Available profiles:
+ * - QUICK: 20 seconds, minimal coverage (developer rapid feedback)
+ * - STANDARD: 60 seconds, balanced (default CI behavior)
+ * - THOROUGH: 120 seconds, deeper coverage (comprehensive validation)
+ * - EXHAUSTIVE: 300 seconds, maximum coverage (deep audit)
+ */
+
+import { createScanBudget } from './scan-budget.js';
+
+/**
+ * QUICK profile: Fast feedback for development
+ * - maxScanDurationMs: 20 seconds (vs 60)
+ * - maxInteractionsPerPage: 20 (vs 30) 
+ * - maxPages: 2 (vs 50)
+ * - maxFlows: 1 (vs 3)
+ * Recommended for: Local development, PR checks, pre-commit
+ */
+const QUICK_PROFILE = {
+  maxScanDurationMs: 20000,
+  maxInteractionsPerPage: 20,
+  maxPages: 2,
+  maxFlows: 1,
+  maxFlowSteps: 3
+};
+
+/**
+ * STANDARD profile: Balanced coverage (DEFAULT)
+ * - maxScanDurationMs: 60 seconds (default)
+ * - maxInteractionsPerPage: 30 (default)
+ * - maxPages: 50 (default)
+ * - maxFlows: 3 (default)
+ * Recommended for: CI/CD pipelines, standard regression testing
+ */
+const STANDARD_PROFILE = {};
+
+/**
+ * THOROUGH profile: Deeper coverage for comprehensive validation
+ * - maxScanDurationMs: 120 seconds (2x default)
+ * - maxInteractionsPerPage: 50 (1.67x default)
+ * - maxPages: 50 (unchanged)
+ * - maxFlows: 5 (1.67x default)
+ * - stabilizationWindowMs: 6000 (2x default for flakiness reduction)
+ * - adaptiveStabilization: true (extend settle if DOM/network still changing)
+ * Recommended for: Pre-release testing, critical applications
+ */
+const THOROUGH_PROFILE = {
+  maxScanDurationMs: 120000,
+  maxInteractionsPerPage: 50,
+  maxFlows: 5,
+  maxFlowSteps: 7,
+  stabilizationWindowMs: 6000,
+  adaptiveStabilization: true
+};
+
+/**
+ * EXHAUSTIVE profile: Maximum coverage for deep audit
+ * - maxScanDurationMs: 300 seconds (5x default)
+ * - maxInteractionsPerPage: 100 (3.3x default)
+ * - maxPages: 50 (unchanged, depth not breadth)
+ * - maxFlows: 10 (3.3x default)
+ * - stabilizationWindowMs: 8000 (2.67x default for comprehensive stability)
+ * - adaptiveStabilization: true (extend settle generously for difficult applications)
+ * Recommended for: Security audits, full app validation, non-time-critical analysis
+ */
+const EXHAUSTIVE_PROFILE = {
+  maxScanDurationMs: 300000,
+  maxInteractionsPerPage: 100,
+  maxFlows: 10,
+  maxFlowSteps: 10,
+  stabilizationWindowMs: 8000,
+  adaptiveStabilization: true
+};
+
+const PROFILES = {
+  QUICK: QUICK_PROFILE,
+  STANDARD: STANDARD_PROFILE,
+  THOROUGH: THOROUGH_PROFILE,
+  EXHAUSTIVE: EXHAUSTIVE_PROFILE
+};
+
+/**
+ * Get the active budget profile based on VERAX_BUDGET_PROFILE env var.
+ * Defaults to STANDARD if not set.
+ * @returns {Object} Profile overrides
+ */
+export function getActiveBudgetProfile() {
+  const profileName = process.env.VERAX_BUDGET_PROFILE || 'STANDARD';
+  const profile = PROFILES[profileName.toUpperCase()];
+  
+  if (!profile) {
+    console.warn(
+      `Warning: Unknown budget profile '${profileName}'. ` +
+      `Available profiles: ${Object.keys(PROFILES).join(', ')}. ` +
+      `Defaulting to STANDARD.`
+    );
+    return STANDARD_PROFILE;
+  }
+  
+  return profile;
+}
+
+/**
+ * Create a scan budget with the active profile applied.
+ * @returns {Object} Complete scan budget with profile applied
+ */
+export function createScanBudgetWithProfile() {
+  const profile = getActiveBudgetProfile();
+  return createScanBudget(profile);
+}
+
+/**
+ * Get profile metadata for logging/debugging.
+ * @returns {Object} Profile name and configuration
+ */
+export function getProfileMetadata() {
+  const profileName = process.env.VERAX_BUDGET_PROFILE || 'STANDARD';
+  const profile = PROFILES[profileName.toUpperCase()] || STANDARD_PROFILE;
+  const budget = createScanBudget(profile);
+  
+  return {
+    name: profileName.toUpperCase(),
+    maxScanDurationMs: budget.maxScanDurationMs,
+    maxInteractionsPerPage: budget.maxInteractionsPerPage,
+    maxPages: budget.maxPages,
+    maxFlows: budget.maxFlows,
+    maxFlowSteps: budget.maxFlowSteps
+  };
+}
+
+export { PROFILES };

package/src/verax/shared/caching.js

@@ -10,7 +10,7 @@
 
 import { createHash } from 'crypto';
 import { readFileSync, existsSync, statSync } from 'fs';
-import { resolve, join } from 'path';
+import { resolve } from 'path';
 
 const memoryCache = new Map(); // Global in-memory cache
 

package/src/verax/shared/ci-detection.js

@@ -0,0 +1,39 @@
+/**
+ * Wave 5 — CI Detection
+ * 
+ * Detects CI environment and handles CI-specific behavior.
+ */
+
+/**
+ * Detect if running in CI environment
+ * @param {Object} options - Options with explicit ci flag
+ * @returns {boolean} True if in CI mode
+ */
+export function isCI(options = {}) {
+  // Explicit --ci flag takes precedence
+  if (options.ci === true || options.ci === 'true') {
+    return true;
+  }
+  
+  // Check common CI environment variables
+  const ciEnvVars = [
+    'CI',
+    'CONTINUOUS_INTEGRATION',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'JENKINS_URL',
+    'TRAVIS',
+    'CIRCLECI',
+    'BITBUCKET_COMMIT',
+    'TEAMCITY_VERSION'
+  ];
+  
+  for (const envVar of ciEnvVars) {
+    if (process.env[envVar]) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+

package/src/verax/shared/config-loader.js

@@ -0,0 +1,169 @@
+/**
+ * Wave 7 — Config File Support
+ * 
+ * Loads and validates .verax/config.json configuration file.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+/**
+ * Default config values
+ */
+const DEFAULT_CONFIG = {
+  defaultUrl: 'http://localhost:3000',
+  projectRoot: '.',
+  outDir: '.verax/runs',
+  ciDefaults: {
+    json: true,
+    zip: true,
+    explain: false
+  },
+  safety: {
+    allowlistDomains: [],
+    denyKeywords: ['delete', 'remove', 'billing', 'payment']
+  }
+};
+
+/**
+ * Validate config structure
+ * @param {Object} config - Config object to validate
+ * @returns {Object} { valid: boolean, errors: string[] }
+ */
+export function validateConfig(config) {
+  const errors = [];
+  
+  if (typeof config !== 'object' || config === null) {
+    errors.push('Config must be an object');
+    return { valid: false, errors };
+  }
+  
+  // Validate defaultUrl
+  if (config.defaultUrl !== undefined) {
+    if (typeof config.defaultUrl !== 'string' || config.defaultUrl.trim() === '') {
+      errors.push('defaultUrl must be a non-empty string');
+    } else {
+      try {
+        new URL(config.defaultUrl);
+      } catch (e) {
+        errors.push(`defaultUrl is not a valid URL: ${config.defaultUrl}`);
+      }
+    }
+  }
+  
+  // Validate projectRoot
+  if (config.projectRoot !== undefined && typeof config.projectRoot !== 'string') {
+    errors.push('projectRoot must be a string');
+  }
+  
+  // Validate outDir
+  if (config.outDir !== undefined && typeof config.outDir !== 'string') {
+    errors.push('outDir must be a string');
+  }
+  
+  // Validate ciDefaults
+  if (config.ciDefaults !== undefined) {
+    if (typeof config.ciDefaults !== 'object' || config.ciDefaults === null) {
+      errors.push('ciDefaults must be an object');
+    } else {
+      if (config.ciDefaults.json !== undefined && typeof config.ciDefaults.json !== 'boolean') {
+        errors.push('ciDefaults.json must be a boolean');
+      }
+      if (config.ciDefaults.zip !== undefined && typeof config.ciDefaults.zip !== 'boolean') {
+        errors.push('ciDefaults.zip must be a boolean');
+      }
+      if (config.ciDefaults.explain !== undefined && typeof config.ciDefaults.explain !== 'boolean') {
+        errors.push('ciDefaults.explain must be a boolean');
+      }
+    }
+  }
+  
+  // Validate safety
+  if (config.safety !== undefined) {
+    if (typeof config.safety !== 'object' || config.safety === null) {
+      errors.push('safety must be an object');
+    } else {
+      if (config.safety.allowlistDomains !== undefined) {
+        if (!Array.isArray(config.safety.allowlistDomains)) {
+          errors.push('safety.allowlistDomains must be an array');
+        } else {
+          for (const domain of config.safety.allowlistDomains) {
+            if (typeof domain !== 'string') {
+              errors.push('safety.allowlistDomains must contain only strings');
+              break;
+            }
+          }
+        }
+      }
+      if (config.safety.denyKeywords !== undefined) {
+        if (!Array.isArray(config.safety.denyKeywords)) {
+          errors.push('safety.denyKeywords must be an array');
+        } else {
+          for (const keyword of config.safety.denyKeywords) {
+            if (typeof keyword !== 'string') {
+              errors.push('safety.denyKeywords must contain only strings');
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Load config file from project directory
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object|null} Config object or null if not found
+ * @throws {Error} If config file exists but is invalid
+ */
+export function loadConfig(projectRoot) {
+  const configPath = resolve(projectRoot, '.verax', 'config.json');
+  
+  if (!existsSync(configPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(content);
+    
+    const validation = validateConfig(config);
+    if (!validation.valid) {
+      throw new Error(`Invalid config file: ${validation.errors.join(', ')}`);
+    }
+    
+    // Merge with defaults
+    return {
+      ...DEFAULT_CONFIG,
+      ...config,
+      ciDefaults: {
+        ...DEFAULT_CONFIG.ciDefaults,
+        ...(config.ciDefaults || {})
+      },
+      safety: {
+        ...DEFAULT_CONFIG.safety,
+        ...(config.safety || {})
+      }
+    };
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Config file is not valid JSON: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get default config (for init)
+ * @returns {Object} Default config object
+ */
+export function getDefaultConfig() {
+  return JSON.parse(JSON.stringify(DEFAULT_CONFIG));
+}
+

package/src/verax/shared/dynamic-route-utils.js

@@ -0,0 +1,224 @@
+/**
+ * DYNAMIC ROUTE UTILITIES
+ * 
+ * Safely converts dynamic route patterns into executable example paths.
+ * Patterns are deterministic - always produce the same example paths.
+ * 
+ * Supported patterns:
+ * - React Router: /users/:id
+ * - Next.js: /users/[id], /blog/[slug]
+ * - Vue Router: /users/:id
+ * - Template literals: /blog/${slug}
+ */
+
+/**
+ * Detect if a path contains dynamic parameters.
+ * 
+ * @param {string} path - Route path
+ * @returns {boolean} - True if path contains dynamic parameters
+ */
+export function isDynamicPath(path) {
+  if (!path || typeof path !== 'string') return false;
+  // React/Vue Router :param
+  if (/:(\w+)/.test(path)) return true;
+  // Next.js [param]
+  if (/\[\w+\]/.test(path)) return true;
+  // Template literal ${param}
+  if (/\$\{\w+\}/.test(path)) return true;
+  return false;
+}
+
+/**
+ * Alternative name for isDynamicPath for compatibility.
+ */
+export function isDynamicRoute(path) {
+  return isDynamicPath(path);
+}
+
+/**
+ * Generate a deterministic example value for a parameter.
+ * Always produces the same value for the same parameter name.
+ * 
+ * @param {string} paramName - Parameter name
+ * @returns {string} - Example value
+ */
+function getExampleValue(paramName) {
+  // Parameter name heuristics (deterministic)
+  const lowerName = paramName.toLowerCase();
+  
+  // IDs → numeric
+  if (lowerName.includes('id') || 
+      lowerName.includes('num') || 
+      lowerName.includes('index')) {
+    return '1';
+  }
+  
+  // Slugs, names, titles, etc → 'example'
+  if (lowerName.includes('slug') || 
+      lowerName.includes('name') || 
+      lowerName.includes('title') || 
+      lowerName.includes('username') ||
+      lowerName.includes('email') ||
+      lowerName.includes('author')) {
+    return 'example';
+  }
+  
+  // UUIDs → 'uuid-example'
+  if (lowerName.includes('uuid') || lowerName.includes('guid')) {
+    return 'uuid-example';
+  }
+  
+  // Default: use 'example'
+  return 'example';
+}
+
+/**
+ * Convert a dynamic route pattern into an executable example path.
+ * 
+ * @param {string} originalPath - Route with dynamic parameters
+ * @returns {Object|null} - { examplePath, originalPattern, isDynamic } or null
+ */
+export function createExamplePath(originalPath) {
+  if (!originalPath || typeof originalPath !== 'string') {
+    return null;
+  }
+  
+  if (!isDynamicPath(originalPath)) {
+    return null;
+  }
+  
+  let examplePath = originalPath;
+  let _isDynamic = false;
+  const parameters = new Set();
+  
+  // Replace React/Vue :param
+  examplePath = examplePath.replace(/:(\w+)/g, (match, paramName) => {
+    _isDynamic = true;
+    parameters.add(paramName);
+    return getExampleValue(paramName);
+  });
+  
+  // Replace Next.js [param]
+  examplePath = examplePath.replace(/\[(\w+)\]/g, (match, paramName) => {
+    _isDynamic = true;
+    parameters.add(paramName);
+    return getExampleValue(paramName);
+  });
+  
+  // Replace template ${param}
+  examplePath = examplePath.replace(/\$\{(\w+)\}/g, (match, paramName) => {
+    _isDynamic = true;
+    parameters.add(paramName);
+    return getExampleValue(paramName);
+  });
+  
+  return {
+    examplePath,
+    originalPattern: originalPath,
+    isDynamic: true,
+    exampleExecution: true,
+    parameters: Array.from(parameters)
+  };
+}
+
+/**
+ * Normalize a dynamic route pattern (alias for createExamplePath).
+ * 
+ * @param {string} pattern - Original route pattern
+ * @returns {Object|null} - Normalized result
+ */
+export function normalizeDynamicRoute(pattern) {
+  return createExamplePath(pattern);
+}
+
+/**
+ * Check if a target can be safely normalized (is string literal or simple pattern).
+ * 
+ * @param {string} target - Navigation target
+ * @returns {boolean} - True if can be normalized safely
+ */
+export function canNormalizeTarget(target) {
+  if (!target || typeof target !== 'string') return false;
+  
+  // Pure variable reference like ${path} - can't normalize
+  if (target === '${path}' || target === '${id}') {
+    return false;
+  }
+  
+  return true;
+}
+
+/**
+ * Normalize a navigation target with potential template literals.
+ * 
+ * @param {string} originalTarget - Original target string
+ * @returns {Object} - { exampleTarget, originalTarget, isDynamic, parameters }
+ */
+export function normalizeNavigationTarget(originalTarget) {
+  if (!canNormalizeTarget(originalTarget)) {
+    return {
+      exampleTarget: null,
+      originalTarget: null,
+      isDynamic: false,
+      parameters: []
+    };
+  }
+  
+  // Check if it has template literals
+  const templateRegex = /\$\{(\w+)\}/g;
+  const matches = [...originalTarget.matchAll(templateRegex)];
+  
+  if (matches.length === 0) {
+    // No template literals - static path
+    return {
+      exampleTarget: originalTarget,
+      originalTarget: null,
+      isDynamic: false,
+      parameters: []
+    };
+  }
+  
+  // Extract parameter names
+  const parameters = matches.map(m => m[1]);
+  
+  // Replace ${param} with example values
+  let exampleTarget = originalTarget;
+  for (const match of matches) {
+    const paramName = match[1];
+    const exampleValue = getExampleValue(paramName);
+    exampleTarget = exampleTarget.replace(match[0], exampleValue);
+  }
+  
+  return {
+    exampleTarget,
+    originalTarget,
+    isDynamic: true,
+    parameters
+  };
+}
+
+/**
+ * Normalize a template literal string (for backwards compatibility).
+ * 
+ * @param {string} template - Template literal or string
+ * @returns {Object|null} - Result or null
+ */
+export function normalizeTemplateLiteral(template) {
+  if (!template || typeof template !== 'string') {
+    return null;
+  }
+  
+  const result = normalizeNavigationTarget(template);
+  
+  if (result.isDynamic) {
+    return {
+      originalPattern: result.originalTarget,
+      examplePath: result.exampleTarget,
+      isDynamic: true,
+      exampleExecution: true,
+      parameters: result.parameters
+    };
+  }
+  
+  return null;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Wave 9 — Expectation Coverage Signal
+ * 
+ * Computes and explains expectation coverage.
+ */
+
+/**
+ * Calculate expectation coverage
+ * @param {Object} context - Coverage context
+ * @returns {Object} { discovered: number, exercised: number, coveragePercent: number, explanation: string }
+ */
+export function calculateCoverage(context = {}) {
+  const {
+    expectationsTotal = 0,
+    expectationsUsed = 0
+  } = context;
+  
+  const discovered = expectationsTotal;
+  const exercised = expectationsUsed;
+  
+  let coveragePercent = 0;
+  if (discovered > 0) {
+    coveragePercent = Math.round((exercised / discovered) * 100);
+  }
+  
+  let explanation = '';
+  if (discovered === 0) {
+    explanation = 'No expectations found in code';
+  } else if (coveragePercent === 100) {
+    explanation = 'All expectations were exercised';
+  } else if (coveragePercent >= 50) {
+    explanation = `${discovered - exercised} expectation(s) not exercised during scan`;
+  } else {
+    explanation = `Most expectations (${discovered - exercised}) were not exercised`;
+  }
+  
+  return {
+    discovered,
+    exercised,
+    coveragePercent,
+    explanation
+  };
+}
+

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

@@ -0,0 +1,81 @@
+/**
+ * NO-GUESSING GUARANTEE
+ * 
+ * VERAX only generates findings from PROVEN expectations.
+ * Unproven expectations become coverage gaps, not failures.
+ * 
+ * This module provides the single source of truth for "what is proven?"
+ */
+
+/**
+ * Check if an expectation is PROVEN.
+ * 
+ * ABSOLUTE RULES:
+ * - Returns true ONLY if the expectation has definitive code evidence
+ * - Returns false for heuristic/label-matched/guessed expectations
+ * 
+ * @param {Object} expectation - Expectation object to check
+ * @returns {boolean} - true if PROVEN, false otherwise
+ */
+export function isProvenExpectation(expectation) {
+  if (!expectation) {
+    return false;
+  }
+  
+  // Rule 1: Explicit proof marker
+  if (expectation.proof === 'PROVEN_EXPECTATION') {
+    return true;
+  }
+  
+  // Rule 2: Has sourceRef with file + line (code location)
+  if (expectation.sourceRef) {
+    const ref = expectation.sourceRef;
+    // Must include file path AND line number (format: "file.js:123")
+    if (typeof ref === 'string' && ref.includes(':')) {
+      const parts = ref.split(':');
+      if (parts.length >= 2 && parts[1].match(/^\d+$/)) {
+        return true;
+      }
+    }
+  }
+  
+  // Rule 3: Static HTML expectations with evidence.source (file path)
+  if (expectation.evidence && expectation.evidence.source) {
+    // Static HTML parsing provides file path as evidence
+    return true;
+  }
+  
+  // Rule 4: Explicit proven flag
+  if (expectation.proven === true) {
+    return true;
+  }
+  
+  // Everything else is unproven
+  return false;
+}
+
+/**
+ * Create a coverage gap entry for an unproven expectation.
+ * 
+ * @param {Object} expectation - The unproven expectation
+ * @param {Object} interaction - The interaction that triggered this gap
+ * @returns {Object} - Coverage gap entry
+ */
+export function createCoverageGap(expectation, interaction) {
+  return {
+    expectationId: expectation.id || null,
+    type: expectation.type || 'unknown',
+    reason: 'UNPROVEN_EXPECTATION',
+    source: expectation.sourceRef || expectation.source?.file || expectation.evidence?.source || null,
+    interaction: {
+      type: interaction.type,
+      selector: interaction.selector,
+      label: interaction.label || null
+    },
+    metadata: {
+      proof: expectation.proof || 'none',
+      expectationType: expectation.type,
+      targetPath: expectation.targetPath || null
+    }
+  };
+}