@paths.design/caws-cli 10.2.0 → 11.0.0

package/dist/commands/evaluate.js

@@ -1,314 +0,0 @@
-/**
- * CAWS Evaluate Command
- *
- * Evaluates work against CAWS quality standards and provides
- * actionable feedback on meeting acceptance criteria.
- *
- * @author @darianrosebrook
- */
-
-const path = require('path');
-const chalk = require('chalk');
-const { initializeGlobalSetup } = require('../config');
-const { resolveSpec } = require('../utils/spec-resolver');
-const { recordEvaluation } = require('../utils/working-state');
-const { appendEvent } = require('../utils/event-log');
-
-/**
- * Evaluate command handler
- *
- * @param {string} specFile - Path to working spec file
- * @param {object} options - Command options
- */
-async function evaluateCommand(specFile, options = {}) {
-  try {
-    console.log('Detecting CAWS setup...');
-    const setup = initializeGlobalSetup();
-
-    if (setup.hasWorkingSpec) {
-      console.log(`Detected ${setup.type} CAWS setup`);
-      console.log(`   Capabilities: ${setup.capabilities.join(', ')}`);
-    }
-
-    const resolved = await resolveSpec({
-      specId: options.specId,
-      specFile: specFile || undefined,
-      warnLegacy: false,
-      interactive: false,
-    });
-    const specPath = resolved.path;
-    const spec = resolved.spec;
-
-    console.log(chalk.blue('\nEvaluating CAWS Quality Standards\n'));
-    console.log('-'.repeat(60));
-    console.log(chalk.gray(`Spec: ${path.relative(process.cwd(), specPath)}`));
-    console.log(chalk.gray(`Type: ${resolved.type}`));
-
-    // Evaluation results
-    const results = {
-      score: 0,
-      maxScore: 0,
-      checks: [],
-      recommendations: [],
-      warnings: [],
-    };
-
-    // 1. Check working spec validity
-    results.maxScore += 10;
-    if (spec.id && spec.title && spec.risk_tier && spec.mode) {
-      results.score += 10;
-      results.checks.push({ name: 'Working Spec Structure', status: 'pass', points: 10 });
-    } else {
-      results.checks.push({ name: 'Working Spec Structure', status: 'fail', points: 0 });
-      results.warnings.push('Working spec missing required fields');
-    }
-
-    // 2. Check acceptance criteria
-    results.maxScore += 15;
-    if (spec.acceptance && spec.acceptance.length > 0) {
-      const validCriteria = spec.acceptance.filter((a) => a.id && a.given && a.when && a.then);
-      const criteriaScore = Math.floor((validCriteria.length / spec.acceptance.length) * 15);
-      results.score += criteriaScore;
-      results.checks.push({
-        name: 'Acceptance Criteria',
-        status: criteriaScore === 15 ? 'pass' : 'partial',
-        points: criteriaScore,
-        detail: `${validCriteria.length}/${spec.acceptance.length} complete`,
-      });
-
-      if (criteriaScore < 15) {
-        results.recommendations.push(
-          'Complete all acceptance criteria with Given-When-Then format'
-        );
-      }
-    } else {
-      results.checks.push({ name: 'Acceptance Criteria', status: 'fail', points: 0 });
-      results.warnings.push('No acceptance criteria defined');
-    }
-
-    // 3. Check scope definition
-    results.maxScore += 10;
-    if (spec.scope && spec.scope.in && spec.scope.in.length > 0) {
-      results.score += 10;
-      results.checks.push({ name: 'Scope Definition', status: 'pass', points: 10 });
-    } else {
-      results.checks.push({ name: 'Scope Definition', status: 'fail', points: 0 });
-      results.warnings.push('Scope not clearly defined');
-    }
-
-    // 4. Check change budget
-    results.maxScore += 10;
-    if (spec.change_budget && spec.change_budget.max_files && spec.change_budget.max_loc) {
-      results.score += 10;
-      results.checks.push({ name: 'Change Budget', status: 'pass', points: 10 });
-    } else {
-      results.checks.push({ name: 'Change Budget', status: 'fail', points: 0 });
-      results.recommendations.push('Define change budget (max_files, max_loc)');
-    }
-
-    // 5. Check invariants
-    results.maxScore += 10;
-    if (spec.invariants && spec.invariants.length > 0) {
-      results.score += 10;
-      results.checks.push({ name: 'System Invariants', status: 'pass', points: 10 });
-    } else {
-      results.checks.push({ name: 'System Invariants', status: 'partial', points: 5 });
-      results.recommendations.push('Define system invariants to maintain');
-    }
-
-    // 6. Check non-functional requirements
-    results.maxScore += 15;
-    let nfrScore = 0;
-    if (spec.non_functional) {
-      if (spec.non_functional.a11y && spec.non_functional.a11y.length > 0) nfrScore += 5;
-      if (spec.non_functional.perf && spec.non_functional.perf.api_p95_ms) nfrScore += 5;
-      if (spec.non_functional.security && spec.non_functional.security.length > 0) nfrScore += 5;
-    }
-    results.score += nfrScore;
-    results.checks.push({
-      name: 'Non-Functional Requirements',
-      status: nfrScore === 15 ? 'pass' : 'partial',
-      points: nfrScore,
-    });
-
-    if (nfrScore < 15) {
-      results.recommendations.push('Define a11y, performance, and security requirements');
-    }
-
-    // 7. Check rollback plan
-    results.maxScore += 10;
-    if (spec.rollback && spec.rollback.length > 0) {
-      results.score += 10;
-      results.checks.push({ name: 'Rollback Plan', status: 'pass', points: 10 });
-    } else {
-      results.checks.push({ name: 'Rollback Plan', status: 'fail', points: 0 });
-      results.recommendations.push('Document rollback procedures');
-    }
-
-    // 8. Check observability
-    results.maxScore += 10;
-    if (
-      spec.observability &&
-      (spec.observability.logs?.length > 0 ||
-        spec.observability.metrics?.length > 0 ||
-        spec.observability.traces?.length > 0)
-    ) {
-      results.score += 10;
-      results.checks.push({ name: 'Observability', status: 'pass', points: 10 });
-    } else {
-      results.checks.push({ name: 'Observability', status: 'partial', points: 3 });
-      results.recommendations.push('Define logging, metrics, and tracing strategy');
-    }
-
-    // 9. Risk tier appropriateness
-    results.maxScore += 10;
-    const hasCriticalScope = spec.blast_radius?.modules?.some(
-      (m) => m.includes('auth') || m.includes('payment') || m.includes('billing')
-    );
-    const hasDataMigration = spec.blast_radius?.data_migration === true;
-
-    if (hasCriticalScope || hasDataMigration) {
-      if (spec.risk_tier === 1) {
-        results.score += 10;
-        results.checks.push({ name: 'Risk Tier Appropriateness', status: 'pass', points: 10 });
-      } else {
-        results.checks.push({ name: 'Risk Tier Appropriateness', status: 'fail', points: 0 });
-        results.warnings.push(`Risk tier ${spec.risk_tier} may be too low for critical changes`);
-      }
-    } else {
-      results.score += 10;
-      results.checks.push({ name: 'Risk Tier Appropriateness', status: 'pass', points: 10 });
-    }
-
-    // Display results
-    console.log('\nQuality Checks:\n');
-    results.checks.forEach((check) => {
-      const icon = check.status === 'pass' ? '' : check.status === 'partial' ? '' : '';
-      const detail = check.detail ? ` (${check.detail})` : '';
-      console.log(
-        `${icon} ${check.name}: ${check.points}/${results.maxScore / results.checks.length}${detail}`
-      );
-    });
-
-    // Calculate percentage
-    const percentage = Math.round((results.score / results.maxScore) * 100);
-    const grade =
-      percentage >= 90
-        ? 'A'
-        : percentage >= 80
-          ? 'B'
-          : percentage >= 70
-            ? 'C'
-            : percentage >= 60
-              ? 'D'
-              : 'F';
-
-    // Record to working state (Phase 1 dual-write: state layer + event log)
-    const checksPassed = results.checks.filter(c => c.status === 'pass').length;
-    const evaluationPayload = {
-      score: results.score,
-      max_score: results.maxScore,
-      percentage,
-      grade,
-      checks_passed: checksPassed,
-      checks_total: results.checks.length,
-    };
-    // CAWSFIX-02: guard recordEvaluation with `spec && spec.id` check to
-    // prevent the .caws/state/undefined.json bug class. Matches the pattern
-    // gates.js already uses and the appendEvent call below.
-    if (spec && spec.id) {
-      try {
-        recordEvaluation(spec.id, evaluationPayload);
-      } catch { /* non-fatal */ }
-    }
-
-    // EVLOG-001: emit evaluation_completed event alongside state write.
-    if (spec && spec.id) {
-      await appendEvent(
-        { actor: 'cli', event: 'evaluation_completed', spec_id: spec.id, data: evaluationPayload }
-      );
-    }
-
-    console.log('\n' + '-'.repeat(60));
-    console.log(
-      chalk.bold(
-        `\nOverall Score: ${results.score}/${results.maxScore} (${percentage}%) - Grade: ${grade}\n`
-      )
-    );
-
-    // Display warnings
-    if (results.warnings.length > 0) {
-      console.log(chalk.yellow('Warnings:\n'));
-      results.warnings.forEach((warning) => {
-        console.log(chalk.yellow(`   - ${warning}`));
-      });
-      console.log();
-    }
-
-    // Display recommendations
-    if (results.recommendations.length > 0) {
-      console.log(chalk.blue('Recommendations:\n'));
-      results.recommendations.forEach((rec) => {
-        console.log(chalk.blue(`   - ${rec}`));
-      });
-      console.log();
-    }
-
-    // Risk tier specific guidance
-    console.log(chalk.bold(`\nRisk Tier ${spec.risk_tier} Requirements:\n`));
-
-    const tierRequirements = {
-      1: {
-        coverage: '90%+',
-        mutation: '70%+',
-        contracts: 'Required',
-        review: 'Manual code review required',
-      },
-      2: {
-        coverage: '80%+',
-        mutation: '50%+',
-        contracts: 'Required for external APIs',
-        review: 'Optional',
-      },
-      3: {
-        coverage: '70%+',
-        mutation: '30%+',
-        contracts: 'Optional',
-        review: 'Optional',
-      },
-    };
-
-    const req = tierRequirements[spec.risk_tier] || tierRequirements[2];
-    console.log(`   Branch Coverage: ${req.coverage}`);
-    console.log(`   Mutation Score: ${req.mutation}`);
-    console.log(`   Contract Tests: ${req.contracts}`);
-    console.log(`   Code Review: ${req.review}`);
-
-    console.log(chalk.blue('\nNext Steps:\n'));
-    console.log('   1. Address warnings and recommendations above');
-    console.log('   2. Implement acceptance criteria with tests');
-    console.log('   3. Run: caws validate to check spec validity');
-    console.log('   4. Run: caws diagnose for health checks');
-    console.log('   5. Ensure test coverage meets risk tier requirements');
-
-    // Exit with appropriate code
-    if (percentage < 70) {
-      console.log(
-        chalk.red('\nQuality score below 70% - improvements needed before proceeding\n')
-      );
-      process.exit(1);
-    } else if (percentage < 90) {
-      console.log(chalk.yellow('\nQuality score acceptable but improvements recommended\n'));
-    } else {
-      console.log(chalk.green('\nExcellent quality score - ready to proceed!\n'));
-    }
-  } catch (error) {
-    console.error(chalk.red(`\nEvaluation failed: ${error.message}`));
-    if (options.verbose) {
-      console.error(error.stack);
-    }
-    process.exit(1);
-  }
-}
-
-module.exports = { evaluateCommand };

package/dist/commands/gates.js

@@ -1,149 +0,0 @@
-/**
- * @fileoverview Unified quality gates CLI command
- * Delegates to the v2 gate pipeline (src/gates/pipeline.js) for evaluation
- * and formatting (src/gates/format.js) for output.
- * @author @darianrosebrook
- */
-
-const { evaluateGates } = require('../gates/pipeline');
-const { formatText, formatJson, formatEnrichedText } = require('../gates/format');
-const { enrichGateResults } = require('../gates/feedback');
-const { resolveSpec } = require('../utils/spec-resolver');
-const { commandWrapper } = require('../utils/command-wrapper');
-// EVLOG-002 Phase 2 read flip: gates still writes via recordGates (state layer)
-// AND emits a gates_evaluated event (from Phase 1), but the feedback-enrichment
-// READ at line ~116 now goes through the event log renderer instead of loadState.
-// The write path is deliberately unchanged in Phase 2 — only reads flip.
-const { recordGates } = require('../utils/working-state');
-const { loadStateFromEvents } = require('../utils/event-renderer');
-const { appendEvent } = require('../utils/event-log');
-
-/**
- * Run quality gates via the v2 pipeline
- * @param {Object} options - Command options
- * @param {string} [options.context] - Execution context (cli, commit, edit)
- * @param {string} [options.specId] - Target spec ID
- * @param {string} [options.specFile] - Explicit spec file path
- * @param {string} [options.file] - Single file to check (for edit context)
- * @param {boolean} [options.json] - Output as JSON
- * @param {string} [options.format] - Output format (text, json)
- * @param {boolean} [options.quiet] - Minimal output
- */
-async function gatesCommand(options = {}) {
-  return commandWrapper(
-    async () => {
-      const projectRoot = process.cwd();
-      const context = options.context || 'cli';
-
-      // Resolve spec (working-spec or feature spec)
-      let spec = null;
-      try {
-        const resolved = await resolveSpec({
-          specId: options.specId,
-          specFile: options.specFile,
-          warnLegacy: false,
-          interactive: false,
-        });
-        spec = resolved.spec;
-      } catch {
-        // No spec available — gates that need it will handle gracefully
-      }
-
-      // Get file list based on context
-      let stagedFiles = [];
-      const { execSync } = require('child_process');
-      if (context === 'commit') {
-        try {
-          stagedFiles = execSync('git diff --cached --name-only', {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-          })
-            .trim()
-            .split('\n')
-            .filter(Boolean);
-        } catch {
-          /* no staged files */
-        }
-      } else if (options.file) {
-        stagedFiles = [options.file];
-      } else if (context === 'cli') {
-        // For CLI context, use all tracked files so gates can provide meaningful analysis
-        try {
-          stagedFiles = execSync('git ls-files', {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            maxBuffer: 10 * 1024 * 1024,
-            stdio: ['ignore', 'pipe', 'pipe'],
-          })
-            .trim()
-            .split('\n')
-            .filter(Boolean);
-        } catch {
-          /* not a git repo or git unavailable */
-        }
-      }
-
-      const report = await evaluateGates({ projectRoot, stagedFiles, spec, context });
-
-      // Record to working state (Phase 1 dual-write: state layer + event log)
-      if (spec && spec.id) {
-        try { recordGates(spec.id, report, context, projectRoot); } catch { /* non-fatal */ }
-
-        // EVLOG-001: emit gates_evaluated event alongside state write.
-        // Payload shape mirrors the `gates` field produced by recordGates.
-        await appendEvent(
-          {
-            actor: 'cli',
-            event: 'gates_evaluated',
-            spec_id: spec.id,
-            data: {
-              context,
-              passed: report.passed,
-              summary: report.summary || {},
-              gates: (report.gates || []).map((g) => ({
-                name: g.name,
-                status: g.status,
-                mode: g.mode,
-              })),
-            },
-          },
-          { projectRoot }
-        );
-      }
-
-      if (options.json || options.format === 'json') {
-        console.log(formatJson(report));
-      } else if (!options.quiet) {
-        // Enrich feedback on failure or --verbose (EVLOG-002: from event log)
-        if (!report.passed || options.verbose) {
-          try {
-            const state = spec?.id ? loadStateFromEvents(spec.id, { projectRoot }) : null;
-            const enrichments = enrichGateResults(report, { spec, state, projectRoot });
-            if (enrichments.size > 0) {
-              console.log(formatEnrichedText(report, enrichments));
-            } else {
-              console.log(formatText(report));
-            }
-          } catch {
-            console.log(formatText(report));
-          }
-        } else {
-          console.log(formatText(report));
-        }
-      }
-
-      // Exit with appropriate code
-      if (!report.passed) {
-        process.exit(1);
-      }
-    },
-    {
-      commandName: 'gates',
-      context: { options },
-      exitOnError: true,
-    }
-  );
-}
-
-module.exports = { gatesCommand };