@veraxhq/verax 0.1.0 → 0.2.1

package/src/types/ts-ast.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TypeScript AST Node type extensions
+ * These extend the base Node type to include properties used by VERAX
+ */
+
+import type * as ts from 'typescript';
+
+declare module 'typescript' {
+  interface Node {
+    attributes?: ts.NodeArray<ts.JSDocAttribute>;
+    tagName?: ts.Identifier;
+    body?: ts.Node;
+    arguments?: ts.NodeArray<ts.Expression>;
+    initializer?: ts.Expression;
+    expression?: ts.Expression;
+    children?: ts.NodeArray<ts.Node>;
+  }
+  
+  namespace ts {
+    // Add isFalseKeyword if it doesn't exist (it might be in a different version)
+    function isFalseKeyword(node: ts.Node): node is ts.FalseKeyword;
+  }
+}
+

package/src/verax/cli/ci-summary.js

@@ -0,0 +1,35 @@
+/**
+ * CI One-Line Summary
+ * 
+ * Prints a deterministic one-line summary for CI logs.
+ * OBSERVATIONAL ONLY - no verdicts, no trust badges, no judgments.
+ */
+
+/**
+ * Generate CI one-line summary
+ * @param {Object} context - Summary context
+ * @returns {string} One-line summary
+ */
+export function generateCISummary(context = {}) {
+  const {
+    expectations = 0,
+    interactions = 0,
+    findings = 0,
+    gaps = 0,
+    silences = 0,
+    runId = 'unknown'
+  } = context;
+  
+  // Format: VERAX | expectations=... | interactions=... | findings=... | gaps=... | silences=... | run=...
+  return `VERAX | expectations=${expectations} | interactions=${interactions} | findings=${findings} | gaps=${gaps} | silences=${silences} | run=${runId}`;
+}
+
+/**
+ * Print CI one-line summary
+ * @param {Object} context - Summary context
+ */
+export function printCISummary(context) {
+  const summary = generateCISummary(context);
+  console.error(summary);
+}
+

package/src/verax/cli/context-explanation.js

@@ -0,0 +1,89 @@
+/**
+ * Wave 4.1 — Context Validation Explanation
+ * 
+ * Provides detailed explanations when context validation fails or matches.
+ */
+
+/**
+ * Generate context validation explanation
+ * @param {Object} contextCheck - Context check result
+ * @param {Array} projectRoutes - Routes extracted from project
+ * @returns {Array<string>} Explanation lines
+ */
+export function explainContextValidation(contextCheck, projectRoutes = []) {
+  const lines = [];
+  
+  if (!contextCheck.ran) {
+    if (contextCheck.reason === 'no_routes_extracted') {
+      lines.push('Context validation skipped: No routes extracted from project.');
+    } else if (contextCheck.reason === 'invalid_url') {
+      lines.push('Context validation skipped: Invalid URL format.');
+    } else {
+      lines.push('Context validation skipped.');
+    }
+    return lines;
+  }
+  
+  if (contextCheck.verdict === 'VALID_CONTEXT') {
+    lines.push(`✓ Context validated: URL matches project`);
+    lines.push(`  ${contextCheck.matchedRoutesCount} of ${contextCheck.totalRoutesChecked || projectRoutes.length} routes matched`);
+    if (contextCheck.sampleMatched && contextCheck.sampleMatched.length > 0) {
+      lines.push(`  Sample matched routes: ${contextCheck.sampleMatched.slice(0, 3).join(', ')}`);
+    }
+    return lines;
+  }
+  
+  // INVALID_CONTEXT or INVALID_CONTEXT_FORCED
+  lines.push(`⚠ Context mismatch: URL does not match project`);
+  lines.push(`  Project routes found: ${projectRoutes.length}`);
+  lines.push(`  Routes matched: ${contextCheck.matchedRoutesCount} of ${contextCheck.totalRoutesChecked || projectRoutes.length}`);
+  
+  if (projectRoutes.length > 0 && contextCheck.matchedRoutesCount === 0) {
+    lines.push('');
+    lines.push('  Project routes (sample):');
+    const sampleRoutes = projectRoutes.slice(0, 5);
+    for (const route of sampleRoutes) {
+      lines.push(`    - ${route}`);
+    }
+    
+    if (contextCheck.internalLinksFound !== undefined) {
+      lines.push(`  Live site internal links found: ${contextCheck.internalLinksFound}`);
+    }
+    
+    lines.push('');
+    lines.push('  Possible reasons:');
+    lines.push('    • Route paths don\'t match (e.g., /about vs /about.html)');
+    lines.push('    • Project routes not linked on homepage');
+    lines.push('    • SPA routes not accessible at expected paths');
+    
+    if (contextCheck.verdict === 'INVALID_CONTEXT') {
+      lines.push('');
+      lines.push('  Next steps:');
+      lines.push('    • Use --force to scan anyway');
+      lines.push('    • Verify URL matches project deployment');
+      lines.push('    • Check that routes exist on the live site');
+    } else {
+      lines.push('');
+      lines.push('  Scan continued with --force flag despite mismatch.');
+    }
+  }
+  
+  return lines;
+}
+
+/**
+ * Print context validation explanation
+ * @param {Object} contextCheck - Context check result
+ * @param {Array} projectRoutes - Routes extracted from project
+ */
+export function printContextExplanation(contextCheck, projectRoutes = []) {
+  const lines = explainContextValidation(contextCheck, projectRoutes);
+  if (lines.length > 0) {
+    console.error('');
+    console.error('Context Validation:');
+    lines.forEach(line => {
+      console.error(line);
+    });
+  }
+}
+

package/src/verax/cli/doctor.js

@@ -0,0 +1,277 @@
+/**
+ * Wave 7 — VERAX Doctor
+ * 
+ * Checks environment, dependencies, and project setup.
+ */
+
+import { mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { chromium } from 'playwright';
+import { get } from 'http';
+import { get as httpsGet } from 'https';
+import { learn } from '../index.js';
+
+/**
+ * Check Node version
+ * @returns {Object} { status: 'ok'|'warn'|'fail', message: string }
+ */
+function checkNodeVersion() {
+  const requiredMajor = 18;
+  const nodeVersion = process.version;
+  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  
+  if (majorVersion >= requiredMajor) {
+    return { status: 'ok', message: `Node.js ${nodeVersion} (required: >=${requiredMajor}.0.0)` };
+  } else {
+    return { 
+      status: 'fail', 
+      message: `Node.js ${nodeVersion} is too old (required: >=${requiredMajor}.0.0)`,
+      fix: `Upgrade Node.js: nvm install ${requiredMajor} or visit nodejs.org`
+    };
+  }
+}
+
+/**
+ * Check write permissions to output directory
+ * @param {string} projectRoot - Project root
+ * @returns {Object} { status: 'ok'|'fail', message: string }
+ */
+function checkWritePermissions(projectRoot) {
+  try {
+    const veraxDir = resolve(projectRoot, '.verax');
+    mkdirSync(veraxDir, { recursive: true });
+    
+    const testFile = resolve(veraxDir, '.write-test');
+    writeFileSync(testFile, 'test');
+    unlinkSync(testFile);
+    
+    return { status: 'ok', message: 'Can write to .verax directory' };
+  } catch (error) {
+    return {
+      status: 'fail',
+      message: `Cannot write to .verax directory: ${error.message}`,
+      fix: 'Check file permissions or run with appropriate access'
+    };
+  }
+}
+
+/**
+ * Check Playwright availability
+ * @returns {Promise<Object>} { status: 'ok'|'fail', message: string }
+ */
+async function checkPlaywright() {
+  try {
+    const browser = await chromium.launch({ headless: true });
+    await browser.close();
+    return { status: 'ok', message: 'Playwright browser is available' };
+  } catch (error) {
+    // Detect common error messages and provide specific fixes
+    const errorMsg = error.message.toLowerCase();
+    let fix = 'Run: npx playwright install';
+    
+    if (errorMsg.includes('chromium') || errorMsg.includes('executable')) {
+      fix = 'Run: npx playwright install chromium';
+    } else if (errorMsg.includes('missing') || errorMsg.includes('not found')) {
+      fix = 'Run: npx playwright install --with-deps chromium';
+    }
+    
+    return {
+      status: 'fail',
+      message: `Playwright browser not available: ${error.message}`,
+      fix: fix
+    };
+  }
+}
+
+/**
+ * Check project detection and expectations
+ * @param {string} projectRoot - Project root
+ * @returns {Promise<Object>} { status: 'ok'|'warn', message: string, details: Object }
+ */
+async function checkProjectExpectations(projectRoot) {
+  try {
+    const manifest = await learn(projectRoot);
+    const projectType = manifest.projectType || 'unknown';
+    const expectationsCount = manifest.learnTruth?.expectationsDiscovered || 0;
+    
+    if (expectationsCount > 0) {
+      return {
+        status: 'ok',
+        message: `Project type: ${projectType}, ${expectationsCount} expectations found`,
+        details: {
+          projectType,
+          expectationsCount,
+          routesCount: manifest.publicRoutes?.length || 0
+        }
+      };
+    } else {
+      return {
+        status: 'warn',
+        message: `Project type: ${projectType}, but 0 expectations found`,
+        details: {
+          projectType,
+          expectationsCount: 0
+        },
+        fix: 'Add static patterns (HTML links, static fetch calls, or state mutations)'
+      };
+    }
+  } catch (error) {
+    return {
+      status: 'fail',
+      message: `Failed to analyze project: ${error.message}`,
+      fix: 'Check that projectRoot is correct and project is readable'
+    };
+  }
+}
+
+/**
+ * Check URL reachability
+ * @param {string} url - URL to check
+ * @returns {Promise<Object>} { status: 'ok'|'fail', message: string }
+ */
+async function checkUrlReachability(url) {
+  return new Promise((resolve) => {
+    try {
+      const urlObj = new URL(url);
+      const clientGet = urlObj.protocol === 'https:' ? httpsGet : get;
+
+      const request = clientGet(url, { timeout: 5000 }, (response) => {
+        request.destroy();
+        if (response.statusCode >= 200 && response.statusCode < 400) {
+          resolve({ status: 'ok', message: `URL ${url} is reachable (${response.statusCode})` });
+        } else {
+          resolve({ 
+            status: 'warn', 
+            message: `URL ${url} returned ${response.statusCode}`,
+            fix: 'Verify URL is correct and server is running'
+          });
+        }
+      });
+      
+      request.on('error', (error) => {
+        resolve({
+          status: 'fail',
+          message: `Cannot reach ${url}: ${error.message}`,
+          fix: 'Ensure server is running and URL is correct'
+        });
+      });
+      
+      request.on('timeout', () => {
+        request.destroy();
+        resolve({
+          status: 'warn',
+          message: `URL ${url} did not respond within 5 seconds`,
+          fix: 'Check if server is running and accessible'
+        });
+      });
+      
+      request.setTimeout(5000);
+    } catch (error) {
+      resolve({
+        status: 'fail',
+        message: `Invalid URL: ${error.message}`,
+        fix: 'Provide a valid URL (e.g., http://localhost:3000)'
+      });
+    }
+  });
+}
+
+/**
+ * Run doctor checks
+ * @param {Object} options - { projectRoot, url, json }
+ * @returns {Promise<Object>} Doctor results
+ */
+export async function runDoctor(options = {}) {
+  const { projectRoot = process.cwd(), url = null, json: _json = false } = options;
+  
+  const checks = [];
+  let overallStatus = 'ok';
+  
+  // Check 1: Node version
+  const nodeCheck = checkNodeVersion();
+  checks.push({ name: 'Node.js Version', ...nodeCheck });
+  if (nodeCheck.status === 'fail') overallStatus = 'fail';
+  
+  // Check 2: Write permissions
+  const writeCheck = checkWritePermissions(projectRoot);
+  checks.push({ name: 'Write Permissions', ...writeCheck });
+  if (writeCheck.status === 'fail') overallStatus = 'fail';
+  
+  // Check 3: Playwright
+  const playwrightCheck = await checkPlaywright();
+  checks.push({ name: 'Playwright Browser', ...playwrightCheck });
+  if (playwrightCheck.status === 'fail') overallStatus = 'fail';
+  
+  // Check 4: Project expectations
+  const projectCheck = await checkProjectExpectations(projectRoot);
+  checks.push({ name: 'Project Analysis', ...projectCheck });
+  if (projectCheck.status === 'fail') overallStatus = 'fail';
+  else if (projectCheck.status === 'warn' && overallStatus === 'ok') overallStatus = 'warn';
+  
+  // Check 5: URL reachability (if provided)
+  if (url) {
+    const urlCheck = await checkUrlReachability(url);
+    checks.push({ name: 'URL Reachability', ...urlCheck });
+    if (urlCheck.status === 'fail') overallStatus = 'fail';
+    else if (urlCheck.status === 'warn' && overallStatus === 'ok') overallStatus = 'warn';
+  }
+  
+  // Collect fixes
+  const fixes = checks.filter(c => c.fix).map(c => c.fix);
+  
+  return {
+    status: overallStatus,
+    checks,
+    fixes
+  };
+}
+
+/**
+ * Print doctor results
+ * @param {Object} results - Doctor results
+ * @param {boolean} json - Whether to output JSON
+ */
+export function printDoctorResults(results, json = false) {
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  
+  // Human-readable output
+  console.error('\n' + '═'.repeat(60));
+  console.error('VERAX Doctor');
+  console.error('═'.repeat(60));
+  
+  const statusEmoji = {
+    'ok': '✅',
+    'warn': '⚠️',
+    'fail': '❌'
+  };
+  
+  for (const check of results.checks) {
+    const emoji = statusEmoji[check.status] || '❓';
+    console.error(`\n${emoji} ${check.name}`);
+    console.error(`   ${check.message}`);
+    if (check.details) {
+      for (const [key, value] of Object.entries(check.details)) {
+        console.error(`   ${key}: ${value}`);
+      }
+    }
+    if (check.fix) {
+      console.error(`   Fix: ${check.fix}`);
+    }
+  }
+  
+  console.error('\n' + '─'.repeat(60));
+  console.error(`Overall Status: ${results.status.toUpperCase()}`);
+  
+  if (results.fixes.length > 0) {
+    console.error('\nRecommended Fixes:');
+    results.fixes.forEach((fix, index) => {
+      console.error(`  ${index + 1}. ${fix}`);
+    });
+  }
+  
+  console.error('═'.repeat(60) + '\n');
+}
+

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