arcvision 0.2.14 → 0.2.15

package/src/core/invariant-enforcer.js

@@ -0,0 +1,171 @@
+/**
+ * Invariant Enforcer - Non-bypassable enforcement layer
+ * Ensures developers cannot accidentally bypass invariants
+ */
+
+const { invariantRegistry } = require('./invariant-registry');
+const { invariantHooks } = require('./invariant-hooks');
+
+class InvariantEnforcer {
+  constructor() {
+    // Sealed wrappers for critical operations
+    this.wrappers = new Map();
+    this.enforcedInterfaces = new Map();
+  }
+
+  /**
+   * Create a sealed wrapper that enforces invariants
+   * @param {string} name - Name of the wrapper
+   * @param {Function} implementation - The actual implementation
+   * @param {string} hookName - The hook to execute before the implementation
+   */
+  createSealedWrapper(name, implementation, hookName) {
+    if (this.wrappers.has(name)) {
+      throw new Error(`Wrapper with name ${name} already exists`);
+    }
+
+    const wrappedFunction = async (...args) => {
+      // Execute the hook with invariant checking before the actual implementation
+      return await invariantHooks.executeHook(hookName, { args }, (data) => {
+        return implementation(...data.args);
+      });
+    };
+
+    this.wrappers.set(name, wrappedFunction);
+    return wrappedFunction;
+  }
+
+  /**
+   * Create a synchronous sealed wrapper
+   */
+  createSealedWrapperSync(name, implementation, hookName) {
+    if (this.wrappers.has(name)) {
+      throw new Error(`Wrapper with name ${name} already exists`);
+    }
+
+    const wrappedFunction = (...args) => {
+      // Execute the hook with invariant checking before the actual implementation
+      return invariantHooks.executeHookSync(hookName, { args }, (data) => {
+        return implementation(...data.args);
+      });
+    };
+
+    this.wrappers.set(name, wrappedFunction);
+    return wrappedFunction;
+  }
+
+  /**
+   * Get a sealed wrapper by name
+   */
+  getWrapper(name) {
+    return this.wrappers.get(name);
+  }
+
+  /**
+   * Seal an interface to enforce invariants
+   * @param {Object} targetInterface - The interface/object to seal
+   * @param {Object} invariantSpecs - Specifications for invariant enforcement
+   */
+  sealInterface(targetInterface, invariantSpecs) {
+    const sealedInterface = {};
+    
+    for (const [methodName, spec] of Object.entries(invariantSpecs)) {
+      if (typeof targetInterface[methodName] === 'function') {
+        sealedInterface[methodName] = async (...args) => {
+          // Execute the appropriate hook before the method
+          return await invariantHooks.executeHook(spec.hookName, { args }, (data) => {
+            return targetInterface[methodName](...data.args);
+          });
+        };
+        
+        // Also create a synchronous version
+        sealedInterface[`${methodName}Sync`] = (...args) => {
+          return invariantHooks.executeHookSync(spec.hookName, { args }, (data) => {
+            return targetInterface[methodName](...data.args);
+          });
+        };
+      }
+    }
+    
+    // Prevent further modifications to enforce the contract
+    Object.freeze(sealedInterface);
+    this.enforcedInterfaces.set(targetInterface.constructor?.name || 'anonymous', sealedInterface);
+    
+    return sealedInterface;
+  }
+
+  /**
+   * Decorator-style enforcement for class methods
+   */
+  enforceMethod(target, methodName, hookName) {
+    const originalMethod = target[methodName];
+    
+    if (typeof originalMethod !== 'function') {
+      throw new Error(`Method ${methodName} does not exist on target`);
+    }
+
+    // Replace the method with an invariant-enforced version
+    target[methodName] = async function(...args) {
+      return await invariantHooks.executeHook(hookName, { args, context: this }, (data) => {
+        return originalMethod.apply(data.context, data.args);
+      });
+    };
+    
+    // Also add a sync version
+    target[`${methodName}Sync`] = function(...args) {
+      return invariantHooks.executeHookSync(hookName, { args, context: this }, (data) => {
+        return originalMethod.apply(data.context, data.args);
+      });
+    };
+  }
+
+  /**
+   * Framework-level hook integration
+   * This would be used to integrate with the existing ArcVision architecture
+   */
+  integrateWithFramework(frameworkHooks) {
+    // Example: Integrate with existing ArcVision hooks
+    if (frameworkHooks && typeof frameworkHooks.addPreHook === 'function') {
+      frameworkHooks.addPreHook('parse-file', async (context) => {
+        // This runs before file parsing and enforces invariants
+        await invariantHooks.executeHook('pre-parse', context, () => {});
+      });
+
+      frameworkHooks.addPostHook('analyze-file', async (context) => {
+        // This runs after analysis and enforces invariants
+        await invariantHooks.executeHook('post-analyze', context, () => {});
+      });
+    }
+  }
+
+  /**
+   * Get all active enforcement mechanisms
+   */
+  getStatus() {
+    return {
+      wrapperCount: this.wrappers.size,
+      interfaceCount: this.enforcedInterfaces.size,
+      registeredHooks: invariantHooks.hooks.size,
+      registeredInvariants: invariantRegistry.getAll().length
+    };
+  }
+}
+
+// Singleton enforcer instance
+const invariantEnforcer = new InvariantEnforcer();
+
+// Initialize common sealed wrappers for ArcVision operations
+function initializeEnforcementMechanisms() {
+  console.log('Initializing invariant enforcement mechanisms...');
+  
+  // Example: Seal critical ArcVision operations
+  // These would wrap the actual parsing, analysis, and persistence functions
+  
+  console.log('Invariant enforcement mechanisms initialized');
+}
+
+module.exports = {
+  InvariantEnforcer,
+  invariantEnforcer,
+  initializeEnforcementMechanisms
+};

package/src/core/invariant-evaluation-utils.js

@@ -0,0 +1,172 @@
+/**
+ * Enhanced Invariant Evaluation Utilities
+ * Provides strengthened logic for invariant validation and evaluation
+ */
+
+/**
+ * Validates that an invariant object has required properties
+ */
+function isValidInvariant(invariant) {
+  if (!invariant || typeof invariant !== 'object') {
+    return false;
+  }
+  
+  // Check for required fields
+  if (!invariant.id || typeof invariant.id !== 'string' || invariant.id.trim().length === 0) {
+    return false;
+  }
+  
+  if (!invariant.system || typeof invariant.system !== 'string' || invariant.system.trim().length === 0) {
+    return false;
+  }
+  
+  if (!invariant.description || typeof invariant.description !== 'string' || invariant.description.trim().length === 0) {
+    return false;
+  }
+  
+  if (!invariant.severity || typeof invariant.severity !== 'string' || !['block', 'risk', '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;
+  }
+  
+  return true;
+}
+
+/**
+ * Sanitize and normalize changed files array
+ */
+function sanitizeChangedFiles(changedFiles) {
+  if (!Array.isArray(changedFiles)) {
+    return [];
+  }
+  
+  return changedFiles
+    .filter(file => file && typeof file === 'string' && file.trim().length > 0)
+    .map(file => file.trim());
+}
+
+/**
+ * Sanitize and normalize invariants array
+ */
+function sanitizeInvariants(invariants) {
+  if (!Array.isArray(invariants)) {
+    return [];
+  }
+  
+  return invariants
+    .filter(inv => inv && typeof inv === 'object' && isValidInvariant(inv));
+}
+
+/**
+ * Enhanced evaluation result formatter
+ */
+function formatEnhancedResult(decision, violations, input) {
+  const blockingViolations = violations.filter(v => 
+    v.severity === 'block' || v.severity === 'BLOCK'
+  );
+  
+  const riskyViolations = violations.filter(v => 
+    v.severity === 'risk' || v.severity === 'RISK'
+  );
+  
+  const baseResult = {
+    decision,
+    violations,
+    blockingViolations: blockingViolations.length,
+    riskyViolations: riskyViolations.length,
+    details: calculateImpactDetails(input, violations)
+  };
+  
+  switch (decision) {
+    case 'BLOCKED':
+      return {
+        ...baseResult,
+        reasons: violations.map(v => v.description || `Critical violation in invariant: ${v.id}`)
+      };
+    
+    case 'RISKY':
+      return {
+        ...baseResult,
+        reasons: violations.map(v => v.description || `Potential violation in invariant: ${v.id}`)
+      };
+    
+    case 'ALLOWED':
+    default:
+      return {
+        ...baseResult,
+        violations: [],
+        reasons: ['No invariant violations detected']
+      };
+  }
+}
+
+/**
+ * Calculate impact details for the evaluation result
+ */
+function calculateImpactDetails(input, violations) {
+  const { changedFiles, dependencyGraph, context } = input || {};
+  
+  // Calculate affected nodes from dependency graph
+  let affectedNodes = 0;
+  if (dependencyGraph && dependencyGraph.nodes && Array.isArray(dependencyGraph.nodes)) {
+    affectedNodes = dependencyGraph.nodes.filter((node) => 
+      changedFiles && Array.isArray(changedFiles) && 
+      changedFiles.includes(node.id || node.path)
+    ).length;
+  }
+
+  // Calculate blast radius impact if available in context
+  let blastRadiusImpact = 0;
+  if (context && context.blastRadiusAnalysis) {
+    blastRadiusImpact = context.blastRadiusAnalysis.totalAffected || 0;
+  }
+
+  // Check for authority core changes
+  let authorityCoreChanges = false;
+  if (context && Array.isArray(context.authorityCores)) {
+    authorityCoreChanges = changedFiles && Array.isArray(changedFiles) && 
+      changedFiles.some(file => 
+        context.authorityCores.some((core) => core.path === file)
+      );
+  }
+
+  return {
+    affectedNodes,
+    blastRadiusImpact,
+    authorityCoreChanges
+  };
+}
+
+/**
+ * Enhanced error result creator
+ */
+function createEnhancedErrorResult(errorMessage) {
+  return {
+    decision: 'ERROR',
+    violations: [],
+    blockingViolations: 0,
+    riskyViolations: 0,
+    reasons: [errorMessage],
+    details: {
+      affectedNodes: 0,
+      blastRadiusImpact: 0,
+      authorityCoreChanges: false
+    }
+  };
+}
+
+module.exports = {
+  isValidInvariant,
+  sanitizeChangedFiles,
+  sanitizeInvariants,
+  formatEnhancedResult,
+  calculateImpactDetails,
+  createEnhancedErrorResult
+};

package/src/core/invariant-hooks.js

@@ -0,0 +1,152 @@
+/**
+ * Invariant Hooks - Critical path enforcement points
+ * Implements mandatory invariant checks at high-leverage choke points
+ */
+
+const { invariantRegistry } = require('./invariant-registry');
+
+class InvariantHooks {
+  constructor() {
+    this.hooks = new Map();
+  }
+
+  /**
+   * Register a hook at a critical execution point
+   * @param {string} hookName - Name of the hook (e.g., 'pre-parse', 'post-analyze')
+   * @param {string[]} invariantIds - Array of invariant IDs to check at this hook
+   * @param {Function} contextProvider - Function that provides context for invariant evaluation
+   */
+  registerHook(hookName, invariantIds, contextProvider) {
+    this.hooks.set(hookName, {
+      invariantIds,
+      contextProvider
+    });
+  }
+
+  /**
+   * Execute a hook with invariant checking
+   * @param {string} hookName - Name of the hook to execute
+   * @param {any} data - Input data for the hook
+   * @param {Function} next - The actual function to execute after invariant checks
+   */
+  async executeHook(hookName, data, next) {
+    const hook = this.hooks.get(hookName);
+    if (!hook) {
+      // If no hook is registered, just execute the function
+      return await next(data);
+    }
+
+    // Get context for invariant evaluation
+    const context = hook.contextProvider ? hook.contextProvider(data) : data;
+
+    // Check all registered invariants for this hook
+    const results = invariantRegistry.checkMultiple(hook.invariantIds, context);
+
+    // If all invariants passed, proceed with the actual function
+    if (Object.values(results).every(result => result === true)) {
+      return await next(data);
+    } else {
+      // Some invariants failed, the registry already handled the violation
+      // according to each invariant's critical_path setting
+      throw new Error(`Invariant violation prevented execution of hook: ${hookName}`);
+    }
+  }
+
+  /**
+   * Execute a hook synchronously
+   */
+  executeHookSync(hookName, data, next) {
+    const hook = this.hooks.get(hookName);
+    if (!hook) {
+      return next(data);
+    }
+
+    // Get context for invariant evaluation
+    const context = hook.contextProvider ? hook.contextProvider(data) : data;
+
+    // Check all registered invariants for this hook
+    const results = invariantRegistry.checkMultiple(hook.invariantIds, context);
+
+    // If all invariants passed, proceed with the actual function
+    if (Object.values(results).every(result => result === true)) {
+      return next(data);
+    } else {
+      // Some invariants failed, the registry already handled the violation
+      throw new Error(`Invariant violation prevented execution of hook: ${hookName}`);
+    }
+  }
+}
+
+// Create singleton instance
+const invariantHooks = new InvariantHooks();
+
+// Predefined critical path hooks for ArcVision system
+const CRITICAL_HOOKS = {
+  // Hook for when a file is about to be parsed
+  PRE_PARSE: 'pre-parse',
+  
+  // Hook for when AST analysis is complete
+  POST_ANALYZE: 'post-analyze',
+  
+  // Hook for when context is about to be persisted
+  PRE_PERSIST: 'pre-persist',
+  
+  // Hook for when external data is received (e.g., from dashboard API)
+  PRE_EXTERNAL_INPUT: 'pre-external-input',
+  
+  // Hook for when module dependencies are being resolved
+  PRE_DEPENDENCY_RESOLUTION: 'pre-dependency-resolution'
+};
+
+// Register critical path hooks with appropriate invariants
+function initializeCriticalHooks() {
+  // Hook before file parsing - check parser state integrity and file path boundaries
+  invariantHooks.registerHook(
+    CRITICAL_HOOKS.PRE_PARSE,
+    ['parser-state-integrity', 'file-path-boundary'],
+    (data) => ({
+      parserState: data.parserState,
+      filePath: data.filePath
+    })
+  );
+
+  // Hook after analysis - check context schema conformance
+  invariantHooks.registerHook(
+    CRITICAL_HOOKS.POST_ANALYZE,
+    ['context-schema-conformance'],
+    (data) => data.context
+  );
+
+  // Hook before persisting context - check schema conformance
+  invariantHooks.registerHook(
+    CRITICAL_HOOKS.PRE_PERSIST,
+    ['context-schema-conformance'],
+    (data) => data.context
+  );
+
+  // Hook for external input - check schema and boundaries
+  invariantHooks.registerHook(
+    CRITICAL_HOOKS.PRE_EXTERNAL_INPUT,
+    ['context-schema-conformance', 'file-path-boundary'],
+    (data) => data
+  );
+
+  // Hook for dependency resolution - check dependency consistency
+  invariantHooks.registerHook(
+    CRITICAL_HOOKS.PRE_DEPENDENCY_RESOLUTION,
+    ['dependency-consistency'],
+    (data) => ({
+      dependencies: data.dependencies,
+      availableModules: data.availableModules
+    })
+  );
+
+  console.log(`${invariantHooks.hooks.size} critical path hooks initialized`);
+}
+
+module.exports = {
+  InvariantHooks,
+  invariantHooks,
+  CRITICAL_HOOKS,
+  initializeCriticalHooks
+};

package/src/core/invariant-integration-example.js

@@ -0,0 +1,186 @@
+/**
+ * Invariant Integration Example
+ * Shows how the invariant system integrates with existing ArcVision components
+ */
+
+const { invariantRegistry } = require('./invariant-registry');
+const { invariantHooks, CRITICAL_HOOKS } = require('./invariant-hooks');
+const { invariantEnforcer } = require('./invariant-enforcer');
+const { registerExampleInvariants } = require('./example-invariants');
+
+// Example ArcVision Parser class (representing existing functionality)
+class ArcVisionParser {
+  constructor() {
+    this.currentState = {
+      currentFile: null,
+      dependencies: [],
+      ast: null
+    };
+  }
+
+  // Method to parse a file - this would be wrapped with invariant enforcement
+  async parseFile(filePath) {
+    console.log(`Parsing file: ${filePath}`);
+    
+    // Simulate parsing logic
+    this.currentState.currentFile = filePath;
+    this.currentState.dependencies = ['example-dependency'];
+    this.currentState.ast = { type: 'Program', body: [] };
+    
+    return this.currentState.ast;
+  }
+
+  // Method to analyze dependencies - this would also be wrapped
+  async analyzeDependencies(dependencies) {
+    console.log(`Analyzing ${dependencies.length} dependencies`);
+    
+    // Simulate analysis logic
+    const analysisResults = dependencies.map(dep => ({
+      name: dep,
+      status: 'valid',
+      references: []
+    }));
+    
+    return analysisResults;
+  }
+
+  // Method to persist context - this would be wrapped too
+  async persistContext(context) {
+    console.log(`Persisting context with ${context.nodes?.length || 0} nodes`);
+    
+    // Simulate persistence logic
+    return { success: true, id: 'context-id' };
+  }
+}
+
+// Example of how to integrate invariants with the existing parser
+class InvariantAwareParser {
+  constructor() {
+    this.parser = new ArcVisionParser();
+    
+    // Initialize the invariant system
+    registerExampleInvariants();
+    require('./invariant-hooks').initializeCriticalHooks();
+    require('./invariant-enforcer').initializeEnforcementMechanisms();
+    
+    // Seal the parser interface with invariant enforcement
+    this.sealedParser = invariantEnforcer.sealInterface(this.parser, {
+      parseFile: { hookName: CRITICAL_HOOKS.PRE_PARSE },
+      analyzeDependencies: { hookName: CRITICAL_HOOKS.PRE_DEPENDENCY_RESOLUTION },
+      persistContext: { hookName: CRITICAL_HOOKS.PRE_PERSIST }
+    });
+  }
+
+  // Public methods that enforce invariants
+  async parseFile(filePath) {
+    // This calls the sealed interface which enforces invariants
+    return await this.sealedParser.parseFile(filePath);
+  }
+
+  async analyzeDependencies(dependencies) {
+    // This calls the sealed interface which enforces invariants
+    return await this.sealedParser.analyzeDependencies(dependencies);
+  }
+
+  async persistContext(context) {
+    // This calls the sealed interface which enforces invariants
+    return await this.sealedParser.persistContext(context);
+  }
+
+  // Alternative: Use method decoration on existing instances
+  static enhanceExistingParser(parserInstance) {
+    // Decorate individual methods with invariant enforcement
+    invariantEnforcer.enforceMethod(parserInstance, 'parseFile', CRITICAL_HOOKS.PRE_PARSE);
+    invariantEnforcer.enforceMethod(parserInstance, 'analyzeDependencies', CRITICAL_HOOKS.PRE_DEPENDENCY_RESOLUTION);
+    invariantEnforcer.enforceMethod(parserInstance, 'persistContext', CRITICAL_HOOKS.PRE_PERSIST);
+    
+    return parserInstance;
+  }
+}
+
+// Example of using sealed wrappers for specific operations
+function createInvariantProtectedOperations() {
+  // Create a protected file parsing operation
+  const protectedParseFile = invariantEnforcer.createSealedWrapper(
+    'protected-parse-file',
+    async (filePath) => {
+      console.log(`Actually parsing file: ${filePath}`);
+      // Actual parsing logic here
+      return { ast: { type: 'Program' }, filePath };
+    },
+    CRITICAL_HOOKS.PRE_PARSE
+  );
+
+  // Create a protected persistence operation
+  const protectedPersistContext = invariantEnforcer.createSealedWrapper(
+    'protected-persist-context',
+    async (context) => {
+      console.log(`Actually persisting context: ${context.id}`);
+      // Actual persistence logic here
+      return { success: true, persistedId: context.id };
+    },
+    CRITICAL_HOOKS.PRE_PERSIST
+  );
+
+  return {
+    protectedParseFile,
+    protectedPersistContext
+  };
+}
+
+// Demonstration function showing how invariants prevent systemic issues
+async function demonstrateInvariantProtection() {
+  console.log('\n=== Demonstrating Invariant Protection ===\n');
+  
+  const parser = new InvariantAwareParser();
+  
+  try {
+    // This should work fine - valid inputs that satisfy invariants
+    console.log('1. Valid operation:');
+    await parser.parseFile('./valid-file.js');
+    console.log('   ✓ Parse successful\n');
+    
+    // This should trigger dependency consistency warning (non-critical)
+    console.log('2. Testing dependency consistency:');
+    await parser.analyzeDependencies([{ name: 'missing-dep' }]);
+    console.log('   ^ Warning logged but operation continues\n');
+    
+    // This should fail critically if parser state is invalid
+    console.log('3. Testing parser state integrity:');
+    try {
+      // Simulate invalid parser state
+      await invariantHooks.executeHook(
+        CRITICAL_HOOKS.PRE_PARSE, 
+        { parserState: { currentFile: '', dependencies: 'invalid-type' } },
+        () => {}
+      );
+    } catch (error) {
+      console.log(`   ✓ Critical violation properly blocked: ${error.message}\n`);
+    }
+    
+    // Show system status
+    console.log('4. System Status:');
+    const status = invariantEnforcer.getStatus();
+    console.log(`   - Registered invariants: ${status.registeredInvariants}`);
+    console.log(`   - Active hooks: ${status.registeredHooks}`);
+    console.log(`   - Protected wrappers: ${status.wrapperCount}`);
+    
+  } catch (error) {
+    console.error('Error during demonstration:', error);
+  }
+}
+
+// Export for use in other parts of the system
+module.exports = {
+  ArcVisionParser,
+  InvariantAwareParser,
+  createInvariantProtectedOperations,
+  demonstrateInvariantProtection
+};
+
+// If run directly, demonstrate the system
+if (require.main === module) {
+  demonstrateInvariantProtection()
+    .then(() => console.log('\nDemonstration complete'))
+    .catch(console.error);
+}