@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/policy/PolicyManager.js

@@ -1,470 +0,0 @@
-/**
- * @fileoverview Policy Manager with Intelligent Caching
- * Manages policy.yaml loading with caching, default fallback, and waiver validation.
- * Ported from agent-agency v2 CAWS integration patterns.
- * @author @darianrosebrook
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-const yaml = require('js-yaml');
-const { createValidator, getSchemaPath } = require('../utils/schema-validator');
-
-/**
- * Policy Manager - Handles policy loading with intelligent caching
- *
- * Features:
- * - TTL-based caching for performance
- * - Graceful fallback to defaults when policy.yaml missing
- * - Cache inspection and management API
- * - Waiver validation and delta application
- */
-class PolicyManager {
-  constructor(options = {}) {
-    this.enableCaching = options.enableCaching ?? true;
-    this.cacheTTL = options.cacheTTL ?? 300000; // 5 minutes default
-    this.policyCache = new Map(); // projectRoot -> { policy, cachedAt, ttl }
-  }
-
-  /**
-   * Load CAWS policy from policy.yaml with caching
-   *
-   * @param {string} projectRoot - Project root directory
-   * @param {Object} options - Loading options
-   * @param {boolean} options.useCache - Use cache if available (default: true)
-   * @param {number} options.cacheTTL - Cache TTL override in milliseconds
-   * @returns {Promise<Object>} Policy object
-   */
-  async loadPolicy(projectRoot, options = {}) {
-    const useCache = options.useCache ?? this.enableCaching;
-    const cacheTTL = options.cacheTTL ?? this.cacheTTL;
-    const startTime = Date.now();
-
-    try {
-      // Check cache first
-      if (useCache && this.policyCache.has(projectRoot)) {
-        const cached = this.policyCache.get(projectRoot);
-        const cacheAge = Date.now() - cached.cachedAt;
-
-        if (cacheAge < cacheTTL) {
-          return {
-            ...cached.policy,
-            _cacheHit: true,
-            _loadDuration: Date.now() - startTime,
-          };
-        }
-      }
-
-      // Load from file - check multiple locations for backward compatibility
-      const policyPaths = [
-        path.join(projectRoot, '.caws', 'policy.yaml'), // Preferred location
-        path.join(projectRoot, '.caws', 'policy', 'tier-policy.json'), // Legacy location
-      ];
-
-      let policyPath = null;
-      let policyContent = null;
-
-      // Try each path in order
-      for (const candidatePath of policyPaths) {
-        try {
-          if (await fs.pathExists(candidatePath)) {
-            policyPath = candidatePath;
-            const content = await fs.readFile(candidatePath, 'utf-8');
-
-            // Handle JSON format (legacy)
-            if (candidatePath.endsWith('.json')) {
-              policyContent = JSON.parse(content);
-            } else {
-              // Handle YAML format (preferred)
-              policyContent = yaml.load(content);
-            }
-            break;
-          }
-        } catch (error) {
-          // Continue to next path if this one fails
-          continue;
-        }
-      }
-
-      if (policyPath && policyContent) {
-        // Schema validation (warn and fall back to defaults on failure)
-        try {
-          const schemaFilePath = getSchemaPath('policy.schema.json', projectRoot);
-          const validate = createValidator(schemaFilePath);
-          const schemaResult = validate(policyContent);
-          if (!schemaResult.valid) {
-            console.warn('Policy has schema violations:', schemaResult.errors);
-            console.warn('Falling back to default policy');
-            const defaultPolicy = this.getDefaultPolicy();
-            if (this.enableCaching) {
-              this.policyCache.set(projectRoot, {
-                policy: defaultPolicy,
-                cachedAt: Date.now(),
-                ttl: cacheTTL,
-              });
-            }
-            return {
-              ...defaultPolicy,
-              _isDefault: true,
-              _schemaErrors: schemaResult.errors,
-              _cacheHit: false,
-              _loadDuration: Date.now() - startTime,
-            };
-          }
-        } catch (schemaErr) {
-          console.warn('Could not validate policy schema:', schemaErr.message);
-        }
-
-        // Validate policy structure
-        this.validatePolicy(policyContent);
-
-        // Update cache
-        if (this.enableCaching) {
-          this.policyCache.set(projectRoot, {
-            policy: policyContent,
-            cachedAt: Date.now(),
-            ttl: cacheTTL,
-          });
-        }
-
-        // Warn if using legacy location
-        if (policyPath.endsWith('.json')) {
-          console.warn(
-            'Using legacy policy file location: .caws/policy/tier-policy.json\n' +
-              '   Migrate to .caws/policy.yaml for better compatibility\n' +
-              '   Run: caws init --migrate-policy'
-          );
-        }
-
-        return {
-          ...policyContent,
-          _cacheHit: false,
-          _loadDuration: Date.now() - startTime,
-          _policyPath: policyPath,
-        };
-      } else {
-        // Policy file doesn't exist - use default
-        const defaultPolicy = this.getDefaultPolicy();
-
-        if (this.enableCaching) {
-          this.policyCache.set(projectRoot, {
-            policy: defaultPolicy,
-            cachedAt: Date.now(),
-            ttl: cacheTTL,
-          });
-        }
-
-        return {
-          ...defaultPolicy,
-          _isDefault: true,
-          _cacheHit: false,
-          _loadDuration: Date.now() - startTime,
-        };
-      }
-    } catch (error) {
-      throw new Error(`Policy load failed: ${error.message}`);
-    }
-  }
-
-  /**
-   * Load a waiver document by ID
-   *
-   * @param {string} waiverId - Waiver ID (e.g., WV-0001)
-   * @param {string} projectRoot - Project root directory
-   * @returns {Promise<Object|null>} Waiver document or null if not found
-   */
-  async loadWaiver(waiverId, projectRoot) {
-    try {
-      const waiverPath = path.join(projectRoot, '.caws', 'waivers', `${waiverId}.yaml`);
-
-      const content = await fs.readFile(waiverPath, 'utf-8');
-      return yaml.load(content);
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        return null;
-      }
-      throw new Error(`Failed to load waiver ${waiverId}: ${error.message}`);
-    }
-  }
-
-  /**
-   * Check if a waiver is currently valid
-   *
-   * @param {Object} waiver - Waiver document
-   * @returns {boolean} True if waiver is valid and active
-   */
-  isWaiverValid(waiver) {
-    if (!waiver) {
-      return false;
-    }
-
-    // Check status
-    if (waiver.status !== 'active') {
-      return false;
-    }
-
-    // Check expiry
-    if (waiver.expires_at) {
-      const expiryDate = new Date(waiver.expires_at);
-      const now = new Date();
-      if (now > expiryDate) {
-        return false;
-      }
-    }
-
-    // Check if it has required approvals
-    if (!waiver.approvers || waiver.approvers.length === 0) {
-      return false;
-    }
-
-    return true;
-  }
-
-  /**
-   * Apply waivers to baseline budget
-   *
-   * @param {Object} baseline - Baseline budget from policy
-   * @param {string[]} waiverIds - Array of waiver IDs to apply
-   * @param {string} projectRoot - Project root directory
-   * @returns {Promise<Object>} Effective budget with waivers applied
-   */
-  async applyWaivers(baseline, waiverIds, projectRoot) {
-    const effective = { ...baseline };
-    const applied = [];
-
-    for (const waiverId of waiverIds) {
-      const waiver = await this.loadWaiver(waiverId, projectRoot);
-
-      if (waiver && this.isWaiverValid(waiver)) {
-        // Apply additive delta
-        if (waiver.delta) {
-          if (waiver.delta.max_files) {
-            effective.max_files += waiver.delta.max_files;
-          }
-          if (waiver.delta.max_loc) {
-            effective.max_loc += waiver.delta.max_loc;
-          }
-        }
-        applied.push(waiverId);
-      }
-    }
-
-    return {
-      effective,
-      applied,
-    };
-  }
-
-  /**
-   * Validate policy structure
-   *
-   * @param {Object} policy - Policy to validate
-   * @throws {Error} If policy is invalid
-   */
-  validatePolicy(policy) {
-    if (!policy.version) {
-      throw new Error('Policy missing version field');
-    }
-
-    if (!policy.risk_tiers) {
-      throw new Error('Policy missing risk_tiers configuration');
-    }
-
-    const tierKeys = Object.keys(policy.risk_tiers);
-    if (tierKeys.length === 0) {
-      throw new Error('Policy risk_tiers must define at least one risk tier (1, 2, or 3)');
-    }
-    for (const key of tierKeys) {
-      if (!/^[1-3]$/.test(key)) {
-        throw new Error(`Policy risk_tiers has unknown tier '${key}' (expected 1, 2, or 3)`);
-      }
-      const budget = policy.risk_tiers[key];
-      if (typeof budget.max_files !== 'number' || typeof budget.max_loc !== 'number') {
-        throw new Error(`Risk tier ${key} missing or invalid budget limits`);
-      }
-    }
-
-    // Validate edit rules if present
-    if (policy.edit_rules) {
-      if (typeof policy.edit_rules.policy_and_code_same_pr !== 'boolean') {
-        throw new Error('edit_rules.policy_and_code_same_pr must be boolean');
-      }
-      if (typeof policy.edit_rules.min_approvers_for_budget_raise !== 'number') {
-        throw new Error('edit_rules.min_approvers_for_budget_raise must be number');
-      }
-    }
-  }
-
-  /**
-   * Get default CAWS policy
-   *
-   * Returns sensible defaults when policy.yaml doesn't exist.
-   *
-   * @returns {Object} Default policy configuration
-   */
-  getDefaultPolicy() {
-    return {
-      version: 1,
-      risk_tiers: {
-        1: {
-          max_files: 25,
-          max_loc: 1000,
-          description: 'Critical changes requiring manual review',
-        },
-        2: {
-          max_files: 50,
-          max_loc: 2000,
-          description: 'Standard features with automated gates',
-        },
-        3: {
-          max_files: 100,
-          max_loc: 5000,
-          description: 'Low-risk changes with minimal oversight',
-        },
-      },
-      edit_rules: {
-        policy_and_code_same_pr: false,
-        min_approvers_for_budget_raise: 2,
-        require_signed_commits: true,
-      },
-      gates: {
-        budget_limit: {
-          enabled: true,
-          mode: 'block',
-          description: 'Enforce change budget limits',
-        },
-        spec_completeness: {
-          enabled: true,
-          mode: 'block',
-          description: 'Require complete working specifications',
-        },
-        scope_boundary: {
-          enabled: true,
-          mode: 'block',
-          description: 'Enforce spec scope boundaries',
-        },
-        god_object: {
-          enabled: true,
-          mode: 'warn',
-          thresholds: { warning: 1750, critical: 2000 },
-          description: 'Detect oversized source files',
-        },
-        todo_detection: {
-          enabled: true,
-          mode: 'warn',
-          thresholds: { min_confidence: 0.8 },
-          description: 'Scan for TODO/FIXME/HACK/XXX markers',
-        },
-      },
-      // CAWSFIX-26 / D9: empty by default. Projects that need to opt a
-      // subtree out of scope enforcement (e.g., research/, playground/)
-      // add glob patterns here, e.g. ['research/**']. Paths matching any
-      // pattern bypass scope-boundary checks entirely.
-      non_governed_zones: [],
-    };
-  }
-
-  /**
-   * Clear policy cache
-   *
-   * @param {string} [projectRoot] - Specific project to clear, or all if omitted
-   */
-  clearCache(projectRoot) {
-    if (projectRoot) {
-      this.policyCache.delete(projectRoot);
-    } else {
-      this.policyCache.clear();
-    }
-  }
-
-  /**
-   * Get cache status for a project
-   *
-   * @param {string} projectRoot - Project root directory
-   * @returns {Object} Cache status information
-   */
-  getCacheStatus(projectRoot) {
-    const cached = this.policyCache.get(projectRoot);
-
-    if (!cached) {
-      return {
-        cached: false,
-        ttl: this.cacheTTL,
-      };
-    }
-
-    return {
-      cached: true,
-      age: Date.now() - cached.cachedAt,
-      ttl: cached.ttl,
-      remainingTTL: Math.max(0, cached.ttl - (Date.now() - cached.cachedAt)),
-    };
-  }
-
-  /**
-   * Reload policy from disk (bypassing cache)
-   *
-   * @param {string} projectRoot - Project root directory
-   * @returns {Promise<Object>} Fresh policy
-   */
-  async reloadPolicy(projectRoot) {
-    this.clearCache(projectRoot);
-    return this.loadPolicy(projectRoot, { useCache: false });
-  }
-
-  /**
-   * Get all cached projects
-   *
-   * @returns {string[]} Array of project roots with cached policies
-   */
-  getCachedProjects() {
-    return Array.from(this.policyCache.keys());
-  }
-
-  /**
-   * Get cache statistics
-   *
-   * @returns {Object} Cache statistics
-   */
-  getCacheStats() {
-    const projects = this.getCachedProjects();
-    const now = Date.now();
-
-    const stats = {
-      totalCached: projects.length,
-      validCaches: 0,
-      expiredCaches: 0,
-      totalAge: 0,
-    };
-
-    for (const project of projects) {
-      const cached = this.policyCache.get(project);
-      const age = now - cached.cachedAt;
-
-      stats.totalAge += age;
-
-      if (age < cached.ttl) {
-        stats.validCaches++;
-      } else {
-        stats.expiredCaches++;
-      }
-    }
-
-    stats.averageAge = projects.length > 0 ? stats.totalAge / projects.length : 0;
-
-    return stats;
-  }
-}
-
-// Export singleton instance with default configuration
-const defaultPolicyManager = new PolicyManager();
-
-module.exports = {
-  PolicyManager,
-  defaultPolicyManager,
-
-  // Convenience exports for backward compatibility
-  loadPolicy: (projectRoot, options) => defaultPolicyManager.loadPolicy(projectRoot, options),
-  clearCache: (projectRoot) => defaultPolicyManager.clearCache(projectRoot),
-  getCacheStatus: (projectRoot) => defaultPolicyManager.getCacheStatus(projectRoot),
-};