@paths.design/caws-cli 10.2.0 → 11.0.0

package/dist/gates/feedback.js

@@ -1,260 +0,0 @@
-/**
- * @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

@@ -1,179 +0,0 @@
-/**
- * @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

@@ -1,117 +0,0 @@
-/**
- * @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 };