@paths.design/caws-cli 9.3.2 → 10.1.0

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,109 @@
+/**
+ * @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.
+  // CAWSFIX-03: The canonical project-level schema lives at
+  // `.caws/working-spec.schema.json` (flat layout, matches the pattern used for
+  // policy.schema.json and waiver.schema.json). Older projects may still have
+  // a `.caws/schemas/` directory from scaffolded templates, so we check both.
+  // Bundled fallbacks cover packaged installs.
+  const schemaPaths = [
+    path.join(projectRoot, '.caws', 'working-spec.schema.json'),
+    path.join(projectRoot, '.caws', 'schemas', 'working-spec.schema.json'),
+    path.join(projectRoot, 'node_modules', '@caws', 'cli', 'templates', '.caws', 'schemas', 'working-spec.schema.json'),
+    path.join(projectRoot, 'node_modules', '@paths.design', '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 };

package/dist/gates/todo-detection.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview TODO/FIXME scanning gate
+ * Detects actionable TODO, FIXME, HACK, XXX markers in comments.
+ * Filters out false positives: string literals, regex definitions, test assertions,
+ * and documentation about the TODO system itself.
+ * Context-aware: commit context scans staged diff, cli/edit context scans file content.
+ * @author @darianrosebrook
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const name = 'todo_detection';
+
+const TODO_MARKERS = /\b(TODO|FIXME|HACK|XXX)\b/g;
+
+/**
+ * Comment patterns for languages we scan.
+ * A line is a "comment TODO" if the TODO marker appears after a comment introducer.
+ */
+const COMMENT_TODO = /(?:\/\/|#|\/?\*|\{\/\*)\s*\b(TODO|FIXME|HACK|XXX)\b/;
+
+/**
+ * Patterns that indicate the line is ABOUT the TODO system, not an actual TODO.
+ * These are lines where TODO appears as data, not as intent.
+ */
+const FALSE_POSITIVE_PATTERNS = [
+  /TODO_PATTERN/,                       // regex variable name
+  /TODO\/FIXME/,                        // describing the pattern itself
+  /\btoMatch\b|\btoContain\b|\bexpect\(/,  // test assertions
+  /writeFileSync.*TODO/,                // test fixture data
+  /\bdescribe\(.*TODO|\btest\(.*TODO|\bit\(.*TODO/,  // test names
+  /Pattern.*TODO|regex.*TODO/i,         // documentation about patterns
+  /["'`].*\bTODO\b.*["'`]/,            // string literals containing TODO
+];
+
+/** Directories to skip when scanning files directly */
+const EXCLUDE_DIRS = ['node_modules/', 'dist/', 'dist-bundle/', 'build/', '.next/', 'coverage/', 'vendor/', '__pycache__/'];
+
+/** Files that are part of the TODO detection system itself — skip to avoid self-analysis */
+const SELF_FILES = ['todo-detection.js', 'todo_detection.js', 'todo_analyzer.py', 'todo-analyzer'];
+
+/** Extensions to scan */
+const SOURCE_EXTENSIONS = ['.js', '.ts', '.tsx', '.jsx', '.py', '.rs', '.go', '.java', '.rb', '.cs', '.sh'];
+
+/**
+ * Check if a file should be excluded from scanning.
+ * @param {string} filePath - Relative file path
+ * @returns {boolean}
+ */
+function isExcluded(filePath) {
+  for (const dir of EXCLUDE_DIRS) {
+    if (filePath.startsWith(dir) || filePath.includes('/' + dir)) return true;
+  }
+  // Skip the gate's own implementation files
+  const basename = path.basename(filePath);
+  for (const self of SELF_FILES) {
+    if (basename === self || basename.includes(self)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a line contains a real TODO comment (not a false positive).
+ * Returns the marker name if real, null if false positive.
+ * @param {string} line - Source line
+ * @returns {string|null} The marker found, or null
+ */
+function findRealTodo(line) {
+  const trimmed = line.trim();
+
+  // Must contain a marker at all
+  TODO_MARKERS.lastIndex = 0;
+  if (!TODO_MARKERS.test(trimmed)) return null;
+
+  // Filter out false positives
+  for (const fp of FALSE_POSITIVE_PATTERNS) {
+    if (fp.test(trimmed)) return null;
+  }
+
+  // Must look like a comment containing the marker — not just any line with TODO in it
+  if (!COMMENT_TODO.test(trimmed)) return null;
+
+  // Extract which marker
+  TODO_MARKERS.lastIndex = 0;
+  const match = TODO_MARKERS.exec(trimmed);
+  return match ? match[1] : null;
+}
+
+/**
+ * Scan staged diff for newly-added TODO markers.
+ * Used in commit context — only flags markers being added, not pre-existing ones.
+ */
+function scanStagedDiff(projectRoot) {
+  const messages = [];
+  let totalCount = 0;
+
+  const diff = execSync('git diff --cached -U0', {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  let currentFile = null;
+  let lineNum = 0;
+
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ b/')) {
+      currentFile = line.slice(6);
+      continue;
+    }
+    if (line.startsWith('@@')) {
+      const match = line.match(/@@ -\d+(?:,\d+)? \+(\d+)/);
+      if (match) {
+        lineNum = parseInt(match[1], 10) - 1;
+      }
+      continue;
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      lineNum++;
+      const content = line.slice(1); // remove the leading +
+      const marker = findRealTodo(content);
+      if (marker) {
+        totalCount++;
+        messages.push(`${currentFile}:${lineNum}: ${marker} found`);
+      }
+    } else if (!line.startsWith('-')) {
+      lineNum++;
+    }
+  }
+
+  return { totalCount, messages };
+}
+
+/**
+ * Scan file contents directly for TODO markers.
+ * Used in cli/edit context — reports all existing markers in the given files.
+ */
+function scanFiles(stagedFiles, projectRoot) {
+  const messages = [];
+  let totalCount = 0;
+
+  const filesToScan = stagedFiles.filter(f =>
+    SOURCE_EXTENSIONS.some(ext => f.endsWith(ext)) && !isExcluded(f)
+  );
+
+  for (const file of filesToScan) {
+    try {
+      const fullPath = path.resolve(projectRoot, file);
+      if (!fs.existsSync(fullPath)) continue;
+
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const marker = findRealTodo(lines[i]);
+        if (marker) {
+          totalCount++;
+          messages.push(`${file}:${i + 1}: ${marker} found`);
+        }
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return { totalCount, messages };
+}
+
+/**
+ * Run the TODO detection gate
+ * @param {Object} params - Gate parameters
+ * @param {string[]} params.stagedFiles - File paths to check
+ * @param {string} params.projectRoot - Project root
+ * @param {string} [params.context] - Execution context (commit, cli, edit)
+ * @returns {Promise<Object>} Gate result with status and messages
+ */
+async function run({ stagedFiles, projectRoot, context }) {
+  try {
+    let result;
+
+    if (context === 'commit') {
+      // Commit context: scan only newly-added lines in staged diff
+      result = scanStagedDiff(projectRoot);
+    } else {
+      // CLI/edit context: scan file contents directly
+      result = scanFiles(stagedFiles, projectRoot);
+    }
+
+    if (result.totalCount > 0) {
+      result.messages.unshift(`Found ${result.totalCount} TODO/FIXME/HACK/XXX marker(s)${context === 'commit' ? ' in staged changes' : ''}`);
+      return { status: 'warn', messages: result.messages };
+    }
+
+    return { status: 'pass', messages: [] };
+  } catch (err) {
+    return {
+      status: 'warn',
+      messages: [`Cannot scan for TODO markers: ${err.message}`],
+    };
+  }
+}
+
+module.exports = { name, run };