@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/validation/spec-validation.js

@@ -4,8 +4,43 @@
  * @author @darianrosebrook
  */
 
-const { deriveBudget, checkBudgetCompliance } = require('../budget-derivation');
+const fs = require('fs');
+const path = require('path');
+const { deriveBudgetSync, checkBudgetCompliance } = require('../budget-derivation');
 const { execSync } = require('child_process');
+const { createValidator, getSchemaPath } = require('../utils/schema-validator');
+
+/**
+ * CAWSFIX-10: Canonical regex for valid spec IDs.
+ *
+ * Accepts:
+ *   - Single-segment: FEAT-001, EVLOG-002, CAWSFIX-06 (legacy shape)
+ *   - Multi-segment:  P03-IMPL-01, ALG-001A-HARDEN-01, CAWS-FIX-03
+ *
+ * Rejects:
+ *   - lowercase (feat-001)
+ *   - leading digit (01-FEAT)
+ *   - missing number suffix (FEAT-)
+ *   - trailing hyphen (FEAT-01-)
+ *   - leading/double hyphen (--FEAT-01, FEAT--001)
+ *   - empty string
+ *
+ * Grammar: [PREFIX](-[SEGMENT])*-NUMBER
+ *   - PREFIX  = [A-Z] followed by zero+ [A-Z0-9]
+ *   - SEGMENT = one+ [A-Z0-9]  (alphanumeric, uppercase only)
+ *   - NUMBER  = one+ digits
+ *
+ * Defined once per A4 invariant; referenced by both the basic validator
+ * (line ~125 pre-fix) and the enhanced validator (line ~307 pre-fix).
+ */
+const SPEC_ID_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*-\d+$/;
+
+/**
+ * User-facing error message for bad spec IDs (CAWSFIX-10 A5).
+ * Kept as a module constant so the message stays in sync with the pattern.
+ */
+const SPEC_ID_ERROR_MESSAGE =
+  'Project ID should be in format: PREFIX-NUMBER or PREFIX-SEGMENT-NUMBER (e.g., FEAT-001, P03-IMPL-01)';
 
 /**
  * Get actual budget statistics from git history
@@ -21,27 +56,31 @@ function getActualBudgetStats(specDir) {
     try {
       baseRef = execSync('git describe --tags --abbrev=0 2>/dev/null', {
         cwd,
-        encoding: 'utf8'
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
       }).trim();
     } catch {
       // No tags found, use initial commit
       baseRef = execSync('git rev-list --max-parents=0 HEAD', {
         cwd,
-        encoding: 'utf8'
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
       }).trim();
     }
 
     // Count files changed since base ref
     const filesOutput = execSync(`git diff --name-only ${baseRef}..HEAD`, {
       cwd,
-      encoding: 'utf8'
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
     const files_changed = filesOutput.trim().split('\n').filter(Boolean).length;
 
     // Count lines changed (added + removed)
     const numstatOutput = execSync(`git diff --numstat ${baseRef}..HEAD`, {
       cwd,
-      encoding: 'utf8'
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
     let lines_changed = 0;
     for (const line of numstatOutput.trim().split('\n').filter(Boolean)) {
@@ -59,6 +98,42 @@ function getActualBudgetStats(specDir) {
   }
 }
 
+/**
+ * Alias the modern `acceptance_criteria` key into `acceptance` so the semantic
+ * validator (which historically keys off `acceptance`) accepts both shapes.
+ *
+ * Precedence (per CAWSFIX-09 A3 invariant):
+ *   - If `acceptance` is present (legacy shape: {id,given,when,then}), it wins.
+ *   - Otherwise `acceptance_criteria` (modern shape: {id,description,test_nodeids,status})
+ *     is copied into `acceptance`.
+ *
+ * IMPORTANT: this function mutates the spec in place. The existing validator
+ * also mutates in place (risk_tier string→number coercion at line ~141; auto-fix
+ * writes via `current[pathParts[...]] = fix.value`). Callers of
+ * `validateWorkingSpecWithSuggestions({...}, {autoFix:true})` observe those
+ * mutations on the object they passed in — see `Multiple Auto-Fixes` tests.
+ * Returning a clone here would silently break that contract.
+ *
+ * @param {Object} spec - Raw spec object (mutated in place)
+ * @returns {Object} Same spec reference
+ */
+function aliasAcceptanceCriteria(spec) {
+  if (!spec || typeof spec !== 'object') return spec;
+
+  const hasLegacy = Array.isArray(spec.acceptance) && spec.acceptance.length > 0;
+  const hasModern =
+    Array.isArray(spec.acceptance_criteria) && spec.acceptance_criteria.length > 0;
+
+  // Only alias when: legacy is absent AND modern has content.
+  // (Legacy wins when both present; empty modern arrays do not satisfy the
+  // required-field check — see edge-case tests in acceptance-criteria-alias.test.js.)
+  if (!hasLegacy && hasModern) {
+    spec.acceptance = spec.acceptance_criteria;
+  }
+
+  return spec;
+}
+
 /**
  * Basic validation of working spec
  * @param {Object} spec - Working spec object
@@ -67,7 +142,30 @@ function getActualBudgetStats(specDir) {
  */
 const validateWorkingSpec = (spec, _options = {}) => {
   try {
-    // Basic structural validation for essential fields
+    // CAWSFIX-09: Alias `acceptance_criteria` -> `acceptance` before any
+    // semantic checks so specs using the modern shape don't trigger
+    // "Missing required field: acceptance" false negatives.
+    aliasAcceptanceCriteria(spec);
+
+    // First pass: AJV schema validation (non-blocking — results collected as warnings)
+    let schemaWarnings = [];
+    try {
+      const schemaPath = getSchemaPath('working-spec.schema.json', process.cwd());
+      const validate = createValidator(schemaPath);
+      const schemaResult = validate(spec);
+      if (!schemaResult.valid) {
+        schemaWarnings = schemaResult.errors.map(e => ({
+          instancePath: e.path,
+          message: e.message,
+        }));
+      }
+    } catch (schemaErr) {
+      // Schema not available — fall through to semantic validation
+    }
+
+    // Second pass: semantic checks (authoritative — always runs as fallback)
+
+    // Check required fields (schema may not be available)
     const requiredFields = [
       'id',
       'title',
@@ -82,17 +180,6 @@ const validateWorkingSpec = (spec, _options = {}) => {
       'contracts',
     ];
 
-    // For new policy-based specs, change_budget is not required
-    // It's derived from policy.yaml + waivers
-
-    // Normalize risk_tier: accept "T1"/"T2"/"T3" strings and convert to numeric
-    if (spec.risk_tier !== undefined && typeof spec.risk_tier === 'string') {
-      const match = spec.risk_tier.match(/^T?(\d)$/i);
-      if (match) {
-        spec.risk_tier = parseInt(match[1], 10);
-      }
-    }
-
     for (const field of requiredFields) {
       if (!spec[field]) {
         return {
@@ -107,19 +194,27 @@ const validateWorkingSpec = (spec, _options = {}) => {
       }
     }
 
-    // Validate specific field formats
-    if (!/^[A-Z]+-\d+$/.test(spec.id)) {
+    // Validate specific field formats (CAWSFIX-10: DRY regex via SPEC_ID_PATTERN)
+    if (!SPEC_ID_PATTERN.test(spec.id)) {
       return {
         valid: false,
         errors: [
           {
             instancePath: '/id',
-            message: 'Project ID should be in format: PREFIX-NUMBER (e.g., FEAT-1234)',
+            message: SPEC_ID_ERROR_MESSAGE,
           },
         ],
       };
     }
 
+    // Normalize risk_tier: accept "T1"/"T2"/"T3" strings and convert to numeric
+    if (spec.risk_tier !== undefined && typeof spec.risk_tier === 'string') {
+      const match = spec.risk_tier.match(/^T?(\d)$/i);
+      if (match) {
+        spec.risk_tier = parseInt(match[1], 10);
+      }
+    }
+
     // Validate status field if present
     if (spec.status) {
       const { SPEC_STATUSES } = require('../constants/spec-types');
@@ -203,7 +298,10 @@ const validateWorkingSpec = (spec, _options = {}) => {
       };
     }
 
-    return { valid: true };
+    return {
+      valid: true,
+      schemaWarnings: schemaWarnings.length > 0 ? schemaWarnings : undefined,
+    };
   } catch (error) {
     return {
       valid: false,
@@ -227,7 +325,36 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
   const { autoFix = false, checkBudget = false, projectRoot } = options;
 
   try {
-    // Basic structural validation for essential fields
+    // CAWSFIX-09: Alias `acceptance_criteria` -> `acceptance` so the
+    // required-field check and the "No acceptance criteria defined" warning
+    // recognize the modern shape as valid. Mutates in place to preserve the
+    // existing auto-fix contract (callers observe fixes on their object).
+    aliasAcceptanceCriteria(spec);
+
+    let errors = [];
+    let warnings = [];
+    let fixes = [];
+
+    // First pass: AJV schema validation (non-blocking — results collected as warnings)
+    try {
+      const schemaPath = getSchemaPath('working-spec.schema.json', projectRoot || process.cwd());
+      const validate = createValidator(schemaPath);
+      const schemaResult = validate(spec);
+      if (!schemaResult.valid) {
+        for (const e of schemaResult.errors) {
+          const fieldName = e.path ? e.path.replace(/^\//, '').split('/')[0] : '';
+          warnings.push({
+            instancePath: e.path,
+            message: `Schema: ${e.message}`,
+            suggestion: fieldName ? getFieldSuggestion(fieldName, spec) : undefined,
+          });
+        }
+      }
+    } catch (schemaErr) {
+      // Schema not available — non-fatal
+    }
+
+    // Required fields check (authoritative — always runs regardless of schema)
     const requiredFields = [
       'id',
       'title',
@@ -242,10 +369,6 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       'contracts',
     ];
 
-    let errors = [];
-    let warnings = [];
-    let fixes = [];
-
     for (const field of requiredFields) {
       if (!spec[field]) {
         errors.push({
@@ -257,12 +380,14 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       }
     }
 
-    // Validate specific field formats
-    if (spec.id && !/^[A-Z]+-\d+$/.test(spec.id)) {
+    // Semantic checks that AJV can't express
+
+    // Validate specific field formats (CAWSFIX-10: DRY regex via SPEC_ID_PATTERN)
+    if (spec.id && !SPEC_ID_PATTERN.test(spec.id)) {
       errors.push({
         instancePath: '/id',
-        message: 'Project ID should be in format: PREFIX-NUMBER (e.g., FEAT-1234)',
-        suggestion: 'Use format like: PROJ-001, FEAT-002, FIX-003',
+        message: SPEC_ID_ERROR_MESSAGE,
+        suggestion: 'Use format like: PROJ-001, FEAT-002, P03-IMPL-01, ALG-001A-HARDEN-01',
         canAutoFix: false,
       });
     }
@@ -575,11 +700,43 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
     // Budget enforcement is derived from policy.yaml risk_tier + waivers.
     // No warning emitted — the field is valid and expected.
 
+    // Validate scope.json against scope.schema.json if it exists
+    if (projectRoot) {
+      const scopeJsonPath = path.join(projectRoot, '.caws', 'scope.json');
+      if (fs.existsSync(scopeJsonPath)) {
+        try {
+          const schemaPath = getSchemaPath('scope.schema.json', projectRoot);
+          const validate = createValidator(schemaPath);
+          const scopeData = JSON.parse(fs.readFileSync(scopeJsonPath, 'utf8'));
+          const scopeResult = validate(scopeData);
+          if (!scopeResult.valid) {
+            for (const err of scopeResult.errors) {
+              warnings.push({
+                instancePath: `/scope.json${err.path}`,
+                message: `scope.json schema violation: ${err.message}`,
+                suggestion: 'Fix .caws/scope.json to match scope.schema.json',
+              });
+            }
+          }
+        } catch (schemaErr) {
+          // Non-fatal — don't block validation on schema issues
+        }
+      }
+    }
+
     // Derive and check budget if requested
+    //
+    // CAWSFIX-07: use `deriveBudgetSync` here. The async `deriveBudget`
+    // returns a Promise; this synchronous function previously passed the
+    // Promise straight into `checkBudgetCompliance`, which then read
+    // `derivedBudget.effective.max_files` on an undefined `.effective` and
+    // threw "Cannot read properties of undefined (reading 'max_files')" —
+    // surfaced as the "Budget derivation failed" warning on every
+    // schema-compliant spec.
     let budgetCheck = null;
     if (checkBudget && projectRoot) {
       try {
-        const derivedBudget = deriveBudget(spec, projectRoot);
+        const derivedBudget = deriveBudgetSync(spec, projectRoot);
 
         // Get actual stats from git history
         const actualStats = getActualBudgetStats(projectRoot) || {
@@ -758,4 +915,7 @@ module.exports = {
   canAutoFixField,
   calculateComplianceScore,
   getComplianceGrade,
+  // CAWSFIX-10: exported so init.js and tests reference the same regex
+  SPEC_ID_PATTERN,
+  SPEC_ID_ERROR_MESSAGE,
 };

package/dist/waivers-manager.js

@@ -195,6 +195,29 @@ class WaiversManager {
     return waiver;
   }
 
+  /**
+   * Find an active, non-expired waiver that covers a specific gate.
+   * Used by the gate evaluation pipeline to skip gates with active waivers.
+   * @param {string} gateName - Gate identifier (e.g. 'budget_limit', 'god_object')
+   * @returns {Promise<{waiverId: string, reason: string}|null>}
+   */
+  async getActiveWaiverForGate(gateName) {
+    const activeWaivers = await this.loadActiveWaivers();
+    const now = new Date();
+
+    for (const waiver of activeWaivers) {
+      const gates = Array.isArray(waiver.gates) ? waiver.gates : [waiver.gate];
+      const expiresAt = new Date(waiver.expires_at || waiver.expiry);
+
+      if (gates.includes(gateName) || gates.includes('*')) {
+        if ((!waiver.status || waiver.status === 'active') && expiresAt > now) {
+          return { waiverId: waiver.id, reason: waiver.reason };
+        }
+      }
+    }
+    return null;
+  }
+
   /**
    * Check if waiver applies to specific gates
    */
@@ -252,6 +275,90 @@ class WaiversManager {
     return activeWaivers;
   }
 
+  /**
+   * Enumerate individual waiver files (WV-XXXX.yaml) on disk and return
+   * their parsed contents. These files are the source of truth per the
+   * CAWSFIX-04 invariants; active-waivers.yaml is an aggregate index.
+   *
+   * @returns {Array<{id: string, path: string, data: object}>}
+   */
+  enumerateWaiverFiles() {
+    const out = [];
+    if (!fs.existsSync(this.waiversDir)) return out;
+
+    const files = fs.readdirSync(this.waiversDir);
+    for (const file of files) {
+      const match = file.match(/^(WV-\d{4})\.yaml$/);
+      if (!match) continue;
+
+      const filePath = path.join(this.waiversDir, file);
+      let data;
+      try {
+        data = yaml.load(fs.readFileSync(filePath, 'utf8'));
+      } catch (err) {
+        // Skip unparseable files; do not swallow — warn the caller.
+        console.warn(`Warning: could not parse ${file}: ${err.message}`);
+        continue;
+      }
+      if (data && typeof data === 'object') {
+        out.push({ id: match[1], path: filePath, data });
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Identify waivers that are candidates for expiry-based pruning.
+   * A waiver is prunable iff `status === 'active'` AND
+   * `expires_at < now`. Already-expired or revoked waivers are skipped
+   * (their status is correct; pruning wouldn't change anything).
+   *
+   * @param {Date} [nowOverride] — inject clock for tests
+   * @returns {Array<{id: string, path: string, expires_at: string}>}
+   */
+  findExpiredWaivers(nowOverride) {
+    const now = nowOverride instanceof Date ? nowOverride : new Date();
+    const records = this.enumerateWaiverFiles();
+    const candidates = [];
+
+    for (const rec of records) {
+      const w = rec.data;
+      const status = w.status;
+      // Only active waivers are prunable. Waivers with no status field are
+      // treated as active (matches existing loadActiveWaivers() assumption).
+      if (status && status !== 'active') continue;
+      if (!w.expires_at) continue;
+
+      const expiresAt = new Date(w.expires_at);
+      if (!Number.isFinite(expiresAt.getTime())) continue; // malformed date
+      if (expiresAt < now) {
+        candidates.push({
+          id: rec.id,
+          path: rec.path,
+          expires_at: w.expires_at,
+        });
+      }
+    }
+    return candidates;
+  }
+
+  /**
+   * Transition a single waiver file from `status: active` to
+   * `status: expired` in place. The file is rewritten with its existing
+   * field order where possible; a `status` field is added or replaced.
+   *
+   * @param {string} filePath
+   * @returns {object} the updated waiver object
+   */
+  markWaiverExpired(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const data = yaml.load(raw) || {};
+    data.status = 'expired';
+    data.expired_at = new Date().toISOString();
+    fs.writeFileSync(filePath, yaml.dump(data, { lineWidth: -1 }), 'utf8');
+    return data;
+  }
+
   /**
    * Revoke a waiver
    */
@@ -367,15 +474,46 @@ class WaiversManager {
   // Private helper methods
 
   async generateWaiverId() {
-    const existingWaivers = await this.loadActiveWaivers();
-    const usedIds = new Set(existingWaivers.map((w) => parseInt(w.id.split('-')[1])));
+    // Scan all waiver files in the directory (not just active-waivers.yaml)
+    // to avoid recycling IDs from expired/revoked waivers
+    const usedIds = new Set();
+
+    // Collect IDs from active-waivers.yaml
+    const activeWaivers = await this.loadActiveWaivers();
+    for (const w of activeWaivers) {
+      if (w.id) usedIds.add(w.id);
+    }
+
+    // Collect IDs from individual waiver files (WV-XXXX.yaml)
+    try {
+      const files = fs.readdirSync(this.waiversDir);
+      for (const file of files) {
+        const match = file.match(/^(WV-\d{4})\.yaml$/);
+        if (match) usedIds.add(match[1]);
+      }
+    } catch {
+      // Directory may not exist yet
+    }
 
-    let counter = 1;
-    while (usedIds.has(counter)) {
-      counter++;
+    // Generate a random 4-digit ID that doesn't collide
+    const maxAttempts = 100;
+    for (let i = 0; i < maxAttempts; i++) {
+      const num = Math.floor(Math.random() * 10000);
+      const candidate = `WV-${num.toString().padStart(4, '0')}`;
+      if (!usedIds.has(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Fallback: sequential scan if random keeps colliding (>100 attempts)
+    for (let n = 1; n <= 9999; n++) {
+      const candidate = `WV-${n.toString().padStart(4, '0')}`;
+      if (!usedIds.has(candidate)) {
+        return candidate;
+      }
     }
 
-    return `WV-${counter.toString().padStart(4, '0')}`;
+    throw new Error('No available waiver IDs (all 9999 slots used)');
   }
 
   validateWaiver(waiver) {