arcvision 0.2.14 → 0.2.15

package/src/core/invariant-registry.js

@@ -0,0 +1,298 @@
+/**
+ * Invariant Registry - Defines system rules that must never be violated
+ */
+
+class InvariantRegistry {
+  constructor() {
+    this.invariants = new Map();
+  }
+
+  /**
+   * Register a new invariant
+   */
+  register(invariant) {
+    if (!invariant || typeof invariant !== 'object') {
+      console.warn('Warning: Cannot register invalid invariant (not an object)');
+      return false;
+    }
+
+    if (!invariant.id) {
+      console.warn('Warning: Cannot register invariant without ID');
+      return false;
+    }
+
+    // Validate invariant structure
+    if (!this.validateInvariant(invariant)) {
+      console.warn(`Warning: Invariant ${invariant.id} does not meet required structure`);
+      return false;
+    }
+
+    // Add timestamp if not provided
+    if (!invariant.createdAt) {
+      invariant.createdAt = new Date().toISOString();
+    } else {
+      // Ensure createdAt is a valid ISO string
+      try {
+        new Date(invariant.createdAt);
+      } catch (error) {
+        invariant.createdAt = new Date().toISOString();
+      }
+    }
+    
+    this.invariants.set(invariant.id, invariant);
+    return true;
+  }
+
+  /**
+   * Validate invariant structure
+   */
+  validateInvariant(invariant) {
+    if (!invariant.id || typeof invariant.id !== 'string') return false;
+    if (!invariant.system || typeof invariant.system !== 'string') return false;
+    if (!invariant.description || typeof invariant.description !== 'string') return false;
+    if (!invariant.severity || typeof invariant.severity !== 'string' || !['block', 'risk'].includes(invariant.severity)) return false;
+    if (!invariant.scope || typeof invariant.scope !== 'object') return false;
+    if (!invariant.rule || typeof invariant.rule !== 'object') return false;
+    if (!invariant.rule.type || typeof invariant.rule.type !== 'string') return false;
+
+    return true;
+  }
+
+  /**
+   * Get all invariants
+   */
+  getAll() {
+    return Array.from(this.invariants.values());
+  }
+
+  /**
+   * Get invariants by system
+   */
+  getBySystem(system) {
+    if (typeof system !== 'string') {
+      console.warn('Warning: Invalid system parameter for getBySystem');
+      return [];
+    }
+    
+    return this.getAll().filter(inv => inv.system === system);
+  }
+
+  /**
+   * Get invariants that match scope
+   */
+  getMatchingInvariants(files) {
+    if (!Array.isArray(files)) {
+      console.warn('Warning: Invalid files parameter for getMatchingInvariants');
+      return [];
+    }
+    
+    return this.getAll().filter(invariant => 
+      this.matchesScope(files, invariant.scope)
+    );
+  }
+
+  /**
+   * Check if files match invariant scope
+   */
+  matchesScope(files, scope) {
+    if (!Array.isArray(files)) return false;
+    if (!scope || typeof scope !== 'object') return false;
+
+    // If no scope restrictions, always matches
+    if (!scope.files && !scope.components && !scope.flows) {
+      return true;
+    }
+
+    // Check file patterns using robust pattern matcher
+    if (scope.files && Array.isArray(scope.files) && scope.files.length > 0) {
+      try {
+        const { patternMatcher } = require('./pattern-matcher');
+        return files.some(file => {
+          if (typeof file !== 'string') return false;
+          return scope.files.some(pattern => {
+            if (typeof pattern !== 'string') return false;
+            try {
+              return patternMatcher.match(file, pattern, { matchBase: true });
+            } catch (error) {
+              console.warn(`Warning: Invalid pattern "${pattern}" in scope:`, error.message);
+              return false;
+            }
+          });
+        });
+      } catch (error) {
+        console.warn('Warning: Could not process pattern matching for scope matching:', error.message);
+        return false;
+      }
+    }
+
+    // For now, just check files - we can expand to components/flows later
+    return true;
+  }
+
+  /**
+   * Remove invariant by ID
+   */
+  remove(id) {
+    if (typeof id !== 'string') {
+      console.warn('Warning: Invalid ID parameter for remove');
+      return false;
+    }
+    
+    const existed = this.invariants.has(id);
+    this.invariants.delete(id);
+    return existed;
+  }
+
+  /**
+   * Update existing invariant
+   */
+  update(id, invariantUpdates) {
+    if (typeof id !== 'string') {
+      console.warn('Warning: Invalid ID parameter for update');
+      return false;
+    }
+    
+    if (!invariantUpdates || typeof invariantUpdates !== 'object') {
+      console.warn('Warning: Invalid updates parameter for update');
+      return false;
+    }
+
+    const existing = this.invariants.get(id);
+    if (existing) {
+      const updated = { 
+        ...existing, 
+        ...invariantUpdates, 
+        id, // Ensure ID stays the same
+        lastModified: new Date().toISOString() 
+      };
+      
+      // Validate the updated invariant
+      if (this.validateInvariant(updated)) {
+        this.invariants.set(id, updated);
+        return true;
+      } else {
+        console.warn(`Warning: Updated invariant ${id} does not meet required structure`);
+        return false;
+      }
+    }
+    
+    return false;
+  }
+  
+  /**
+   * Load invariants from file
+   */
+  loadFromFile(filePath) {
+    if (typeof filePath !== 'string') {
+      console.warn('Warning: Invalid file path for loadFromFile');
+      return false;
+    }
+
+    try {
+      const fs = require('fs');
+      if (!fs.existsSync(filePath)) {
+        console.warn(`Warning: Invariants file does not exist: ${filePath}`);
+        return false;
+      }
+      
+      const content = fs.readFileSync(filePath, 'utf8');
+      const data = JSON.parse(content);
+      
+      // Handle different possible structures
+      let invariantsToLoad = [];
+      
+      if (Array.isArray(data)) {
+        // Direct array of invariants
+        invariantsToLoad = data;
+      } else if (data.project_specific_invariants) {
+        // Standard ArcVision format
+        invariantsToLoad = data.project_specific_invariants;
+      } else if (data.invariants) {
+        // Alternative format
+        invariantsToLoad = data.invariants;
+      } else {
+        // Try to find invariants in any property
+        const keys = Object.keys(data);
+        for (const key of keys) {
+          if (Array.isArray(data[key]) && data[key].length > 0 && data[key][0].id) {
+            invariantsToLoad = data[key];
+            break;
+          }
+        }
+      }
+      
+      if (!Array.isArray(invariantsToLoad)) {
+        console.warn(`Warning: Could not find valid invariants array in ${filePath}`);
+        return false;
+      }
+
+      // Validate each invariant before loading
+      const validInvariants = invariantsToLoad.filter(invariant => {
+        if (!this.validateInvariant(invariant)) {
+          console.warn(`Warning: Skipping invalid invariant with ID: ${invariant.id || 'unknown'}`);
+          return false;
+        }
+        return true;
+      });
+      
+      // Clear existing invariants and load new ones
+      this.invariants.clear();
+      let loadedCount = 0;
+      validInvariants.forEach(inv => {
+        if (this.register(inv)) {
+          loadedCount++;
+        }
+      });
+      
+      console.log(`Loaded ${loadedCount} valid invariants from ${filePath}`);
+      return true;
+    } catch (error) {
+      console.warn(`Could not load invariants from ${filePath}:`, error.message);
+      return false;
+    }
+  }
+  
+  /**
+   * Save invariants to file
+   */
+  saveToFile(filePath) {
+    if (typeof filePath !== 'string') {
+      console.warn('Warning: Invalid file path for saveToFile');
+      return false;
+    }
+
+    try {
+      const fs = require('fs');
+      const invariants = this.getAll();
+      const data = {
+        version: '1.0',
+        project_specific_invariants: invariants,
+        generated_at: new Date().toISOString()
+      };
+      
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+      return true;
+    } catch (error) {
+      console.error(`Could not save invariants to ${filePath}:`, error.message);
+      return false;
+    }
+  }
+  
+  /**
+   * Get count of registered invariants
+   */
+  getCount() {
+    return this.invariants.size;
+  }
+  
+  /**
+   * Clear all invariants
+   */
+  clear() {
+    this.invariants.clear();
+  }
+}
+
+// Export singleton instance
+const invariantRegistry = new InvariantRegistry();
+module.exports = { InvariantRegistry, invariantRegistry };

package/src/core/invariant-registry.ts

@@ -0,0 +1,100 @@
+/**
+ * Invariant Registry - Defines system rules that must never be violated
+ */
+export type Invariant = {
+  id: string
+  system: string               // e.g. "payments", "auth", "database"
+  description: string
+  severity: "block" | "risk" | "warning"
+  scope: {
+    files?: string[]           // glob paths like "**/payment/**/*.js"
+    components?: string[]      // component names like ["PaymentService", "AuthService"]
+    flows?: string[]          // flow names like ["payment-processing", "auth-flow"]
+  }
+  rule: {
+    type: "dependency" | "flow" | "ownership" | "access_control" | "data_flow"
+    condition: any             // abstract, interpreted by evaluator
+  }
+  owner?: string              // team/person responsible for this invariant
+  createdAt: string          // ISO date string
+  lastModified?: string      // ISO date string
+}
+
+/**
+ * Invariant Registry Manager
+ */
+export class InvariantRegistry {
+  private invariants: Map<string, Invariant> = new Map()
+
+  /**
+   * Register a new invariant
+   */
+  register(invariant: Invariant): void {
+    this.invariants.set(invariant.id, invariant)
+  }
+
+  /**
+   * Get all invariants
+   */
+  getAll(): Invariant[] {
+    return Array.from(this.invariants.values())
+  }
+
+  /**
+   * Get invariants by system
+   */
+  getBySystem(system: string): Invariant[] {
+    return this.getAll().filter(inv => inv.system === system)
+  }
+
+  /**
+   * Get invariants that match scope
+   */
+  getMatchingInvariants(files: string[]): Invariant[] {
+    return this.getAll().filter(invariant => 
+      this.matchesScope(files, invariant.scope)
+    )
+  }
+
+  /**
+   * Check if files match invariant scope
+   */
+  private matchesScope(files: string[], scope: Invariant['scope']): boolean {
+    if (!scope.files && !scope.components && !scope.flows) {
+      return true // no scope restriction = matches all
+    }
+
+    // Check file patterns
+    if (scope.files && scope.files.length > 0) {
+      const minimatch = require('minimatch')
+      return files.some(file => 
+        scope.files!.some(pattern => 
+          minimatch(file, pattern, { matchBase: true })
+        )
+      )
+    }
+
+    // For now, just check files - we can expand to components/flows later
+    return true
+  }
+
+  /**
+   * Remove invariant by ID
+   */
+  remove(id: string): void {
+    this.invariants.delete(id)
+  }
+
+  /**
+   * Update existing invariant
+   */
+  update(id: string, invariant: Partial<Invariant>): void {
+    const existing = this.invariants.get(id)
+    if (existing) {
+      this.invariants.set(id, { ...existing, ...invariant, lastModified: new Date().toISOString() })
+    }
+  }
+}
+
+// Export singleton instance
+export const invariantRegistry = new InvariantRegistry()

package/src/core/invariant-types.js

@@ -0,0 +1,66 @@
+/**
+ * Type definitions for Invariant System
+ * Defines the contract and structure for architectural invariants
+ */
+
+/**
+ * @typedef {Object} Invariant
+ * @property {string} id - Unique identifier for the invariant
+ * @property {string} description - Human-readable description of what the invariant ensures
+ * @property {'module'|'boundary'|'system'} scope - Scope at which the invariant applies
+ * @property {boolean} critical_path - Whether violation causes existential system failure
+ * @property {Function} assertion - Function that evaluates to boolean given context
+ * @property {Function} [on_violation] - Optional handler for when invariant is violated
+ */
+
+/**
+ * @typedef {Object} ViolationEvent
+ * @property {string} timestamp - ISO string timestamp of violation
+ * @property {string} invariantId - ID of the violated invariant
+ * @property {string} invariantDescription - Description of the violated invariant
+ * @property {'module'|'boundary'|'system'} scope - Scope of the invariant
+ * @property {boolean} criticalPath - Whether this is a critical path violation
+ * @property {any} context - Context where violation occurred
+ * @property {string|null} error - Error message if applicable
+ * @property {string|null} stack - Stack trace if applicable
+ */
+
+/**
+ * @typedef {Object} InvariantResult
+ * @property {boolean} passed - Whether the invariant held
+ * @property {ViolationEvent|null} violation - Violation event if invariant failed
+ */
+
+/**
+ * Interface for invariant-aware modules
+ */
+class InvariantAwareInterface {
+  /**
+   * Register invariants for this module/component
+   * @param {Invariant[]} invariants - Array of invariants to register
+   */
+  registerInvariants(invariants) {
+    throw new Error('Must be implemented by subclass');
+  }
+
+  /**
+   * Validate that all registered invariants hold for given context
+   * @param {any} context - Context to validate against
+   * @returns {Object} - Validation results
+   */
+  validateInvariants(context) {
+    throw new Error('Must be implemented by subclass');
+  }
+
+  /**
+   * Get registered invariants
+   * @returns {Invariant[]} - Array of registered invariants
+   */
+  getInvariants() {
+    throw new Error('Must be implemented by subclass');
+  }
+}
+
+module.exports = {
+  InvariantAwareInterface
+};

package/src/core/invariants-index.js

@@ -0,0 +1,88 @@
+/**
+ * Invariant System Index - Main entry point for the invariant system
+ * Provides unified access to all invariant functionality
+ */
+
+const { InvariantRegistry, invariantRegistry } = require('./invariant-registry');
+const { InvariantAwareInterface } = require('./invariant-types');
+const { 
+  CONTEXT_SCHEMA_INVARIANT, 
+  FILE_PATH_BOUNDARY_INVARIANT, 
+  DEPENDENCY_CONSISTENCY_INVARIANT, 
+  PARSER_STATE_INTEGRITY_INVARIANT,
+  registerExampleInvariants 
+} = require('./example-invariants');
+const { 
+  InvariantHooks, 
+  invariantHooks, 
+  CRITICAL_HOOKS, 
+  initializeCriticalHooks 
+} = require('./invariant-hooks');
+const { 
+  InvariantEnforcer, 
+  invariantEnforcer, 
+  initializeEnforcementMechanisms 
+} = require('./invariant-enforcer');
+const {
+  ArcVisionParser,
+  InvariantAwareParser,
+  createInvariantProtectedOperations,
+  demonstrateInvariantProtection
+} = require('./invariant-integration-example');
+
+// Initialize the complete invariant system
+function initializeInvariantSystem() {
+  console.log('Initializing ArcVision Invariant System...');
+  
+  // Register all example invariants
+  registerExampleInvariants();
+  
+  // Initialize critical path hooks
+  initializeCriticalHooks();
+  
+  // Initialize enforcement mechanisms
+  initializeEnforcementMechanisms();
+  
+  console.log('ArcVision Invariant System initialized successfully');
+  console.log(`- ${invariantRegistry.getAll().length} invariants registered`);
+  console.log(`- ${invariantHooks.hooks.size} critical hooks configured`);
+  console.log('- Enforcement mechanisms active');
+}
+
+module.exports = {
+  // Core classes
+  InvariantRegistry,
+  InvariantAwareInterface,
+  InvariantHooks,
+  InvariantEnforcer,
+  
+  // Singleton instances
+  invariantRegistry,
+  invariantHooks,
+  invariantEnforcer,
+  
+  // Example invariants
+  CONTEXT_SCHEMA_INVARIANT,
+  FILE_PATH_BOUNDARY_INVARIANT,
+  DEPENDENCY_CONSISTENCY_INVARIANT,
+  PARSER_STATE_INTEGRITY_INVARIANT,
+  
+  // Registration functions
+  registerExampleInvariants,
+  
+  // Critical hooks
+  CRITICAL_HOOKS,
+  initializeCriticalHooks,
+  
+  // Enforcement
+  initializeEnforcementMechanisms,
+  
+  // Integration examples
+  ArcVisionParser,
+  InvariantAwareParser,
+  createInvariantProtectedOperations,
+  demonstrateInvariantProtection,
+  
+  // System initialization
+  initializeInvariantSystem
+};