@vibecheckai/cli 3.2.6 → 3.3.0

package/bin/runners/lib/agent-firewall/lawbook/evaluator.js

@@ -0,0 +1,604 @@
+/**
+ * Lawbook Invariant Evaluator
+ * 
+ * Evaluates change proposals against organizational invariant rules.
+ * Returns violations with severity and remediation suggestions.
+ * 
+ * Codename: Lawbook
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { minimatch } = require("minimatch");
+
+const {
+  INVARIANT_TYPES,
+  INVARIANT_SEVERITY,
+  validateInvariant,
+} = require("./schema.js");
+const { lawbookLogger: log, getErrorMessage } = require("../logger.js");
+
+/**
+ * @typedef {Object} Violation
+ * @property {string} invariantId - Invariant that was violated
+ * @property {string} rule - Rule type
+ * @property {string} severity - Violation severity
+ * @property {string} file - File where violation occurred
+ * @property {number} line - Line number (if applicable)
+ * @property {string} message - Human-readable message
+ * @property {string} evidence - Evidence of the violation
+ * @property {Object} suggestion - Suggested fix
+ */
+
+/**
+ * @typedef {Object} EvaluationResult
+ * @property {boolean} passed - Did evaluation pass (no blocking violations)
+ * @property {Violation[]} violations - All violations found
+ * @property {Object} summary - Summary by severity
+ */
+
+/**
+ * Invariant Evaluator class
+ */
+class InvariantEvaluator {
+  constructor(options = {}) {
+    this.invariants = [];
+    this.envRegistry = null;
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.strictMode = options.strictMode || false;
+  }
+  
+  /**
+   * Load invariants from a lawbook
+   * @param {Object} lawbook - Parsed lawbook
+   */
+  loadLawbook(lawbook) {
+    if (!lawbook || !lawbook.invariants) return;
+    
+    for (const invariant of lawbook.invariants) {
+      const validation = validateInvariant(invariant);
+      if (validation.valid) {
+        this.invariants.push(invariant);
+      } else if (this.strictMode) {
+        throw new Error(`Invalid invariant ${invariant.id}: ${validation.errors.map(e => e.message).join(", ")}`);
+      }
+    }
+  }
+  
+  /**
+   * Load environment variable registry for env-must-be-registered rules
+   * @param {string} registryPath - Path to registry file
+   */
+  loadEnvRegistry(registryPath) {
+    try {
+      const fullPath = path.resolve(this.projectRoot, registryPath);
+      const content = fs.readFileSync(fullPath, "utf-8");
+      
+      // Parse .env.example style file
+      const registry = new Set();
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        
+        const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=/);
+        if (match) {
+          registry.add(match[1]);
+        }
+      }
+      
+      this.envRegistry = registry;
+    } catch (error) {
+      log.warn(`Failed to load env registry: ${getErrorMessage(error)}`);
+    }
+  }
+  
+  /**
+   * Evaluate a change proposal against all invariants
+   * @param {Object} proposal - Change proposal
+   * @returns {EvaluationResult} Evaluation result
+   */
+  evaluate(proposal) {
+    const violations = [];
+    
+    for (const invariant of this.invariants) {
+      const invariantViolations = this.evaluateInvariant(invariant, proposal);
+      violations.push(...invariantViolations);
+    }
+    
+    // Calculate summary
+    const summary = {
+      total: violations.length,
+      block: violations.filter(v => v.severity === INVARIANT_SEVERITY.BLOCK).length,
+      error: violations.filter(v => v.severity === INVARIANT_SEVERITY.ERROR).length,
+      warning: violations.filter(v => v.severity === INVARIANT_SEVERITY.WARNING).length,
+      info: violations.filter(v => v.severity === INVARIANT_SEVERITY.INFO).length,
+    };
+    
+    return {
+      passed: summary.block === 0 && summary.error === 0,
+      violations,
+      summary,
+    };
+  }
+  
+  /**
+   * Evaluate a single invariant against a proposal
+   * @param {Object} invariant - Invariant to check
+   * @param {Object} proposal - Change proposal
+   * @returns {Violation[]} Violations found
+   */
+  evaluateInvariant(invariant, proposal) {
+    switch (invariant.rule) {
+      case INVARIANT_TYPES.NO_MODIFY:
+        return this.evaluateNoModify(invariant, proposal);
+        
+      case INVARIANT_TYPES.NO_DELETE:
+        return this.evaluateNoDelete(invariant, proposal);
+        
+      case INVARIANT_TYPES.NO_CREATE:
+        return this.evaluateNoCreate(invariant, proposal);
+        
+      case INVARIANT_TYPES.NEVER:
+        return this.evaluateNever(invariant, proposal);
+        
+      case INVARIANT_TYPES.ALWAYS:
+        return this.evaluateAlways(invariant, proposal);
+        
+      case INVARIANT_TYPES.ALL_THROUGH:
+        return this.evaluateAllThrough(invariant, proposal);
+        
+      case INVARIANT_TYPES.NO_DIRECT:
+        return this.evaluateNoDirect(invariant, proposal);
+        
+      case INVARIANT_TYPES.ENV_MUST_BE_REGISTERED:
+        return this.evaluateEnvMustBeRegistered(invariant, proposal);
+        
+      case INVARIANT_TYPES.REQUIRE_APPROVAL:
+        return this.evaluateRequireApproval(invariant, proposal);
+        
+      default:
+        return [];
+    }
+  }
+  
+  /**
+   * Check if a file matches an invariant's scope
+   * @param {string} filePath - File path to check
+   * @param {Object} invariant - Invariant with scope
+   * @returns {boolean} Does file match scope
+   */
+  matchesScope(filePath, invariant) {
+    if (!invariant.scope) return true;
+    
+    const relativePath = path.relative(this.projectRoot, filePath).replace(/\\/g, "/");
+    
+    // Check if matches scope
+    const matchesInclude = minimatch(relativePath, invariant.scope, { dot: true });
+    
+    // Check if excluded
+    if (matchesInclude && invariant.exclude) {
+      const excludes = Array.isArray(invariant.exclude) ? invariant.exclude : [invariant.exclude];
+      for (const exclude of excludes) {
+        if (minimatch(relativePath, exclude, { dot: true })) {
+          return false;
+        }
+      }
+    }
+    
+    return matchesInclude;
+  }
+  
+  /**
+   * Create a violation object
+   * @param {Object} invariant - Violated invariant
+   * @param {Object} details - Violation details
+   * @returns {Violation} Violation object
+   */
+  createViolation(invariant, details) {
+    return {
+      invariantId: invariant.id,
+      rule: invariant.rule,
+      severity: invariant.severity || INVARIANT_SEVERITY.ERROR,
+      file: details.file || null,
+      line: details.line || null,
+      message: details.message || invariant.message || invariant.description,
+      evidence: details.evidence || null,
+      suggestion: details.suggestion || null,
+    };
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // RULE EVALUATORS
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  /**
+   * Evaluate no-modify rule
+   */
+  evaluateNoModify(invariant, proposal) {
+    const violations = [];
+    
+    for (const op of proposal.operations || []) {
+      if (op.type === "modify" || op.type === "update") {
+        const filePath = op.path || op.file;
+        if (filePath && this.matchesScope(filePath, invariant)) {
+          violations.push(this.createViolation(invariant, {
+            file: filePath,
+            message: `File is protected by '${invariant.id}' - modifications not allowed`,
+            evidence: `Attempted to modify: ${filePath}`,
+            suggestion: {
+              action: "remove_operation",
+              reason: invariant.description || "This file/path is protected",
+              incident: invariant.incident,
+            },
+          }));
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate no-delete rule
+   */
+  evaluateNoDelete(invariant, proposal) {
+    const violations = [];
+    
+    for (const op of proposal.operations || []) {
+      if (op.type === "delete" || op.type === "remove") {
+        const filePath = op.path || op.file;
+        if (filePath && this.matchesScope(filePath, invariant)) {
+          violations.push(this.createViolation(invariant, {
+            file: filePath,
+            message: `File is protected by '${invariant.id}' - deletion not allowed`,
+            evidence: `Attempted to delete: ${filePath}`,
+            suggestion: {
+              action: "remove_operation",
+              reason: invariant.description || "This file/path cannot be deleted",
+            },
+          }));
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate no-create rule
+   */
+  evaluateNoCreate(invariant, proposal) {
+    const violations = [];
+    
+    for (const op of proposal.operations || []) {
+      if (op.type === "create" || op.type === "add") {
+        const filePath = op.path || op.file;
+        if (filePath && this.matchesScope(filePath, invariant)) {
+          violations.push(this.createViolation(invariant, {
+            file: filePath,
+            message: `Creating files matching '${invariant.scope}' is not allowed`,
+            evidence: `Attempted to create: ${filePath}`,
+            suggestion: {
+              action: "remove_operation",
+              reason: invariant.description || "This pattern is forbidden",
+            },
+          }));
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate never rule (pattern must not appear)
+   */
+  evaluateNever(invariant, proposal) {
+    const violations = [];
+    const pattern = new RegExp(invariant.pattern, "gm");
+    
+    for (const op of proposal.operations || []) {
+      const filePath = op.path || op.file;
+      if (!filePath || !this.matchesScope(filePath, invariant)) continue;
+      
+      const content = op.content || op.newContent;
+      if (!content) continue;
+      
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const matches = line.match(pattern);
+        
+        if (matches) {
+          violations.push(this.createViolation(invariant, {
+            file: filePath,
+            line: i + 1,
+            message: `Pattern '${invariant.pattern}' is forbidden by '${invariant.id}'`,
+            evidence: line.trim(),
+            suggestion: {
+              action: "remove_pattern",
+              pattern: invariant.pattern,
+              reason: invariant.description,
+            },
+          }));
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate always rule (pattern must be present)
+   */
+  evaluateAlways(invariant, proposal) {
+    const violations = [];
+    const pattern = new RegExp(invariant.pattern);
+    
+    for (const op of proposal.operations || []) {
+      const filePath = op.path || op.file;
+      if (!filePath || !this.matchesScope(filePath, invariant)) continue;
+      
+      // Only check newly created or modified files
+      if (op.type !== "create" && op.type !== "modify") continue;
+      
+      const content = op.content || op.newContent;
+      if (!content) continue;
+      
+      if (!pattern.test(content)) {
+        violations.push(this.createViolation(invariant, {
+          file: filePath,
+          message: `Required pattern '${invariant.pattern}' is missing (required by '${invariant.id}')`,
+          evidence: `Pattern not found in file`,
+          suggestion: {
+            action: "add_pattern",
+            pattern: invariant.pattern,
+            reason: invariant.description,
+          },
+        }));
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate all-through rule (all X must go through Y)
+   */
+  evaluateAllThrough(invariant, proposal) {
+    const violations = [];
+    
+    if (!invariant.violations || !invariant.target) return violations;
+    
+    for (const op of proposal.operations || []) {
+      const filePath = op.path || op.file;
+      if (!filePath) continue;
+      
+      // Skip the target file itself
+      const relativePath = path.relative(this.projectRoot, filePath).replace(/\\/g, "/");
+      if (relativePath === invariant.target || minimatch(relativePath, invariant.target, { dot: true })) {
+        continue;
+      }
+      
+      const content = op.content || op.newContent;
+      if (!content) continue;
+      
+      // Check each violation pattern
+      for (const violationDef of invariant.violations) {
+        // Skip if file is excluded
+        if (violationDef.exclude) {
+          const excludes = Array.isArray(violationDef.exclude) ? violationDef.exclude : [violationDef.exclude];
+          let excluded = false;
+          for (const exclude of excludes) {
+            if (minimatch(relativePath, exclude, { dot: true })) {
+              excluded = true;
+              break;
+            }
+          }
+          if (excluded) continue;
+        }
+        
+        const pattern = new RegExp(violationDef.pattern, "gm");
+        const lines = content.split("\n");
+        
+        for (let i = 0; i < lines.length; i++) {
+          if (pattern.test(lines[i])) {
+            violations.push(this.createViolation(invariant, {
+              file: filePath,
+              line: i + 1,
+              message: violationDef.message || `Must use ${invariant.target} instead of direct access`,
+              evidence: lines[i].trim(),
+              suggestion: {
+                action: "use_approved_path",
+                target: invariant.target,
+                reason: invariant.description,
+              },
+            }));
+          }
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate no-direct rule (must use approved pattern)
+   */
+  evaluateNoDirect(invariant, proposal) {
+    const violations = [];
+    const pattern = new RegExp(invariant.pattern, "gm");
+    
+    for (const op of proposal.operations || []) {
+      const filePath = op.path || op.file;
+      if (!filePath || !this.matchesScope(filePath, invariant)) continue;
+      
+      const content = op.content || op.newContent;
+      if (!content) continue;
+      
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i])) {
+          violations.push(this.createViolation(invariant, {
+            file: filePath,
+            line: i + 1,
+            message: `Direct access to '${invariant.pattern}' is forbidden`,
+            evidence: lines[i].trim(),
+            suggestion: {
+              action: "use_abstraction",
+              reason: invariant.description,
+            },
+          }));
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate env-must-be-registered rule
+   */
+  evaluateEnvMustBeRegistered(invariant, proposal) {
+    const violations = [];
+    
+    // Load registry if not loaded
+    if (!this.envRegistry && invariant.registry) {
+      this.loadEnvRegistry(invariant.registry);
+    }
+    
+    if (!this.envRegistry) return violations;
+    
+    // Pattern to find env var usage
+    const envPattern = /process\.env\.([A-Z_][A-Z0-9_]*)|import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g;
+    
+    for (const op of proposal.operations || []) {
+      const filePath = op.path || op.file;
+      if (!filePath || !this.matchesScope(filePath, invariant)) continue;
+      
+      const content = op.content || op.newContent;
+      if (!content) continue;
+      
+      let match;
+      const lines = content.split("\n");
+      
+      for (let i = 0; i < lines.length; i++) {
+        while ((match = envPattern.exec(lines[i])) !== null) {
+          const envVar = match[1] || match[2];
+          
+          if (!this.envRegistry.has(envVar)) {
+            violations.push(this.createViolation(invariant, {
+              file: filePath,
+              line: i + 1,
+              message: `Environment variable '${envVar}' is not registered in ${invariant.registry}`,
+              evidence: lines[i].trim(),
+              suggestion: {
+                action: "register_env_var",
+                variable: envVar,
+                registry: invariant.registry,
+              },
+            }));
+          }
+        }
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Evaluate require-approval rule
+   */
+  evaluateRequireApproval(invariant, proposal) {
+    const violations = [];
+    
+    for (const op of proposal.operations || []) {
+      const filePath = op.path || op.file;
+      if (!filePath || !this.matchesScope(filePath, invariant)) continue;
+      
+      // Check if proposal has required approval
+      const hasApproval = proposal.approvals?.some(a => 
+        a.invariantId === invariant.id && a.approved
+      );
+      
+      if (!hasApproval) {
+        violations.push(this.createViolation(invariant, {
+          file: filePath,
+          message: `Changes to '${filePath}' require approval`,
+          evidence: `Operation type: ${op.type}`,
+          suggestion: {
+            action: "request_approval",
+            owner: invariant.owner,
+            reason: invariant.description,
+          },
+        }));
+      }
+    }
+    
+    return violations;
+  }
+  
+  /**
+   * Get all invariants
+   * @returns {Object[]} All loaded invariants
+   */
+  getInvariants() {
+    return [...this.invariants];
+  }
+  
+  /**
+   * Get invariant by ID
+   * @param {string} id - Invariant ID
+   * @returns {Object|null} Invariant or null
+   */
+  getInvariant(id) {
+    return this.invariants.find(i => i.id === id) || null;
+  }
+  
+  /**
+   * Add a single invariant
+   * @param {Object} invariant - Invariant to add
+   */
+  addInvariant(invariant) {
+    const validation = validateInvariant(invariant);
+    if (!validation.valid) {
+      throw new Error(`Invalid invariant: ${validation.errors.map(e => e.message).join(", ")}`);
+    }
+    this.invariants.push(invariant);
+  }
+  
+  /**
+   * Remove an invariant
+   * @param {string} id - Invariant ID to remove
+   * @returns {boolean} Success
+   */
+  removeInvariant(id) {
+    const index = this.invariants.findIndex(i => i.id === id);
+    if (index !== -1) {
+      this.invariants.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  
+  /**
+   * Clear all invariants
+   */
+  clear() {
+    this.invariants = [];
+    this.envRegistry = null;
+  }
+}
+
+/**
+ * Create an evaluator instance
+ * @param {Object} options - Options
+ * @returns {InvariantEvaluator} Evaluator instance
+ */
+function createEvaluator(options = {}) {
+  return new InvariantEvaluator(options);
+}
+
+module.exports = { InvariantEvaluator, createEvaluator };