@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/gates/budget-limit.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Budget enforcement gate
+ * Checks changes against tier budget limits from policy.
+ * Context-aware: commit context counts staged changes, cli context skips (budget is per-change, not per-repo).
+ * @author @darianrosebrook
+ */
+
+const { deriveBudget, checkBudgetCompliance } = require('../budget-derivation');
+const { execSync } = require('child_process');
+
+const name = 'budget_limit';
+
+/**
+ * Count staged files and lines of code from git diff
+ * @param {string[]} stagedFiles - List of staged file paths
+ * @param {string} projectRoot - Project root directory
+ * @returns {Object} Stats with files_changed and lines_changed
+ */
+function getStagedStats(stagedFiles, projectRoot) {
+  const filesChanged = stagedFiles.length;
+  let linesChanged = 0;
+
+  try {
+    const numstat = execSync('git diff --cached --numstat', {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    for (const line of numstat.trim().split('\n').filter(Boolean)) {
+      const [added, removed] = line.split('\t');
+      const addedNum = added === '-' ? 0 : parseInt(added, 10) || 0;
+      const removedNum = removed === '-' ? 0 : parseInt(removed, 10) || 0;
+      linesChanged += addedNum + removedNum;
+    }
+  } catch (err) {
+    // Fail-closed: if git fails, we cannot verify budget compliance
+    return {
+      files_changed: filesChanged,
+      lines_changed: -1,
+      error: `Cannot count staged line changes: ${err.message}`,
+    };
+  }
+
+  return { files_changed: filesChanged, lines_changed: linesChanged };
+}
+
+/**
+ * Run the budget limit gate
+ * @param {Object} params - Gate parameters
+ * @param {string[]} params.stagedFiles - Staged file paths
+ * @param {Object} params.spec - Working spec
+ * @param {Object} params.policy - Policy configuration
+ * @param {string} params.projectRoot - Project root
+ * @param {number} params.riskTier - Risk tier number
+ * @param {string} [params.context] - Execution context (commit, cli, edit)
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ stagedFiles, spec, _policy, projectRoot, riskTier, context }) {
+  const messages = [];
+
+  // Budget limits apply to changes, not to the entire repo.
+  // In cli context with all tracked files, budget check is meaningless.
+  // Return 'skipped' (not 'pass') so the pipeline summary counts this gate under
+  // `skipped`, matching pipeline.js semantics for gates that did not actually run.
+  if (context === 'cli') {
+    return {
+      status: 'skipped',
+      messages: ['Budget check skipped in CLI context (budget applies to changes, not full repo)'],
+    };
+  }
+
+  // Build a minimal spec for deriveBudget
+  const specForBudget = {
+    risk_tier: riskTier,
+    waiver_ids: spec?.waiver_ids || [],
+  };
+
+  try {
+    const budget = await deriveBudget(specForBudget, projectRoot, { useCache: true });
+    const stats = getStagedStats(stagedFiles, projectRoot);
+
+    // Fail-closed: if git stats errored, report it
+    if (stats.error) {
+      messages.push(stats.error);
+      return { status: 'fail', messages };
+    }
+
+    const compliance = checkBudgetCompliance(budget, stats);
+
+    if (!compliance.compliant) {
+      for (const violation of compliance.violations) {
+        messages.push(violation.message);
+      }
+      return { status: 'fail', messages };
+    }
+
+    // Emit budget:pressure if usage > 80% but still compliant
+    try {
+      const filePercent = budget.max_files > 0 ? stats.files_changed / budget.max_files : 0;
+      const locPercent = budget.max_loc > 0 ? stats.lines_changed / budget.max_loc : 0;
+      if (filePercent > 0.8 || locPercent > 0.8) {
+        const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
+        lifecycle.emit(EVENTS.BUDGET_PRESSURE, {
+          specId: spec?.id || null,
+          filesUsed: stats.files_changed,
+          filesLimit: budget.max_files,
+          locUsed: stats.lines_changed,
+          locLimit: budget.max_loc,
+          percentUsed: Math.round(Math.max(filePercent, locPercent) * 100),
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch { /* non-fatal */ }
+
+    return { status: 'pass', messages };
+  } catch (err) {
+    return { status: 'fail', messages: [`Budget check error: ${err.message}`] };
+  }
+}
+
+module.exports = { name, run };

package/dist/gates/feedback.js

@@ -0,0 +1,260 @@
+/**
+ * @fileoverview Gate Feedback Enrichment
+ *
+ * Post-processes raw gate results into enriched feedback with:
+ * - why: human-readable explanation of the failure
+ * - category: scope | policy | quality | architectural
+ * - recurrence: how many times this gate has failed recently
+ * - nextStep: the smallest safe action to resolve
+ * - remediation: a CLI command to fix or waive
+ *
+ * This module sits between the gate pipeline output and the formatter.
+ *
+ * @author @darianrosebrook
+ */
+
+// ---------------------------------------------------------------------------
+// Gate → category mapping
+// ---------------------------------------------------------------------------
+
+const GATE_CATEGORIES = {
+  scope_boundary: 'scope',
+  budget_limit: 'policy',
+  god_object: 'architectural',
+  todo_detection: 'quality',
+  spec_completeness: 'quality',
+};
+
+// ---------------------------------------------------------------------------
+// Per-gate enrichment
+// ---------------------------------------------------------------------------
+
+/**
+ * Enrich a scope_boundary failure.
+ * Messages follow: "Out of scope (excluded): FILE" or "Out of scope (not in allowed paths): FILE"
+ */
+function enrichScopeBoundary(gate, spec) {
+  const scopeIn = spec?.scope?.in || [];
+  const files = gate.messages
+    .filter(m => m.startsWith('Out of scope'))
+    .map(m => m.replace(/^Out of scope \([^)]+\): /, ''));
+
+  if (files.length === 0) return null;
+
+  const why = files.length === 1
+    ? `${files[0]} is outside scope.in patterns [${scopeIn.join(', ')}]`
+    : `${files.length} files are outside scope.in patterns [${scopeIn.join(', ')}]`;
+
+  return {
+    why,
+    nextStep: files.length === 1
+      ? `Add the file's directory to scope.in, or move the change to a separate spec`
+      : `Expand scope.in to cover these paths, or split into a separate spec`,
+    remediation: 'caws waivers create --gates scope_boundary',
+  };
+}
+
+/**
+ * Enrich a budget_limit failure.
+ * Messages follow: violation messages from checkBudgetCompliance.
+ */
+function enrichBudgetLimit(gate) {
+  const why = gate.messages.length > 0
+    ? gate.messages[0]
+    : 'Change exceeds the budget limits for this risk tier';
+
+  return {
+    why,
+    nextStep: 'Split this change into smaller commits, or request a waiver',
+    remediation: 'caws waivers create --gates budget_limit',
+  };
+}
+
+/**
+ * Enrich a god_object failure.
+ * Messages follow: "CRITICAL: FILE has N lines (threshold: T)"
+ */
+function enrichGodObject(gate) {
+  const criticals = gate.messages.filter(m => m.startsWith('CRITICAL'));
+  const file = criticals.length > 0
+    ? criticals[0].replace(/^CRITICAL[^:]*: /, '').replace(/ has \d+.*/, '')
+    : null;
+
+  const why = criticals.length > 0
+    ? criticals[0]
+    : gate.messages[0] || 'File exceeds line-count threshold';
+
+  return {
+    why,
+    nextStep: file
+      ? `Extract helper modules from ${file} to reduce its size`
+      : 'Extract helper modules to reduce file size',
+    remediation: 'caws waivers create --gates god_object',
+  };
+}
+
+/**
+ * Enrich a todo_detection failure.
+ * Messages follow: "FILE:LINE: MARKER found"
+ */
+function enrichTodoDetection(gate) {
+  const markers = gate.messages.filter(m => m.includes(' found'));
+  const why = markers.length > 0
+    ? `${markers.length} TODO/FIXME marker(s) detected in staged changes`
+    : 'Actionable markers detected';
+
+  return {
+    why,
+    nextStep: 'Resolve the TODO/FIXME items before committing, or convert to tracked issues',
+    remediation: 'caws waivers create --gates todo_detection',
+  };
+}
+
+/**
+ * Enrich a spec_completeness failure.
+ */
+function enrichSpecCompleteness(gate) {
+  return {
+    why: gate.messages[0] || 'Working spec does not pass schema validation',
+    nextStep: 'Run: caws validate for detailed errors and suggestions',
+    remediation: null,
+  };
+}
+
+/**
+ * Generic fallback enrichment.
+ */
+function enrichGeneric(gate) {
+  return {
+    why: gate.messages[0] || `Gate "${gate.name}" failed`,
+    nextStep: `Investigate the gate failure and resolve the issue`,
+    remediation: `caws waivers create --gates ${gate.name}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Enrichment dispatch
+// ---------------------------------------------------------------------------
+
+const ENRICHERS = {
+  scope_boundary: enrichScopeBoundary,
+  budget_limit: enrichBudgetLimit,
+  god_object: enrichGodObject,
+  todo_detection: enrichTodoDetection,
+  spec_completeness: enrichSpecCompleteness,
+};
+
+// ---------------------------------------------------------------------------
+// Recurrence detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check how many recent gate runs had this gate failing.
+ * Uses working state history entries where command === 'gates'.
+ * @param {string} gateName
+ * @param {object|null} state - Working state object
+ * @returns {{ count: number, lastSeen: string }|null}
+ */
+function getRecurrence(gateName, state) {
+  if (!state?.history) return null;
+
+  // Look at previous gate run results stored in state.gates
+  // History entries only have command + summary, but state.gates.results
+  // has the per-gate results from the LAST run. For recurrence we need
+  // to check if the current failure matches blockers that existed before.
+  // Since we only store the latest gate results, we count consecutive
+  // history entries with "blocked" in their summary.
+  const gateEntries = state.history.filter(h => h.command === 'gates');
+  if (gateEntries.length <= 1) return null; // Only the current run
+
+  let count = 0;
+  let lastSeen = null;
+
+  // Count backward from second-to-last (the previous runs, not current)
+  for (let i = gateEntries.length - 2; i >= 0; i--) {
+    const entry = gateEntries[i];
+    // Summary format: "N passed, M blocked, K warned"
+    // Must check for non-zero blocked count (not just substring "blocked")
+    const blockedMatch = entry.summary && entry.summary.match(/(\d+) blocked/);
+    if (blockedMatch && parseInt(blockedMatch[1], 10) > 0) {
+      count++;
+      if (!lastSeen) lastSeen = entry.timestamp;
+    } else {
+      break; // Stop at first non-blocked run
+    }
+  }
+
+  if (count === 0) return null;
+
+  // Format lastSeen as relative time
+  const lastSeenRelative = formatTimeSince(lastSeen);
+
+  return { count, lastSeen: lastSeenRelative };
+}
+
+/**
+ * Format an ISO timestamp as a relative time string.
+ * @param {string} isoTimestamp
+ * @returns {string}
+ */
+function formatTimeSince(isoTimestamp) {
+  if (!isoTimestamp) return 'unknown';
+  const diff = Date.now() - new Date(isoTimestamp).getTime();
+  if (isNaN(diff)) return 'unknown';
+
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} min ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+// ---------------------------------------------------------------------------
+// Main enrichment function
+// ---------------------------------------------------------------------------
+
+/**
+ * Enrich gate results with contextual feedback.
+ * @param {object} report - Pipeline report from evaluateGates()
+ * @param {object} context
+ * @param {object} [context.spec] - Resolved spec
+ * @param {object} [context.state] - Working state (from loadState)
+ * @returns {Map<string, object>} Map of gate name → enrichment object
+ */
+function enrichGateResults(report, context = {}) {
+  const { spec, state } = context;
+  const enrichments = new Map();
+
+  for (const gate of report.gates) {
+    // Only enrich failed or warned gates
+    if (gate.status === 'pass' || gate.status === 'skipped') continue;
+    if (gate.waived) continue;
+
+    const enricher = ENRICHERS[gate.name] || enrichGeneric;
+    const result = enricher(gate, spec);
+    if (!result) continue;
+
+    const category = GATE_CATEGORIES[gate.name] || 'quality';
+    const recurrence = getRecurrence(gate.name, state);
+
+    enrichments.set(gate.name, {
+      gate: gate.name,
+      category,
+      why: result.why,
+      recurrence,
+      nextStep: result.nextStep,
+      remediation: result.remediation,
+    });
+  }
+
+  return enrichments;
+}
+
+module.exports = {
+  enrichGateResults,
+  getRecurrence,
+  formatTimeSince,
+  GATE_CATEGORIES,
+};

package/dist/gates/format.js

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Report formatters for quality gate results
+ * Provides human-readable text and machine-readable JSON output.
+ * @author @darianrosebrook
+ */
+
+const STATUS_ICONS = {
+  pass: '\u2713',   // checkmark
+  fail: '\u2717',   // X mark
+  warn: '\u26A0',   // warning triangle
+  skipped: '\u2014', // em dash
+};
+
+/**
+ * Format gate report as human-readable text for terminal output
+ * @param {Object} report - Report from evaluateGates()
+ * @returns {string} Formatted text output
+ */
+function formatText(report) {
+  const lines = [];
+
+  lines.push('Quality Gates Report');
+  lines.push('====================');
+  lines.push('');
+
+  for (const gate of report.gates) {
+    const icon = STATUS_ICONS[gate.status] || '?';
+    const modeLabel = gate.mode === 'block' ? '[BLOCK]' : gate.mode === 'warn' ? '[WARN]' : `[${gate.mode.toUpperCase()}]`;
+    const waiverNote = gate.waived ? ' (waived)' : '';
+
+    lines.push(`  ${icon} ${gate.name} ${modeLabel}${waiverNote} (${gate.duration}ms)`);
+
+    if (gate.messages && gate.messages.length > 0) {
+      for (const msg of gate.messages) {
+        lines.push(`      ${msg}`);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('--------------------');
+
+  const { summary } = report;
+  const parts = [];
+  if (summary.passed > 0) parts.push(`${summary.passed} passed`);
+  if (summary.warned > 0) parts.push(`${summary.warned} warned`);
+  if (summary.blocked > 0) parts.push(`${summary.blocked} blocked`);
+  if (summary.skipped > 0) parts.push(`${summary.skipped} skipped`);
+  if (summary.waived > 0) parts.push(`${summary.waived} waived`);
+
+  lines.push(`Summary: ${parts.join(', ')}`);
+
+  if (report.warnings && report.warnings.length > 0) {
+    for (const w of report.warnings) {
+      lines.push(`WARNING: ${w}`);
+    }
+  }
+
+  if (report.passed) {
+    // Only say "all passed" if every enabled gate actually ran and passed
+    const enabledGates = report.gates.filter(g => g.status !== 'skipped');
+    const allRanAndPassed = enabledGates.length > 0 && enabledGates.every(g => g.status === 'pass');
+    if (allRanAndPassed) {
+      lines.push('Result: All enabled gates passed.');
+    } else {
+      lines.push('Result: No blocking failures.');
+    }
+  } else {
+    lines.push('Result: Commit blocked by failing gates.');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format gate report as JSON for CI/hooks consumption
+ * @param {Object} report - Report from evaluateGates()
+ * @returns {string} JSON string
+ */
+function formatJson(report) {
+  return JSON.stringify({
+    passed: report.passed,
+    summary: report.summary,
+    gates: report.gates.map(g => ({
+      name: g.name,
+      mode: g.mode,
+      status: g.status,
+      waived: g.waived,
+      waiverId: g.waiverId || null,
+      messages: g.messages,
+      duration: g.duration,
+    })),
+    warnings: report.warnings || [],
+    timestamp: new Date().toISOString(),
+  }, null, 2);
+}
+
+/**
+ * Format gate report with enriched feedback for failed/warned gates.
+ * Falls back to standard format for gates without enrichment.
+ * @param {Object} report - Report from evaluateGates()
+ * @param {Map<string, Object>} enrichments - Map of gate name → enrichment from feedback.js
+ * @returns {string} Formatted text output
+ */
+function formatEnrichedText(report, enrichments) {
+  const lines = [];
+
+  lines.push('Quality Gates Report');
+  lines.push('====================');
+  lines.push('');
+
+  for (const gate of report.gates) {
+    const icon = STATUS_ICONS[gate.status] || '?';
+    const modeLabel = gate.mode === 'block' ? '[BLOCK]' : gate.mode === 'warn' ? '[WARN]' : `[${gate.mode.toUpperCase()}]`;
+    const waiverNote = gate.waived ? ' (waived)' : '';
+    const enrichment = enrichments.get(gate.name);
+    const categoryTag = enrichment ? ` [${enrichment.category}]` : '';
+
+    lines.push(`  ${icon} ${gate.name} ${modeLabel}${categoryTag}${waiverNote} (${gate.duration}ms)`);
+
+    // Raw messages first
+    if (gate.messages && gate.messages.length > 0) {
+      for (const msg of gate.messages) {
+        lines.push(`      ${msg}`);
+      }
+    }
+
+    // Enrichment details for failed/warned gates
+    if (enrichment) {
+      if (enrichment.why) {
+        lines.push(`      Why: ${enrichment.why}`);
+      }
+      if (enrichment.recurrence) {
+        lines.push(`      Recurring: failed ${enrichment.recurrence.count} time(s) (last: ${enrichment.recurrence.lastSeen})`);
+      }
+      if (enrichment.nextStep) {
+        lines.push(`      Next step: ${enrichment.nextStep}`);
+      }
+      if (enrichment.remediation) {
+        lines.push(`      Fix: ${enrichment.remediation}`);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('--------------------');
+
+  const { summary } = report;
+  const parts = [];
+  if (summary.passed > 0) parts.push(`${summary.passed} passed`);
+  if (summary.warned > 0) parts.push(`${summary.warned} warned`);
+  if (summary.blocked > 0) parts.push(`${summary.blocked} blocked`);
+  if (summary.skipped > 0) parts.push(`${summary.skipped} skipped`);
+  if (summary.waived > 0) parts.push(`${summary.waived} waived`);
+
+  lines.push(`Summary: ${parts.join(', ')}`);
+
+  if (report.warnings && report.warnings.length > 0) {
+    for (const w of report.warnings) {
+      lines.push(`WARNING: ${w}`);
+    }
+  }
+
+  if (report.passed) {
+    const enabledGates = report.gates.filter(g => g.status !== 'skipped');
+    const allRanAndPassed = enabledGates.length > 0 && enabledGates.every(g => g.status === 'pass');
+    if (allRanAndPassed) {
+      lines.push('Result: All enabled gates passed.');
+    } else {
+      lines.push('Result: No blocking failures.');
+    }
+  } else {
+    lines.push('Result: Commit blocked by failing gates.');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { formatText, formatJson, formatEnrichedText };

package/dist/gates/god-object.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview God object detection gate
+ * Flags large files that exceed line-count thresholds.
+ * Test files use a higher threshold since large integration tests are normal.
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const name = 'god_object';
+
+const SOURCE_EXTENSIONS = ['.js', '.ts', '.tsx', '.jsx', '.py', '.rs', '.go', '.java', '.rb', '.cs'];
+
+/** Directories and patterns that are always excluded (generated/vendored content) */
+const DEFAULT_EXCLUDE_DIRS = [
+  'dist/', 'dist-bundle/', 'build/', '.next/', 'out/',
+  'node_modules/', '__pycache__/', '.nuxt/', 'coverage/',
+  'vendor/', '.cache/',
+];
+
+/** File patterns that are always excluded */
+const DEFAULT_EXCLUDE_PATTERNS = ['.min.', '.bundle.', '.generated.'];
+
+/** Patterns that identify test files (get higher thresholds) */
+const TEST_PATTERNS = [
+  '.test.', '.spec.', '_test.', '_spec.',
+  'tests/', 'test/', '__tests__/', '__test__/',
+  'proving-grounds/', 'fixtures/',
+];
+
+/** Default multiplier for test file thresholds (2x = test files get double the threshold) */
+const TEST_THRESHOLD_MULTIPLIER = 2;
+
+/**
+ * Check if a file should be excluded from god-object analysis.
+ * @param {string} filePath - Relative file path
+ * @returns {boolean} Whether the file is excluded
+ */
+function isExcluded(filePath) {
+  for (const dir of DEFAULT_EXCLUDE_DIRS) {
+    if (filePath.startsWith(dir) || filePath.includes('/' + dir)) return true;
+  }
+  for (const pat of DEFAULT_EXCLUDE_PATTERNS) {
+    if (filePath.includes(pat)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a file is a test file.
+ * @param {string} filePath - Relative file path
+ * @returns {boolean}
+ */
+function isTestFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return TEST_PATTERNS.some(pat => lower.includes(pat));
+}
+
+/**
+ * Run the god object detection gate
+ * @param {Object} params - Gate parameters
+ * @param {string[]} params.stagedFiles - Staged file paths
+ * @param {string} params.projectRoot - Project root
+ * @param {Object} [params.thresholds] - Override thresholds
+ * @param {number} [params.thresholds.warning=1750] - Warning line threshold
+ * @param {number} [params.thresholds.critical=2000] - Critical/fail line threshold
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ stagedFiles, projectRoot, thresholds }) {
+  const baseWarning = thresholds?.warning || 1750;
+  const baseCritical = thresholds?.critical || 2000;
+  const messages = [];
+  let hasCritical = false;
+  let hasWarning = false;
+
+  const sourceFiles = stagedFiles.filter(f =>
+    SOURCE_EXTENSIONS.some(ext => f.endsWith(ext)) && !isExcluded(f)
+  );
+
+  for (const file of sourceFiles) {
+    try {
+      const fullPath = path.resolve(projectRoot, file);
+      if (!fs.existsSync(fullPath)) continue;
+
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const lineCount = content.split('\n').length;
+
+      // Test files get a higher threshold — large integration tests are normal
+      const mult = isTestFile(file) ? TEST_THRESHOLD_MULTIPLIER : 1;
+      const warningThreshold = baseWarning * mult;
+      const criticalThreshold = baseCritical * mult;
+
+      if (lineCount >= criticalThreshold) {
+        hasCritical = true;
+        const label = mult > 1 ? 'CRITICAL (test file)' : 'CRITICAL';
+        messages.push(`${label}: ${file} has ${lineCount} lines (threshold: ${criticalThreshold})`);
+      } else if (lineCount >= warningThreshold) {
+        hasWarning = true;
+        const label = mult > 1 ? 'WARNING (test file)' : 'WARNING';
+        messages.push(`${label}: ${file} has ${lineCount} lines (threshold: ${warningThreshold})`);
+      }
+    } catch (err) {
+      messages.push(`WARNING: Could not read ${file}: ${err.message}`);
+    }
+  }
+
+  if (hasCritical) {
+    return { status: 'fail', messages };
+  }
+  if (hasWarning) {
+    return { status: 'warn', messages };
+  }
+  return { status: 'pass', messages };
+}
+
+module.exports = { name, run };