specweave 0.23.2 → 0.23.4

package/dist/src/core/ac-test-validator.js

@@ -0,0 +1,292 @@
+/**
+ * AC Test Validator
+ *
+ * Validates that all Acceptance Criteria linked to a task have passing tests
+ * before allowing the task to be marked complete.
+ *
+ * **CRITICAL QUALITY GATE**: This is the enforcement point that prevents
+ * tasks from being marked complete without validated ACs.
+ *
+ * Workflow:
+ * 1. Task completion requested via TodoWrite
+ * 2. Validator extracts task's satisfiesACs field
+ * 3. Validator finds corresponding test files from Test Plan section
+ * 4. Validator runs tests using configured test runner (vitest/jest)
+ * 5. If ALL tests pass → Allow completion, auto-check ACs in spec.md
+ * 6. If ANY test fails → Block completion, show detailed error
+ */
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+const execAsync = promisify(exec);
+/**
+ * AC Test Validator - Core validation engine
+ */
+export class ACTestValidator {
+    constructor(config) {
+        this.config = {
+            timeout: 30000, // 30 second default timeout
+            ...config
+        };
+    }
+    /**
+     * Validate all ACs for a task have passing tests
+     *
+     * @param task - Task to validate (must have satisfiesACs field)
+     * @param projectRoot - Project root directory
+     * @returns Validation result
+     */
+    async validateTask(task, projectRoot) {
+        const startTime = Date.now();
+        // Initialize result
+        const result = {
+            passed: false,
+            taskId: task.id,
+            acIds: task.satisfiesACs || [],
+            testResults: new Map(),
+            summary: {
+                totalACs: 0,
+                acsTested: 0,
+                acsUntested: 0,
+                testsPassed: 0,
+                testsFailed: 0
+            },
+            errors: []
+        };
+        // Check if task has ACs to validate
+        if (!task.satisfiesACs || task.satisfiesACs.length === 0) {
+            result.errors.push(`Task ${task.id} has no Acceptance Criteria linked (satisfiesACs field missing or empty)`);
+            return result;
+        }
+        result.summary.totalACs = task.satisfiesACs.length;
+        // Extract test file from task's Test Plan section
+        const testFile = this.extractTestFile(task);
+        if (!testFile) {
+            result.errors.push(`Task ${task.id} has no Test Plan section or test file specified`);
+            return result;
+        }
+        // Check test file exists
+        const testFilePath = path.join(projectRoot, testFile);
+        if (!await fs.pathExists(testFilePath)) {
+            result.errors.push(`Test file not found: ${testFile}`);
+            return result;
+        }
+        // Run tests for each AC
+        for (const acId of task.satisfiesACs) {
+            const acTestResult = await this.validateAC(acId, testFile, projectRoot);
+            result.testResults.set(acId, acTestResult);
+            if (acTestResult.passed) {
+                result.summary.acsTested++;
+                result.summary.testsPassed++;
+            }
+            else {
+                result.summary.acsUntested++;
+                result.summary.testsFailed++;
+                result.errors.push(`AC ${acId} tests failed: ${acTestResult.error || 'Unknown error'}`);
+            }
+        }
+        // Overall pass/fail
+        result.passed = result.summary.testsFailed === 0 && result.summary.acsTested === result.summary.totalACs;
+        const duration = Date.now() - startTime;
+        console.log(`\n${chalk.blue('[AC Test Validator]')} Validated task ${task.id} in ${duration}ms`);
+        return result;
+    }
+    /**
+     * Validate a single AC has passing tests
+     */
+    async validateAC(acId, testFile, projectRoot) {
+        const startTime = Date.now();
+        const result = {
+            acId,
+            testFile,
+            testCases: [],
+            passed: false,
+            duration: 0
+        };
+        try {
+            // Run test file with filter for AC-ID
+            // Most test runners support filtering: vitest -t "AC-US1-01", jest --testNamePattern="AC-US1-01"
+            const command = this.buildTestCommand(testFile, acId);
+            console.log(`  ${chalk.gray('Running:')} ${command}`);
+            const { stdout, stderr } = await execAsync(command, {
+                cwd: this.config.cwd,
+                env: { ...process.env, ...this.config.env },
+                timeout: this.config.timeout
+            });
+            // Parse test output (basic implementation - can be enhanced)
+            const output = stdout + stderr;
+            result.testCases = this.extractTestCases(output, acId);
+            // Check for test failures
+            const hasFailures = output.includes('FAIL') ||
+                output.includes('failed') ||
+                output.includes('✗') ||
+                output.includes('0 passed');
+            result.passed = !hasFailures && result.testCases.length > 0;
+            if (!result.passed) {
+                result.error = this.extractFailureMessage(output);
+            }
+        }
+        catch (error) {
+            result.passed = false;
+            result.error = error.message || 'Test execution failed';
+            // Check if it's a timeout
+            if (error.killed && error.signal === 'SIGTERM') {
+                result.error = `Test timeout (exceeded ${this.config.timeout}ms)`;
+            }
+        }
+        result.duration = Date.now() - startTime;
+        return result;
+    }
+    /**
+     * Build test command with AC-ID filter
+     */
+    buildTestCommand(testFile, acId) {
+        // Detect test runner from config command
+        const command = this.config.command.toLowerCase();
+        if (command.includes('vitest')) {
+            // Vitest: vitest run <file> -t "AC-US1-01"
+            return `${this.config.command} ${testFile} -t "${acId}"`;
+        }
+        else if (command.includes('jest')) {
+            // Jest: jest <file> --testNamePattern="AC-US1-01"
+            return `${this.config.command} ${testFile} --testNamePattern="${acId}"`;
+        }
+        else if (command.includes('npm test')) {
+            // NPM script - try to pass args
+            return `${this.config.command} -- ${testFile} -t "${acId}"`;
+        }
+        else {
+            // Default: assume vitest-style
+            return `${this.config.command} ${testFile} -t "${acId}"`;
+        }
+    }
+    /**
+     * Extract test case names from test output
+     */
+    extractTestCases(output, acId) {
+        const testCases = [];
+        // Look for lines containing the AC-ID and test indicators
+        const lines = output.split('\n');
+        for (const line of lines) {
+            if (line.includes(acId) && (line.includes('✓') || line.includes('PASS') || line.includes('√'))) {
+                // Extract test name (basic heuristic)
+                const match = line.match(/✓\s+(.+)/) || line.match(/PASS\s+(.+)/);
+                if (match) {
+                    testCases.push(match[1].trim());
+                }
+            }
+        }
+        return testCases;
+    }
+    /**
+     * Extract failure message from test output
+     */
+    extractFailureMessage(output) {
+        const lines = output.split('\n');
+        // Find first error/failure message
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.includes('FAIL') || line.includes('✗') || line.includes('Error:')) {
+                // Collect next few lines for context
+                const errorLines = lines.slice(i, i + 5).join('\n');
+                return errorLines.substring(0, 200); // Truncate long messages
+            }
+        }
+        // Fallback: return last few lines
+        return lines.slice(-5).join('\n');
+    }
+    /**
+     * Extract test file path from task description (Test Plan section)
+     */
+    extractTestFile(task) {
+        if (!task.description)
+            return null;
+        // Look for Test Plan section with file path
+        // Format: **Test Plan**:
+        //         - **File**: `tests/unit/component.test.ts`
+        const testFileRegex = /\*\*File\*\*:\s*`([^`]+)`/;
+        const match = task.description.match(testFileRegex);
+        return match ? match[1] : null;
+    }
+    /**
+     * Format validation result for display
+     */
+    formatResult(result) {
+        const lines = [];
+        lines.push(chalk.bold(`\nAC Test Validation: ${result.taskId}`));
+        lines.push(chalk.gray('─'.repeat(60)));
+        // Summary
+        lines.push(chalk.bold('Summary:'));
+        lines.push(`  Total ACs: ${result.summary.totalACs}`);
+        lines.push(`  ACs Tested: ${chalk.green(result.summary.acsTested)}`);
+        lines.push(`  ACs Untested: ${chalk.red(result.summary.acsUntested)}`);
+        lines.push(`  Tests Passed: ${chalk.green(result.summary.testsPassed)}`);
+        lines.push(`  Tests Failed: ${chalk.red(result.summary.testsFailed)}`);
+        // Overall status
+        lines.push('');
+        if (result.passed) {
+            lines.push(chalk.green.bold('✓ VALIDATION PASSED'));
+            lines.push(chalk.green('All Acceptance Criteria have passing tests. Task can be marked complete.'));
+        }
+        else {
+            lines.push(chalk.red.bold('✗ VALIDATION FAILED'));
+            lines.push(chalk.red('Task cannot be marked complete until all AC tests pass.'));
+        }
+        // Errors
+        if (result.errors.length > 0) {
+            lines.push('');
+            lines.push(chalk.bold('Errors:'));
+            result.errors.forEach(error => {
+                lines.push(chalk.red(`  • ${error}`));
+            });
+        }
+        // Test details
+        if (result.testResults.size > 0) {
+            lines.push('');
+            lines.push(chalk.bold('Test Results:'));
+            result.testResults.forEach((acResult, acId) => {
+                const icon = acResult.passed ? chalk.green('✓') : chalk.red('✗');
+                const status = acResult.passed ? chalk.green('PASSED') : chalk.red('FAILED');
+                lines.push(`  ${icon} ${acId}: ${status} (${acResult.duration}ms)`);
+                if (acResult.testCases.length > 0) {
+                    acResult.testCases.forEach(testCase => {
+                        lines.push(chalk.gray(`    - ${testCase}`));
+                    });
+                }
+                if (acResult.error) {
+                    lines.push(chalk.red(`    Error: ${acResult.error}`));
+                }
+            });
+        }
+        lines.push(chalk.gray('─'.repeat(60)));
+        return lines.join('\n');
+    }
+}
+/**
+ * Create AC test validator from project config
+ */
+export async function createACTestValidator(projectRoot) {
+    // Read test configuration from package.json or specweave config
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    let testCommand = 'npm test';
+    if (await fs.pathExists(packageJsonPath)) {
+        const packageJson = await fs.readJson(packageJsonPath);
+        // Detect test runner
+        if (packageJson.devDependencies?.vitest || packageJson.dependencies?.vitest) {
+            testCommand = 'npx vitest run';
+        }
+        else if (packageJson.devDependencies?.jest || packageJson.dependencies?.jest) {
+            testCommand = 'npx jest';
+        }
+    }
+    const config = {
+        command: testCommand,
+        pattern: 'tests/**/*.test.ts',
+        cwd: projectRoot,
+        timeout: 30000
+    };
+    return new ACTestValidator(config);
+}
+//# sourceMappingURL=ac-test-validator.js.map

package/dist/src/core/ac-test-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ac-test-validator.js","sourceRoot":"","sources":["../../../src/core/ac-test-validator.ts"],"names":[],"mappings":"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"}

package/dist/src/core/increment/desync-detector.d.ts

@@ -0,0 +1,142 @@
+/**
+ * DesyncDetector - Detect and fix status desyncs between metadata.json and spec.md
+ *
+ * Prevents silent failures by validating source-of-truth consistency.
+ * Critical for maintaining data integrity across increment lifecycle.
+ *
+ * Incident Reference: 2025-11-20 - Silent failure in /specweave:done caused
+ * increment 0047 to have metadata.json="completed" while spec.md="active",
+ * breaking status line and user trust.
+ *
+ * CLAUDE.md Rule #7: spec.md and metadata.json are BOTH source of truth and MUST stay in sync.
+ */
+import { IncrementStatus } from '../types/increment-metadata.js';
+import { Logger } from '../../utils/logger.js';
+/**
+ * Desync detection result for a single increment
+ */
+export interface DesyncResult {
+    incrementId: string;
+    hasDesync: boolean;
+    metadataStatus: IncrementStatus | null;
+    specStatus: IncrementStatus | null;
+    metadataPath: string;
+    specPath: string;
+    error?: string;
+}
+/**
+ * Desync scan report for multiple increments
+ */
+export interface DesyncScanReport {
+    totalScanned: number;
+    totalDesyncs: number;
+    desyncs: DesyncResult[];
+    healthy: string[];
+    errors: string[];
+}
+/**
+ * Options for desync detection
+ */
+export interface DesyncDetectorOptions {
+    logger?: Logger;
+    projectRoot?: string;
+    autoFix?: boolean;
+}
+/**
+ * DesyncDetector - Validates status consistency between metadata.json and spec.md
+ *
+ * Key Features:
+ * - Detects status desyncs across all increments
+ * - Provides detailed desync reports
+ * - Auto-fix capability (optional)
+ * - Validates before critical operations
+ *
+ * Usage:
+ * ```typescript
+ * // Check single increment
+ * const detector = new DesyncDetector();
+ * const result = await detector.checkIncrement('0047-us-task-linkage');
+ * if (result.hasDesync) {
+ *   console.error('Desync detected!', result);
+ * }
+ *
+ * // Scan all increments
+ * const report = await detector.scanAll();
+ * console.log(`Found ${report.totalDesyncs} desyncs`);
+ * ```
+ */
+export declare class DesyncDetector {
+    private logger;
+    private projectRoot;
+    constructor(options?: DesyncDetectorOptions);
+    /**
+     * Check single increment for status desync
+     *
+     * @param incrementId - Increment ID (e.g., "0047-us-task-linkage")
+     * @returns Desync result with detailed status info
+     *
+     * @example
+     * ```typescript
+     * const result = await detector.checkIncrement('0047-us-task-linkage');
+     * if (result.hasDesync) {
+     *   console.error(`Desync: metadata=${result.metadataStatus}, spec=${result.specStatus}`);
+     * }
+     * ```
+     */
+    checkIncrement(incrementId: string): Promise<DesyncResult>;
+    /**
+     * Scan all increments for desyncs
+     *
+     * @returns Comprehensive scan report
+     *
+     * @example
+     * ```typescript
+     * const report = await detector.scanAll();
+     * console.log(`Scanned ${report.totalScanned} increments`);
+     * console.log(`Found ${report.totalDesyncs} desyncs`);
+     * report.desyncs.forEach(d => console.error(`- ${d.incrementId}`));
+     * ```
+     */
+    scanAll(): Promise<DesyncScanReport>;
+    /**
+     * Fix desync by updating spec.md to match metadata.json (source of truth for status)
+     *
+     * IMPORTANT: metadata.json is considered the source of truth because it's updated
+     * atomically and used by the CLI. spec.md should mirror it.
+     *
+     * @param incrementId - Increment ID to fix
+     * @returns true if fixed successfully, false if no desync or fix failed
+     *
+     * @example
+     * ```typescript
+     * const fixed = await detector.fixDesync('0047-us-task-linkage');
+     * if (fixed) {
+     *   console.log('Desync fixed!');
+     * }
+     * ```
+     */
+    fixDesync(incrementId: string): Promise<boolean>;
+    /**
+     * Validate increment has no desync, throw if found
+     *
+     * Use this before critical operations (e.g., closing increment, archiving)
+     *
+     * @param incrementId - Increment ID to validate
+     * @throws Error if desync detected
+     *
+     * @example
+     * ```typescript
+     * await detector.validateOrThrow('0047-us-task-linkage');
+     * // Throws if desync found, continues if healthy
+     * ```
+     */
+    validateOrThrow(incrementId: string): Promise<void>;
+    /**
+     * Generate human-readable report for desyncs
+     *
+     * @param report - Scan report
+     * @returns Formatted report string
+     */
+    formatReport(report: DesyncScanReport): string;
+}
+//# sourceMappingURL=desync-detector.d.ts.map

package/dist/src/core/increment/desync-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desync-detector.d.ts","sourceRoot":"","sources":["../../../../src/core/increment/desync-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,GAAE,qBAA0B;IAK/C;;;;;;;;;;;;;OAaG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA4DhE;;;;;;;;;;;;OAYG;IACG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAwC1C;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyCtD;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzD;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM;CAoD/C"}