vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/agent-firewall/intent/alignment-engine.js

@@ -0,0 +1,634 @@
+/**
+ * Intent Alignment Engine - Core Enforcement Logic
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AGENT FIREWALL™ - INTENT ALIGNMENT ENGINE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * For every Change Event:
+ * - Compare change against declared intent
+ * - Enforce STRICT matching rules
+ * - BLOCK if intent is violated
+ * 
+ * This is NOT advisory. This is enforcement.
+ * 
+ * @module intent/alignment-engine
+ * @version 2.0.0
+ */
+
+"use strict";
+
+const path = require("path");
+
+// Try to load minimatch, fallback to simple pattern matching if not available
+let minimatch = null;
+try {
+  minimatch = require("minimatch").minimatch;
+} catch {
+  // minimatch not available, will use fallback
+}
+
+/**
+ * Violation codes for machine-readable errors
+ */
+const VIOLATION_CODES = {
+  NO_INTENT: "NO_INTENT_DECLARED",
+  INTENT_EXPIRED: "INTENT_EXPIRED",
+  INTENT_CORRUPTED: "INTENT_INTEGRITY_FAILED",
+  UNDECLARED_ROUTE: "UNDECLARED_ROUTE",
+  UNDECLARED_ENV: "UNDECLARED_ENV_VAR",
+  UNDECLARED_FILE: "UNDECLARED_FILE_CHANGE",
+  CONSTRAINT_VIOLATED: "CONSTRAINT_VIOLATED",
+  SCOPE_VIOLATION: "SCOPE_VIOLATION",
+  DOMAIN_VIOLATION: "DOMAIN_NOT_ALLOWED",
+  PERMISSION_CHANGE: "UNAUTHORIZED_PERMISSION_CHANGE",
+  AUTH_MODIFICATION: "UNAUTHORIZED_AUTH_MODIFICATION",
+  PAYMENT_MODIFICATION: "UNAUTHORIZED_PAYMENT_MODIFICATION",
+  MOCK_DATA_DETECTED: "MOCK_DATA_IN_PRODUCTION_CODE",
+  TODO_DETECTED: "UNRESOLVED_TODO_PLACEHOLDER",
+  FAKE_HANDLER: "FAKE_HANDLER_DETECTED",
+  UI_WITHOUT_BACKEND: "UI_SUCCESS_WITHOUT_BACKEND_PROOF",
+};
+
+/**
+ * Alignment Check Result
+ * @typedef {Object} AlignmentResult
+ * @property {boolean} aligned - Whether change is aligned with intent
+ * @property {string} decision - PASS or BLOCK
+ * @property {Object[]} violations - Array of violations
+ * @property {string} intent_hash - Hash of intent used for checking
+ */
+
+/**
+ * Violation object structure
+ * @typedef {Object} Violation
+ * @property {string} code - Machine-readable violation code
+ * @property {string} rule - Human-readable rule name
+ * @property {string} message - Detailed violation message
+ * @property {string} resource - Resource that caused violation
+ * @property {string} intent_ref - Reference to violated intent element
+ * @property {string} severity - Always "block" for violations
+ */
+
+/**
+ * Check if a path matches any allowed pattern
+ * @param {string} filePath - Path to check
+ * @param {Object[]} allowed_changes - Allowed changes from intent
+ * @returns {boolean} True if allowed
+ */
+function isFileChangeAllowed(filePath, allowed_changes = []) {
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  
+  for (const allowed of allowed_changes) {
+    if (allowed.type === "file_create" || allowed.type === "file_modify" || allowed.type === "file_delete") {
+      // Check exact target match
+      if (allowed.target && allowed.target.replace(/\\/g, "/") === normalizedPath) {
+        return true;
+      }
+      
+      // Check pattern match
+      if (allowed.pattern) {
+        try {
+          // Use minimatch if available, otherwise simple glob
+          if (typeof minimatch === "function") {
+            if (minimatch(normalizedPath, allowed.pattern, { matchBase: true })) {
+              return true;
+            }
+          } else {
+            // Simple pattern matching fallback using placeholders
+            // Use placeholders to avoid escaping issues
+            const regex = new RegExp(
+              "^" + allowed.pattern
+                .replace(/\*\*\//g, "{{DIRSTAR}}")  // Placeholder for **/
+                .replace(/\*\*/g, "{{GLOBSTAR}}")  // Placeholder for **
+                .replace(/\?/g, "{{QMARK}}")       // Placeholder for ?
+                .replace(/\./g, "\\.")             // Escape dots
+                .replace(/\*/g, "[^/]*")           // * matches anything except /
+                .replace(/{{DIRSTAR}}/g, "(?:.*/)?")  // **/ matches zero or more dirs
+                .replace(/{{GLOBSTAR}}/g, ".*")    // ** matches anything
+                .replace(/{{QMARK}}/g, ".") + "$"  // ? matches single char
+            );
+            if (regex.test(normalizedPath)) {
+              return true;
+            }
+          }
+        } catch {
+          // Skip invalid patterns
+        }
+      }
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Check if a route is allowed by intent
+ * @param {string} method - HTTP method
+ * @param {string} routePath - Route path
+ * @param {Object[]} allowed_changes - Allowed changes from intent
+ * @returns {boolean} True if allowed
+ */
+function isRouteAllowed(method, routePath, allowed_changes = []) {
+  for (const allowed of allowed_changes) {
+    if (allowed.type === "route_add" || allowed.type === "route_modify") {
+      // Check exact match
+      if (allowed.target === routePath) {
+        return true;
+      }
+      
+      // Check pattern match (e.g., /api/users/*)
+      if (allowed.pattern) {
+        try {
+          const regex = new RegExp(
+            "^" + allowed.pattern
+              .replace(/\*/g, "[^/]+")
+              .replace(/\*\*/g, ".*") + "$"
+          );
+          if (regex.test(routePath)) {
+            return true;
+          }
+        } catch {
+          // Skip invalid patterns
+        }
+      }
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Check if env var addition is allowed by intent
+ * @param {string} envVar - Environment variable name
+ * @param {Object[]} allowed_changes - Allowed changes from intent
+ * @returns {boolean} True if allowed
+ */
+function isEnvVarAllowed(envVar, allowed_changes = []) {
+  for (const allowed of allowed_changes) {
+    if (allowed.type === "env_add") {
+      if (allowed.target === envVar) {
+        return true;
+      }
+      // Pattern match (e.g., STRIPE_*)
+      if (allowed.pattern) {
+        try {
+          const regex = new RegExp("^" + allowed.pattern.replace(/\*/g, ".*") + "$");
+          if (regex.test(envVar)) {
+            return true;
+          }
+        } catch {
+          // Skip invalid patterns
+        }
+      }
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Check if path is within allowed scope
+ * @param {string} filePath - File path to check
+ * @param {Object} scope - Intent scope restrictions
+ * @returns {boolean} True if within scope
+ */
+function isWithinScope(filePath, scope) {
+  if (!scope) return true; // No scope = everything allowed
+  
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  
+  // Check excluded paths first
+  if (scope.excluded_paths) {
+    for (const excluded of scope.excluded_paths) {
+      const normalizedExcluded = excluded.replace(/\\/g, "/");
+      if (normalizedPath.startsWith(normalizedExcluded) || normalizedPath === normalizedExcluded) {
+        return false;
+      }
+    }
+  }
+  
+  // Check directory restrictions
+  if (scope.directories && scope.directories.length > 0) {
+    const inAllowedDir = scope.directories.some(dir => {
+      const normalizedDir = dir.replace(/\\/g, "/");
+      return normalizedPath.startsWith(normalizedDir);
+    });
+    if (!inAllowedDir) {
+      return false;
+    }
+  }
+  
+  // Check file pattern restrictions
+  if (scope.file_patterns && scope.file_patterns.length > 0) {
+    const matchesPattern = scope.file_patterns.some(pattern => {
+      try {
+        if (typeof minimatch === "function") {
+          return minimatch(normalizedPath, pattern, { matchBase: true });
+        }
+        const regex = new RegExp(
+          "^" + pattern
+            .replace(/\*\*/g, "{{GLOBSTAR}}")
+            .replace(/\*/g, "[^/]*")
+            .replace(/{{GLOBSTAR}}/g, ".*") + "$"
+        );
+        return regex.test(normalizedPath);
+      } catch {
+        return false;
+      }
+    });
+    if (!matchesPattern) {
+      return false;
+    }
+  }
+  
+  return true;
+}
+
+/**
+ * Check if domain is allowed by intent
+ * @param {string} domain - Domain classification
+ * @param {Object} scope - Intent scope restrictions
+ * @returns {boolean} True if allowed
+ */
+function isDomainAllowed(domain, scope) {
+  if (!scope || !scope.domains || scope.domains.length === 0) {
+    return true; // No domain restrictions
+  }
+  return scope.domains.includes(domain);
+}
+
+/**
+ * Check constraint violations
+ * @param {string[]} constraints - Intent constraints
+ * @param {Object} changeEvent - Change event to check
+ * @returns {Object[]} Array of constraint violations
+ */
+function checkConstraintViolations(constraints, changeEvent) {
+  const violations = [];
+  
+  for (let i = 0; i < constraints.length; i++) {
+    const constraint = constraints[i].toLowerCase();
+    
+    // No new routes
+    if (constraint.includes("no new routes") || constraint.includes("no_new_routes")) {
+      if (changeEvent.type === "route_add" || 
+          (changeEvent.claims && changeEvent.claims.some(c => c.type === "route"))) {
+        violations.push({
+          code: VIOLATION_CODES.CONSTRAINT_VIOLATED,
+          rule: "constraint_no_new_routes",
+          message: "New route addition blocked by constraint",
+          resource: changeEvent.location,
+          intent_ref: `constraints[${i}]`,
+          severity: "block",
+        });
+      }
+    }
+    
+    // No auth changes
+    if (constraint.includes("no auth") || constraint.includes("no_auth_changes")) {
+      if (changeEvent.domain === "auth" || 
+          (changeEvent.claims && changeEvent.claims.some(c => c.type === "auth_boundary"))) {
+        violations.push({
+          code: VIOLATION_CODES.AUTH_MODIFICATION,
+          rule: "constraint_no_auth_changes",
+          message: "Auth modification blocked by constraint",
+          resource: changeEvent.location,
+          intent_ref: `constraints[${i}]`,
+          severity: "block",
+        });
+      }
+    }
+    
+    // No new environment variables
+    if (constraint.includes("no new env") || constraint.includes("no_env_additions")) {
+      if (changeEvent.type === "env_ref" && !changeEvent.env_exists) {
+        violations.push({
+          code: VIOLATION_CODES.UNDECLARED_ENV,
+          rule: "constraint_no_env_additions",
+          message: `New env var '${changeEvent.resource}' blocked by constraint`,
+          resource: changeEvent.resource,
+          intent_ref: `constraints[${i}]`,
+          severity: "block",
+        });
+      }
+    }
+    
+    // No payment changes
+    if (constraint.includes("no payment") || constraint.includes("no_payment_changes")) {
+      if (changeEvent.domain === "payments") {
+        violations.push({
+          code: VIOLATION_CODES.PAYMENT_MODIFICATION,
+          rule: "constraint_no_payment_changes",
+          message: "Payment code modification blocked by constraint",
+          resource: changeEvent.location,
+          intent_ref: `constraints[${i}]`,
+          severity: "block",
+        });
+      }
+    }
+    
+    // Tests required
+    if (constraint.includes("tests required") || constraint.includes("tests_required")) {
+      if (!changeEvent.includes_tests) {
+        violations.push({
+          code: VIOLATION_CODES.CONSTRAINT_VIOLATED,
+          rule: "constraint_tests_required",
+          message: "Tests required by constraint but none provided",
+          resource: changeEvent.location,
+          intent_ref: `constraints[${i}]`,
+          severity: "block",
+        });
+      }
+    }
+    
+    // Single file only
+    if (constraint.includes("single file") || constraint.includes("single_file_only")) {
+      if (changeEvent.file_count > 1) {
+        violations.push({
+          code: VIOLATION_CODES.CONSTRAINT_VIOLATED,
+          rule: "constraint_single_file",
+          message: `Multiple files (${changeEvent.file_count}) modified but constraint requires single file`,
+          resource: changeEvent.location,
+          intent_ref: `constraints[${i}]`,
+          severity: "block",
+        });
+      }
+    }
+  }
+  
+  return violations;
+}
+
+/**
+ * Detect code quality violations (mock data, TODOs, fake handlers)
+ * @param {Object} changeEvent - Change event with diff
+ * @returns {Object[]} Array of violations
+ */
+function detectCodeQualityViolations(changeEvent) {
+  const violations = [];
+  const content = changeEvent.diff?.after || changeEvent.content || "";
+  
+  // Mock data detection
+  const mockPatterns = [
+    /mock\s*data/i,
+    /fake\s*response/i,
+    /stub\s*data/i,
+    /dummy\s*data/i,
+    /\[\s*"test"\s*,\s*"data"\s*\]/,
+    /return\s+\{\s*success:\s*true\s*\}/,
+    /setTimeout\s*\(\s*\(\)\s*=>\s*\{[^}]*success/i,
+  ];
+  
+  for (const pattern of mockPatterns) {
+    if (pattern.test(content)) {
+      violations.push({
+        code: VIOLATION_CODES.MOCK_DATA_DETECTED,
+        rule: "no_mock_data",
+        message: "Mock/fake data detected in production code",
+        resource: changeEvent.location,
+        intent_ref: "enforcement_rule",
+        severity: "block",
+      });
+      break;
+    }
+  }
+  
+  // TODO/FIXME detection
+  const todoPattern = /\b(TODO|FIXME|XXX|HACK|BUG)[\s:]/i;
+  if (todoPattern.test(content)) {
+    violations.push({
+      code: VIOLATION_CODES.TODO_DETECTED,
+      rule: "no_todos",
+      message: "Unresolved TODO/FIXME comment detected",
+      resource: changeEvent.location,
+      intent_ref: "enforcement_rule",
+      severity: "block",
+    });
+  }
+  
+  // Fake handler detection
+  const fakeHandlerPatterns = [
+    /async\s+function\s+\w+\s*\([^)]*\)\s*\{\s*\}/,
+    /const\s+\w+\s*=\s*async\s*\([^)]*\)\s*=>\s*\{\s*\}/,
+    /\w+Handler\s*=\s*\(\)\s*=>\s*\{\s*\}/,
+    /notImplemented/i,
+    /throw\s+new\s+Error\s*\(\s*["']not\s+implemented/i,
+  ];
+  
+  for (const pattern of fakeHandlerPatterns) {
+    if (pattern.test(content)) {
+      violations.push({
+        code: VIOLATION_CODES.FAKE_HANDLER,
+        rule: "no_fake_handlers",
+        message: "Empty or placeholder handler detected",
+        resource: changeEvent.location,
+        intent_ref: "enforcement_rule",
+        severity: "block",
+      });
+      break;
+    }
+  }
+  
+  return violations;
+}
+
+/**
+ * Main alignment check function
+ * 
+ * @param {Object} intent - Declared intent
+ * @param {Object} changeEvent - Normalized change event
+ * @returns {AlignmentResult} Alignment result
+ */
+function checkAlignment(intent, changeEvent) {
+  const violations = [];
+  
+  // BLOCK if no intent
+  if (!intent) {
+    return {
+      aligned: false,
+      decision: "BLOCK",
+      violations: [{
+        code: VIOLATION_CODES.NO_INTENT,
+        rule: "intent_required",
+        message: "No intent declared - all changes blocked by default",
+        resource: changeEvent.location || "unknown",
+        intent_ref: "system",
+        severity: "block",
+      }],
+      intent_hash: null,
+    };
+  }
+  
+  // Check intent is the blocking intent
+  if (intent.summary?.includes("NO INTENT DECLARED")) {
+    return {
+      aligned: false,
+      decision: "BLOCK",
+      violations: [{
+        code: VIOLATION_CODES.NO_INTENT,
+        rule: "intent_required",
+        message: "No intent declared - all changes blocked by default",
+        resource: changeEvent.location || "unknown",
+        intent_ref: "system",
+        severity: "block",
+      }],
+      intent_hash: intent.hash,
+    };
+  }
+  
+  // 1. Check file changes against allowed_changes
+  if (changeEvent.type === "file_write" || changeEvent.type === "file_create" || changeEvent.type === "file_modify") {
+    if (intent.allowed_changes && intent.allowed_changes.length > 0) {
+      if (!isFileChangeAllowed(changeEvent.location, intent.allowed_changes)) {
+        violations.push({
+          code: VIOLATION_CODES.UNDECLARED_FILE,
+          rule: "file_change_not_declared",
+          message: `File change not declared in intent: ${changeEvent.location}`,
+          resource: changeEvent.location,
+          intent_ref: "allowed_changes",
+          severity: "block",
+        });
+      }
+    }
+  }
+  
+  // 2. Check routes against allowed_changes
+  if (changeEvent.type === "route_add") {
+    if (!isRouteAllowed(changeEvent.method, changeEvent.resource, intent.allowed_changes)) {
+      violations.push({
+        code: VIOLATION_CODES.UNDECLARED_ROUTE,
+        rule: "route_not_declared",
+        message: `Route not declared in intent: ${changeEvent.method || "?"} ${changeEvent.resource}`,
+        resource: changeEvent.resource,
+        intent_ref: "allowed_changes",
+        severity: "block",
+      });
+    }
+  }
+  
+  // 3. Check env vars against allowed_changes
+  if (changeEvent.type === "env_ref" && !changeEvent.env_exists) {
+    if (!isEnvVarAllowed(changeEvent.resource, intent.allowed_changes)) {
+      violations.push({
+        code: VIOLATION_CODES.UNDECLARED_ENV,
+        rule: "env_var_not_declared",
+        message: `Environment variable not declared in intent or missing: ${changeEvent.resource}`,
+        resource: changeEvent.resource,
+        intent_ref: "allowed_changes",
+        severity: "block",
+      });
+    }
+  }
+  
+  // 4. Check scope restrictions
+  if (intent.scope && changeEvent.location) {
+    if (!isWithinScope(changeEvent.location, intent.scope)) {
+      violations.push({
+        code: VIOLATION_CODES.SCOPE_VIOLATION,
+        rule: "scope_violation",
+        message: `Change outside allowed scope: ${changeEvent.location}`,
+        resource: changeEvent.location,
+        intent_ref: "scope",
+        severity: "block",
+      });
+    }
+  }
+  
+  // 5. Check domain restrictions
+  if (intent.scope && changeEvent.domain) {
+    if (!isDomainAllowed(changeEvent.domain, intent.scope)) {
+      violations.push({
+        code: VIOLATION_CODES.DOMAIN_VIOLATION,
+        rule: "domain_not_allowed",
+        message: `Domain '${changeEvent.domain}' not allowed by intent`,
+        resource: changeEvent.location,
+        intent_ref: "scope.domains",
+        severity: "block",
+      });
+    }
+  }
+  
+  // 6. Check constraints
+  if (intent.constraints && intent.constraints.length > 0) {
+    const constraintViolations = checkConstraintViolations(intent.constraints, changeEvent);
+    violations.push(...constraintViolations);
+  }
+  
+  // 7. Check code quality (mock data, TODOs, fake handlers)
+  const qualityViolations = detectCodeQualityViolations(changeEvent);
+  violations.push(...qualityViolations);
+  
+  // 8. Check UI success without backend proof
+  if (changeEvent.claims) {
+    const uiSuccessClaims = changeEvent.claims.filter(c => c.type === "ui_success_claim");
+    for (const claim of uiSuccessClaims) {
+      if (!claim.backend_verified) {
+        violations.push({
+          code: VIOLATION_CODES.UI_WITHOUT_BACKEND,
+          rule: "ui_success_requires_proof",
+          message: `UI success state without backend proof: ${claim.value || claim.pointer}`,
+          resource: claim.file || changeEvent.location,
+          intent_ref: "enforcement_rule",
+          severity: "block",
+        });
+      }
+    }
+  }
+  
+  // Final decision
+  const aligned = violations.length === 0;
+  
+  return {
+    aligned,
+    decision: aligned ? "PASS" : "BLOCK",
+    violations,
+    intent_hash: intent.hash,
+  };
+}
+
+/**
+ * Batch alignment check for multiple change events
+ * @param {Object} intent - Declared intent
+ * @param {Object[]} changeEvents - Array of change events
+ * @returns {AlignmentResult} Aggregated alignment result
+ */
+function checkAlignmentBatch(intent, changeEvents) {
+  const allViolations = [];
+  
+  for (const event of changeEvents) {
+    const result = checkAlignment(intent, event);
+    allViolations.push(...result.violations);
+  }
+  
+  // De-duplicate violations by code + resource
+  const seen = new Set();
+  const uniqueViolations = allViolations.filter(v => {
+    const key = `${v.code}:${v.resource}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  
+  const aligned = uniqueViolations.length === 0;
+  
+  return {
+    aligned,
+    decision: aligned ? "PASS" : "BLOCK",
+    violations: uniqueViolations,
+    intent_hash: intent?.hash || null,
+  };
+}
+
+module.exports = {
+  checkAlignment,
+  checkAlignmentBatch,
+  isFileChangeAllowed,
+  isRouteAllowed,
+  isEnvVarAllowed,
+  isWithinScope,
+  isDomainAllowed,
+  checkConstraintViolations,
+  detectCodeQualityViolations,
+  VIOLATION_CODES,
+};