@paths.design/caws-cli 9.3.2 → 10.0.1

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 };

package/dist/gates/pipeline.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Central gate evaluation pipeline
+ * Auto-discovers gate modules and evaluates them against policy configuration.
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const { PolicyManager } = require('../policy/PolicyManager');
+const WaiversManager = require('../waivers-manager');
+const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
+
+/**
+ * Auto-discover gate modules from the gates directory
+ * Skips pipeline.js and format.js; requires each module to export `name` and `run`.
+ * @returns {Object} Map of gate name to gate module
+ */
+function loadGates() {
+  const gateDir = __dirname;
+  const gates = {};
+  for (const file of fs.readdirSync(gateDir)) {
+    if (file === 'pipeline.js' || file === 'format.js' || !file.endsWith('.js')) continue;
+    try {
+      const gate = require(path.join(gateDir, file));
+      if (gate.name && typeof gate.run === 'function') {
+        gates[gate.name] = gate;
+      }
+    } catch { /* skip broken gate modules */ }
+  }
+  return gates;
+}
+
+/**
+ * Evaluate all configured gates against staged files and spec
+ * @param {Object} params - Evaluation parameters
+ * @param {string} params.projectRoot - Project root directory
+ * @param {string[]} params.stagedFiles - List of staged file paths
+ * @param {Object} [params.spec] - Working spec object
+ * @param {Object} [params.context] - Additional context
+ * @returns {Promise<Object>} Evaluation report with gate results and summary
+ */
+async function evaluateGates({ projectRoot, stagedFiles, spec, context }) {
+  const policyManager = new PolicyManager();
+  const policy = await policyManager.loadPolicy(projectRoot);
+  const riskTier = spec?.risk_tier || policy?.risk_tiers?.default || 2;
+  const usingDefaults = !!policy?._isDefault;
+
+  const availableGates = loadGates();
+  const gateConfigs = policy?.gates || {};
+  const results = [];
+  const waiversManager = new WaiversManager({ projectRoot });
+
+  for (const [gateName, config] of Object.entries(gateConfigs)) {
+    if (!config.enabled) continue;
+
+    const mode = config.mode || 'warn';
+    if (mode === 'skip') {
+      results.push({ name: gateName, mode, status: 'skipped', waived: false, messages: [], duration: 0 });
+      continue;
+    }
+
+    // Check waivers
+    let waived = false;
+    let waiverId = null;
+    try {
+      const waiverResult = await waiversManager.getActiveWaiverForGate(gateName);
+      if (waiverResult) {
+        waived = true;
+        waiverId = waiverResult.waiverId;
+        results.push({ name: gateName, mode, status: 'pass', waived: true, waiverId, messages: [`Waived: ${waiverResult.reason}`], duration: 0 });
+        continue;
+      }
+    } catch (err) {
+      // Waiver check failed — log it so the failure is visible, then proceed without waiver
+      results.push({
+        name: gateName, mode, status: 'fail', waived: false,
+        messages: [`Waiver check error (fail-closed): ${err.message}`], duration: 0,
+      });
+      continue;
+    }
+
+    const gate = availableGates[gateName];
+    if (!gate) {
+      // Fail-closed for block/warn mode: a gate referenced in policy but not found is a config error
+      const status = mode === 'block' ? 'fail' : 'warn';
+      results.push({
+        name: gateName, mode, status, waived: false,
+        messages: [`Gate "${gateName}" is configured in policy but not implemented. Check for typos in policy.yaml.`],
+        duration: 0,
+      });
+      continue;
+    }
+
+    const start = Date.now();
+    try {
+      const result = await gate.run({ stagedFiles, spec, policy, projectRoot, riskTier, thresholds: config.thresholds, context });
+      results.push({
+        name: gateName,
+        mode,
+        status: result.status,
+        waived,
+        waiverId,
+        messages: result.messages || [],
+        duration: Date.now() - start,
+      });
+    } catch (err) {
+      results.push({
+        name: gateName,
+        mode,
+        status: 'fail',
+        waived: false,
+        messages: [`Gate error: ${err.message}`],
+        duration: Date.now() - start,
+      });
+    }
+  }
+
+  const blocked = results.filter(r => r.mode === 'block' && r.status === 'fail' && !r.waived);
+  const warned = results.filter(r => r.status === 'warn' || (r.mode === 'warn' && r.status === 'fail'));
+  const passed = results.filter(r => r.status === 'pass');
+  const skipped = results.filter(r => r.status === 'skipped');
+  const waivedGates = results.filter(r => r.waived);
+
+  const report = {
+    passed: blocked.length === 0,
+    gates: results,
+    summary: {
+      blocked: blocked.length,
+      warned: warned.length,
+      passed: passed.length,
+      skipped: skipped.length,
+      waived: waivedGates.length,
+    },
+  };
+
+  if (usingDefaults) {
+    report.warnings = report.warnings || [];
+    report.warnings.push('No policy.yaml found — using built-in defaults. Create .caws/policy.yaml for project-specific gate configuration.');
+  }
+
+  // Emit lifecycle events
+  try {
+    if (blocked.length > 0) {
+      for (const b of blocked) {
+        lifecycle.emit(EVENTS.GATES_BLOCKED, {
+          specId: spec?.id || null,
+          gateName: b.name,
+          mode: b.mode,
+          messages: b.messages,
+          context,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } else {
+      lifecycle.emit(EVENTS.GATES_PASSED, {
+        specId: spec?.id || null,
+        summary: report.summary,
+        context,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  } catch { /* non-fatal */ }
+
+  return report;
+}
+
+module.exports = { evaluateGates, loadGates };

package/dist/gates/scope-boundary.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Scope enforcement gate
+ * Validates staged files against spec.scope.in and spec.scope.out patterns.
+ * @author @darianrosebrook
+ */
+
+const picomatch = require('picomatch');
+
+const name = 'scope_boundary';
+
+/**
+ * Check if a file path matches any of the given glob patterns.
+ * Uses picomatch for correct glob semantics (** matches zero or more segments).
+ * @param {string} filePath - File path to check
+ * @param {string[]} patterns - Glob patterns
+ * @returns {boolean} Whether the file matches any pattern
+ */
+function matchesAny(filePath, patterns) {
+  if (!patterns || patterns.length === 0) return false;
+  return picomatch.isMatch(filePath, patterns, { dot: true });
+}
+
+/**
+ * Check if a file is an infrastructure file that always passes scope checks.
+ * Root-level files are exempt UNLESS they match an explicit scope.out pattern.
+ * @param {string} filePath - File path to check
+ * @returns {boolean} Whether the file is exempt from scope.in checks
+ */
+function isExempt(filePath) {
+  // .caws and .claude directories always pass (infrastructure)
+  if (filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) return true;
+  return false;
+}
+
+/**
+ * Check if a file is a root-level file (no directory separator).
+ * Root-level files skip scope.in checks but still respect scope.out.
+ * @param {string} filePath - File path to check
+ * @returns {boolean} Whether the file is root-level
+ */
+function isRootLevel(filePath) {
+  return !filePath.includes('/');
+}
+
+/**
+ * Run the scope boundary gate
+ * @param {Object} params - Gate parameters
+ * @param {string[]} params.stagedFiles - Staged file paths
+ * @param {Object} params.spec - Working spec with scope.in/scope.out
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ stagedFiles, spec }) {
+  const messages = [];
+  const violations = [];
+
+  const scopeIn = spec?.scope?.in || [];
+  const scopeOut = spec?.scope?.out || [];
+
+  // If no scope defined, pass
+  if (scopeIn.length === 0 && scopeOut.length === 0) {
+    return { status: 'pass', messages: ['No scope boundaries defined'] };
+  }
+
+  for (const file of stagedFiles) {
+    // Infrastructure dirs are always exempt
+    if (isExempt(file)) continue;
+
+    // Check scope.out first (explicit exclusion) — applies to ALL files including root-level
+    if (scopeOut.length > 0 && matchesAny(file, scopeOut)) {
+      violations.push(file);
+      messages.push(`Out of scope (excluded): ${file}`);
+      continue;
+    }
+
+    // Root-level files skip scope.in checks (but scope.out above still applies)
+    if (isRootLevel(file)) continue;
+
+    // Check scope.in (must match if defined)
+    if (scopeIn.length > 0 && !matchesAny(file, scopeIn)) {
+      violations.push(file);
+      messages.push(`Out of scope (not in allowed paths): ${file}`);
+    }
+  }
+
+  if (violations.length > 0) {
+    messages.unshift(`${violations.length} file(s) outside spec scope boundaries`);
+    return { status: 'fail', messages };
+  }
+
+  return { status: 'pass', messages };
+}
+
+module.exports = { name, run };

package/dist/gates/spec-completeness.js

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Schema validation gate
+ * Validates the working spec against the CAWS schema.
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const Ajv = require('ajv');
+
+const name = 'spec_completeness';
+
+/**
+ * Run the spec completeness gate
+ * @param {Object} params - Gate parameters
+ * @param {string} params.projectRoot - Project root
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ projectRoot, spec }) {
+  const messages = [];
+
+  let specObject = spec;
+  if (!specObject) {
+    const specPath = path.join(projectRoot, '.caws', 'working-spec.yaml');
+    if (!await fs.pathExists(specPath)) {
+      return {
+        status: 'fail',
+        messages: ['No working-spec.yaml found. Create one with: caws init or caws specs create <id>'],
+      };
+    }
+
+    try {
+      const content = await fs.readFile(specPath, 'utf8');
+      specObject = yaml.load(content);
+    } catch (err) {
+      return { status: 'fail', messages: [`Failed to parse working-spec.yaml: ${err.message}`] };
+    }
+  }
+
+  if (!specObject) {
+    return { status: 'fail', messages: ['Resolved spec is empty'] };
+  }
+
+  // Try to find and load the schema
+  const schemaPaths = [
+    path.join(projectRoot, '.caws', 'schemas', 'working-spec.schema.json'),
+    path.join(projectRoot, 'node_modules', '@caws', 'cli', 'templates', '.caws', 'schemas', 'working-spec.schema.json'),
+  ];
+
+  let schema = null;
+  for (const schemaPath of schemaPaths) {
+    if (await fs.pathExists(schemaPath)) {
+      try {
+        const schemaContent = await fs.readFile(schemaPath, 'utf8');
+        schema = JSON.parse(schemaContent);
+        break;
+      } catch {
+        // Try next path
+      }
+    }
+  }
+
+  if (!schema) {
+    // No schema available; do basic structural validation
+    const requiredFields = ['title', 'risk_tier'];
+    const missing = requiredFields.filter(f => !(f in specObject));
+    if (missing.length > 0) {
+      messages.push(`Missing required fields: ${missing.join(', ')}`);
+      return { status: 'fail', messages };
+    }
+    return { status: 'pass', messages: ['Basic structure valid (no schema file found for full validation)'] };
+  }
+
+  // Validate with AJV — use 2020-12 draft if schema requires it
+  try {
+    const isDraft2020 = schema.$schema && schema.$schema.includes('2020-12');
+    let ajv;
+    if (isDraft2020) {
+      const Ajv2020 = require('ajv/dist/2020');
+      ajv = new Ajv2020({ allErrors: true, strict: false });
+    } else {
+      ajv = new Ajv({ allErrors: true, strict: false });
+    }
+    const validate = ajv.compile(schema);
+    const valid = validate(specObject);
+
+    if (!valid) {
+      for (const error of validate.errors) {
+        const location = error.instancePath || '/';
+        messages.push(`${location}: ${error.message}`);
+      }
+      return { status: 'fail', messages };
+    }
+
+    return { status: 'pass', messages };
+  } catch (err) {
+    return { status: 'fail', messages: [`Schema validation error: ${err.message}`] };
+  }
+}
+
+module.exports = { name, run };