@paths.design/caws-cli 10.0.1 → 10.2.0

package/dist/validation/spec-validation.js

@@ -6,10 +6,45 @@
 
 const fs = require('fs');
 const path = require('path');
-const { deriveBudget, checkBudgetCompliance } = require('../budget-derivation');
+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
+ *   - Lowercase suffix: APC-01a, ALG-01b (CAWSFIX-25 / D2)
+ *
+ * Rejects:
+ *   - lowercase prefix (feat-001)
+ *   - lowercase in a non-final segment (AB-cd-01)
+ *   - 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[SUFFIX]?
+ *   - PREFIX  = [A-Z] followed by zero+ [A-Z0-9]
+ *   - SEGMENT = one+ [A-Z0-9]  (alphanumeric, uppercase only)
+ *   - NUMBER  = one+ digits
+ *   - SUFFIX  = zero+ [a-z]    (optional lowercase tail on final segment only)
+ *
+ * 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+[a-z]*$/;
+
+/**
+ * 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 with optional lowercase suffix (e.g., FEAT-001, P03-IMPL-01, APC-01a)';
+
 /**
  * Get actual budget statistics from git history
  * Analyzes changes since last tag or initial commit
@@ -66,6 +101,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
@@ -74,6 +145,11 @@ function getActualBudgetStats(specDir) {
  */
 const validateWorkingSpec = (spec, _options = {}) => {
   try {
+    // 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 {
@@ -121,14 +197,14 @@ 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,
           },
         ],
       };
@@ -252,6 +328,12 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
   const { autoFix = false, checkBudget = false, projectRoot } = options;
 
   try {
+    // 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 = [];
@@ -303,12 +385,12 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
 
     // Semantic checks that AJV can't express
 
-    // Validate specific field formats
-    if (spec.id && !/^[A-Z]+-\d+$/.test(spec.id)) {
+    // 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,
       });
     }
@@ -646,10 +728,18 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
     }
 
     // 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) || {
@@ -828,4 +918,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

@@ -275,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
    */