arcvision 0.2.14 → 0.2.16

package/src/core/invariant-detector.js

@@ -0,0 +1,548 @@
+/**
+ * Invariant Detector - Detects architectural invariants in scanned repositories
+ * Analyzes code structure to identify system-level constraints that must always hold
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+class InvariantDetector {
+  constructor() {
+    this.detectedInvariants = [];
+  }
+
+
+
+  /**
+   * Detect invariants in a scanned codebase
+   * @param {Object} scanResult - The result from the scanner
+   * @param {string} directory - The directory that was scanned
+   * @returns {Array} - Array of detected invariants
+   */
+  async detectInvariants(scanResult, directory) {
+    this.detectedInvariants = [];
+    
+    try {
+      // Analyze the structural context for potential invariants
+      await this.analyzeNodesForInvariants(scanResult.nodes, directory);
+      await this.analyzeEdgesForInvariants(scanResult.edges);
+      await this.analyzeCodeFilesForInvariants(directory);
+      
+      console.log(`\n🛡️  Invariant Detection Complete`);
+      console.log(`   Found ${this.detectedInvariants.length} potential system invariants`);
+      
+      return this.detectedInvariants;
+    } catch (error) {
+      console.error('Invariant detection failed:', error.message);
+      return [];
+    }
+  }
+
+  /**
+   * Analyze nodes for invariant patterns
+   */
+  async analyzeNodesForInvariants(nodes, directory) {
+    for (const node of nodes) {
+      if (!node.path) continue;
+      
+      try {
+        const filePath = path.join(directory, node.path);
+        if (await this.isFileAccessible(filePath)) {
+          const content = await fs.readFile(filePath, 'utf8');
+          
+          // Look for validation/assertion patterns in the file
+          const fileInvariants = this.extractInvariantsFromFile(content, node.path);
+          
+          for (const invariant of fileInvariants) {
+            const nodeId = node.path || node.id || 'unknown';
+            this.detectedInvariants.push({
+              id: this.generateInvariantId(invariant.pattern, nodeId),
+              statement: invariant.description,
+              description: invariant.description,
+              scope: this.determineScopeFromPath(nodeId),
+              critical_path: invariant.isCritical,
+              assertion: `Pattern: ${invariant.pattern}`,
+              status: 'suspected',
+              confidence: this.calculateConfidenceScore(invariant.pattern, nodeId, content),
+              source_file: nodeId,
+              detected_at: new Date().toISOString()
+            });
+          }
+        }
+      } catch (error) {
+        // Skip files that can't be read
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Analyze edges for potential invariant relationships
+   */
+  async analyzeEdgesForInvariants(edges) {
+    // Look for dependency patterns that suggest invariants
+    const dependencyConstraints = this.identifyDependencyInvariants(edges);
+    
+    for (const constraint of dependencyConstraints) {
+      this.detectedInvariants.push({
+        id: this.generateInvariantId('dependency_constraint', constraint.from + '_' + constraint.to),
+        statement: constraint.description,
+        description: constraint.description,
+        scope: 'boundary',
+        critical_path: constraint.critical,
+        assertion: `Dependency constraint: ${constraint.from} -> ${constraint.to}`,
+        status: 'suspected',
+        confidence: this.calculateConfidenceScore('dependency_constraint', constraint.from, ''),
+        source_relationship: `${constraint.from} -> ${constraint.to}`,
+        detected_at: new Date().toISOString()
+      });
+    }
+  }
+
+  /**
+   * Analyze code files directly for invariant patterns
+   */
+  async analyzeCodeFilesForInvariants(directory) {
+    const invariantFiles = await this.findInvariantRelatedFiles(directory);
+    
+    for (const filePath of invariantFiles) {
+      try {
+        const content = await fs.readFile(filePath, 'utf8');
+        const relativePath = path.relative(directory, filePath);
+        
+        // Look for common invariant implementation patterns
+        const patterns = this.searchForInvariantPatterns(content);
+        
+        for (const pattern of patterns) {
+          this.detectedInvariants.push({
+            id: this.generateInvariantId(pattern.type, relativePath),
+            statement: `System invariant implemented in ${relativePath}: ${pattern.description}`,
+            description: `System invariant implemented in ${relativePath}: ${pattern.description}`,
+            scope: 'system',
+            critical_path: true,  // File specifically for invariants is likely critical
+            assertion: pattern.assertion,
+            status: 'suspected',
+            confidence: this.calculateConfidenceScore(pattern.type, relativePath, content),
+            source_file: relativePath,
+            implementation_type: pattern.type,
+            detected_at: new Date().toISOString()
+          });
+        }
+      } catch (error) {
+        // Skip files that can't be read
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Extract invariants from file content based on patterns
+   */
+  extractInvariantsFromFile(content, filePath) {
+    const invariants = [];
+    
+    // Check for validation function patterns
+    const validationPatterns = [
+      /function\s+validate\w+/gi,
+      /function\s+check\w+/gi,
+      /function\s+ensure\w+/gi,
+      /function\s+guard\w+/gi,
+      /function\s+verify\w+/gi,
+      /function\s+assert\w+/gi,
+      /function\s+enforce\w+/gi
+    ];
+    
+    for (const pattern of validationPatterns) {
+      const matches = content.match(pattern);
+      if (matches) {
+        invariants.push({
+          pattern: pattern.source,
+          description: `Validation function pattern found in ${filePath}: ${matches.length} matches`,
+          isCritical: true
+        });
+      }
+    }
+    
+    // Check for error handling patterns that suggest invariant enforcement
+    const errorHandlingPatterns = [
+      /try\s*\{/gi,
+      /catch\s*\(/gi,
+      /throw\s+new/gi,
+      /if\s*\([^)]+\)\s*throw/gi,
+      /error\.message/gi
+    ];
+    
+    for (const pattern of errorHandlingPatterns) {
+      const match = content.match(pattern);
+      if (match) {
+        invariants.push({
+          pattern: pattern.source,
+          description: `Constraint enforcement pattern found in ${filePath}`,
+          isCritical: false
+        });
+      }
+    }
+    
+    // Check for state management patterns
+    const stateManagementPatterns = [
+      /setState\s*\(/gi,
+      /dispatch\s*\(/gi,
+      /useReducer/gi,
+      /useState/gi,
+      /store\./gi,
+      /state\./gi,
+      /state\s*=\s*/gi
+    ];
+    
+    for (const pattern of stateManagementPatterns) {
+      const match = content.match(pattern);
+      if (match) {
+        invariants.push({
+          pattern: pattern.source,
+          description: `State transition constraint pattern found in ${filePath}`,
+          isCritical: true
+        });
+      }
+    }
+    
+    // Check for boundary enforcement patterns
+    const boundaryCheckPatterns = [
+      /boundary\s*check/gi,
+      /range\s*check/gi,
+      /limit\s*check/gi,
+      /max\s*\w*\s*>/gi,
+      /min\s*\w*\s*</gi,
+      /within\s*bound/gi,
+      /validate\s*input/gi,
+      /sanitiz/gi
+    ];
+    
+    for (const pattern of boundaryCheckPatterns) {
+      const match = content.match(pattern);
+      if (match) {
+        invariants.push({
+          pattern: pattern.source,
+          description: `Boundary enforcement pattern found in ${filePath}`,
+          isCritical: true
+        });
+      }
+    }
+    
+    // Check for invariant indicators from pass 1
+    const invariantIndicators = this.extractDetailedInvariantIndicators(content, filePath);
+    for (const indicator of invariantIndicators) {
+      invariants.push(indicator);
+    }
+    
+    return invariants;
+  }
+  
+  /**
+   * Extract detailed invariant indicators from content
+   */
+  extractDetailedInvariantIndicators(content, filePath) {
+    const indicators = [];
+    
+    // Look for common invariant/pattern validation patterns
+    const patterns = [
+      // Assertion and validation patterns
+      { pattern: /assert\(/gi, description: 'Assertion-based invariant check', critical: true },
+      { pattern: /console\.assert\(/gi, description: 'Console assertion pattern', critical: true },
+      { pattern: /validate[A-Z]/gi, description: 'Validate function pattern', critical: false },
+      { pattern: /check[A-Z]/gi, description: 'Check function pattern', critical: false },
+      { pattern: /ensure[A-Z]/gi, description: 'Ensure function pattern', critical: true },
+      { pattern: /guard[A-Z]/gi, description: 'Guard function pattern', critical: true },
+      { pattern: /verify[A-Z]/gi, description: 'Verify function pattern', critical: false },
+      { pattern: /validate\(/gi, description: 'Validation function call', critical: false },
+      
+      // Constraint and invariant mentions
+      { pattern: /Invariant/gi, description: 'Invariant mention', critical: true },
+      { pattern: /constraint/gi, description: 'Constraint mention', critical: true },
+      { pattern: /require\(/gi, description: 'Requirement assertion', critical: true },
+      { pattern: /enforce/gi, description: 'Enforcement pattern', critical: true },
+      
+      // Conditional guard patterns
+      { pattern: /must.*be/gi, description: 'Must-be pattern', critical: true },
+      { pattern: /should.*be/gi, description: 'Should-be pattern', critical: false },
+      { pattern: /expected.*to/gi, description: 'Expected-to pattern', critical: false },
+      { pattern: /if.*!\s*[^\s]+\s*throw/gi, description: 'Guard clause pattern', critical: true },
+      { pattern: /if.*!\s*[^\s]+\s*reject/gi, description: 'Promise rejection guard', critical: true },
+      { pattern: /throw.*Error/gi, description: 'Error throwing pattern', critical: true },
+      
+      // Boundary and validation patterns
+      { pattern: /boundary.*check/gi, description: 'Boundary check', critical: true },
+      { pattern: /range.*check/gi, description: 'Range check', critical: true },
+      { pattern: /within.*bounds/gi, description: 'Bounds check', critical: true },
+      { pattern: /validat(e|ion)/gi, description: 'Validation pattern', critical: false },
+      { pattern: /guard/i, description: 'Guard pattern', critical: true },
+      
+      // Access control and security patterns
+      { pattern: /access.*control/gi, description: 'Access control', critical: true },
+      { pattern: /permission.*check/gi, description: 'Permission check', critical: true },
+      { pattern: /auth(?:oriz|enticat)/gi, description: 'Authorization/authentication', critical: true },
+      { pattern: /acl/gi, description: 'Access Control List', critical: true },
+      
+      // State management patterns
+      { pattern: /state.*transition/gi, description: 'State transition', critical: true },
+      { pattern: /setState/gi, description: 'State setter', critical: true },
+      { pattern: /update.*state/gi, description: 'State updater', critical: true },
+      { pattern: /transition/gi, description: 'Transition pattern', critical: true },
+      { pattern: /immutable/gi, description: 'Immutability pattern', critical: true },
+      
+      // Type and schema validation patterns
+      { pattern: /zod/gi, description: 'Zod validation schema', critical: false },
+      { pattern: /joi/gi, description: 'Joi validation schema', critical: false },
+      { pattern: /yup/gi, description: 'Yup validation schema', critical: false },
+      { pattern: /ajv/gi, description: 'Ajv validation schema', critical: false },
+      { pattern: /schema/gi, description: 'Schema definition', critical: false },
+      
+      // Configuration patterns
+      { pattern: /config.*environ/gi, description: 'Environment configuration', critical: true },
+      { pattern: /env.*validation/gi, description: 'Environment validation', critical: true }
+    ];
+    
+    for (const item of patterns) {
+      if (!item.pattern || !content) continue; // Skip if pattern or content is undefined
+      let match;
+      try {
+        while ((match = item.pattern.exec(content)) !== null) {
+          // Avoid duplicate matches by position
+          const position = item.pattern.lastIndex;
+          const prevMatch = indicators.find(ind => ind.pattern === item.pattern.source && 
+                                           ind.description.includes(match[0]));
+          if (!prevMatch) {
+            indicators.push({
+              pattern: item.pattern.source,
+              description: `${item.description} found in ${filePath}: '${match[0]}' at position ${position}`,
+              isCritical: item.critical
+            });
+          }
+        }
+      } catch (error) {
+        // Continue if regex execution fails
+        continue;
+      }
+    }
+    
+    return indicators;
+  }
+
+  /**
+   * Identify dependency-based invariants from edges
+   */
+  identifyDependencyInvariants(edges) {
+    const constraints = [];
+    
+    // Look for patterns like core modules that should not depend on peripheral modules
+    const coreModules = new Set();
+    const peripheralModules = new Set();
+    
+    for (const edge of edges) {
+      // Identify potential architectural layers based on file paths
+      if (this.isCoreLayer(edge.from) && this.isPeripheralLayer(edge.to)) {
+        // This suggests an invariant: core modules shouldn't depend on peripheral modules
+        constraints.push({
+          from: edge.from,
+          to: edge.to,
+          description: `Potential architectural invariant: Core module ${edge.from} depends on peripheral module ${edge.to}`,
+          critical: true
+        });
+      }
+    }
+    
+    return constraints;
+  }
+
+  /**
+   * Find files that are likely related to invariant implementation
+   */
+  async findInvariantRelatedFiles(directory) {
+    const invariantFiles = [];
+    
+    const walk = async (dir) => {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          
+          if (entry.isDirectory()) {
+            await walk(fullPath);
+          } else if (entry.isFile()) {
+            const fileName = entry.name.toLowerCase();
+            
+            // Look for files that commonly contain invariants
+            if (
+              fileName.includes('invariant') ||
+              fileName.includes('validation') ||
+              fileName.includes('guard') ||
+              fileName.includes('assert') ||
+              fileName.includes('constraint') ||
+              fileName.includes('boundary') ||
+              fileName.includes('policy') ||
+              fileName.includes('rule')
+            ) {
+              invariantFiles.push(fullPath);
+            }
+          }
+        }
+      } catch (error) {
+        // Skip directories we can't access
+      }
+    };
+    
+    await walk(directory);
+    return invariantFiles;
+  }
+
+  /**
+   * Search for specific invariant implementation patterns
+   */
+  searchForInvariantPatterns(content) {
+    const patterns = [];
+    
+    // Look for assertion/verification patterns
+    if (content.includes('assert(') || content.includes('AssertionError')) {
+      patterns.push({
+        type: 'assertion',
+        description: 'Assertion-based invariant checking found',
+        assertion: 'Code contains assert() calls for invariant enforcement'
+      });
+    }
+    
+    // Look for validation patterns
+    if (content.includes('validate(') || content.includes('isValid') || content.includes('checkValid')) {
+      patterns.push({
+        type: 'validation',
+        description: 'Validation-based invariant checking found',
+        assertion: 'Code contains validation functions for invariant enforcement'
+      });
+    }
+    
+    // Look for guard clauses
+    if (content.includes('if (!condition) throw') || content.includes('guard clause')) {
+      patterns.push({
+        type: 'guard_clause',
+        description: 'Guard clause invariant enforcement found',
+        assertion: 'Code contains early-exit guard clauses for invariant enforcement'
+      });
+    }
+    
+    // Look for state machine patterns
+    if (content.includes('state') && (content.includes('transition') || content.includes('transitions'))) {
+      patterns.push({
+        type: 'state_machine',
+        description: 'State transition invariant found',
+        assertion: 'Code implements state machine with transition constraints'
+      });
+    }
+    
+    return patterns;
+  }
+
+  /**
+   * Determine scope based on file path
+   */
+  determineScopeFromPath(filePath) {
+    if (!filePath) return 'module'; // Default to module if no path provided
+    if (filePath.includes('/core/') || filePath.includes('/lib/') || filePath.includes('/shared/')) {
+      return 'system';
+    } else if (filePath.includes('/modules/') || filePath.includes('/components/')) {
+      return 'boundary';
+    } else {
+      return 'module';
+    }
+  }
+
+  /**
+   * Check if file is accessible
+   */
+  async isFileAccessible(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if path represents a core layer
+   */
+  isCoreLayer(filePath) {
+    if (!filePath) return false;
+    return filePath.includes('/core/') || 
+           filePath.includes('/lib/') || 
+           filePath.includes('/shared/') ||
+           filePath.includes('config') ||
+           filePath.includes('auth');
+  }
+
+  /**
+   * Check if path represents a peripheral layer
+   */
+  isPeripheralLayer(filePath) {
+    if (!filePath) return false;
+    return filePath.includes('/views/') || 
+           filePath.includes('/templates/') || 
+           filePath.includes('/ui/') ||
+           filePath.includes('/tests/') ||
+           filePath.includes('/mocks/');
+  }
+
+  /**
+   * Generate unique invariant ID
+   */
+  generateInvariantId(pattern, context) {
+    const baseId = `${pattern}_${context}`.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return baseId.substring(0, 100); // Limit length
+  }
+  
+  /**
+   * Calculate confidence score for an invariant based on various factors
+   */
+  calculateConfidenceScore(pattern, context, content = '') {
+    let score = 0.5; // Base confidence
+    
+    // Increase confidence based on pattern type
+    if (pattern.includes('assert') || pattern.includes('validate') || pattern.includes('guard')) {
+      score += 0.2;
+    }
+    
+    if (pattern.includes('state') || pattern.includes('mutation') || pattern.includes('setState')) {
+      score += 0.15;
+    }
+    
+    // Increase confidence if context suggests critical file
+    if (context.includes('core') || context.includes('lib') || context.includes('shared')) {
+      score += 0.1;
+    }
+    
+    // Increase confidence based on frequency of pattern in content
+    if (content && typeof content === 'string') {
+      const matches = content.match(new RegExp(pattern, 'gi'));
+      if (matches && matches.length > 1) {
+        score += Math.min(matches.length * 0.05, 0.2); // Up to 0.2 for multiple matches
+      }
+    }
+    
+    // Ensure score stays within bounds
+    return Math.min(Math.max(score, 0.1), 1.0);
+  }
+  
+  /**
+   * Determine the owner of an invariant based on the source file
+   */
+  determineOwnerFromPath(filePath) {
+    if (!filePath) return 'unknown';
+    
+    // Extract function or module name from file path
+    const parts = filePath.split(/[\/]/);
+    const fileName = parts[parts.length - 1];
+    const baseName = fileName.replace(/\.[^/.]+$/, ''); // Remove extension
+    
+    return baseName;
+  }
+}
+
+module.exports = { InvariantDetector };