@veraxhq/verax 0.2.0 → 0.3.0

package/src/cli/entry.js

@@ -3,6 +3,11 @@
 /**
  * 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)
@@ -22,11 +27,47 @@ 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 { getExitCode, UsageError, DataError, CrashError } from './util/errors.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('========================');
+}
+
 // Read package.json for version
 function getVersion() {
   try {
@@ -38,84 +79,263 @@ function getVersion() {
   }
 }
 
-async function main() {
-  const args = process.argv.slice(2);
+/**
+ * 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' };
+  }
   
-  try {
-    // Handle --version
-    if (args.includes('--version') || args.includes('-v')) {
-      console.log(`verax ${getVersion()}`);
-      process.exit(0);
+  // 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');
     }
-    
-    // Handle explicit --help
-    if (args.includes('--help') || args.includes('-h')) {
-      showHelp();
-      process.exit(0);
+    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
+    };
+  }
+  
+  // 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');
     }
-    
-    // If no args, run default command
-    if (args.length === 0) {
-      await defaultCommand({});
-      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')
     }
+  };
+}
+
+/**
+ * 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);
     
-    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');
-      }
-      
-      const result = await runCommand({ url, src, out, json, verbose });
-      process.exit(0);
+    if (isInspectionCommand) {
+      enableInspectionMode();
     }
     
-    // Handle 'inspect' command
-    if (command === 'inspect') {
-      if (args.length < 2) {
-        throw new UsageError('inspect command requires a run path argument');
+    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}`);
+      }
+    } finally {
+      if (isInspectionCommand) {
+        disableInspectionMode();
       }
-      
-      const runPath = args[1];
-      const json = args.includes('--json');
-      
-      const result = await inspectCommand(runPath, { json });
-      process.exit(0);
-    }
-
-    // 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 result = await doctorCommand({ json, extraFlags });
-      process.exit(0);
     }
-    
-    // Handle 'help' command
-    if (command === 'help' || command === '--help' || command === '-h') {
-      showHelp();
-      process.exit(0);
+  } catch (error) {
+    // Print error message
+    if (error.message) {
+      console.error(`Error: ${error.message}`);
     }
     
-    // Default command: smart scanning mode
-    // Options can be passed as flags before/after the default command position
-    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');
+    // 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);
     
-    const result = await defaultCommand({ url, src, out, json, verbose });
-    process.exit(0);
+    // PHASE B: Dispatch with isolation enforcement
+    await dispatch(parsed);
   } catch (error) {
     // Print error message
     if (error.message) {
@@ -130,24 +350,41 @@ 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: .)
+  --src <path>       Source directory (default: .) — required; URL-only scans are blocked
   --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

@@ -0,0 +1,179 @@
+/**
+ * PHASE 20 — Angular Component Extractor
+ * 
+ * Extracts component metadata, template, and class content from Angular TypeScript files.
+ * Handles @Component decorators, template files, and component class methods.
+ * Deterministic and robust (no external runtime execution).
+ */
+
+/**
+ * PHASE 20: Extract Angular component metadata
+ * 
+ * @param {string} content - Full .ts file content
+ * @param {string} filePath - Path to the .ts file (for context)
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} { componentClass: {content, startLine}, template: {content, path, isInline}, decorator: {content, startLine} }
+ */
+export function extractAngularComponent(content, filePath, projectRoot) {
+  const result = {
+    componentClass: null,
+    template: null,
+    decorator: null,
+  };
+  
+  try {
+    // Extract @Component decorator
+    const decoratorRegex = /@Component\s*\(\s*\{([\s\S]*?)\}\s*\)/;
+    const decoratorMatch = content.match(decoratorRegex);
+    
+    if (decoratorMatch) {
+      const decoratorContent = decoratorMatch[0];
+      const decoratorConfig = decoratorMatch[1];
+      const beforeDecorator = content.substring(0, decoratorMatch.index);
+      const decoratorStartLine = (beforeDecorator.match(/\n/g) || []).length + 1;
+      
+      result.decorator = {
+        content: decoratorConfig,
+        startLine: decoratorStartLine,
+      };
+      
+      // Extract template (inline or external file)
+      const templateMatch = decoratorConfig.match(/template\s*:\s*['"`]([\s\S]*?)['"`]/);
+      const templateUrlMatch = decoratorConfig.match(/templateUrl\s*:\s*['"`]([^'"`]+)['"`]/);
+      
+      if (templateMatch) {
+        // Inline template
+        result.template = {
+          content: templateMatch[1],
+          path: filePath,
+          isInline: true,
+        };
+      } else if (templateUrlMatch) {
+        // External template file
+        const templateUrl = templateUrlMatch[1];
+        const templatePath = resolveTemplatePath(templateUrl, filePath, projectRoot);
+        result.template = {
+          path: templatePath,
+          isInline: false,
+        };
+      }
+    }
+    
+    // Extract component class
+    const classRegex = /export\s+class\s+(\w+)\s*(?:extends\s+\w+)?\s*\{([\s\S]*?)\n\}/;
+    const classMatch = content.match(classRegex);
+    
+    if (classMatch) {
+      const beforeClass = content.substring(0, classMatch.index);
+      const classStartLine = (beforeClass.match(/\n/g) || []).length + 1;
+      
+      result.componentClass = {
+        content: classMatch[2],
+        className: classMatch[1],
+        startLine: classStartLine,
+      };
+    }
+  } catch (error) {
+    // Skip if extraction fails
+  }
+  
+  return result;
+}
+
+/**
+ * Resolve template path from templateUrl
+ * 
+ * @param {string} templateUrl - Template URL from decorator
+ * @param {string} componentPath - Path to component file
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Resolved template path
+ */
+function resolveTemplatePath(templateUrl, componentPath, projectRoot) {
+  const { join, dirname, resolve } = require('path');
+  
+  if (templateUrl.startsWith('./') || templateUrl.startsWith('../')) {
+    // Relative path
+    return resolve(dirname(componentPath), templateUrl);
+  } else {
+    // Absolute path from project root
+    return resolve(projectRoot, templateUrl);
+  }
+}
+
+/**
+ * Extract template bindings from Angular template
+ * Detects event handlers, property bindings, and structural directives
+ * 
+ * @param {string} templateContent - Template content
+ * @returns {Object} { eventHandlers: [], propertyBindings: [], structuralDirectives: [] }
+ */
+export function extractTemplateBindings(templateContent) {
+  const eventHandlers = [];
+  const propertyBindings = [];
+  const structuralDirectives = [];
+  
+  // Extract event handlers: (click)="handler()", (submit)="onSubmit()"
+  const eventHandlerRegex = /\((\w+)\)\s*=\s*["']([^"']+)["']/g;
+  let handlerMatch;
+  while ((handlerMatch = eventHandlerRegex.exec(templateContent)) !== null) {
+    eventHandlers.push({
+      event: handlerMatch[1],
+      handler: handlerMatch[2],
+      line: (templateContent.substring(0, handlerMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  // Extract property bindings: [property]="value", [disabled]="isDisabled"
+  const propertyBindingRegex = /\[(\w+)\]\s*=\s*["']([^"']+)["']/g;
+  let bindingMatch;
+  while ((bindingMatch = propertyBindingRegex.exec(templateContent)) !== null) {
+    propertyBindings.push({
+      property: bindingMatch[1],
+      value: bindingMatch[2],
+      line: (templateContent.substring(0, bindingMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  // Extract structural directives: *ngIf="condition", *ngFor="item of items"
+  const structuralDirectiveRegex = /\*ng(If|For|Switch)\s*=\s*["']([^"']+)["']/g;
+  let directiveMatch;
+  while ((directiveMatch = structuralDirectiveRegex.exec(templateContent)) !== null) {
+    structuralDirectives.push({
+      directive: directiveMatch[1],
+      expression: directiveMatch[2],
+      line: (templateContent.substring(0, directiveMatch.index).match(/\n/g) || []).length + 1,
+    });
+  }
+  
+  return {
+    eventHandlers,
+    propertyBindings,
+    structuralDirectives,
+  };
+}
+
+/**
+ * Map template handlers to component class methods
+ * 
+ * @param {Array} eventHandlers - Event handlers from template
+ * @param {string} classContent - Component class content
+ * @returns {Array} Mapped handlers with method references
+ */
+export function mapTemplateHandlersToClass(eventHandlers, classContent) {
+  return eventHandlers.map(handler => {
+    // Extract method name from handler expression
+    const methodName = handler.handler.split('(')[0].trim();
+    
+    // Try to find method definition in class
+    const methodRegex = new RegExp(`(?:public|private|protected)?\\s*(?:async\\s+)?${methodName}\\s*\\(`, 'g');
+    const methodMatch = methodRegex.exec(classContent);
+    
+    return {
+      ...handler,
+      methodName,
+      methodFound: !!methodMatch,
+      methodLine: methodMatch ? (classContent.substring(0, methodMatch.index).match(/\n/g) || []).length + 1 : null,
+    };
+  });
+}
+