@veraxhq/verax 0.3.0 → 0.4.0

package/src/cli/entry.js

@@ -3,13 +3,7 @@
 /**
  * VERAX CLI Entry Point
  * 
- * PHASE 21.6.1: Two-Phase CLI Bootstrap
- * 
- * Phase A: Raw argv parsing with zero side effects
- * Phase B: Dispatch - inspection commands bypass execution bootstrap
- * 
  * Commands:
- * - verax                    (smart default with URL detection/prompting)
  * - verax run --url <url>    (strict, non-interactive)
  * - verax inspect <runPath>  (read and display run summary)
  * 
@@ -18,324 +12,121 @@
  * - 2:  internal crash
  * - 64: invalid CLI usage
  * - 65: invalid input data
+ * 
+ * DESIGN: Lazy imports for heavy modules
+ * --version and --help are fast and don't load Playwright or observation-engine
+ * Heavy modules are only loaded when running actual commands (run, inspect, doctor)
  */
 
 import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 import { readFileSync } from 'fs';
-import { defaultCommand } from './commands/default.js';
-import { runCommand } from './commands/run.js';
-import { inspectCommand } from './commands/inspect.js';
-import { doctorCommand } from './commands/doctor.js';
-import { gatesCommand } from './commands/gates.js';
-import { gaCommand } from './commands/ga.js';
-import { releaseCheckCommand } from './commands/release-check.js';
-import { securityCheckCommand } from './commands/security-check.js';
-import { baselineCommand } from './commands/baseline.js';
-import { truthCommand } from './commands/truth.js';
 import { getExitCode, UsageError } from './util/errors.js';
-import { getSourceCodeRequirementBanner } from '../verax/core/product-definition.js';
-import { enableInspectionMode, disableInspectionMode } from './util/bootstrap-guard.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/**
- * PHASE 21.6.1: CLI Self-Identification
- * Prints diagnostic information to identify which binary is executed
- */
-function printCLIIdentity(args) {
-  const verbose = args.includes('--verbose');
-  const debugCli = process.env.VERAX_DEBUG_CLI === '1';
-  
-  if (!verbose && !debugCli) {
-    return;
-  }
-  
-  console.error('=== VERAX CLI IDENTITY ===');
-  console.error(`process.argv[1]: ${process.argv[1]}`);
-  console.error(`__filename: ${__filename}`);
-  
-  try {
-    const pkgPath = resolve(__dirname, '../../package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-    console.error(`package.json version: ${pkg.version}`);
-    console.error(`package.json location: ${pkgPath}`);
-  } catch (error) {
-    console.error(`Failed to read package.json: ${error.message}`);
-  }
-  
-  console.error('========================');
+// Lazy loaders for heavy modules (loaded only when needed)
+async function loadRunCommand() {
+  const mod = await import('./commands/run.js');
+  return mod.runCommand;
+}
+
+async function loadInspectCommand() {
+  const mod = await import('./commands/inspect.js');
+  return mod.inspectCommand;
+}
+
+async function loadDoctorCommand() {
+  const mod = await import('./commands/doctor.js');
+  return mod.doctorCommand;
 }
 
 // Read package.json for version
 function getVersion() {
   try {
     const pkgPath = resolve(__dirname, '../../package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  // @ts-expect-error - readFileSync with encoding returns string
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
     return pkg.version;
   } catch {
     return 'unknown';
   }
 }
 
-/**
- * PHASE A: Raw argv parsing with zero side effects
- * 
- * @param {string[]} args - Raw command line arguments
- * @returns {Object} Parsed command structure
- */
-function parseCommand(args) {
-  // Handle --version (no side effects)
-  if (args.includes('--version') || args.includes('-v')) {
-    return { type: 'version' };
-  }
-  
-  // Handle explicit --help (no side effects)
-  if (args.includes('--help') || args.includes('-h')) {
-    return { type: 'help' };
-  }
-  
-  // If no args, default to smart mode
-  if (args.length === 0) {
-    return { type: 'default', options: {} };
-  }
-  
-  const command = args[0];
-  
-  // Inspection commands (must bypass execution bootstrap)
-  if (command === 'inspect') {
-    if (args.length < 2) {
-      throw new UsageError('inspect command requires a run path argument');
-    }
-    return {
-      type: 'inspect',
-      runPath: args[1],
-      json: args.includes('--json'),
-      timeline: args.includes('--timeline'),
-      decisions: args.includes('--decisions'),
-      failures: args.includes('--failures'),
-      performance: args.includes('--performance'),
-      evidence: args.includes('--evidence')
-    };
-  }
-  
-  if (command === 'gates') {
-    return {
-      type: 'gates',
-      json: args.includes('--json'),
-      verbose: args.includes('--verbose')
-    };
-  }
-  
-  if (command === 'ga') {
-    return {
-      type: 'ga',
-      runId: parseArg(args, '--run-id'),
-      json: args.includes('--json')
-    };
-  }
-  
-  if (command === 'release:check' || command === 'release-check') {
-    return {
-      type: 'release:check',
-      json: args.includes('--json')
-    };
-  }
-  
-  if (command === 'security:check' || command === 'security-check') {
-    return {
-      type: 'security:check',
-      json: args.includes('--json')
-    };
-  }
-  
-  if (command === 'baseline') {
-    return {
-      type: 'baseline',
-      json: args.includes('--json')
-    };
-  }
-  
-  if (command === 'truth') {
-    return {
-      type: 'truth',
-      runId: parseArg(args, '--run-id'),
-      json: args.includes('--json')
-    };
-  }
-  
-  if (command === 'doctor') {
-    const allowedFlags = new Set(['--json']);
-    const extraFlags = args.slice(1).filter((a) => a.startsWith('-') && !allowedFlags.has(a));
-    return {
-      type: 'doctor',
-      json: args.includes('--json'),
-      extraFlags
-    };
-  }
+async function main() {
+  const args = process.argv.slice(2);
   
-  // Execution commands
-  if (command === 'run') {
-    const url = parseArg(args, '--url');
-    const fixture = parseArg(args, '--fixture');
-    if (!url && !fixture) {
-      throw new UsageError('run command requires --url <url> or --fixture <fixture> argument');
+  try {
+    // Handle --version
+    if (args.includes('--version') || args.includes('-v')) {
+      console.log(`verax ${getVersion()}`);
+      process.exit(0);
     }
-    return {
-      type: 'run',
-      url,
-      fixture,
-      src: parseArg(args, '--src') || '.',
-      out: parseArg(args, '--out') || '.verax',
-      json: args.includes('--json'),
-      verbose: args.includes('--verbose'),
-      determinism: args.includes('--determinism'),
-      determinismRuns: args.includes('--determinism') ? parseInt(parseArg(args, '--determinism-runs') || '2', 10) : 0
-    };
-  }
-  
-  if (command === 'help' || command === '--help' || command === '-h') {
-    return { type: 'help' };
-  }
-  
-  // Default command: smart scanning mode
-  return {
-    type: 'default',
-    options: {
-      url: parseArg(args, '--url'),
-      src: parseArg(args, '--src') || '.',
-      out: parseArg(args, '--out') || '.verax',
-      json: args.includes('--json'),
-      verbose: args.includes('--verbose')
+    
+    // Handle explicit --help
+    if (args.includes('--help') || args.includes('-h')) {
+      showHelp();
+      process.exit(0);
     }
-  };
-}
-
-/**
- * PHASE B: Dispatch with isolation enforcement
- * 
- * @param {Object} parsed - Parsed command from Phase A
- */
-async function dispatch(parsed) {
-  try {
-    // Inspection commands: enable guard mode
-    const isInspectionCommand = ['inspect', 'gates', 'ga', 'doctor', 'release:check', 'security:check', 'baseline', 'truth'].includes(parsed.type);
     
-    if (isInspectionCommand) {
-      enableInspectionMode();
+    // If no args, show help (no interactive mode)
+    if (args.length === 0) {
+      showHelp();
+      process.exit(64);
     }
     
-    try {
-      switch (parsed.type) {
-        case 'version':
-          console.log(`verax ${getVersion()}`);
-          process.exit(0);
-          break;
-          
-        case 'help':
-          showHelp();
-          process.exit(0);
-          break;
-          
-        case 'inspect':
-          await inspectCommand(parsed.runPath, { 
-            json: parsed.json,
-            timeline: parsed.timeline,
-            decisions: parsed.decisions,
-            failures: parsed.failures,
-            performance: parsed.performance,
-            evidence: parsed.evidence
-          });
-          process.exit(0);
-          break;
-          
-        case 'gates':
-          await gatesCommand({ json: parsed.json, verbose: parsed.verbose });
-          // gatesCommand handles exit code internally
-          return;
-          
-        case 'ga':
-          await gaCommand({ runId: parsed.runId, json: parsed.json });
-          // gaCommand handles exit code internally
-          return;
-          
-        case 'release:check':
-          await releaseCheckCommand({ json: parsed.json });
-          // releaseCheckCommand handles exit code internally
-          return;
-          
-        case 'security:check':
-          await securityCheckCommand({ json: parsed.json });
-          // securityCheckCommand handles exit code internally
-          return;
-          
-        case 'baseline':
-          await baselineCommand(process.cwd(), { json: parsed.json });
-          process.exit(0);
-          break;
-          
-        case 'truth':
-          await truthCommand(process.cwd(), { json: parsed.json, runId: parsed.runId });
-          process.exit(0);
-          break;
-          
-        case 'doctor':
-          await doctorCommand({ json: parsed.json, extraFlags: parsed.extraFlags });
-          process.exit(0);
-          break;
-          
-        case 'run':
-          await runCommand({
-            url: parsed.url,
-            fixture: parsed.fixture,
-            src: parsed.src,
-            out: parsed.out,
-            json: parsed.json,
-            verbose: parsed.verbose,
-            determinism: parsed.determinism,
-            determinismRuns: parsed.determinismRuns
-          });
-          process.exit(0);
-          break;
-          
-        case 'default':
-          await defaultCommand(parsed.options);
-          process.exit(0);
-          break;
-          
-        default:
-          throw new UsageError(`Unknown command: ${parsed.type}`);
+    const command = args[0];
+    
+    // Handle 'run' command
+    if (command === 'run') {
+      const url = parseArg(args, '--url');
+      const src = parseArg(args, '--src') || '.';
+      const out = parseArg(args, '--out') || '.verax';
+      const json = args.includes('--json');
+      const verbose = args.includes('--verbose');
+      
+      if (!url) {
+        throw new UsageError('run command requires --url <url> argument');
       }
-    } finally {
-      if (isInspectionCommand) {
-        disableInspectionMode();
+      
+      const runCommand = await loadRunCommand();
+      await runCommand({ url, src, out, json, verbose });
+      process.exit(0);
+    }
+    
+    // Handle 'inspect' command
+    if (command === 'inspect') {
+      if (args.length < 2) {
+        throw new UsageError('inspect command requires a run path argument');
       }
+      
+      const runPath = args[1];
+      const json = args.includes('--json');
+      
+      const inspectCommand = await loadInspectCommand();
+      await inspectCommand(runPath, { json });
+      process.exit(0);
     }
-  } catch (error) {
-    // Print error message
-    if (error.message) {
-      console.error(`Error: ${error.message}`);
+
+    // Handle 'doctor' command
+    if (command === 'doctor') {
+      const allowedFlags = new Set(['--json']);
+      const extraFlags = args.slice(1).filter((a) => a.startsWith('-') && !allowedFlags.has(a));
+      const json = args.includes('--json');
+      const doctorCommand = await loadDoctorCommand();
+      await doctorCommand({ json, extraFlags });
+      process.exit(0);
     }
     
-    // Get exit code
-    const exitCode = getExitCode(error);
-    process.exit(exitCode);
-  }
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  
-  // PHASE 21.6.1: Print CLI identity for debugging
-  printCLIIdentity(args);
-  
-  try {
-    // PHASE A: Parse command (zero side effects)
-    const parsed = parseCommand(args);
+    // Handle 'help' command
+    if (command === 'help' || command === '--help' || command === '-h') {
+      showHelp();
+      process.exit(0);
+    }
     
-    // PHASE B: Dispatch with isolation enforcement
-    await dispatch(parsed);
+    // Interactive mode removed
+    throw new UsageError('Interactive mode is disabled. Use: verax run --url <url>');
   } catch (error) {
     // Print error message
     if (error.message) {
@@ -350,41 +141,23 @@ async function main() {
 
 function showHelp() {
   const version = getVersion();
-  const banner = getSourceCodeRequirementBanner();
   console.log(`
 verax ${version}
 VERAX — Silent failure detection for websites
 
- ${banner}
- Canonical product contract: docs/README.md
-
 USAGE:
-  verax [options]                              Smart mode (detects/prompts for URL)
   verax run --url <url> [options]             Strict mode (non-interactive, CI-friendly)
   verax inspect <runPath> [--json]            Inspect an existing run
-  verax inspect <runPath> --timeline         Show chronological timeline
-  verax inspect <runPath> --decisions         Show decision trace
-  verax inspect <runPath> --failures          Show failure ledger
-  verax inspect <runPath> --performance       Show performance metrics
-  verax inspect <runPath> --evidence          Show evidence cross-index
   verax doctor [--json]                       Diagnose local environment
-  verax gates [--json] [--verbose]            Evaluate capability gates (PHASE 19)
-  verax ga [--run-id <id>] [--json]            Evaluate GA readiness (PHASE 21.6)
-  verax release:check [--json]                Check release readiness (PHASE 21.7)
-  verax security:check [--json]               Check security baseline (PHASE 21.8)
-  verax baseline [--json]                     Show baseline hash and drift status (PHASE 21.11)
-  verax truth [--run-id <id>] [--json]         Show truth certificate (PHASE 21.11)
   verax --version                              Show version
   verax --help                                 Show this help
 
 OPTIONS:
   --url <url>        Target URL to scan
-  --src <path>       Source directory (default: .) — required; URL-only scans are blocked
+  --src <path>       Source directory (default: .)
   --out <path>       Output directory for artifacts (default: .verax)
   --json             Output as JSON lines (progress events)
   --verbose          Verbose output
-  --determinism      Run determinism check (executes scan multiple times and compares results)
-  --determinism-runs <N>  Number of runs for determinism check (default: 2)
   --help             Show this help
   --version          Show version
 

package/src/cli/util/angular-component-extractor.js

@@ -27,7 +27,7 @@ export function extractAngularComponent(content, filePath, projectRoot) {
     const decoratorMatch = content.match(decoratorRegex);
     
     if (decoratorMatch) {
-      const decoratorContent = decoratorMatch[0];
+      const _decoratorContent = decoratorMatch[0];
       const decoratorConfig = decoratorMatch[1];
       const beforeDecorator = content.substring(0, decoratorMatch.index);
       const decoratorStartLine = (beforeDecorator.match(/\n/g) || []).length + 1;
@@ -89,7 +89,7 @@ export function extractAngularComponent(content, filePath, projectRoot) {
  * @returns {string} Resolved template path
  */
 function resolveTemplatePath(templateUrl, componentPath, projectRoot) {
-  const { join, dirname, resolve } = require('path');
+  const { join: _join, dirname, resolve } = require('path');
   
   if (templateUrl.startsWith('./') || templateUrl.startsWith('../')) {
     // Relative path

package/src/cli/util/angular-navigation-detector.js

@@ -7,7 +7,7 @@
  * - ActivatedRoute navigation
  */
 
-import { extractAngularComponent, extractTemplateBindings, mapTemplateHandlersToClass } from './angular-component-extractor.js';
+import { extractAngularComponent, extractTemplateBindings, mapTemplateHandlersToClass } from './angular-component-extractor.js'; // eslint-disable-line no-unused-vars
 import { parse } from '@babel/parser';
 import traverse from '@babel/traverse';
 import { readFileSync, existsSync } from 'fs';
@@ -37,7 +37,7 @@ export function detectAngularNavigation(filePath, content, projectRoot) {
       }
       
       if (templateContent) {
-        const templateBindings = extractTemplateBindings(templateContent);
+        const _templateBindings = extractTemplateBindings(templateContent);
         
         // Extract routerLink directives
         const routerLinkRegex = /routerLink\s*=\s*["']([^"']+)["']/g;

package/src/cli/util/ast-interactive-detector.js

@@ -23,11 +23,11 @@ const traverse = _traverse.default || _traverse;
 /**
  * Detect interactive elements without href and their navigation promises
  * @param {string} content - File content
- * @param {string} filePath - Absolute file path
- * @param {string} relPath - Relative path from source root
+ * @param {string} _filePath - Absolute file path (unused)
+ * @param {string} _relPath - Relative path from source root (unused)
  * @returns {Array} Array of interactive element detections with navigation promises
  */
-export function detectInteractiveElementsAST(content, filePath, relPath) {
+export function detectInteractiveElementsAST(content, _filePath, _relPath) {
   const detections = [];
   const lines = content.split('\n');
   
@@ -183,8 +183,6 @@ export function detectInteractiveElementsAST(content, filePath, relPath) {
               handlerLoc = handlerSource.loc;
             } else if (handlerSource.expression?.loc) {
               handlerLoc = handlerSource.expression.loc;
-            } else if (handlerSource.type === 'JSXExpressionContainer' && handlerSource.expression?.loc) {
-              handlerLoc = handlerSource.expression.loc;
             }
           }
           const astSource = handlerSource ? extractASTSource(handlerSource, lines, handlerLoc) : null;
@@ -411,7 +409,7 @@ function extractStringValue(node) {
 /**
  * Extract selector hint from JSX element
  */
-function extractSelectorHint(node, path) {
+function extractSelectorHint(node, _path) {
   let selector = node.name.name || '';
   
   // Check for id attribute

package/src/cli/util/ast-network-detector.js

@@ -23,11 +23,11 @@ const traverse = _traverse.default || _traverse;
 /**
  * Detect network calls in source code using AST parsing
  * @param {string} content - File content
- * @param {string} filePath - Absolute file path
- * @param {string} relPath - Relative path from source root
+ * @param {string} _filePath - Absolute file path (unused)
+ * @param {string} _relPath - Relative path from source root (unused)
  * @returns {Array} Array of detected network calls with metadata including AST source
  */
-export function detectNetworkCallsAST(content, filePath, relPath) {
+export function detectNetworkCallsAST(content, _filePath, _relPath) {
   const detections = [];
   const lines = content.split('\n');