@veraxhq/verax 0.1.0 → 0.2.0

package/src/verax/cli/error-normalizer.js

@@ -0,0 +1,154 @@
+/**
+ * Wave 3 — Error Normalizer
+ * 
+ * Converts technical errors into human-friendly messages with next steps.
+ */
+
+/**
+ * Normalize error into user-friendly message
+ * @param {Error} error - Error object
+ * @param {Object} context - Context information
+ * @param {boolean} debug - Whether to show full stack
+ * @returns {Object} { message: string, nextSteps: string[], stack: string }
+ */
+export function normalizeError(error, context = {}, debug = false) {
+  const errorMessage = error.message || String(error);
+  const stack = error.stack || '';
+  
+  // Missing URL
+  if (errorMessage.includes('--url is required') || errorMessage.includes('URL is required')) {
+    return {
+      message: 'URL is required to run a scan.',
+      nextSteps: [
+        'Try: verax run --url http://localhost:3000',
+        'Or run: verax (interactive wizard)'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // Project root not found
+  if (errorMessage.includes('does not exist') && context.projectRoot) {
+    return {
+      message: `Project directory not found: ${context.projectRoot}`,
+      nextSteps: [
+        'Check that the path is correct',
+        'Or specify a different path with --projectRoot',
+        'Or run from the project directory: cd /path/to/project && verax run --url <url>'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // INVALID_CONTEXT
+  if (errorMessage.includes('INVALID_CONTEXT') || context.verdict === 'INVALID_CONTEXT') {
+    return {
+      message: 'The URL you\'re scanning doesn\'t match the project being analyzed.',
+      nextSteps: [
+        'Ensure the URL matches your project (e.g., localhost:3000 for local dev server)',
+        'Or use --force to scan anyway (not recommended)',
+        'Or specify the correct --projectRoot that matches the URL'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // NO_EXPECTATIONS_FOUND
+  if (errorMessage.includes('NO_EXPECTATIONS_FOUND') || context.verdict === 'NO_EXPECTATIONS_FOUND') {
+    return {
+      message: 'No code-derived expectations found in your project.',
+      nextSteps: [
+        'VERAX needs static, proven patterns in your code:',
+        '  • HTML links: <a href="/about">',
+        '  • Static fetch/axios: fetch("/api/users") (no template literals)',
+        '  • State mutations: useState, Redux dispatch, Zustand set',
+        'Dynamic routes and URLs are intentionally skipped.',
+        'See README for supported patterns.'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // Playwright launch failure
+  const lowerError = errorMessage.toLowerCase();
+  const lowerStack = stack.toLowerCase();
+  if (lowerError.includes('executable') || 
+      lowerError.includes('browsertype') ||
+      lowerError.includes('chromium') ||
+      lowerError.includes('playwright') ||
+      lowerStack.includes('playwright')) {
+    return {
+      message: 'Browser automation failed. Playwright browsers are not installed.',
+      nextSteps: [
+        'Install Playwright browsers: npx playwright install chromium',
+        'Or with system dependencies: npx playwright install --with-deps chromium',
+        'See: https://playwright.dev/docs/installation'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // Network/navigation errors
+  if (errorMessage.includes('net::ERR') || errorMessage.includes('Navigation timeout') || errorMessage.includes('Protocol error')) {
+    return {
+      message: `Cannot connect to ${context.url || 'the URL'}.`,
+      nextSteps: [
+        'Ensure the URL is correct and the server is running',
+        'Check network connectivity',
+        'For localhost: ensure your dev server is started'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // Flow file not found
+  if (errorMessage.includes('Flow file not found')) {
+    return {
+      message: `Flow file not found: ${context.flowPath || 'specified path'}`,
+      nextSteps: [
+        'Check that the file path is correct',
+        'Ensure the flow file exists',
+        'See README for flow file format'
+      ],
+      stack: debug ? stack : null
+    };
+  }
+  
+  // Generic error
+  return {
+    message: errorMessage,
+    nextSteps: [
+      'Check the error message above',
+      'Run with --debug for detailed error information',
+      'See README or run: verax --help'
+    ],
+    stack: debug ? stack : null
+  };
+}
+
+/**
+ * Print normalized error to console
+ * @param {Error} error - Error object
+ * @param {Object} context - Context
+ * @param {boolean} debug - Debug mode
+ */
+export function printNormalizedError(error, context = {}, debug = false) {
+  const normalized = normalizeError(error, context, debug);
+  
+  console.error(`\nError: ${normalized.message}\n`);
+  
+  if (normalized.nextSteps && normalized.nextSteps.length > 0) {
+    console.error('Next steps:');
+    normalized.nextSteps.forEach(step => {
+      console.error(`  ${step}`);
+    });
+    console.error('');
+  }
+  
+  if (normalized.stack && debug) {
+    console.error('Stack trace:');
+    console.error(normalized.stack);
+    console.error('');
+  }
+}
+

package/src/verax/cli/explain-output.js

@@ -0,0 +1,105 @@
+/**
+ * Wave 4 — Explain Output
+ * 
+ * Human-readable explanation of expectations and their usage.
+ */
+
+/**
+ * Format expectation for --explain output
+ * @param {Object} expectation - Expectation object from expectations.json
+ * @returns {string} Formatted string
+ */
+function formatExpectation(expectation) {
+  const lines = [];
+  
+  lines.push(`  ID: ${expectation.id}`);
+  lines.push(`  Type: ${expectation.type}`);
+  lines.push(`  Proof: ${expectation.proof}`);
+  lines.push(`  Reason: ${expectation.reason}`);
+  
+  if (expectation.source) {
+    const sourceStr = expectation.source.file 
+      ? `${expectation.source.file}${expectation.source.line ? `:${expectation.source.line}` : ''}`
+      : 'unknown source';
+    lines.push(`  Source: ${sourceStr}`);
+  }
+  
+  lines.push(`  Used: ${expectation.used ? 'YES' : 'NO'}`);
+  
+  if (expectation.usedReason) {
+    lines.push(`  Used Reason: ${expectation.usedReason}`);
+  } else if (!expectation.used) {
+    lines.push(`  Not Used: ${expectation.usedReason || 'no matching interaction'}`);
+  }
+  
+  return lines.join('\n');
+}
+
+/**
+ * Print explain output
+ * @param {Array} expectations - Array of expectation objects
+ * @param {Object} summary - Expectations summary
+ */
+export function printExplainOutput(expectations, summary) {
+  console.error('\n' + '═'.repeat(60));
+  console.error('VERAX Expectations Explanation');
+  console.error('═'.repeat(60));
+  console.error('');
+  
+  console.error(`Summary:`);
+  console.error(`  Total expectations: ${summary.total}`);
+  console.error(`  By type: navigation=${summary.byType.navigation}, network_action=${summary.byType.network_action}, state_action=${summary.byType.state_action}`);
+  console.error(`  Used: ${summary.total - summary.skipped}`);
+  console.error(`  Unused: ${summary.skipped}`);
+  console.error('');
+  
+  if (expectations.length === 0) {
+    console.error('No expectations found in your project.');
+    console.error('VERAX needs static code patterns to create expectations.');
+    console.error('See README for supported patterns.');
+    console.error('');
+    return;
+  }
+  
+  // Group by type
+  const byType = {
+    navigation: expectations.filter(e => e.type === 'navigation'),
+    network_action: expectations.filter(e => e.type === 'network_action'),
+    state_action: expectations.filter(e => e.type === 'state_action')
+  };
+  
+  // Print by type
+  for (const [type, exps] of Object.entries(byType)) {
+    if (exps.length === 0) continue;
+    
+    console.error(`${type.toUpperCase().replace('_', ' ')} (${exps.length}):`);
+    console.error('─'.repeat(60));
+    
+    for (const exp of exps) {
+      console.error(formatExpectation(exp));
+      console.error('');
+    }
+  }
+  
+  // Summary of unused expectations
+  const unused = expectations.filter(e => !e.used);
+  if (unused.length > 0) {
+    console.error('Unused Expectations Summary:');
+    console.error('─'.repeat(60));
+    
+    const unusedByReason = {};
+    for (const exp of unused) {
+      const reason = exp.usedReason || 'no matching interaction';
+      unusedByReason[reason] = (unusedByReason[reason] || 0) + 1;
+    }
+    
+    for (const [reason, count] of Object.entries(unusedByReason)) {
+      console.error(`  ${reason}: ${count}`);
+    }
+    console.error('');
+  }
+  
+  console.error('═'.repeat(60));
+  console.error('');
+}
+

package/src/verax/cli/finding-explainer.js

@@ -0,0 +1,130 @@
+/**
+ * Wave 6 — Finding Explanation
+ * 
+ * Formats findings in a clear, human-readable way showing the chain:
+ * Expectation → Observation → Mismatch → Why this is a silent failure
+ */
+
+/**
+ * Format a single finding for console output
+ * @param {Object} finding - Finding object
+ * @param {Object} expectation - Related expectation (if available)
+ * @returns {string} Formatted finding text
+ */
+export function formatFinding(finding, expectation = null) {
+  const lines = [];
+  
+  // Finding type and confidence
+  const confidenceLevel = finding.confidence?.level || 'UNKNOWN';
+  const confidenceScore = finding.confidence?.score || 0;
+  lines.push(`  [${confidenceLevel} (${confidenceScore}%)] ${finding.type || 'unknown'}`);
+  
+  // Expectation (what was promised)
+  if (expectation) {
+    let expectationDesc = '';
+    if (expectation.type === 'navigation') {
+      const target = expectation.raw?.targetPath || expectation.targetPath || 'route';
+      expectationDesc = `Expected navigation to ${target}`;
+    } else if (expectation.type === 'network_action') {
+      const method = expectation.raw?.method || 'request';
+      const url = expectation.raw?.urlPath || expectation.urlPath || 'endpoint';
+      expectationDesc = `Expected ${method} request to ${url}`;
+    } else if (expectation.type === 'state_action') {
+      expectationDesc = `Expected state mutation`;
+    } else {
+      expectationDesc = `Expected ${expectation.type}`;
+    }
+    lines.push(`  └─ Expectation: ${expectationDesc}`);
+  } else if (finding.expectationId) {
+    lines.push(`  └─ Expectation: Referenced expectation ${finding.expectationId}`);
+  }
+  
+  // Observation (what actually happened)
+  const interaction = finding.interaction || {};
+  if (interaction.type) {
+    let interactionDesc = `${interaction.type}`;
+    if (interaction.selector) {
+      interactionDesc += ` on "${interaction.label || interaction.selector}"`;
+    }
+    lines.push(`  └─ Observation: User interacted (${interactionDesc})`);
+  }
+  
+  // Mismatch (what went wrong)
+  const evidence = finding.evidence || {};
+  if (finding.type === 'silent_failure' || finding.type === 'navigation_silent_failure') {
+    if (!evidence.hasUrlChange && !evidence.hasVisibleChange) {
+      lines.push(`  └─ Mismatch: No navigation occurred, no visible change`);
+    } else if (evidence.hasUrlChange && !evidence.hasVisibleChange) {
+      lines.push(`  └─ Mismatch: URL changed but no visible feedback`);
+    } else {
+      lines.push(`  └─ Mismatch: Expected navigation did not occur`);
+    }
+  } else if (finding.type === 'network_silent_failure') {
+    if (evidence.slowRequests && evidence.slowRequests > 0) {
+      lines.push(`  └─ Mismatch: Request was slow (${evidence.slowRequests} slow request(s))`);
+    } else {
+      lines.push(`  └─ Mismatch: Request failed or returned error with no user feedback`);
+    }
+  } else if (finding.type === 'missing_network_action') {
+    lines.push(`  └─ Mismatch: Expected network request never fired`);
+  } else if (finding.type === 'missing_state_action') {
+    lines.push(`  └─ Mismatch: Expected state change did not occur`);
+  }
+  
+  // Why this is a silent failure
+  if (finding.reason) {
+    lines.push(`  └─ Silent Failure: ${finding.reason}`);
+  } else {
+    lines.push(`  └─ Silent Failure: User receives no feedback when expected behavior fails`);
+  }
+  
+  // Source location if available
+  if (expectation?.source?.file) {
+    const sourceLine = expectation.source.line ? `:${expectation.source.line}` : '';
+    lines.push(`  └─ Source: ${expectation.source.file}${sourceLine}`);
+  }
+  
+  return lines.join('\n');
+}
+
+/**
+ * Print top findings with explanations
+ * @param {Array} findings - Array of finding objects
+ * @param {Array} expectations - Array of expectation objects (for lookup)
+ * @param {number} limit - Maximum number of findings to print
+ */
+export function printFindings(findings, expectations = [], limit = 5) {
+  if (!findings || findings.length === 0) {
+    return;
+  }
+  
+  console.error('\n' + '─'.repeat(60));
+  console.error(`Top Findings (${Math.min(findings.length, limit)} of ${findings.length})`);
+  console.error('─'.repeat(60));
+  
+  const topFindings = findings.slice(0, limit);
+  
+  // Create expectation lookup map
+  const expectationMap = new Map();
+  for (const exp of expectations) {
+    if (exp.id) {
+      expectationMap.set(exp.id, exp);
+    }
+  }
+  
+  topFindings.forEach((finding, index) => {
+    const expectation = finding.expectationId 
+      ? expectationMap.get(finding.expectationId)
+      : null;
+    
+    console.error(`\n${index + 1}.`);
+    console.error(formatFinding(finding, expectation));
+  });
+  
+  if (findings.length > limit) {
+    console.error(`\n... and ${findings.length - limit} more (see findings.json)`);
+  }
+  
+  console.error('─'.repeat(60) + '\n');
+}
+

package/src/verax/cli/init.js

@@ -0,0 +1,237 @@
+/**
+ * Wave 7 — VERAX Init
+ * 
+ * Initializes VERAX configuration and templates.
+ */
+
+import { existsSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { getDefaultConfig } from '../shared/config-loader.js';
+
+/**
+ * Initialize VERAX configuration
+ * @param {Object} options - { projectRoot, yes, ciTemplate, flowTemplate }
+ * @returns {Promise<Object>} { created: string[], skipped: string[] }
+ */
+export async function runInit(options = {}) {
+  const {
+    projectRoot = process.cwd(),
+    yes = false,
+    ciTemplate = null,
+    flowTemplate = null
+  } = options;
+  
+  const created = [];
+  const skipped = [];
+  
+  // Create .verax directory if needed
+  const veraxDir = resolve(projectRoot, '.verax');
+  mkdirSync(veraxDir, { recursive: true });
+  
+  // Create config.json
+  const configPath = resolve(veraxDir, 'config.json');
+  if (existsSync(configPath) && !yes) {
+    skipped.push('config.json');
+  } else {
+    const defaultConfig = getDefaultConfig();
+    writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n');
+    created.push('config.json');
+  }
+  
+  // Create CI template if requested
+  if (ciTemplate === 'github') {
+    const workflowsDir = resolve(projectRoot, '.github', 'workflows');
+    mkdirSync(workflowsDir, { recursive: true });
+    
+    const workflowFile = resolve(workflowsDir, 'verax-ci.yml');
+    if (existsSync(workflowFile) && !yes) {
+      skipped.push('.github/workflows/verax-ci.yml');
+    } else {
+      const workflowContent = `name: VERAX CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  verax-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Start fixture server
+        id: fixture-server
+        run: |
+          node test/helpers/fixture-server.js &
+          SERVER_PID=$!
+          echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV
+          sleep 3
+          echo "url=http://127.0.0.1:8888" >> $GITHUB_OUTPUT
+        working-directory: \${{ github.workspace }}
+
+      - name: Run VERAX CI scan
+        id: verax
+        run: |
+          npx @veraxhq/verax ci --url \${{ steps.fixture-server.outputs.url }} --projectRoot .
+        continue-on-error: true
+
+      - name: Stop fixture server
+        if: always()
+        run: |
+          if [ ! -z "$SERVER_PID" ]; then
+            kill $SERVER_PID 2>/dev/null || true
+          fi
+
+      - name: Upload VERAX artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: verax-artifacts
+          path: |
+            .verax/runs/**/*
+            .verax/verax-run-*.zip
+          retention-days: 7
+          if-no-files-found: ignore
+
+      - name: Check VERAX exit code and fail gate
+        if: always()
+        run: |
+          EXIT_CODE=\${{ steps.verax.exitcode }}
+          if [ "$EXIT_CODE" == "" ]; then
+            EXIT_CODE=\${{ steps.verax.outcome == 'success' && 0 || 1 }}
+          fi
+          
+          if [ "$EXIT_CODE" == "0" ]; then
+            echo "✅ VERAX: VERIFIED - Scan passed"
+          elif [ "$EXIT_CODE" == "1" ]; then
+            echo "⚠️ VERAX: NO_EXPECTATIONS_FOUND or MEDIUM/LOW findings"
+            echo "Gate passes (non-blocking)"
+          elif [ "$EXIT_CODE" == "2" ]; then
+            echo "❌ VERAX: HIGH severity findings detected"
+            echo "Gate fails (blocking)"
+            exit 2
+          elif [ "$EXIT_CODE" == "4" ]; then
+            echo "❌ VERAX: INVALID_CONTEXT - URL does not match project"
+            echo "Gate fails (blocking)"
+            exit 4
+          elif [ "$EXIT_CODE" == "3" ]; then
+            echo "❌ VERAX: FATAL error"
+            echo "Gate fails (blocking)"
+            exit 3
+          else
+            echo "❌ VERAX: Unexpected exit code $EXIT_CODE"
+            exit $EXIT_CODE
+          fi
+`;
+      writeFileSync(workflowFile, workflowContent);
+      created.push('.github/workflows/verax-ci.yml');
+    }
+  }
+  
+  // Create flow template if requested
+  if (flowTemplate === 'login') {
+    const flowsDir = resolve(projectRoot, 'flows');
+    mkdirSync(flowsDir, { recursive: true });
+    
+    const flowFile = resolve(flowsDir, 'login.json');
+    if (existsSync(flowFile) && !yes) {
+      skipped.push('flows/login.json');
+    } else {
+      const flowContent = {
+        name: 'login',
+        description: 'User login flow',
+        steps: [
+          {
+            type: 'goto',
+            url: '${VERAX_BASE_URL}/login'
+          },
+          {
+            type: 'fill',
+            selector: 'input[name="email"]',
+            value: '${VERAX_TEST_EMAIL}'
+          },
+          {
+            type: 'fill',
+            selector: 'input[name="password"]',
+            value: '${VERAX_TEST_PASSWORD}',
+            isSecret: true
+          },
+          {
+            type: 'click',
+            selector: 'button[type="submit"]'
+          },
+          {
+            type: 'wait',
+            selector: '[data-testid="dashboard"]',
+            timeout: 5000
+          }
+        ]
+      };
+      writeFileSync(flowFile, JSON.stringify(flowContent, null, 2) + '\n');
+      created.push('flows/login.json');
+    }
+  }
+  
+  return { created, skipped };
+}
+
+/**
+ * Print init results
+ * @param {Object} results - Init results
+ */
+export function printInitResults(results) {
+  console.error('\n' + '═'.repeat(60));
+  console.error('VERAX Init');
+  console.error('═'.repeat(60));
+  
+  if (results.created.length > 0) {
+    console.error('\n✅ Created:');
+    results.created.forEach(file => {
+      console.error(`  • ${file}`);
+    });
+  }
+  
+  if (results.skipped.length > 0) {
+    console.error('\n⏭️  Skipped (already exist):');
+    results.skipped.forEach(file => {
+      console.error(`  • ${file}`);
+    });
+  }
+  
+  if (results.created.includes('config.json')) {
+    console.error('\n📝 Next Steps:');
+    console.error('  1. Review .verax/config.json and adjust settings');
+    console.error('  2. Run: verax doctor (to verify setup)');
+    console.error('  3. Run: verax run --url <your-url>');
+  }
+  
+  if (results.created.includes('.github/workflows/verax-ci.yml')) {
+    console.error('\n🔧 CI Setup:');
+    console.error('  • Review .github/workflows/verax-ci.yml');
+    console.error('  • Update URL placeholder with your deployment URL');
+    console.error('  • Commit and push to enable VERAX in CI');
+  }
+  
+  if (results.created.includes('flows/login.json')) {
+    console.error('\n🔐 Flow Template:');
+    console.error('  • Review flows/login.json');
+    console.error('  • Set VERAX_TEST_EMAIL and VERAX_TEST_PASSWORD environment variables');
+    console.error('  • Note: Flow commands are not available in this version');
+  }
+  
+  console.error('═'.repeat(60) + '\n');
+}
+