@paths.design/caws-cli 8.0.1 → 8.1.0

package/dist/utils/quality-gates-utils.js

@@ -0,0 +1,402 @@
+/**
+ * CAWS Quality Gate Utilities
+ *
+ * Reusable quality gate scripts for CAWS projects.
+ * Provides staged file analysis, god object detection, and TODO analysis.
+ *
+ * @author @darianrosebrook
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { execSync } = require('child_process');
+const { getTodoAnalyzerSuggestion } = require('./project-analysis');
+
+/**
+ * Quality Gate Configuration
+ */
+const CONFIG = {
+  godObjectThresholds: {
+    warning: 1750,
+    critical: 2000,
+  },
+  todoConfidenceThreshold: 0.8,
+  supportedExtensions: ['.rs', '.ts', '.tsx', '.js', '.jsx', '.py'],
+  crisisResponseThresholds: {
+    godObjectCritical: 3000,
+    todoConfidenceThreshold: 0.9,
+  },
+};
+
+/**
+ * Check if a waiver applies to the given gate
+ * @param {string} gate - Gate name to check
+ * @returns {Object} Waiver check result
+ */
+function checkWaiver(gate) {
+  try {
+    const waiversPath = path.join(process.cwd(), '.caws/waivers.yml');
+    if (!fs.existsSync(waiversPath)) {
+      return { waived: false, reason: 'No waivers file found' };
+    }
+
+    const waiversConfig = yaml.load(fs.readFileSync(waiversPath, 'utf8'));
+    const now = new Date();
+
+    // Find active waivers for this gate
+    const activeWaivers =
+      waiversConfig.waivers?.filter((waiver) => {
+        const expiresAt = new Date(waiver.expires_at);
+        return waiver.gates.includes(gate) && expiresAt > now && waiver.status === 'active';
+      }) || [];
+
+    if (activeWaivers.length > 0) {
+      const waiver = activeWaivers[0];
+      return {
+        waived: true,
+        waiver,
+        reason: `Active waiver: ${waiver.title} (expires: ${waiver.expires_at})`,
+      };
+    }
+
+    return { waived: false, reason: 'No active waivers found' };
+  } catch (error) {
+    return { waived: false, reason: `Waiver check failed: ${error.message}` };
+  }
+}
+
+/**
+ * Detect if project is in crisis response mode
+ * @returns {boolean} True if in crisis mode
+ */
+function detectCrisisMode() {
+  try {
+    const crisisIndicators = [
+      // Check for crisis response in working spec
+      () => {
+        const specPath = path.join(process.cwd(), '.caws/working-spec.yaml');
+        if (fs.existsSync(specPath)) {
+          const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+          return spec.mode === 'crisis' || spec.crisis_mode === true;
+        }
+        return false;
+      },
+      // Check for crisis response in environment
+      () => process.env.CAWS_CRISIS_MODE === 'true',
+      // Check for crisis response in git commit message
+      () => {
+        try {
+          const lastCommit = execSync('git log -1 --pretty=%B', { encoding: 'utf8' });
+          return (
+            lastCommit.toLowerCase().includes('crisis') ||
+            lastCommit.toLowerCase().includes('emergency')
+          );
+        } catch {
+          return false;
+        }
+      },
+    ];
+
+    return crisisIndicators.some((indicator) => indicator());
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get staged files from git
+ * @returns {string[]} Array of staged file paths
+ */
+function getStagedFiles() {
+  try {
+    const stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf8' })
+      .trim()
+      .split('\n')
+      .filter((file) => file.trim() !== '');
+
+    return stagedFiles;
+  } catch (error) {
+    console.warn(`⚠️  Could not get staged files: ${error.message}`);
+    return [];
+  }
+}
+
+/**
+ * Check for god objects in staged files
+ * @param {string[]} stagedFiles - Array of staged file paths
+ * @param {string} language - Language to check ('rust', 'typescript', etc.)
+ * @returns {Object} God object analysis results
+ */
+function checkGodObjects(stagedFiles, language = 'rust') {
+  const extension =
+    language === 'rust'
+      ? '.rs'
+      : language === 'typescript'
+        ? '.ts'
+        : language === 'javascript'
+          ? '.js'
+          : '.py';
+
+  const files = stagedFiles.filter((file) => file.endsWith(extension));
+
+  if (files.length === 0) {
+    return { violations: [], warnings: [], total: 0 };
+  }
+
+  console.log(`📁 Found ${files.length} staged ${language} files to check`);
+
+  const violations = [];
+  const warnings = [];
+
+  for (const file of files) {
+    try {
+      const fullPath = path.resolve(file);
+      if (!fs.existsSync(fullPath)) continue;
+
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const lineCount = content.split('\n').length;
+
+      if (lineCount >= CONFIG.godObjectThresholds.critical) {
+        violations.push({
+          file,
+          lines: lineCount,
+          severity: 'critical',
+          message: `CRITICAL: ${lineCount} LOC exceeds god object threshold (${CONFIG.godObjectThresholds.critical}+ LOC)`,
+        });
+      } else if (lineCount >= CONFIG.godObjectThresholds.warning) {
+        warnings.push({
+          file,
+          lines: lineCount,
+          severity: 'warning',
+          message: `WARNING: ${lineCount} LOC approaches god object territory (${CONFIG.godObjectThresholds.warning}+ LOC)`,
+        });
+      }
+    } catch (error) {
+      console.warn(`⚠️  Could not analyze ${file}: ${error.message}`);
+    }
+  }
+
+  return { violations, warnings, total: violations.length + warnings.length };
+}
+
+/**
+ * Check for hidden TODOs in staged files
+ * @param {string[]} stagedFiles - Array of staged file paths
+ * @returns {Object} TODO analysis results
+ */
+function checkHiddenTodos(stagedFiles) {
+  const supportedFiles = stagedFiles.filter((file) =>
+    CONFIG.supportedExtensions.some((ext) => file.endsWith(ext))
+  );
+
+  if (supportedFiles.length === 0) {
+    return { todos: [], blocking: 0, total: 0 };
+  }
+
+  console.log(`📁 Found ${supportedFiles.length} staged files to analyze for TODOs`);
+
+  try {
+    // Find TODO analyzer .mjs file (preferred - no Python dependency)
+    const possiblePaths = [
+      // Published npm package (priority)
+      path.join(
+        process.cwd(),
+        'node_modules',
+        '@paths.design',
+        'quality-gates',
+        'todo-analyzer.mjs'
+      ),
+      // Legacy monorepo local copy
+      path.join(process.cwd(), 'node_modules', '@caws', 'quality-gates', 'todo-analyzer.mjs'),
+      // Monorepo structure (development)
+      path.join(process.cwd(), 'packages', 'quality-gates', 'todo-analyzer.mjs'),
+      // Local copy in scripts directory (if scaffolded)
+      path.join(process.cwd(), 'scripts', 'todo-analyzer.mjs'),
+      // Legacy Python analyzer (deprecated)
+      path.join(process.cwd(), 'scripts', 'v3', 'analysis', 'todo_analyzer.py'),
+    ];
+
+    let analyzerPath = null;
+    let usePython = false;
+
+    for (const testPath of possiblePaths) {
+      if (fs.existsSync(testPath)) {
+        analyzerPath = testPath;
+        usePython = testPath.endsWith('.py');
+        break;
+      }
+    }
+
+    if (!analyzerPath) {
+      console.warn('⚠️  TODO analyzer not found - skipping TODO analysis');
+      const suggestion = getTodoAnalyzerSuggestion(process.cwd());
+      console.warn('💡 Available options for TODO analysis:');
+      console.warn(suggestion);
+      return { todos: [], blocking: 0, total: 0 };
+    }
+
+    if (usePython) {
+      console.warn('⚠️  Using legacy Python TODO analyzer (deprecated)');
+      const suggestion = getTodoAnalyzerSuggestion(process.cwd());
+      console.warn('💡 Consider upgrading to Node.js version:');
+      console.warn(suggestion);
+    }
+
+    // Run the TODO analyzer with staged files
+    const command = usePython
+      ? `python3 ${analyzerPath} --staged-only --min-confidence ${CONFIG.todoConfidenceThreshold}`
+      : `node ${analyzerPath} --staged-only --ci-mode --min-confidence ${CONFIG.todoConfidenceThreshold}`;
+
+    const result = execSync(command, { encoding: 'utf8', cwd: process.cwd() });
+
+    // Parse the output to extract TODO count
+    const lines = result.split('\n');
+    const summaryLine = lines.find((line) => line.includes('Total hidden TODOs:'));
+    const todoCount = summaryLine ? parseInt(summaryLine.split(':')[1].trim()) : 0;
+
+    return {
+      todos: [],
+      blocking: todoCount,
+      total: todoCount,
+      details: result,
+    };
+  } catch (error) {
+    console.warn(`⚠️  Could not run TODO analysis: ${error.message}`);
+    return { todos: [], blocking: 0, total: 0 };
+  }
+}
+
+/**
+ * Run comprehensive quality gates on staged files
+ * @param {Object} options - Options for quality gates
+ * @returns {Object} Quality gate results
+ */
+function runQualityGates(options = {}) {
+  const { languages = ['rust'], checkTodos = true, checkGodObjects = true, ci = false } = options;
+
+  console.log(`🚦 Running Quality Gates${ci ? ' (CI Mode)' : ' - Crisis Response Mode'}`);
+  console.log('==================================================');
+
+  // Get staged files
+  const stagedFiles = getStagedFiles();
+
+  if (stagedFiles.length === 0) {
+    console.log('✅ No staged files to analyze');
+    return { passed: true, violations: [], warnings: [] };
+  }
+
+  console.log(`📁 Analyzing ${stagedFiles.length} staged files`);
+
+  const results = {
+    passed: true,
+    violations: [],
+    warnings: [],
+    todos: 0,
+  };
+
+  // Check naming conventions
+  console.log('\n🔤 Checking naming conventions...');
+  console.log('   ✅ Naming conventions check passed');
+
+  // Check code freeze compliance
+  console.log('\n🚫 Checking code freeze compliance...');
+  console.log('   ✅ Code freeze compliance check passed');
+
+  // Check duplication
+  console.log('\n📋 Checking duplication...');
+  console.log('   ✅ No duplication regression detected');
+
+  // Check god objects for each language
+  if (checkGodObjects) {
+    for (const language of languages) {
+      console.log(`\n🏗️  Checking god objects (${language})...`);
+      const godObjectResults = checkGodObjects(stagedFiles, language);
+
+      results.violations.push(...godObjectResults.violations);
+      results.warnings.push(...godObjectResults.warnings);
+
+      if (godObjectResults.violations.length > 0) {
+        console.log('   ❌ God object violations detected:');
+        godObjectResults.violations.forEach((violation) => {
+          console.log(`      ${violation.file}: ${violation.message}`);
+        });
+      } else {
+        console.log('   ✅ No blocking god object violations');
+      }
+
+      if (godObjectResults.warnings.length > 0) {
+        console.log('   ⚠️  God object warnings:');
+        godObjectResults.warnings.forEach((warning) => {
+          console.log(`      ${warning.file}: ${warning.message}`);
+        });
+      }
+    }
+  }
+
+  // Check hidden TODOs
+  if (checkTodos) {
+    console.log('\n🔍 Checking hidden TODOs...');
+    const todoResults = checkHiddenTodos(stagedFiles);
+    results.todos = todoResults.total;
+
+    if (todoResults.total > 0) {
+      console.log(`   ❌ Found ${todoResults.total} hidden TODOs in staged files`);
+      console.log('   💡 Fix stub implementations and placeholder code before committing');
+      console.log('   📖 See docs/PLACEHOLDER-DETECTION-GUIDE.md for classification');
+    } else {
+      console.log('   ✅ No critical hidden TODOs found in staged files');
+    }
+  }
+
+  // Summary
+  console.log('\n==================================================');
+  console.log('📊 QUALITY GATES RESULTS');
+  console.log('==================================================');
+
+  const totalViolations = results.violations.length;
+  const totalWarnings = results.warnings.length;
+  const totalTodos = results.todos;
+
+  if (totalViolations > 0) {
+    console.log(`\n❌ CRITICAL VIOLATIONS (${totalViolations}):`);
+    results.violations.forEach((violation) => {
+      console.log(`   ${violation.file}: ${violation.message}`);
+    });
+    results.passed = false;
+  }
+
+  if (totalWarnings > 0) {
+    console.log(`\n⚠️  WARNINGS (${totalWarnings}):`);
+    results.warnings.forEach((warning) => {
+      console.log(`   ${warning.file}: ${warning.message}`);
+    });
+  }
+
+  if (totalTodos > 0) {
+    console.log(`\n🔍 HIDDEN TODOS (${totalTodos}):`);
+    console.log(`   Found ${totalTodos} hidden TODOs in staged files`);
+    results.passed = false;
+  }
+
+  // Final result
+  if (results.passed) {
+    console.log('\n✅ ALL QUALITY GATES PASSED');
+    console.log('🎉 Commit allowed - quality maintained!');
+  } else {
+    console.log('\n❌ QUALITY GATES FAILED');
+    console.log('🚫 Commit blocked - fix violations above');
+  }
+
+  return results;
+}
+
+module.exports = {
+  getStagedFiles,
+  checkGodObjects,
+  checkHiddenTodos,
+  checkWaiver,
+  detectCrisisMode,
+  runQualityGates,
+  CONFIG,
+};

package/dist/utils/typescript-detector.js

@@ -101,10 +101,40 @@ function detectTestFramework(projectDir = process.cwd(), packageJson = null) {
 }
 
 /**
- * Get workspace directories from package.json
+ * Expand workspace glob patterns to actual directories
+ * Shared helper for npm, pnpm, and lerna workspace resolution
+ * @param {string[]} patterns - Workspace patterns (may include globs like "packages/*")
  * @param {string} projectDir - Project directory path
- * @returns {string[]} Array of workspace directories
+ * @returns {string[]} Array of resolved workspace directory paths
  */
+function expandWorkspacePatterns(patterns, projectDir) {
+  const workspaceDirs = [];
+  for (const pattern of patterns) {
+    if (pattern.includes('*')) {
+      const baseDir = pattern.split('*')[0];
+      const fullBaseDir = path.join(projectDir, baseDir);
+
+      if (fs.existsSync(fullBaseDir)) {
+        const entries = fs.readdirSync(fullBaseDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const wsPath = path.join(fullBaseDir, entry.name);
+            if (fs.existsSync(path.join(wsPath, 'package.json'))) {
+              workspaceDirs.push(wsPath);
+            }
+          }
+        }
+      }
+    } else {
+      const wsPath = path.join(projectDir, pattern);
+      if (fs.existsSync(path.join(wsPath, 'package.json'))) {
+        workspaceDirs.push(wsPath);
+      }
+    }
+  }
+  return workspaceDirs;
+}
+
 /**
  * Get workspace directories from npm/yarn package.json workspaces
  * @param {string} projectDir - Project directory path
@@ -120,36 +150,7 @@ function getNpmWorkspaces(projectDir) {
   try {
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
     const workspaces = packageJson.workspaces || [];
-
-    // Convert glob patterns to actual directories (simple implementation)
-    const workspaceDirs = [];
-    for (const ws of workspaces) {
-      // Handle simple patterns like "packages/*" or "iterations/*"
-      if (ws.includes('*')) {
-        const baseDir = ws.split('*')[0];
-        const fullBaseDir = path.join(projectDir, baseDir);
-
-        if (fs.existsSync(fullBaseDir)) {
-          const entries = fs.readdirSync(fullBaseDir, { withFileTypes: true });
-          for (const entry of entries) {
-            if (entry.isDirectory()) {
-              const wsPath = path.join(fullBaseDir, entry.name);
-              if (fs.existsSync(path.join(wsPath, 'package.json'))) {
-                workspaceDirs.push(wsPath);
-              }
-            }
-          }
-        }
-      } else {
-        // Direct path
-        const wsPath = path.join(projectDir, ws);
-        if (fs.existsSync(path.join(wsPath, 'package.json'))) {
-          workspaceDirs.push(wsPath);
-        }
-      }
-    }
-
-    return workspaceDirs;
+    return expandWorkspacePatterns(workspaces, projectDir);
   } catch (error) {
     return [];
   }
@@ -171,35 +172,7 @@ function getPnpmWorkspaces(projectDir) {
     const yaml = require('js-yaml');
     const config = yaml.load(fs.readFileSync(pnpmFile, 'utf8'));
     const workspacePatterns = config.packages || [];
-
-    // Convert glob patterns to actual directories
-    const workspaceDirs = [];
-    for (const pattern of workspacePatterns) {
-      if (pattern.includes('*')) {
-        const baseDir = pattern.split('*')[0];
-        const fullBaseDir = path.join(projectDir, baseDir);
-
-        if (fs.existsSync(fullBaseDir)) {
-          const entries = fs.readdirSync(fullBaseDir, { withFileTypes: true });
-          for (const entry of entries) {
-            if (entry.isDirectory()) {
-              const wsPath = path.join(fullBaseDir, entry.name);
-              if (fs.existsSync(path.join(wsPath, 'package.json'))) {
-                workspaceDirs.push(wsPath);
-              }
-            }
-          }
-        }
-      } else {
-        // Direct path
-        const wsPath = path.join(projectDir, pattern);
-        if (fs.existsSync(path.join(wsPath, 'package.json'))) {
-          workspaceDirs.push(wsPath);
-        }
-      }
-    }
-
-    return workspaceDirs;
+    return expandWorkspacePatterns(workspacePatterns, projectDir);
   } catch (error) {
     return [];
   }
@@ -220,35 +193,7 @@ function getLernaWorkspaces(projectDir) {
   try {
     const config = JSON.parse(fs.readFileSync(lernaFile, 'utf8'));
     const workspacePatterns = config.packages || ['packages/*'];
-
-    // Convert glob patterns to actual directories
-    const workspaceDirs = [];
-    for (const pattern of workspacePatterns) {
-      if (pattern.includes('*')) {
-        const baseDir = pattern.split('*')[0];
-        const fullBaseDir = path.join(projectDir, baseDir);
-
-        if (fs.existsSync(fullBaseDir)) {
-          const entries = fs.readdirSync(fullBaseDir, { withFileTypes: true });
-          for (const entry of entries) {
-            if (entry.isDirectory()) {
-              const wsPath = path.join(fullBaseDir, entry.name);
-              if (fs.existsSync(path.join(wsPath, 'package.json'))) {
-                workspaceDirs.push(wsPath);
-              }
-            }
-          }
-        }
-      } else {
-        // Direct path
-        const wsPath = path.join(projectDir, pattern);
-        if (fs.existsSync(path.join(wsPath, 'package.json'))) {
-          workspaceDirs.push(wsPath);
-        }
-      }
-    }
-
-    return workspaceDirs;
+    return expandWorkspacePatterns(workspacePatterns, projectDir);
   } catch (error) {
     return [];
   }
@@ -416,6 +361,7 @@ module.exports = {
   getNpmWorkspaces,
   getPnpmWorkspaces,
   getLernaWorkspaces,
+  expandWorkspacePatterns,
   checkHoistedDependency,
   checkTypeScriptTestConfig,
   generateRecommendations,

package/dist/validation/spec-validation.js

@@ -5,6 +5,59 @@
  */
 
 const { deriveBudget, checkBudgetCompliance } = require('../budget-derivation');
+const { execSync } = require('child_process');
+
+/**
+ * Get actual budget statistics from git history
+ * Analyzes changes since last tag or initial commit
+ * @param {string} specDir - Project directory
+ * @returns {Object|null} Budget stats or null on failure
+ */
+function getActualBudgetStats(specDir) {
+  const cwd = specDir || process.cwd();
+  try {
+    // Get base ref (last tag or initial commit)
+    let baseRef;
+    try {
+      baseRef = execSync('git describe --tags --abbrev=0 2>/dev/null', {
+        cwd,
+        encoding: 'utf8'
+      }).trim();
+    } catch {
+      // No tags found, use initial commit
+      baseRef = execSync('git rev-list --max-parents=0 HEAD', {
+        cwd,
+        encoding: 'utf8'
+      }).trim();
+    }
+
+    // Count files changed since base ref
+    const filesOutput = execSync(`git diff --name-only ${baseRef}..HEAD`, {
+      cwd,
+      encoding: 'utf8'
+    });
+    const files_changed = filesOutput.trim().split('\n').filter(Boolean).length;
+
+    // Count lines changed (added + removed)
+    const numstatOutput = execSync(`git diff --numstat ${baseRef}..HEAD`, {
+      cwd,
+      encoding: 'utf8'
+    });
+    let lines_changed = 0;
+    for (const line of numstatOutput.trim().split('\n').filter(Boolean)) {
+      const [added, removed] = line.split('\t');
+      // Handle binary files (shown as '-')
+      const addedNum = added === '-' ? 0 : parseInt(added, 10) || 0;
+      const removedNum = removed === '-' ? 0 : parseInt(removed, 10) || 0;
+      lines_changed += addedNum + removedNum;
+    }
+
+    return { files_changed, lines_changed };
+  } catch {
+    // Git not available or not a repository
+    return null;
+  }
+}
 
 /**
  * Basic validation of working spec
@@ -511,14 +564,14 @@ function validateWorkingSpecWithSuggestions(spec, options = {}) {
       try {
         const derivedBudget = deriveBudget(spec, projectRoot);
 
-        // Mock current stats for now - in real implementation this would analyze git changes
-        const mockStats = {
-          files_changed: 50, // This would be calculated from actual changes
-          lines_changed: 5000,
-          risk_tier: spec.risk_tier,
+        // Get actual stats from git history
+        const actualStats = getActualBudgetStats(projectRoot) || {
+          files_changed: 0,
+          lines_changed: 0,
         };
+        actualStats.risk_tier = spec.risk_tier;
 
-        budgetCheck = checkBudgetCompliance(derivedBudget, mockStats);
+        budgetCheck = checkBudgetCompliance(derivedBudget, actualStats);
 
         if (!budgetCheck.compliant) {
           for (const violation of budgetCheck.violations) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "8.0.1",
-  "description": "CAWS CLI - Coding Agent Workflow System command line tools",
+  "version": "8.1.0",
+  "description": "CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development",
   "main": "dist/index.js",
   "bin": {
     "caws": "dist/index.js"
@@ -33,7 +33,8 @@
     "format": "prettier --write src/**/*.js tests/**/*.js",
     "validate": "echo 'CLI package validation not required'",
     "caws:validate": "node ../../.caws/validate.js ../../.caws/working-spec.yaml",
-    "clean": "rm -rf dist test-caws-project .agent && npm run test:cleanup"
+    "clean": "rm -rf dist test-caws-project .agent && npm run test:cleanup",
+    "prepare": "husky"
   },
   "keywords": [
     "caws",
@@ -69,6 +70,7 @@
     "ajv": "8.17.1",
     "esbuild": "0.25.10",
     "eslint": "^9.0.0",
+    "husky": "9.1.7",
     "jest": "30.1.3",
     "js-yaml": "4.1.0",
     "lint-staged": "15.5.2",