@paths.design/caws-cli 10.2.0 → 11.0.0

package/dist/gates/pipeline.js

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

@@ -1,112 +0,0 @@
-/**
- * @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 infrastructure or lives in a policy-declared
- * non-governed zone. Exempt files bypass both scope.in and scope.out.
- *
- * @param {string} filePath - File path to check
- * @param {string[]} [nonGovernedZones=[]] - Glob patterns from
- *   policy.non_governed_zones. Paths matching any pattern are exempt
- *   from scope enforcement entirely. (CAWSFIX-26 / D9)
- * @returns {boolean} Whether the file is exempt from scope checks
- */
-function isExempt(filePath, nonGovernedZones = []) {
-  // .caws and .claude directories always pass (infrastructure)
-  if (filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) return true;
-
-  // Policy-declared non-governed zones short-circuit scope enforcement.
-  // Intentionally wins over scope.out: the contract is that these
-  // subtrees are outside the governance model, not merely excluded
-  // from one spec's scope.
-  if (nonGovernedZones.length > 0 && matchesAny(filePath, nonGovernedZones)) {
-    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
- * @param {Object} [params.policy] - Optional CAWS policy. Reads
- *   policy.non_governed_zones for path exemption (CAWSFIX-26 / D9).
- *   When absent or the field is empty, only infra dirs are exempt.
- * @returns {Promise<Object>} Gate result with status and messages
- */
-async function run({ stagedFiles, spec, policy }) {
-  const messages = [];
-  const violations = [];
-
-  const scopeIn = spec?.scope?.in || [];
-  const scopeOut = spec?.scope?.out || [];
-  const nonGovernedZones = Array.isArray(policy?.non_governed_zones)
-    ? policy.non_governed_zones
-    : [];
-
-  // 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 AND policy-declared non-governed zones are exempt.
-    if (isExempt(file, nonGovernedZones)) 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

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

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