arcvision 0.2.25 → 0.2.26

package/README.md

@@ -0,0 +1,59 @@
+# ArcVision CLI
+
+**Architectural Governance and Invariant Detection Tool**
+
+ArcVision is a powerful 4-pass structural analysis engine designed to map, monitor, and enforce architectural integrity in modern codebases.
+
+## Key Features
+
+- **4-Pass Structural Analysis**: Deeply analyzes facts, semantics, structural roles, and signals.
+- **Invariant Detection**: Automatically identifies architectural constraints and assertions.
+- **Change Impact Gating**: Evaluates the blast radius and architectural risk of proposed code changes.
+- **Authority Ledger**: Maintains a verifiable audit trail of architectural decisions and overrides.
+- **Dashboard Integration**: Syncs architectural maps and health metrics to the ArcVision Dashboard.
+
+## Installation
+
+```bash
+npm install -g arcvision
+```
+
+## Quick Start
+
+### 1. Scan a repository
+Generate a comprehensive architectural context and visualize your system structure.
+```bash
+arcvision scan .
+```
+
+### 2. Evaluate changes
+Assess the impact of changes against established invariants.
+```bash
+arcvision evaluate . --simulate-changes src/critical-module.js
+```
+
+### 3. Record decisions
+Manage architectural decisions through the Authority Ledger.
+```bash
+arcvision override --event-id <event-id> --reason "Intentional architectural shift" --owner "arch-lead"
+```
+
+## Commands
+
+- `scan <directory>`: Analyze repository and generate `arcvision.context.json`.
+- `evaluate <directory>`: Run Authoritative Change Impact Gate (ACIG).
+- `diff <old> <new>`: Compare two architectural snapshots.
+- `ledger`: Manage and audit architectural overrides.
+- `link <token>`: Connect your local environment to the ArcVision Dashboard.
+
+## Architectural Health Assessment
+
+ArcVision computes an architectural health score based on:
+- Invariant coverage
+- Coupling degree
+- Criticality signals
+- Structural complexity
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcvision",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "ArcVision CLI - Architectural Governance and Invariant Detection Tool",
   "main": "src/index.js",
   "bin": {

package/src/core/authority-ledger.js

@@ -9,9 +9,10 @@ const crypto = require('crypto');
 
 class AuthorityLedger {
   constructor(ledgerPath) {
-    // Use arcvision_context directory by default
-    const defaultPath = path.join(process.cwd(), 'arcvision_context', 'architecture.authority.ledger.json');
-    this.ledgerPath = ledgerPath || process.env.AUTHORITY_LEDGER_PATH || defaultPath;
+    if (!ledgerPath) {
+      throw new Error('AuthorityLedger requires an explicit ledgerPath');
+    }
+    this.ledgerPath = ledgerPath;
     this.ensureLedgerExists();
   }
 
@@ -26,7 +27,7 @@ class AuthorityLedger {
         fs.mkdirSync(dirPath, { recursive: true });
         console.log(`📁 Created directory for authority ledger: ${dirPath}`);
       }
-      
+
       if (!fs.existsSync(this.ledgerPath)) {
         const initialLedger = {
           schema_version: process.env.ARCHITECTURE_LEDGER_SCHEMA_VERSION || "1.0",
@@ -48,7 +49,7 @@ class AuthorityLedger {
    */
   getSystemId() {
     try {
-      const cwd = process.cwd();
+      const cwd = path.dirname(path.dirname(this.ledgerPath)); // One level up from arcvision_context
       const projectName = path.basename(cwd);
       return projectName;
     } catch (error) {
@@ -115,8 +116,8 @@ class AuthorityLedger {
   isOverridden(commitHash) {
     try {
       const ledger = this.readLedger();
-      return ledger.ledger.some(event => 
-        event.decision === 'OVERRIDDEN' && 
+      return ledger.ledger.some(event =>
+        event.decision === 'OVERRIDDEN' &&
         event.commit === commitHash
       );
     } catch (error) {
@@ -150,7 +151,7 @@ class AuthorityLedger {
 
       // Filter out events that have been overridden
       return blockedEvents.filter(blockedEvent => {
-        return !ledger.ledger.some(overrideEvent => 
+        return !ledger.ledger.some(overrideEvent =>
           overrideEvent.decision === 'OVERRIDDEN' &&
           overrideEvent.original_blocked_event === blockedEvent.event_id
         );
@@ -174,7 +175,7 @@ class AuthorityLedger {
   appendEvent(event) {
     try {
       const ledger = this.readLedger();
-      
+
       // Validate event structure
       if (!event.event_id || !event.timestamp || !event.decision) {
         throw new Error('Invalid event structure');
@@ -182,7 +183,7 @@ class AuthorityLedger {
 
       ledger.ledger.push(event);
       this.writeLedger(ledger);
-      
+
       console.log(`Recorded ${event.decision} decision in authority ledger`);
     } catch (error) {
       console.error('Failed to append to authority ledger:', error.message);
@@ -197,12 +198,12 @@ class AuthorityLedger {
     try {
       const content = fs.readFileSync(this.ledgerPath, 'utf8');
       const ledger = JSON.parse(content);
-      
+
       // Validate structure
       if (!ledger.schema_version || !Array.isArray(ledger.ledger)) {
         throw new Error('Invalid ledger structure');
       }
-      
+
       return ledger;
     } catch (error) {
       console.error('Failed to read authority ledger:', error.message);
@@ -232,7 +233,7 @@ class AuthorityLedger {
       const ledger = this.readLedger();
       const blockedCount = ledger.ledger.filter(e => e.decision === 'BLOCKED').length;
       const overriddenCount = ledger.ledger.filter(e => e.decision === 'OVERRIDDEN').length;
-      
+
       return {
         total_events: ledger.ledger.length,
         blocked_decisions: blockedCount,
@@ -256,7 +257,7 @@ class AuthorityLedger {
   exportLedger(format = 'json') {
     try {
       const ledger = this.readLedger();
-      
+
       switch (format.toLowerCase()) {
         case 'json':
           return JSON.stringify(ledger, null, 2);
@@ -284,17 +285,14 @@ class AuthorityLedger {
       event.author,
       event.violations ? event.violations.length : 0
     ]);
-    
+
     const csvContent = [
       headers.join(','),
       ...rows.map(row => row.join(','))
     ].join('\n');
-    
+
     return csvContent;
   }
 }
 
-// Export singleton instance
-const authorityLedger = new AuthorityLedger();
-
-module.exports = { AuthorityLedger, authorityLedger };
+module.exports = { AuthorityLedger };

package/src/core/change-evaluator.js

@@ -1,4 +1,4 @@
-/**
+ /**
  * Change Impact Evaluator
  * Connects existing ArcVision data to invariants
  */
@@ -16,16 +16,16 @@ function evaluateChange(input) {
   }
 
   const { changedFiles, dependencyGraph, invariants, context } = input;
-  
+
   // Validate required parameters with enhanced checks
   if (!Array.isArray(changedFiles)) {
     return createEnhancedErrorResult('Invalid input: changedFiles must be an array');
   }
-  
+
   if (!dependencyGraph) {
     return createEnhancedErrorResult('Invalid input: dependencyGraph is required');
   }
-  
+
   if (!Array.isArray(invariants)) {
     return createEnhancedErrorResult('Invalid input: invariants must be an array');
   }
@@ -48,10 +48,10 @@ function evaluateChange(input) {
         }
 
         const matchesScope = matchesInvariantScope(sanitizedChangedFiles, invariant);
-        
+
         if (matchesScope) {
           const isViolated = checkInvariantRule(invariant, dependencyGraph, sanitizedChangedFiles);
-          
+
           if (isViolated) {
             violations.push({
               ...invariant,
@@ -60,7 +60,7 @@ function evaluateChange(input) {
             });
           }
         }
-        
+
         processedInvariants.push(invariant.id);
       } catch (ruleError) {
         console.warn(`Warning: Error evaluating invariant ${invariant?.id || 'unknown'}:`, ruleError.message);
@@ -75,7 +75,7 @@ function evaluateChange(input) {
     // Determine decision based on violations with enhanced severity handling
     const blockingViolations = violations.filter(v => v.severity === 'block' || v.severity === 'BLOCK');
     const riskyViolations = violations.filter(v => v.severity === 'risk' || v.severity === 'RISK');
-    
+
     if (blockingViolations.length > 0) {
       return formatEnhancedResult('BLOCKED', violations, input);
     }
@@ -116,7 +116,7 @@ function matchesInvariantScope(changedFiles, invariant) {
   }
 
   const scope = invariant.scope;
-  
+
   // If no scope restrictions, always matches
   if (!scope.files && !scope.components && !scope.flows) {
     return true;
@@ -210,25 +210,25 @@ function checkInvariantRule(invariant, dependencyGraph, changedFiles) {
  */
 function checkGenericRule(condition, dependencyGraph, changedFiles) {
   if (!condition) return false;
-  
+
   try {
     // Handle different condition types dynamically
     if (condition.forbiddenDependency && typeof condition.forbiddenDependency === 'object') {
       return checkForbiddenDependency(condition.forbiddenDependency, dependencyGraph, changedFiles);
     }
-    
+
     if (condition.mustExist) {
       return checkRequirement(condition.mustExist, dependencyGraph, changedFiles);
     }
-    
+
     if (condition.mustNotExist) {
       return checkProhibition(condition.mustNotExist, dependencyGraph, changedFiles);
     }
-    
+
     if (condition.pattern) {
       return checkPatternMatch(condition.pattern, dependencyGraph, changedFiles);
     }
-    
+
     // Default: if condition exists and has properties, consider it potentially violated
     return typeof condition === 'object' && Object.keys(condition).length > 0;
   } catch (error) {
@@ -252,38 +252,38 @@ function checkForbiddenDependency(forbiddenDep, dependencyGraph, changedFiles) {
   if (!forbiddenDep || typeof forbiddenDep !== 'object') {
     return false;
   }
-  
+
   if (!forbiddenDep.from || !forbiddenDep.to) {
     return false;
   }
-  
+
   try {
     // Use enhanced circular dependency detector
     const circularDetector = new CircularDependencyDetector();
-    
+
     // Check if the forbidden dependency pattern is violated
     const result = circularDetector.checkEnhancedForbiddenDependency(
-      forbiddenDep, 
-      dependencyGraph.nodes || [], 
+      forbiddenDep,
+      dependencyGraph.nodes || [],
       dependencyGraph.edges || []
     );
-    
+
     if (result.violated) {
       console.log(`🚨 Forbidden dependency violation detected: ${result.description}`);
       return true;
     }
-    
+
     // Fallback to original method for backward compatibility
     const { patternMatcher } = require('./pattern-matcher');
-    
+
     return changedFiles.some(file => {
       if (typeof file !== 'string') return false;
-      
+
       // Check if file matches the 'from' scope using robust pattern matching
       const matchesFrom = patternMatcher.match(file, forbiddenDep.from, { matchBase: true }) ||
-                         patternMatcher.match(file, `**/${forbiddenDep.from}/**`, { matchBase: false }) ||
-                         file.toLowerCase().includes(forbiddenDep.from.toLowerCase());
-      
+        patternMatcher.match(file, `**/${forbiddenDep.from}/**`, { matchBase: false }) ||
+        file.toLowerCase().includes(forbiddenDep.from.toLowerCase());
+
       if (matchesFrom) {
         // Check if this file now depends on the 'to' component
         return hasDependencyTo(dependencyGraph, file, forbiddenDep.to);
@@ -333,20 +333,20 @@ function checkPatternRule(invariant, dependencyGraph, changedFiles) {
       const { patternMatcher } = require('./pattern-matcher');
       const fs = require('fs');
       const path = require('path');
-      
+
       // Convert pattern to regex for proper matching
       let regexPattern;
       try {
         // Handle the pipe (OR) operator and other regex constructs
         const escapedPattern = pattern.replace(/\./g, '\\.')
-                                      .replace(/\*/g, '.*')
-                                      .replace(/\+/g, '\\+');
+          .replace(/\*/g, '.*')
+          .replace(/\+/g, '\\+');
         regexPattern = new RegExp(escapedPattern, 'gi');
       } catch (regexError) {
         console.warn(`Warning: Could not create regex from pattern "${pattern}": ${regexError.message}`);
         return false;
       }
-      
+
       // Check if any node content matches the pattern by reading actual files
       if (dependencyGraph.nodes && Array.isArray(dependencyGraph.nodes)) {
         return dependencyGraph.nodes.some(node => {
@@ -356,20 +356,23 @@ function checkPatternRule(invariant, dependencyGraph, changedFiles) {
               console.log(`🚨 Pattern violation detected in ${node.path}: matches pattern "${pattern}"`);
               return true;
             }
-            
+
             // Read actual file content to check for pattern violations
             try {
-              // Resolve the full file path
-              const fullPath = path.resolve(node.path);
+              // Resolve the full file path relative to system root if available
+              const rootPath = dependencyGraph.system && dependencyGraph.system.root_path ?
+                dependencyGraph.system.root_path :
+                process.cwd();
+              const fullPath = path.resolve(rootPath, node.path);
               if (fs.existsSync(fullPath)) {
                 const fileContent = fs.readFileSync(fullPath, 'utf8');
-                
+
                 // Check if file content matches the regex pattern
                 if (regexPattern.test(fileContent)) {
                   console.log(`🚨 Pattern violation detected in ${node.path}: content matches pattern "${pattern}"`);
                   return true;
                 }
-                
+
                 // Also check with pattern matcher for glob patterns
                 if (patternMatcher.match(fileContent, `*${pattern}*`, { matchBase: false })) {
                   console.log(`🚨 Pattern violation detected in ${node.path}: content matches pattern "${pattern}"`);
@@ -380,7 +383,7 @@ function checkPatternRule(invariant, dependencyGraph, changedFiles) {
               // Silently continue if file can't be read
             }
           }
-          
+
           return false;
         });
       }
@@ -388,7 +391,7 @@ function checkPatternRule(invariant, dependencyGraph, changedFiles) {
   } catch (error) {
     console.warn(`Warning: Error in pattern rule check:`, error.message);
   }
-  
+
   return false;
 }
 
@@ -400,7 +403,7 @@ function checkExistenceRule(invariant, dependencyGraph, changedFiles) {
     if (invariant.rule.condition && invariant.rule.condition.mustExist) {
       const requiredElement = invariant.rule.condition.mustExist;
       const { patternMatcher } = require('./pattern-matcher');
-      
+
       // Check if required element exists
       if (dependencyGraph.nodes && Array.isArray(dependencyGraph.nodes)) {
         const exists = dependencyGraph.nodes.some(node => {
@@ -409,18 +412,18 @@ function checkExistenceRule(invariant, dependencyGraph, changedFiles) {
           }
           return false;
         });
-        
+
         if (!exists) {
           console.log(`🚨 Existence violation: Required element "${requiredElement}" not found`);
           return true; // Violation - required element doesn't exist
         }
       }
     }
-    
+
     if (invariant.rule.condition && invariant.rule.condition.mustNotExist) {
       const forbiddenElement = invariant.rule.condition.mustNotExist;
       const { patternMatcher } = require('./pattern-matcher');
-      
+
       // Check if forbidden element exists
       if (dependencyGraph.nodes && Array.isArray(dependencyGraph.nodes)) {
         const exists = dependencyGraph.nodes.some(node => {
@@ -429,7 +432,7 @@ function checkExistenceRule(invariant, dependencyGraph, changedFiles) {
           }
           return false;
         });
-        
+
         if (exists) {
           console.log(`🚨 Existence violation: Forbidden element "${forbiddenElement}" found`);
           return true; // Violation - forbidden element exists
@@ -439,7 +442,7 @@ function checkExistenceRule(invariant, dependencyGraph, changedFiles) {
   } catch (error) {
     console.warn(`Warning: Error in existence rule check:`, error.message);
   }
-  
+
   return false;
 }
 
@@ -459,11 +462,11 @@ function checkOwnershipRule(invariant, dependencyGraph, changedFiles) {
     // Check if changed files fall under this invariant's scope and if ownership is violated
     if (invariant.rule.condition && invariant.scope.files) {
       const { authorizedOwners } = invariant.rule.condition;
-      
+
       if (authorizedOwners && Array.isArray(authorizedOwners)) {
         return changedFiles.some(file => {
           if (typeof file !== 'string') return false;
-          
+
           // Check if file matches the scope
           const matchesScope = invariant.scope.files.some(pattern => {
             if (typeof pattern !== 'string') return false;
@@ -475,7 +478,7 @@ function checkOwnershipRule(invariant, dependencyGraph, changedFiles) {
               return false;
             }
           });
-          
+
           if (matchesScope) {
             // Check if current owner is authorized (this would require additional context about who made the change)
             // For now, we'll just check if the invariant has an owner specified and it's different
@@ -489,7 +492,7 @@ function checkOwnershipRule(invariant, dependencyGraph, changedFiles) {
     console.warn(`Warning: Error in ownership rule check:`, error.message);
     return false;
   }
-  
+
   return false;
 }
 
@@ -516,22 +519,22 @@ function hasDependencyTo(dependencyGraph, fromFile, toComponent) {
   if (typeof fromFile !== 'string' || typeof toComponent !== 'string') {
     return false;
   }
-  
+
   try {
     // Simplified implementation - would need to analyze actual dependency graph
     if (dependencyGraph && dependencyGraph.edges && Array.isArray(dependencyGraph.edges)) {
       return dependencyGraph.edges.some((edge) => {
         if (!edge || !edge.source || !edge.target) return false;
-        
-        return edge.source === fromFile && 
-               (edge.target.includes(toComponent) || 
-                edge.target.toLowerCase().includes(toComponent.toLowerCase()));
+
+        return edge.source === fromFile &&
+          (edge.target.includes(toComponent) ||
+            edge.target.toLowerCase().includes(toComponent.toLowerCase()));
       });
     }
   } catch (error) {
     console.warn(`Warning: Error checking dependency graph:`, error.message);
   }
-  
+
   return false;
 }