@veraxhq/verax 0.1.0 → 0.2.1

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 } 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');
+}
+

package/src/verax/cli/run-overview.js

@@ -0,0 +1,163 @@
+/**
+ * Wave 6 — Run Overview
+ * 
+ * Generates a clear, human-readable overview of the scan run.
+ */
+
+/**
+ * Generate run overview data structure
+ * @param {Object} context - Scan context
+ * @returns {Object} Overview data
+ */
+export function generateRunOverview(context = {}) {
+  const {
+    manifest = null,
+    expectationsSummary = { total: 0, navigation: 0, networkActions: 0, stateActions: 0 },
+    interactionsObserved = 0,
+    contextCheck = null,
+    verdict = 'UNKNOWN',
+    findingsCount = 0
+  } = context;
+  
+  const projectType = manifest?.projectType || 'unknown';
+  const expectationsTotal = expectationsSummary.total || 0;
+  
+  // Determine validation status
+  let validationStatus = 'skipped';
+  let validationReason = 'No routes to validate';
+  
+  if (contextCheck && contextCheck.ran) {
+    if (contextCheck.verdict === 'VALID_CONTEXT') {
+      validationStatus = 'validated';
+      validationReason = `${contextCheck.matchedRoutesCount} routes matched`;
+    } else if (contextCheck.verdict === 'INVALID_CONTEXT') {
+      validationStatus = 'mismatch';
+      validationReason = 'URL does not match project';
+    } else if (contextCheck.verdict === 'INVALID_CONTEXT_FORCED') {
+      validationStatus = 'forced';
+      validationReason = 'Scan continued with --force despite mismatch';
+    }
+  }
+  
+  // Generate trust statement
+  let trustLevel = 'low';
+  const trustReasons = [];
+  
+  if (verdict === 'VERIFIED') {
+    trustLevel = 'high';
+    trustReasons.push(`All ${expectationsTotal} expectations validated`);
+    trustReasons.push(`${interactionsObserved} interactions tested`);
+    if (validationStatus === 'validated') {
+      trustReasons.push('Context validated');
+    }
+  } else if (verdict === 'ISSUES_FOUND') {
+    trustLevel = 'high';
+    trustReasons.push(`${expectationsTotal} expectations analyzed`);
+    trustReasons.push(`${interactionsObserved} interactions tested`);
+    trustReasons.push(`${findingsCount} issue(s) detected`);
+  } else if (verdict === 'NO_EXPECTATIONS_FOUND') {
+    trustLevel = 'low';
+    trustReasons.push('No code-derived expectations found');
+    trustReasons.push('Cannot validate without expectations');
+  } else if (verdict === 'INVALID_CONTEXT' || verdict === 'INVALID_CONTEXT_FORCED') {
+    trustLevel = 'partial';
+    trustReasons.push(`${expectationsTotal} expectations found`);
+    if (validationStatus === 'forced') {
+      trustReasons.push('Context mismatch (forced scan)');
+    } else {
+      trustReasons.push('Context mismatch - scan stopped early');
+    }
+    if (interactionsObserved === 0) {
+      trustReasons.push('No interactions executed');
+    }
+  }
+  
+  // Adjust trust level based on interactions
+  if (expectationsTotal > 0 && interactionsObserved === 0 && verdict !== 'INVALID_CONTEXT') {
+    trustLevel = 'partial';
+    if (!trustReasons.some(r => r.includes('No interactions'))) {
+      trustReasons.push('No interactions executed - validation incomplete');
+    }
+  }
+  
+  // Explicitly mention skipped expectations
+  if (context?.expectationsUnused !== undefined && context.expectationsUnused > 0) {
+    if (trustLevel === 'high') {
+      trustLevel = 'partial';
+    }
+    trustReasons.push(`${context.expectationsUnused} expectation(s) unused - partial validation`);
+  }
+  
+  return {
+    projectType: projectType,
+    expectationsFound: expectationsTotal,
+    expectationsByType: {
+      navigation: expectationsSummary.navigation || 0,
+      networkActions: expectationsSummary.networkActions || 0,
+      stateActions: expectationsSummary.stateActions || 0
+    },
+    interactionsExecuted: interactionsObserved,
+    validationStatus: validationStatus,
+    validationReason: validationReason,
+    trustLevel: trustLevel,
+    trustReasons: trustReasons
+  };
+}
+
+/**
+ * Print run overview console block
+ * @param {Object} overview - Overview data from generateRunOverview
+ * @param {boolean} isCI - Whether in CI mode
+ */
+export function printRunOverview(overview, isCI = false) {
+  if (isCI) {
+    // Compact CI format
+    console.error(`VERAX Run: ${overview.projectType} | ${overview.expectationsFound} expectations | ${overview.interactionsExecuted} interactions | ${overview.validationStatus}`);
+    return;
+  }
+  
+  // Full format
+  console.error('\n' + '═'.repeat(60));
+  console.error('Run Overview');
+  console.error('═'.repeat(60));
+  
+  console.error(`Project Type: ${overview.projectType}`);
+  
+  console.error(`\nExpectations Found: ${overview.expectationsFound}`);
+  if (overview.expectationsFound > 0) {
+    const types = [];
+    if (overview.expectationsByType.navigation > 0) {
+      types.push(`navigation (${overview.expectationsByType.navigation})`);
+    }
+    if (overview.expectationsByType.networkActions > 0) {
+      types.push(`network actions (${overview.expectationsByType.networkActions})`);
+    }
+    if (overview.expectationsByType.stateActions > 0) {
+      types.push(`state actions (${overview.expectationsByType.stateActions})`);
+    }
+    if (types.length > 0) {
+      console.error(`  Types: ${types.join(', ')}`);
+    }
+  }
+  
+  console.error(`\nInteractions Executed: ${overview.interactionsExecuted}`);
+  
+  console.error(`\nValidation Status: ${overview.validationStatus}`);
+  console.error(`  ${overview.validationReason}`);
+  
+  // Trust statement
+  console.error(`\nTrust Assessment: ${overview.trustLevel.toUpperCase()}`);
+  const trustPrefix = overview.trustLevel === 'high' 
+    ? 'This result is trustworthy because'
+    : overview.trustLevel === 'partial'
+    ? 'This result is limited because'
+    : 'This result cannot be trusted because';
+  
+  console.error(`  ${trustPrefix}:`);
+  overview.trustReasons.forEach(reason => {
+    console.error(`  • ${reason}`);
+  });
+  
+  console.error('═'.repeat(60) + '\n');
+}
+

package/src/verax/cli/url-safety.js

@@ -0,0 +1,111 @@
+/**
+ * Wave 3 — URL Safety Checks
+ * 
+ * Detects external/public URLs and requires confirmation.
+ */
+
+/**
+ * Check if an IP address is private/local
+ * @param {string} ip - IP address
+ * @returns {boolean} True if private/local
+ */
+function isPrivateIP(ip) {
+  // localhost
+  if (ip === '127.0.0.1' || ip === '::1' || ip === 'localhost') {
+    return true;
+  }
+  
+  // Private IP ranges
+  const privateRanges = [
+    /^10\./,                    // 10.0.0.0/8
+    /^172\.(1[6-9]|2[0-9]|3[01])\./, // 172.16.0.0/12
+    /^192\.168\./,              // 192.168.0.0/16
+    /^169\.254\./,              // Link-local
+    /^fc00:/,                   // IPv6 private
+    /^fe80:/                    // IPv6 link-local
+  ];
+  
+  return privateRanges.some(range => range.test(ip));
+}
+
+/**
+ * Check if URL is external/public (requires confirmation)
+ * @param {string} url - URL to check
+ * @returns {Object} { isExternal: boolean, hostname: string }
+ */
+export function checkUrlSafety(url) {
+  try {
+    const urlObj = new URL(url);
+    const hostname = urlObj.hostname;
+    
+    // Check if localhost
+    if (hostname === 'localhost' || hostname === '127.0.0.1') {
+      return {
+        isExternal: false,
+        hostname: hostname
+      };
+    }
+    
+    // Check if private IP
+    if (isPrivateIP(hostname)) {
+      return {
+        isExternal: false,
+        hostname: hostname
+      };
+    }
+    
+    // All other hosts are considered external
+    return {
+      isExternal: true,
+      hostname: hostname
+    };
+  } catch (error) {
+    // Invalid URL - let other validation catch it
+    return {
+      isExternal: false,
+      hostname: null
+    };
+  }
+}
+
+/**
+ * @typedef {Object} ReadlineInterface
+ * @property {function(string): Promise<string>} question - Prompt user with question
+ * @property {function(): void} close - Close the readline interface
+ */
+
+/**
+ * @typedef {Object} ConfirmExternalUrlOptions
+ * @property {ReadlineInterface} [readlineInterface] - Readline interface (injectable)
+ */
+
+/**
+ * Prompt for external URL confirmation
+ * @param {string} hostname - Hostname to confirm
+ * @param {ConfirmExternalUrlOptions} [options={}] - Options
+ * @returns {Promise<boolean>} True if confirmed
+ */
+export async function confirmExternalUrl(hostname, options = {}) {
+  const rl = options.readlineInterface || null;
+  
+  if (!rl) {
+    // Use readline if not injected
+    const readline = await import('readline/promises');
+    const rlInterface = readline.default.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true
+    });
+    
+    try {
+      const answer = await rlInterface.question(`This will scan a public site (${hostname}). Continue? (y/N): `);
+      return (answer.trim().toLowerCase() || 'n').startsWith('y');
+    } finally {
+      rlInterface.close();
+    }
+  } else {
+    const answer = await rl.question(`This will scan a public site (${hostname}). Continue? (y/N): `);
+    return (answer.trim().toLowerCase() || 'n').startsWith('y');
+  }
+}
+