arcvision 0.2.12 → 0.2.15

package/src/index.js

@@ -0,0 +1,830 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const zlib = require('zlib');
+const scanner = require('./core/scanner');
+const { generateDiffSummary } = require('./core/diff-analyzer');
+const { ChunkedUploader } = require('./core/chunked-uploader');
+const CompressionUtil = require('./core/compression');
+const ProgressTracker = require('./core/progress-tracker');
+const RetryHandler = require('./core/retry-handler');
+// Import new ACIG components
+const { invariantRegistry } = require('./core/invariant-registry');
+const { evaluateChange } = require('./core/change-evaluator');
+// Import authority gate components
+const { authorityLedger } = require('./core/authority-ledger');
+const { overrideHandler } = require('./core/override-handler');
+// Import robust validation and error handling
+const { cliValidator } = require('./core/cli-validator');
+const { cliErrorHandler } = require('./core/cli-error-handler');
+
+// Get version from package.json
+// Use a try-catch to handle bundled environment
+let version = '1.0.0'; // fallback version
+try {
+  // Try to get the package.json path relative to the bundled file
+  const packageJsonPath = path.join(__dirname, '../package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  version = packageJson.version;
+} catch (error) {
+  // Fallback to 1.0.0 if package.json cannot be found
+  // This can happen in bundled environments
+  console.warn('Warning: Could not load version from package.json, using default');
+}
+
+const CONFIG_FILE = path.join(os.homedir(), '.arcvisionrc');
+const API_URL = process.env.ARCVISION_API_URL || 'https://arcvisiondev.vercel.app';
+
+// Blast radius analysis
+const { findHighestBlastRadius, getTopBlastRadiusFiles, computeBlastRadiusWithPercentage } = require('./core/blastRadius');
+
+function analyzeBlastRadius(architectureMap) {
+  // Extract blast radius information from nodes
+  // Handle both old and new schema formats
+  const blastRadiusData = [];
+
+  if (architectureMap.nodes && architectureMap.nodes.length > 0) {
+    // Check if nodes have the old format (with metadata) or new format
+    architectureMap.nodes.forEach(node => {
+      let blastRadius = 0;
+
+      // Try to get blast radius from different possible locations
+      if (node.blast_radius !== undefined) {
+        // Current format: blast_radius is a direct property
+        blastRadius = node.blast_radius;
+      } else if (node.metadata && node.metadata.blast_radius !== undefined) {
+        // Old format
+        blastRadius = node.metadata.blast_radius;
+      } else if (node.signals && node.signals.blast_radius !== undefined) {
+        // New format: blast_radius is in the signals object
+        blastRadius = node.signals.blast_radius;
+      } else if (architectureMap.contextSurface && architectureMap.contextSurface.topBlastRadiusFiles) {
+        // Get from contextSurface if available
+        const foundFile = architectureMap.contextSurface.topBlastRadiusFiles.find(f => f.file === node.path || f.file === node.id);
+        if (foundFile) {
+          blastRadius = foundFile.blastRadius || 0;
+        }
+      }
+
+      blastRadiusData.push({
+        file: node.path || node.id, // Use path if available, otherwise id
+        blast_radius: blastRadius
+      });
+    });
+  }
+
+  const blastRadiusMap = blastRadiusData.reduce((acc, item) => {
+    acc[item.file] = item.blast_radius;
+    return acc;
+  }, {});
+
+  const totalFiles = architectureMap.nodes ? architectureMap.nodes.length : 0;
+
+  // Get top 3 files by blast radius with percentages
+  const topFiles = computeBlastRadiusWithPercentage(blastRadiusMap, totalFiles);
+
+  return {
+    topFiles: topFiles.slice(0, 3),
+    totalFiles: totalFiles
+  };
+}
+
+function saveToken(token) {
+  try {
+    // Validate token format before saving
+    if (!token || typeof token !== 'string' || token.length < 10) {
+      throw new Error('Invalid token format: Token must be a string with at least 10 characters');
+    }
+    
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify({ token }));
+    console.log(chalk.green('✅ Token saved successfully!'));
+  } catch (error) {
+    cliErrorHandler.handleFatalError(error, {
+      operation: 'save_token',
+      file: CONFIG_FILE
+    });
+  }
+}
+
+function getToken() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+      return config.token;
+    }
+  } catch (error) {
+    console.error(chalk.red('❌ Failed to read token configuration:'), error.message);
+    console.error(chalk.yellow('Token file may be corrupted. Run `arcvision link <TOKEN>` to reset.'));
+    return null;
+  }
+  return null;
+}
+
+// Function to upload JSON to database via Token
+async function uploadToDatabase(jsonData) {
+  const token = getToken();
+  if (!token) {
+    console.log(chalk.red('❌ No upload token found.'));
+    console.log(chalk.yellow('Run `arcvision link <TOKEN>` first to connect to a project.'));
+    process.exit(1);
+  }
+
+  try {
+    // Pre-flight validation for upload
+    await cliValidator.preFlightValidation('upload', {
+      contextData: jsonData,
+      token: token
+    });
+
+    console.log(chalk.blue(`Starting upload to ${API_URL}/api/upload...`));
+    
+    // Check the size of the data and decide on strategy
+    const originalSize = Buffer.byteLength(JSON.stringify(jsonData));
+    const sizeInMB = Math.round(originalSize / (1024 * 1024));
+    
+    console.log(chalk.yellow(`Data size: ~${sizeInMB} MB`));
+    
+    // Determine if we need to use compression or chunked upload
+    const needsChunkedUpload = sizeInMB > 3; // Use chunked upload for data > 3MB
+    const needsCompression = CompressionUtil.needsCompression(jsonData, 1024 * 1024 * 2); // Compress if > 2MB
+
+    if (needsCompression) {
+      console.log(chalk.yellow('Compressing data to reduce payload size...'));
+      const compressionRatio = await CompressionUtil.getCompressionRatio(jsonData);
+      console.log(chalk.yellow(`Compression ratio: ${compressionRatio.ratio.toFixed(2)}x (${compressionRatio.percentage}% reduction)`));
+      
+      const compressedData = await CompressionUtil.compress(jsonData);
+      
+      // Check if compressed data still needs chunked upload
+      const compressedSize = Buffer.byteLength(compressedData);
+      const compressedSizeInMB = Math.round(compressedSize / (1024 * 1024));
+      
+      console.log(chalk.yellow(`Compressed size: ~${compressedSizeInMB} MB`));
+      
+      if (compressedSizeInMB > 3 || needsChunkedUpload) {
+        // Use chunked upload for compressed data
+        console.log(chalk.blue('Using chunked upload for large compressed data...'));
+        
+        const chunkedUploader = new ChunkedUploader();
+        const retryHandler = new RetryHandler(2, 2000, 2); // 2 retries, 2s base delay, 2x multiplier
+        
+        // Execute with retry mechanism
+        const result = await retryHandler.executeWithRetry(async () => {
+          return await chunkedUploader.uploadInChunks(
+            { graph: compressedData, compressed: true },
+            token,
+            API_URL
+          );
+        }, 'chunked upload');
+        
+        if (result.success) {
+          console.log(chalk.green('✅ Graph uploaded successfully using chunked upload!'));
+        } else {
+          cliErrorHandler.handleFatalError(result.error, {
+            operation: 'chunked_upload',
+            retryCount: 2
+          });
+        }
+      } else {
+        // Send compressed data in single request
+        console.log(chalk.blue('Sending compressed data in single request...'));
+        
+        const retryHandler = new RetryHandler(3, 1000, 2); // 3 retries, 1s base delay, 2x multiplier
+        
+        const result = await retryHandler.executeWithRetry(async () => {
+          const controller = new AbortController();
+          
+          // Set up progress indicators
+          const progress30s = setTimeout(() => {
+            console.log(chalk.yellow('Upload taking longer than expected, please wait while the process continues...'));
+          }, 30000); // 30 seconds
+          
+          const progress60s = setTimeout(() => {
+            console.log(chalk.yellow('File size is large and may take additional time, process still working...'));
+          }, 60000); // 60 seconds
+          
+          const timeoutId = setTimeout(() => {
+            controller.abort();
+            clearTimeout(progress30s);
+            clearTimeout(progress60s);
+          }, 180000); // 180 second timeout for larger files
+          
+          const response = await fetch(`${API_URL}/api/upload`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${token}`
+            },
+            body: JSON.stringify({
+              graph: compressedData,
+              compressed: true
+            }),
+            signal: controller.signal
+          });
+          
+          // Clear all timeouts
+          clearTimeout(timeoutId);
+          clearTimeout(progress30s);
+          clearTimeout(progress60s);
+          
+          if (response.status === 401) {
+            throw new Error('Invalid or revoked token');
+          }
+          
+          if (response.status === 404) {
+            throw new Error('Project not found');
+          }
+          
+          if (response.status === 429) {
+            throw new Error('Rate limit exceeded');
+          }
+          
+          if (!response.ok) {
+            const text = await response.text().catch(() => 'Unknown error');
+            throw new Error(`${response.status} ${response.statusText}: ${text}`);
+          }
+          
+          return await response.json();
+        }, 'compressed upload');
+        
+        if (result.success && result.result.success) {
+          console.log(chalk.green('✅ Compressed graph uploaded successfully!'));
+        } else {
+          cliErrorHandler.handleFatalError(result.error, {
+            operation: 'compressed_upload',
+            retryCount: 3
+          });
+        }
+      }
+    } else {
+      // Original upload method for smaller data
+      if (needsChunkedUpload) {
+        console.log(chalk.blue('Using chunked upload for large data...'));
+        
+        const chunkedUploader = new ChunkedUploader();
+        const retryHandler = new RetryHandler(2, 2000, 2); // 2 retries, 2s base delay, 2x multiplier
+        
+        // Execute with retry mechanism
+        const result = await retryHandler.executeWithRetry(async () => {
+          return await chunkedUploader.uploadInChunks(
+            { graph: jsonData },
+            token,
+            API_URL
+          );
+        }, 'chunked upload');
+        
+        if (result.success) {
+          console.log(chalk.green('✅ Graph uploaded successfully using chunked upload!'));
+        } else {
+          cliErrorHandler.handleFatalError(result.error, {
+            operation: 'chunked_upload',
+            retryCount: 2
+          });
+        }
+      } else {
+        // Standard upload for small data
+        console.log(chalk.blue('Sending data in single request...'));
+        
+        const retryHandler = new RetryHandler(3, 1000, 2); // 3 retries, 1s base delay, 2x multiplier
+        
+        const result = await retryHandler.executeWithRetry(async () => {
+          const controller = new AbortController();
+          
+          // Set up progress indicators
+          const progress30s = setTimeout(() => {
+            console.log(chalk.yellow('Upload taking longer than expected, please wait while the process continues...'));
+          }, 30000); // 30 seconds
+          
+          const progress60s = setTimeout(() => {
+            console.log(chalk.yellow('File size is large and may take additional time, process still working...'));
+          }, 60000); // 60 seconds
+          
+          const timeoutId = setTimeout(() => {
+            controller.abort();
+            clearTimeout(progress30s);
+            clearTimeout(progress60s);
+          }, 120000); // 120 second timeout
+          
+          const response = await fetch(`${API_URL}/api/upload`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${token}`
+            },
+            body: JSON.stringify({
+              graph: jsonData
+            }),
+            signal: controller.signal
+          });
+          
+          // Clear all timeouts
+          clearTimeout(timeoutId);
+          clearTimeout(progress30s);
+          clearTimeout(progress60s);
+          
+          if (response.status === 401) {
+            throw new Error('Invalid or revoked token');
+          }
+          
+          if (response.status === 404) {
+            throw new Error('Project not found');
+          }
+          
+          if (response.status === 429) {
+            throw new Error('Rate limit exceeded');
+          }
+          
+          if (!response.ok) {
+            const text = await response.text().catch(() => 'Unknown error');
+            throw new Error(`${response.status} ${response.statusText}: ${text}`);
+          }
+          
+          return await response.json();
+        }, 'standard upload');
+        
+        if (result.success && result.result.success) {
+          console.log(chalk.green('✅ Graph uploaded successfully!'));
+        } else {
+          cliErrorHandler.handleFatalError(result.error, {
+            operation: 'standard_upload',
+            retryCount: 3
+          });
+        }
+      }
+    }
+  } catch (error) {
+    cliErrorHandler.handleFatalError(error, {
+      operation: 'upload_to_database'
+    });
+  }
+}
+
+const program = new Command();
+
+program
+  .name('arcvision')
+  .description(process.env.CLI_DESCRIPTION || `CLI to visualize codebase architecture
+
+Quick Start:
+  1. Sign up at the ArcVision dashboard
+  2. Create a project and name it
+  3. Generate a CLI token
+  4. Run: arcvision link <token>
+  5. Run: arcvision scan --upload
+  6. Open dashboard to see results
+  `)
+  .version(version);
+
+program
+  .command('link <token>')
+  .description('Link this CLI to a project via upload token')
+  .action((token) => {
+    try {
+      saveToken(token);
+    } catch (error) {
+      // saveToken already handles its own errors and exits
+      process.exit(1);
+    }
+  });
+
+program
+  .command('scan')
+  .description('Scan the current directory and generate architecture map')
+  .argument('[directory]', 'Directory to scan', '.')
+  .option('-u, --upload', 'Upload to database')
+  .action(async (directory, options) => {
+    const targetDir = path.resolve(directory);
+    
+    try {
+      // Pre-flight validation
+      await cliValidator.preFlightValidation('scan', {
+        directory: targetDir
+      });
+
+      console.log(chalk.blue(`Scanning directory: ${targetDir}`));
+
+      const map = await scanner.scan(targetDir);
+      console.log(chalk.green('Scan complete!'));
+
+      // Analyze and print blast radius insight
+      const blastRadiusAnalysis = analyzeBlastRadius(map);
+      if (blastRadiusAnalysis && blastRadiusAnalysis.topFiles && blastRadiusAnalysis.topFiles.length > 0) {
+        console.log('\n⚠️  Top Structural Context Hubs Detected:\n');
+
+        blastRadiusAnalysis.topFiles.forEach((item, index) => {
+          let warningMessage = '';
+          if (index === 0) {
+            warningMessage = 'Changes here may silently propagate across the system.';
+          } else if (index === 1) {
+            warningMessage = 'Acts as a coordination layer between components.';
+          } else {
+            warningMessage = 'Modifications can cause widespread inconsistencies.';
+          }
+
+          console.log(`${index + 1}. ${item.file}`);
+          console.log(`   Blast Radius: ${item.blastRadius} files (${item.percentOfGraph}%)`);
+          console.log(`   Warning: ${warningMessage}\n`);
+        });
+      } else {
+        console.log('\nNo high-structure files detected based on import dependencies.');
+      }
+
+      // Validate the map before saving or uploading
+      const { validateContext } = require('./engine/context_validator');
+      const validation = validateContext(map);
+
+      if (!validation.valid) {
+        console.warn('⚠️  VALIDATION ISSUES FOUND:');
+        validation.errors.forEach(e => console.warn(' -', e));
+        console.warn('⚠️  Proceeding with output despite validation issues to see results');
+      }
+
+      // Create dedicated arcvision_context directory
+      const arcvisionDir = path.join(targetDir, 'arcvision_context');
+      if (!fs.existsSync(arcvisionDir)) {
+        fs.mkdirSync(arcvisionDir, { recursive: true });
+        console.log(chalk.green(`📁 Created arcvision_context directory: ${arcvisionDir}`));
+      }
+      
+      // Upload to database if requested
+      if (options.upload) {
+        await uploadToDatabase(map);
+        
+        // Generate README for system context when uploading
+        const { generateReadme } = require('./core/readme-generator');
+        generateReadme(arcvisionDir, version, blastRadiusAnalysis);
+      } else {
+        // Save to file with validation in dedicated directory
+        const fs = require('fs');
+        const outputFileName = path.join(arcvisionDir, 'arcvision.context.json');
+        fs.writeFileSync(outputFileName, JSON.stringify(map, null, 2));
+        console.log(chalk.green(`✅ Structural context saved to ${outputFileName}`));
+        
+        // Generate README for system context in dedicated directory
+        const { generateReadme } = require('./core/readme-generator');
+        generateReadme(arcvisionDir, version, blastRadiusAnalysis);
+        
+        console.log(chalk.dim('\nUse --upload to send to dashboard.'));
+      }
+    } catch (error) {
+      cliErrorHandler.handleFatalError(error, {
+        operation: 'scan',
+        directory: targetDir
+      });
+    }
+  });
+
+// Add a diff command to compare two context artifacts
+program
+  .command('diff')
+  .description('Compare two context artifacts and generate diff summary')
+  .argument('<old-file>', 'Path to the old context artifact')
+  .argument('<new-file>', 'Path to the new context artifact')
+  .action(async (oldFile, newFile) => {
+    try {
+      // Pre-flight validation
+      await cliValidator.preFlightValidation('diff', {
+        oldFile,
+        newFile
+      });
+
+      console.log(chalk.blue(`Comparing context artifacts:`));
+      console.log(chalk.blue(`  Old: ${oldFile}`));
+      console.log(chalk.blue(`  New: ${newFile}`));
+      
+      // Read both files
+      const oldContext = JSON.parse(fs.readFileSync(oldFile, 'utf8'));
+      const newContext = JSON.parse(fs.readFileSync(newFile, 'utf8'));
+      
+      // Generate diff summary
+      const diffResult = generateDiffSummary(oldContext, newContext);
+      
+      // Add diff summary to the new context
+      newContext.diff_summary = diffResult.diff_summary;
+      
+      // Save updated context with diff summary in arcvision_context directory
+      const arcvisionDir = path.join(path.dirname(newFile), 'arcvision_context');
+      if (!fs.existsSync(arcvisionDir)) {
+        fs.mkdirSync(arcvisionDir, { recursive: true });
+      }
+      const outputFileName = path.join(arcvisionDir, 'arcvision.context.diff.json');
+      fs.writeFileSync(outputFileName, JSON.stringify(newContext, null, 2));
+      
+      console.log(chalk.green('✅ Structural diff completed!'));
+      console.log(chalk.green(`✅ Diff summary saved to ${outputFileName}`));
+      console.log(chalk.yellow('\nDiff Summary:'));
+      console.log(chalk.yellow(`  Nodes Added: ${diffResult.diff_summary.nodes_added}`));
+      console.log(chalk.yellow(`  Nodes Removed: ${diffResult.diff_summary.nodes_removed}`));
+      console.log(chalk.yellow(`  Edges Added: ${diffResult.diff_summary.edges_added}`));
+      console.log(chalk.yellow(`  Edges Removed: ${diffResult.diff_summary.edges_removed}`));
+      console.log(chalk.yellow(`  Roles Changed: ${diffResult.diff_summary.roles_changed}`));
+      console.log(chalk.yellow(`  Blast Radius Changes: ${diffResult.diff_summary.blast_radius_changes}`));
+      
+    } catch (error) {
+      cliErrorHandler.handleFatalError(error, {
+        operation: 'diff',
+        oldFile,
+        newFile
+      });
+    }
+  });
+
+// Add the new Authoritative Change Impact Gate command
+program
+  .command('evaluate')
+  .alias('acig')
+  .description('Evaluate changes against authoritative invariants (Authoritative Change Impact Gate)')
+  .argument('[directory]', 'Directory to evaluate', '.')
+  .option('-c, --context-file <file>', 'Context file to evaluate against (default: arcvision.context.json)')
+  .option('-i, --invariants-file <file>', 'Invariants file to use (default: .arcvision/invariants.json)')
+  .option('-v, --verbose', 'Show detailed evaluation output')
+  .option('--simulate-changes <files>', 'Simulate changes to specific files (comma-separated)')
+  .option('--fail-on-blocked', 'Exit with error code when decision is BLOCKED (default: false)')
+  .action(async (directory, options) => {
+    const targetDir = path.resolve(directory);
+    
+    try {
+      // Pre-flight validation
+      await cliValidator.preFlightValidation('evaluate', {
+        directory: targetDir,
+        contextFile: options.contextFile,
+        invariantsFile: options.invariantsFile
+      });
+
+      console.log(chalk.blue('🔒 Authoritative Change Impact Gate (ACIG)'));
+      console.log(chalk.blue('Evaluating changes against canonical system invariants...\n'));
+
+      // Load current context from arcvision_context directory
+      const contextFile = options.contextFile || path.join(targetDir, 'arcvision_context', 'arcvision.context.json');
+      if (!fs.existsSync(contextFile)) {
+        console.error(chalk.red(`❌ Context file not found: ${contextFile}`));
+        console.error(chalk.yellow('Run `arcvision scan` first to generate context file'));
+        process.exit(1);
+      }
+      
+      let context;
+      try {
+        const contextContent = fs.readFileSync(contextFile, 'utf8');
+        context = JSON.parse(contextContent);
+      } catch (parseError) {
+        console.error(chalk.red(`❌ Failed to parse context file: ${parseError.message}`));
+        process.exit(1);
+      }
+      
+      console.log(chalk.green(`✅ Loaded context from: ${contextFile}`));
+
+      // Load invariants
+      const invariantsFile = options.invariantsFile || path.join(targetDir, '.arcvision', 'invariants.json');
+      let loadSuccess = false;
+      
+      if (fs.existsSync(invariantsFile)) {
+        loadSuccess = invariantRegistry.loadFromFile(invariantsFile);
+        if (loadSuccess) {
+          console.log(chalk.green(`✅ Loaded invariants from: ${invariantsFile}`));
+        } else {
+          console.log(chalk.yellow(`⚠️  Failed to load invariants from: ${invariantsFile}`));
+          console.log(chalk.yellow('Using default invariants...'));
+        }
+      } else {
+        console.log(chalk.yellow(`⚠️  Invariants file not found: ${invariantsFile}`));
+        console.log(chalk.yellow('Using default invariants...'));
+      }
+
+      // If invariants couldn't be loaded or file doesn't exist, use defaults
+      if (!loadSuccess) {
+        const defaultInvariants = JSON.parse(process.env.DEFAULT_INVARIANTS_JSON || JSON.stringify([
+          {
+            id: 'generic-architecture-rules',
+            system: 'general',
+            description: 'Generic architectural rules - define your own invariants.json',
+            severity: 'risk',
+            scope: { files: ['**/*.js', '**/*.ts', '**/*.jsx', '**/*.tsx'] },
+            rule: { type: 'dependency', condition: {} },
+            createdAt: new Date().toISOString()
+          }
+        ]));
+        // Temporarily override the registry for this evaluation
+        const originalGetAll = invariantRegistry.getAll.bind(invariantRegistry);
+        invariantRegistry.getAll = () => defaultInvariants;
+      }
+
+      // Get list of changed files
+      let changedFiles = [];
+      
+      if (options.simulateChanges) {
+        // Use simulated changes if provided
+        changedFiles = options.simulateChanges.split(',').map(f => f.trim()).filter(f => f);
+        console.log(chalk.blue(`Using simulated changes: ${changedFiles.join(', ')}`));
+      } else {
+        // Otherwise, use all files from the context as "changed" to demonstrate the evaluation
+        changedFiles = context.nodes ? context.nodes.map(node => node.path || node.id).filter(Boolean) : [];
+      }
+      
+      if (changedFiles.length === 0) {
+        console.log(chalk.yellow('No files found in context to evaluate'));
+        process.exit(0);
+      }
+
+      console.log(chalk.blue(`Evaluating ${changedFiles.length} files against ${invariantRegistry.getAll().length} invariants...`));
+
+      // Evaluate changes
+      const evaluation = evaluateChange({
+        changedFiles,
+        dependencyGraph: context,
+        invariants: invariantRegistry.getAll(),
+        context: { blastRadiusAnalysis: analyzeBlastRadius(context) }
+      });
+
+      // Record BLOCKED decisions in authority ledger
+      let eventId = null;
+      if (evaluation.decision === 'BLOCKED') {
+        eventId = authorityLedger.recordBlocked(evaluation, {
+          commit: options.commit || 'HEAD',
+          branch: options.branch || 'unknown',
+          author: options.author || 'unknown'
+        });
+      }
+
+      // Display results
+      console.log('\n' + '='.repeat(60));
+      console.log(chalk.bold(`DECISION: ${evaluation.decision}`));
+      console.log('='.repeat(60));
+
+      if (evaluation.decision === 'BLOCKED') {
+        console.log(chalk.red('❌ CHANGE BLOCKED - Invariant violations detected'));
+        console.log(chalk.red(`❌ ${evaluation.violations.length} invariant(s) violated:`));
+        evaluation.violations.forEach((violation, index) => {
+          console.log(chalk.red(`  ${index + 1}. ${violation.description}`));
+          console.log(chalk.red(`     System: ${violation.system}, Severity: ${violation.severity}`));
+        });
+        
+        if (options.verbose) {
+          console.log(chalk.yellow('\nDetailed Impact:'));
+          console.log(chalk.yellow(`  Affected Nodes: ${evaluation.details.affectedNodes}`));
+          console.log(chalk.yellow(`  Blast Radius Impact: ${evaluation.details.blastRadiusImpact}`));
+          console.log(chalk.yellow(`  Authority Core Changes: ${evaluation.details.authorityCoreChanges ? 'YES' : 'NO'}`));
+        }
+        
+        // Show override instructions if event was recorded
+        if (eventId) {
+          console.log(chalk.red('\n[!] AUTHORITATIVE GATE BLOCKED THIS CHANGE'));
+          console.log(chalk.yellow('To override with permanent record, run:'));
+          console.log(chalk.cyan(process.env.BLOCKED_OVERRIDE_COMMAND_FORMAT || ('arcvision override --event-id ' + eventId)));
+          console.log(chalk.cyan(process.env.BLOCKED_OVERRIDE_REASON_PLACEHOLDER || '  --reason "<detailed explanation>"'));
+          console.log(chalk.cyan(process.env.BLOCKED_OVERRIDE_OWNER_PLACEHOLDER || '  --owner "<your-identifier>"'));
+          console.log(chalk.red(process.env.BLOCKED_OVERRIDE_WARNING || '\n[WARNING] Override creates permanent architectural scar'));
+        }
+        
+        console.log(chalk.red('\n🚨 ACTION REQUIRED: Fix violations before merging'));
+        const exitCode = options.failOnBlocked ? 1 : 0;
+        process.exit(exitCode);
+      } else if (evaluation.decision === 'RISKY') {
+        console.log(chalk.yellow('⚠️  CHANGE IS RISKY - Warnings detected'));
+        console.log(chalk.yellow(`⚠️  ${evaluation.violations.length} warning(s) issued:`));
+        evaluation.violations.forEach((violation, index) => {
+          console.log(chalk.yellow(`  ${index + 1}. ${violation.description}`));
+          console.log(chalk.yellow(`     System: ${violation.system}, Severity: ${violation.severity}`));
+        });
+        
+        if (options.verbose) {
+          console.log(chalk.yellow('\nDetailed Impact:'));
+          console.log(chalk.yellow(`  Affected Nodes: ${evaluation.details.affectedNodes}`));
+          console.log(chalk.yellow(`  Blast Radius Impact: ${evaluation.details.blastRadiusImpact}`));
+          console.log(chalk.yellow(`  Authority Core Changes: ${evaluation.details.authorityCoreChanges ? 'YES' : 'NO'}`));
+        }
+        
+        console.log(chalk.yellow('\n⚠️  REVIEW RECOMMENDED: Check warnings before merging'));
+        process.exit(0); // Exit with success code but warn user
+      } else if (evaluation.decision === 'ERROR') {
+        console.log(chalk.red('💥 EVALUATION ERROR - Could not complete evaluation'));
+        console.log(chalk.red(`💥 ${evaluation.reasons.join('\n')}`));
+        process.exit(1);
+      } else {
+        console.log(chalk.green('✅ CHANGE ALLOWED - No critical violations detected'));
+        console.log(chalk.green(`✅ ${evaluation.reasons.join(', ')}`));
+        
+        if (options.verbose) {
+          console.log(chalk.green('\nImpact Summary:'));
+          console.log(chalk.green(`  Affected Nodes: ${evaluation.details.affectedNodes}`));
+          console.log(chalk.green(`  Blast Radius Impact: ${evaluation.details.blastRadiusImpact}`));
+          console.log(chalk.green(`  Authority Core Changes: ${evaluation.details.authorityCoreChanges ? 'YES' : 'NO'}`));
+        }
+        
+        console.log(chalk.green('\n✅ Ready to merge'));
+        process.exit(0);
+      }
+
+    } catch (error) {
+      cliErrorHandler.handleFatalError(error, {
+        operation: 'evaluate',
+        directory: targetDir
+      });
+    }
+  });
+
+// Add override command for Authoritative Gate
+program
+  .command('override')
+  .description('Override a BLOCKED decision with permanent record (Authoritative Gate)')
+  .requiredOption('--event-id <id>', 'Event ID of the BLOCKED decision to override')
+  .requiredOption('--reason <reason>', 'Detailed reason for override (minimum 10 characters)')
+  .requiredOption('--owner <owner>', 'Person responsible for this override')
+  .option('--commit <hash>', 'Commit hash being overridden (optional)')
+  .option('--branch <name>', 'Branch name (optional)')
+  .action(async (options) => {
+    try {
+      console.log(chalk.blue('🔐 Processing Authoritative Gate Override'));
+      console.log(chalk.blue('Creating permanent architectural scar...\n'));
+
+      const result = await overrideHandler.processOverride({
+        eventId: options.eventId,
+        reason: options.reason,
+        owner: options.owner,
+        commit: options.commit || 'HEAD',
+        branch: options.branch || 'unknown'
+      });
+
+      if (result.success) {
+        console.log(chalk.green('\n✅ OVERRIDE SUCCESSFUL'));
+        console.log(chalk.green('='.repeat(40)));
+        console.log(chalk.green(`Override ID: ${result.overrideEventId}`));
+        console.log(chalk.green(`Original Event: ${result.blockedEventId}`));
+        console.log(chalk.green(`Reason: ${result.reason}`));
+        console.log(chalk.green(`Owner: ${result.owner}`));
+        console.log(chalk.red(process.env.OVERRIDE_PERMANENT_RECORD_MESSAGE || '\n[PERMANENT RECORD] This override is now in the architectural ledger'));
+        console.log(chalk.yellow(process.env.OVERRIDE_FUTURE_SCRUTINY_MESSAGE || 'Future violations will face increased scrutiny'));
+        process.exit(0);
+      }
+    } catch (error) {
+      console.error(chalk.red(process.env.OVERRIDE_FAILURE_HEADER || '\n❌ OVERRIDE FAILED'));
+      console.error(chalk.red(`${process.env.OVERRIDE_FAILURE_ERROR_PREFIX || 'Error:'} ${error.message}`));
+      console.error(chalk.yellow(process.env.OVERRIDE_FAILURE_REQUIREMENTS_HEADER || '\nRequirements:'));
+      console.error(chalk.yellow(process.env.OVERRIDE_FAILURE_BLOCKED_REQUIREMENT || '• Event must be BLOCKED'));
+      console.error(chalk.yellow(process.env.OVERRIDE_FAILURE_REASON_REQUIREMENT || '• Reason must be detailed (>10 chars)'));
+      console.error(chalk.yellow(process.env.OVERRIDE_FAILURE_OWNER_REQUIREMENT || '• Owner must be specified'));
+      console.error(chalk.yellow(process.env.OVERRIDE_FAILURE_DUPLICATE_REQUIREMENT || '• Event must not already be overridden'));
+      process.exit(1);
+    }
+  });
+
+// Add ledger inspection command
+program
+  .command('ledger')
+  .description('Inspect authority ledger records')
+  .option('--stats', 'Show ledger statistics')
+  .option('--recent-blocks', 'Show recent unresolved BLOCKED events')
+  .option('--export <format>', 'Export ledger (json|csv)')
+  .action(async (options) => {
+    try {
+      if (options.stats) {
+        const stats = authorityLedger.getStats();
+        console.log(chalk.blue('📊 Authority Ledger Statistics'));
+        console.log(chalk.blue('=============================='));
+        console.log(chalk.green(`Total Events: ${stats.total_events}`));
+        console.log(chalk.red(`Blocked Decisions: ${stats.blocked_decisions}`));
+        console.log(chalk.yellow(`Overridden Decisions: ${stats.overridden_decisions}`));
+        console.log(chalk.gray(`Last Event: ${stats.last_event || 'None'}`));
+        process.exit(0);
+      }
+
+      if (options.recentBlocks) {
+        const blocks = authorityLedger.getRecentUnresolvedBlocks(10);
+        console.log(chalk.blue('🚨 Recent Unresolved BLOCKED Events'));
+        console.log(chalk.blue('====================================='));
+        
+        if (blocks.length === 0) {
+          console.log(chalk.green('No unresolved blocked events found'));
+        } else {
+          blocks.forEach((block, index) => {
+            console.log(chalk.red(`${index + 1}. Event: ${block.event_id}`));
+            console.log(chalk.red(`   Commit: ${block.commit}`));
+            console.log(chalk.red(`   Timestamp: ${block.timestamp}`));
+            console.log(chalk.red(`   Violations: ${block.violations?.length || 0}`));
+            console.log('');
+          });
+        }
+        process.exit(0);
+      }
+
+      if (options.export) {
+        const exported = authorityLedger.exportLedger(options.export);
+        console.log(exported);
+        process.exit(0);
+      }
+
+      // Default: show ledger info
+      console.log(chalk.blue('Authority Ledger Location: ./architecture.authority.ledger.json'));
+      console.log(chalk.yellow('Use --stats, --recent-blocks, or --export for detailed information'));
+      process.exit(0);
+
+    } catch (error) {
+      console.error(chalk.red('❌ Ledger command failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();