@veraxhq/verax 0.1.0 → 0.2.1

package/src/cli/util/project-discovery.js

@@ -0,0 +1,297 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+/**
+ * Project Discovery Module
+ * Detects framework, router, source root, and dev server configuration
+ * 
+ * @typedef {Object} ProjectProfile
+ * @property {string} framework
+ * @property {string|null} router
+ * @property {string} sourceRoot
+ * @property {string} packageManager
+ * @property {{dev: string|null, build: string|null, start: string|null}} scripts
+ * @property {string} detectedAt
+ * @property {string|null} packageJsonPath
+ * @property {number} [fileCount] - Optional file count for budget calculation
+ */
+
+/**
+ * @param {string} srcPath
+ * @returns {Promise<ProjectProfile>}
+ */
+export async function discoverProject(srcPath) {
+  const projectRoot = resolve(srcPath);
+  
+  // Find the nearest package.json
+  const packageJsonPath = findPackageJson(projectRoot);
+  
+  // If there's a package.json, use its directory
+  // Otherwise, use the srcPath (even if it's a static HTML project)
+  const projectDir = packageJsonPath ? dirname(packageJsonPath) : projectRoot;
+  
+  let packageJson = null;
+  if (packageJsonPath && existsSync(packageJsonPath)) {
+    try {
+      packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    } catch (error) {
+      packageJson = null;
+    }
+  }
+  
+  // Detect framework
+  const framework = detectFramework(projectDir, packageJson);
+  const router = detectRouter(framework, projectDir);
+  
+  // Determine package manager
+  const packageManager = detectPackageManager(projectDir);
+  
+  // Extract scripts
+  const scripts = {
+    dev: packageJson?.scripts?.dev || null,
+    build: packageJson?.scripts?.build || null,
+    start: packageJson?.scripts?.start || null,
+  };
+  
+  return {
+    framework,
+    router,
+    sourceRoot: projectDir,
+    packageManager,
+    scripts,
+    detectedAt: new Date().toISOString(),
+    packageJsonPath,
+  };
+}
+
+/**
+ * Find the nearest package.json by walking up directories
+ */
+function findPackageJson(startPath) {
+  let currentPath = resolve(startPath);
+  
+  // First check if package.json exists in startPath itself
+  const immediatePackage = resolve(currentPath, 'package.json');
+  if (existsSync(immediatePackage)) {
+    return immediatePackage;
+  }
+  
+  // For static HTML projects, don't walk up - use the startPath as project root
+  // This prevents finding parent package.json files that aren't relevant
+  if (hasStaticHtml(currentPath)) {
+    return null;
+  }
+  
+  // Then walk up (limit to 5 levels for monorepos, not 10)
+  for (let i = 0; i < 5; i++) {
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      // Reached filesystem root
+      break;
+    }
+    
+    currentPath = parentPath;
+    const packageJsonPath = resolve(currentPath, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      return packageJsonPath;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Detect the framework type
+ */
+function detectFramework(projectDir, packageJson) {
+  // Check for Next.js
+  if (hasNextJs(projectDir, packageJson)) {
+    return 'nextjs';
+  }
+  
+  // Check for Vite + React
+  if (hasViteReact(projectDir, packageJson)) {
+    return 'react-vite';
+  }
+  
+  // Check for Create React App
+  if (hasCreateReactApp(packageJson)) {
+    return 'react-cra';
+  }
+  
+  // Check for static HTML
+  if (hasStaticHtml(projectDir)) {
+    return 'static-html';
+  }
+  
+  // Unknown framework
+  return 'unknown';
+}
+
+/**
+ * Detect Next.js
+ */
+function hasNextJs(projectDir, packageJson) {
+  // Check for next.config.js or next.config.mjs
+  const hasNextConfig = existsSync(resolve(projectDir, 'next.config.js')) ||
+    existsSync(resolve(projectDir, 'next.config.mjs')) ||
+    existsSync(resolve(projectDir, 'next.config.ts'));
+  
+  if (hasNextConfig) {
+    return true;
+  }
+  
+  // Check for 'next' dependency
+  if (packageJson?.dependencies?.next || packageJson?.devDependencies?.next) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Detect router type for Next.js
+ */
+function detectRouter(framework, projectDir) {
+  if (framework !== 'nextjs') {
+    return null;
+  }
+  
+  // Check for /app directory (app router) - must contain actual files
+  const appPath = resolve(projectDir, 'app');
+  if (existsSync(appPath) && hasRouteFiles(appPath)) {
+    return 'app';
+  }
+  
+  // Check for /pages directory (pages router)
+  if (existsSync(resolve(projectDir, 'pages'))) {
+    return 'pages';
+  }
+  
+  return null;
+}
+
+/**
+ * Check if a directory contains route files (not just an empty scaffold)
+ */
+function hasRouteFiles(dirPath) {
+  try {
+    const entries = readdirSync(dirPath);
+    return entries.some(entry => {
+      // Look for .js, .ts, .jsx, .tsx files (not just directories)
+      return /\.(js|ts|jsx|tsx)$/.test(entry);
+    });
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Detect Vite + React
+ */
+function hasViteReact(projectDir, packageJson) {
+  const hasViteConfig = existsSync(resolve(projectDir, 'vite.config.js')) ||
+    existsSync(resolve(projectDir, 'vite.config.ts')) ||
+    existsSync(resolve(projectDir, 'vite.config.mjs'));
+  
+  if (!hasViteConfig) {
+    return false;
+  }
+  
+  // Check for react dependency
+  if (packageJson?.dependencies?.react || packageJson?.devDependencies?.react) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Detect Create React App
+ */
+function hasCreateReactApp(packageJson) {
+  return !!(packageJson?.dependencies?.['react-scripts'] || 
+    packageJson?.devDependencies?.['react-scripts']);
+}
+
+/**
+ * Detect static HTML (no framework)
+ */
+function hasStaticHtml(projectDir) {
+  return existsSync(resolve(projectDir, 'index.html'));
+}
+
+/**
+ * Detect package manager
+ */
+function detectPackageManager(projectDir) {
+  // Check for pnpm-lock.yaml
+  if (existsSync(resolve(projectDir, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  
+  // Check for yarn.lock
+  if (existsSync(resolve(projectDir, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  
+  // Check for package-lock.json (npm)
+  if (existsSync(resolve(projectDir, 'package-lock.json'))) {
+    return 'npm';
+  }
+  
+  // Default to npm if none found but package.json exists
+  if (existsSync(resolve(projectDir, 'package.json'))) {
+    return 'npm';
+  }
+  
+  return 'unknown';
+}
+
+/**
+ * Get human-readable framework name
+ */
+export function getFrameworkDisplayName(framework, router) {
+  if (framework === 'nextjs') {
+    const routerType = router === 'app' ? 'app router' : router === 'pages' ? 'pages router' : 'unknown router';
+    return `Next.js (${routerType})`;
+  }
+  
+  if (framework === 'react-vite') {
+    return 'Vite + React';
+  }
+  
+  if (framework === 'react-cra') {
+    return 'Create React App';
+  }
+  
+  if (framework === 'static-html') {
+    return 'Static HTML';
+  }
+  
+  return 'Unknown';
+}
+
+/**
+ * Extract probable port from dev script
+ */
+export function extractPortFromScript(script) {
+  if (!script) return null;
+  
+  // Common patterns:
+  // - --port 3000
+  // - -p 3000
+  // - PORT=3000
+  
+  const portMatch = script.match(/(?:--port|-p)\s+(\d+)/);
+  if (portMatch) {
+    return parseInt(portMatch[1], 10);
+  }
+  
+  const portEnvMatch = script.match(/PORT=(\d+)/);
+  if (portEnvMatch) {
+    return parseInt(portEnvMatch[1], 10);
+  }
+  
+  return null;
+}

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

@@ -0,0 +1,26 @@
+import { atomicWriteJson } from './atomic-write.js';
+import { resolve } from 'path';
+
+/**
+ * Write project profile artifact
+ */
+export function writeProjectJson(runPaths, projectProfile) {
+  const projectJsonPath = resolve(runPaths.baseDir, 'project.json');
+  
+  const projectJson = {
+    framework: projectProfile.framework,
+    router: projectProfile.router,
+    sourceRoot: projectProfile.sourceRoot,
+    packageManager: projectProfile.packageManager,
+    scripts: {
+      dev: projectProfile.scripts.dev,
+      build: projectProfile.scripts.build,
+      start: projectProfile.scripts.start,
+    },
+    detectedAt: projectProfile.detectedAt,
+  };
+  
+  atomicWriteJson(projectJsonPath, projectJson);
+  
+  return projectJsonPath;
+}

package/src/cli/util/redact.js

@@ -0,0 +1,128 @@
+/**
+ * Redaction utilities (Phase 8.2)
+ * Deterministic redaction for headers, URLs, bodies, console messages.
+ */
+
+const REDACTED = '***REDACTED***';
+const SENSITIVE_HEADERS = [
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'proxy-authorization',
+];
+
+function ensureCounters(counters) {
+  if (!counters) return { headersRedacted: 0, tokensRedacted: 0 };
+  if (typeof counters.headersRedacted !== 'number') counters.headersRedacted = 0;
+  if (typeof counters.tokensRedacted !== 'number') counters.tokensRedacted = 0;
+  return counters;
+}
+
+export function redactHeaders(headers = {}, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  const c = ensureCounters(counters);
+  const sanitized = {};
+  Object.entries(headers || {}).forEach(([key, value]) => {
+    const lower = key.toLowerCase();
+    if (SENSITIVE_HEADERS.includes(lower)) {
+      sanitized[key] = REDACTED;
+      c.headersRedacted += 1;
+    } else {
+      sanitized[key] = value;
+    }
+  });
+  return sanitized;
+}
+
+export function redactUrl(url, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  if (url == null) return '';
+  return redactTokensInText(url, counters);
+}
+
+export function redactBody(body, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  if (body == null) return body;
+  
+  const c = ensureCounters(counters);
+  
+  if (typeof body === 'string') {
+    return redactTokensInText(body, counters);
+  }
+  
+  if (typeof body === 'object' && !Array.isArray(body)) {
+    // Handle plain objects by redacting sensitive property names
+    const redacted = {};
+    Object.entries(body).forEach(([key, value]) => {
+      const keyLower = key.toLowerCase();
+      if (keyLower === 'token' || keyLower === 'api_key' || keyLower === 'access_token' || 
+          keyLower === 'password' || keyLower === 'secret') {
+        // Redact sensitive property values
+        c.tokensRedacted += 1;
+        redacted[key] = REDACTED;
+      } else if (typeof value === 'string') {
+        // Redact token patterns within string values
+        redacted[key] = redactTokensInText(value, counters);
+      } else if (typeof value === 'object' && value !== null) {
+        // Recursively redact nested objects/arrays
+        redacted[key] = redactBody(value, counters);
+      } else {
+        redacted[key] = value;
+      }
+    });
+    return redacted;
+  }
+  
+  if (Array.isArray(body)) {
+    return body.map(item => redactBody(item, counters));
+  }
+  
+  try {
+    const str = JSON.stringify(body);
+    const redacted = redactTokensInText(str, counters);
+    return JSON.parse(redacted);
+  } catch {
+    return REDACTED;
+  }
+}
+
+export function redactConsole(text = '', counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  return redactTokensInText(text, counters);
+}
+
+export function redactTokensInText(text, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  const c = ensureCounters(counters);
+  if (text == null) return '';
+  if (typeof text !== 'string') return String(text);
+  
+  let output = text;
+
+  // Query/string parameters FIRST (most specific - only api_key, access_token)
+  // Use word boundary \b to avoid matching within words like "token" inside "example.com"
+  output = output.replace(/\b(api_key|access_token)=([^&\s]+)/gi, (match, key, value) => {
+    // Skip if value is itself just REDACTED (avoid double-redacting)
+    if (value === REDACTED) return match;
+    c.tokensRedacted += 1;
+    return `${key}=${REDACTED}`;
+  });
+
+  // Bearer tokens
+  output = output.replace(/Bearer\s+([A-Za-z0-9._-]+)/gi, (_match, _token) => {
+    c.tokensRedacted += 1;
+    return `Bearer ${REDACTED}`;
+  });
+
+  // JWT-like strings (three base64url-ish segments)
+  // More specific: require uppercase or numbers, not just domain patterns like "api.example.com"
+  output = output.replace(/[A-Z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, (_match) => {
+    c.tokensRedacted += 1;
+    return REDACTED;
+  });
+
+  return output;
+}
+
+export function getRedactionCounters(counters) {
+  const c = ensureCounters(counters);
+  return { headersRedacted: c.headersRedacted, tokensRedacted: c.tokensRedacted };
+}
+
+export const REDACTION_PLACEHOLDER = REDACTED;

package/src/cli/util/run-id.js

@@ -0,0 +1,30 @@
+import crypto from 'crypto';
+
+/**
+ * Generate a run ID in format: <ISO_TIMESTAMP_UTC>_<6-8 char short hash>
+ * Example: 2026-01-11T00-59-12Z_4f2a9c
+ */
+export function generateRunId() {
+  // Create ISO timestamp with colons replaced by dashes for filesystem compatibility
+  const now = new Date();
+  const isoString = now.toISOString();
+  // Format: 2026-01-11T00:59:12.123Z -> 2026-01-11T00-59-12Z
+  const timestamp = isoString.replace(/:/g, '-').replace(/\.\d+Z/, 'Z');
+  
+  // Generate a short hash (6-8 chars)
+  const hash = crypto
+    .randomBytes(4)
+    .toString('hex')
+    .substring(0, 6);
+  
+  return `${timestamp}_${hash}`;
+}
+
+/**
+ * Validate a run ID format
+ */
+export function isValidRunId(runId) {
+  // Pattern: YYYY-MM-DDTHH-MM-SSZ_hexchars
+  const pattern = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z_[a-f0-9]{6,8}$/;
+  return pattern.test(runId);
+}

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/summary-writer.js

@@ -0,0 +1,43 @@
+import { atomicWriteJson } from './atomic-write.js';
+
+/**
+ * Write summary.json with deterministic digest
+ * The digest provides stable counts that should be identical across runs
+ * on the same input (assuming site behavior is stable)
+ */
+export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
+  const payload = {
+    runId: summaryData.runId,
+    status: summaryData.status,
+    startedAt: summaryData.startedAt,
+    completedAt: summaryData.completedAt,
+    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: {
+      expectationsTotal: stats.expectationsTotal || 0,
+      attempted: stats.attempted || 0,
+      observed: stats.observed || 0,
+      silentFailures: stats.silentFailures || 0,
+      coverageGaps: stats.coverageGaps || 0,
+      unproven: stats.unproven || 0,
+      informational: stats.informational || 0,
+    },
+  };
+  
+  atomicWriteJson(summaryPath, payload);
+}

package/src/types/global.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Global type declarations for VERAX
+ * These extend built-in types to support runtime-injected properties
+ */
+
+// Extend Window interface for browser-injected properties
+declare global {
+  interface Window {
+    __veraxNavTracking?: any;
+    next?: any;
+    __REDUX_STORE__?: any;
+    store?: any;
+    __REDUX_DEVTOOLS_EXTENSION__?: any;
+    __REACT_DEVTOOLS_GLOBAL_HOOK__?: any;
+    __VERAX_STATE_SENSOR__?: any;
+    __unhandledRejections?: any[];
+    __ZUSTAND_STORE__?: any;
+  }
+}
+
+// Playwright Page type (imported from playwright)
+import type { Page as PlaywrightPage } from 'playwright';
+
+// Re-export for use in JS files
+export type Page = PlaywrightPage;
+
+export {};
+