@zhuan-ai/zhuanspec 2.10.0 → 2.11.2

package/dist/core/hooks/tdd-phase-hook.js

@@ -0,0 +1,313 @@
+/**
+ * PostToolUse Hook - TDD Phase Tracking
+ *
+ * This hook tracks TDD workflow compliance for tasks annotated with @test-case:
+ * 1. Tracks file creation order (test files should precede implementation files)
+ * 2. Detects test execution results (RED → GREEN → REFACTOR phases)
+ * 3. Updates metrics/tdd-phases.json with current TDD status
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { atomicWriteJson } from './record-progress.js';
+// ---------------------------------------------------------------------------
+// Test-file detection patterns
+// ---------------------------------------------------------------------------
+/** Common test-file naming patterns across languages */
+const TEST_FILE_PATTERNS = [
+    /Test\.java$/, // Java – JUnit / TestNG
+    /Tests?\.cs$/, // C# – xUnit / NUnit
+    /\.test\.[jt]sx?$/, // JS/TS – Jest / Vitest
+    /\.spec\.[jt]sx?$/, // JS/TS – Jasmine / Mocha / Vitest
+    /_test\.go$/, // Go
+    /_test\.py$/, // Python – pytest
+    /test_.*\.py$/, // Python – unittest
+    /Spec\.(?:scala|kt)$/, // Scala / Kotlin – ScalaTest / Kotest
+];
+// ---------------------------------------------------------------------------
+// Test-result detection patterns (for Bash output)
+// ---------------------------------------------------------------------------
+const TEST_FAILURE_PATTERNS = [
+    /FAIL(?:ED|URE)?/i,
+    /Tests?\s+failed/i,
+    /BUILD FAILURE/i,
+    /AssertionError/i,
+    /AssertError/i,
+    /FAILURES!/,
+    /failures:\s*[1-9]/i,
+    /errors:\s*[1-9]/i,
+    /TEST.*FAIL/i,
+];
+const TEST_SUCCESS_PATTERNS = [
+    /PASS(?:ED)?/i,
+    /Tests?\s+passed/i,
+    /BUILD SUCCESS/i,
+    /All tests passed/i,
+    /Tests:\s+\d+ passed,\s+\d+ total/i,
+    /OK \(\d+ tests?\)/i,
+    /\d+ passing/i,
+    /failures:\s*0.*errors:\s*0/i,
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Return the path to the TDD phases JSON inside a change directory.
+ */
+function tddPhasesPath(changePath) {
+    return path.join(changePath, 'metrics', 'tdd-phases.json');
+}
+/**
+ * Determine whether a file path looks like a test file.
+ */
+export function isTestFile(filePath) {
+    const basename = path.basename(filePath);
+    return TEST_FILE_PATTERNS.some((pattern) => pattern.test(basename));
+}
+/**
+ * Load the persisted TDD status for a given task.
+ * Returns `null` when no status has been recorded yet.
+ */
+export async function loadTddStatus(changePath, taskId) {
+    const jsonPath = tddPhasesPath(changePath);
+    if (!(await FileSystemUtils.fileExists(jsonPath))) {
+        return null;
+    }
+    try {
+        const content = await FileSystemUtils.readFile(jsonPath);
+        const data = JSON.parse(content);
+        return data.tasks?.[taskId] ?? null;
+    }
+    catch {
+        // Corrupted or unreadable – treat as absent
+        return null;
+    }
+}
+/**
+ * Persist the TDD status for a task into `metrics/tdd-phases.json`.
+ * Creates the file (and parent directories) when they do not exist.
+ */
+export async function saveTddStatus(changePath, taskId, status) {
+    const jsonPath = tddPhasesPath(changePath);
+    let data = { tasks: {}, lastUpdated: '' };
+    if (await FileSystemUtils.fileExists(jsonPath)) {
+        try {
+            const content = await FileSystemUtils.readFile(jsonPath);
+            data = JSON.parse(content);
+        }
+        catch {
+            // Start fresh when the file is corrupted
+        }
+    }
+    data.tasks[taskId] = status;
+    data.lastUpdated = new Date().toISOString();
+    // Ensure the metrics directory exists
+    const metricsDir = path.dirname(jsonPath);
+    await FileSystemUtils.createDirectory(metricsDir);
+    await atomicWriteJson(jsonPath, data);
+}
+/**
+ * Detect whether a Bash tool invocation contains test-execution output
+ * and whether the tests passed or failed.
+ *
+ * Returns `'pass'`, `'fail'`, or `null` (when unable to determine).
+ */
+function detectTestResult(toolOutput) {
+    if (!toolOutput)
+        return null;
+    const hasFail = TEST_FAILURE_PATTERNS.some((p) => p.test(toolOutput));
+    const hasPass = TEST_SUCCESS_PATTERNS.some((p) => p.test(toolOutput));
+    // Failure takes precedence when both signals are present (e.g. "1 passed, 1 failed")
+    if (hasFail)
+        return 'fail';
+    if (hasPass)
+        return 'pass';
+    return null;
+}
+/**
+ * Determine TDD phase transition based on the current status and latest event.
+ *
+ * Transition rules:
+ *   PENDING  → RED        when a test file is created
+ *   RED      → GREEN      when tests pass after initial failure is recorded
+ *   GREEN    → REFACTOR   when an implementation file is modified / created after tests pass
+ *   REFACTOR → DONE       when tests still pass after refactoring
+ */
+export function detectTddPhaseTransition(currentStatus, toolName, filePath, toolOutput) {
+    const status = { ...currentStatus, updatedAt: new Date().toISOString() };
+    const fileIsTest = isTestFile(filePath);
+    // Track file creation
+    if (fileIsTest) {
+        status.testFileCreated = true;
+    }
+    else if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+        status.implFileCreated = true;
+    }
+    // Detect test execution results (only relevant when toolName is Bash)
+    if (toolName === 'Bash') {
+        const result = detectTestResult(toolOutput);
+        switch (status.tddPhase) {
+            case 'PENDING':
+                // If tests are already running and they fail → move to RED
+                if (result === 'fail') {
+                    status.testInitiallyFailed = true;
+                    status.tddPhase = 'RED';
+                }
+                // If a test file was just created, also transition to RED
+                if (status.testFileCreated && status.tddPhase === 'PENDING') {
+                    status.tddPhase = 'RED';
+                }
+                break;
+            case 'RED':
+                if (result === 'fail') {
+                    status.testInitiallyFailed = true;
+                }
+                if (result === 'pass' && status.testInitiallyFailed) {
+                    status.testFinallyPassed = true;
+                    status.tddPhase = 'GREEN';
+                }
+                break;
+            case 'GREEN':
+                // After GREEN, any passing test run during refactor moves to REFACTOR
+                if (result === 'pass') {
+                    status.tddPhase = 'REFACTOR';
+                }
+                break;
+            case 'REFACTOR':
+                // Stays in REFACTOR; transition to DONE is handled externally
+                // when the task is marked complete.
+                if (result === 'pass') {
+                    status.tddPhase = 'DONE';
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    // Also transition PENDING → RED when a test file is created (non-Bash tool)
+    if (status.tddPhase === 'PENDING' && status.testFileCreated) {
+        status.tddPhase = 'RED';
+    }
+    return status;
+}
+/**
+ * Check whether the given task line from tasks.md contains a @test-case annotation.
+ * Returns the list of referenced TC identifiers, or an empty array.
+ */
+function parseTestCaseAnnotations(taskLine) {
+    const match = taskLine.match(/@test-case[:\s]+([^\n]+)/i);
+    if (!match)
+        return [];
+    return match[1]
+        .split(/[,\s]+/)
+        .map((tc) => tc.trim())
+        .filter(Boolean);
+}
+/**
+ * Read tasks.md and locate the line that corresponds to the given taskId.
+ * Returns `null` when the task is not found.
+ */
+async function findTaskLine(changePath, taskId) {
+    const tasksPath = path.join(changePath, 'tasks.md');
+    if (!(await FileSystemUtils.fileExists(tasksPath))) {
+        return null;
+    }
+    const content = await FileSystemUtils.readFile(tasksPath);
+    const lines = content.split('\n');
+    // Normalise taskId for comparison (e.g. "2.1" should match "2.1")
+    const normalised = taskId.trim();
+    for (let idx = 0; idx < lines.length; idx++) {
+        const line = lines[idx];
+        // Match checkbox task lines: "- [ ] 2.1 ..." or "- [x] 2.1 ..."
+        const taskMatch = line.match(/^-\s+\[[ x]\]\s+(\S+)/);
+        if (taskMatch && taskMatch[1] === normalised) {
+            let fullBlock = line;
+            for (let i = idx + 1; i < lines.length; i++) {
+                if (/^\s{2,}/.test(lines[i]) && !/^-\s+\[/.test(lines[i].trim())) {
+                    fullBlock += '\n' + lines[i];
+                }
+                else {
+                    break;
+                }
+            }
+            return fullBlock;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Main hook entry point
+// ---------------------------------------------------------------------------
+/**
+ * TDD Phase Hook – called after tool use to enforce TDD discipline.
+ *
+ * @param changePath  Absolute path to the current change directory
+ * @param toolName    Name of the tool just used (e.g. 'Write', 'Edit', 'Bash')
+ * @param filePath    File affected by the tool invocation
+ * @param taskId      Current task identifier (e.g. "2.1")
+ * @param toolOutput  Optional output captured from Bash executions
+ */
+export async function tddPhaseHook(changePath, toolName, filePath, taskId, toolOutput) {
+    // 1. Determine whether this task is a TDD task (@test-case annotated)
+    const taskLine = await findTaskLine(changePath, taskId);
+    if (!taskLine) {
+        return { action: 'continue' };
+    }
+    const testCases = parseTestCaseAnnotations(taskLine);
+    if (testCases.length === 0) {
+        // Not a TDD task – nothing to enforce
+        return { action: 'continue' };
+    }
+    // 2. Load or initialise TDD status
+    let status = await loadTddStatus(changePath, taskId);
+    if (!status) {
+        status = {
+            taskId,
+            testCases,
+            tddPhase: 'PENDING',
+            testFileCreated: false,
+            testInitiallyFailed: false,
+            testFinallyPassed: false,
+            implFileCreated: false,
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    // 3. Check file creation order: test file should be created before impl file
+    if (!isTestFile(filePath) && !status.testFileCreated) {
+        if (toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit') {
+            // Implementation file created/modified before any test file exists
+            status.implFileCreated = true;
+            status.updatedAt = new Date().toISOString();
+            await saveTddStatus(changePath, taskId, status);
+            return {
+                action: 'warn',
+                message: `TDD violation: Implementation file "${path.basename(filePath)}" ` +
+                    `created before test file. In TDD, write tests first (RED phase).`,
+                updatedStatus: status,
+            };
+        }
+    }
+    // 4. Detect phase transitions & test results
+    const previousPhase = status.tddPhase;
+    status = detectTddPhaseTransition(status, toolName, filePath, toolOutput);
+    // 5. Enforce GREEN-phase constraint: tests must pass
+    if (previousPhase === 'GREEN' && toolName === 'Bash') {
+        const result = detectTestResult(toolOutput);
+        if (result === 'fail') {
+            await saveTddStatus(changePath, taskId, status);
+            return {
+                action: 'block',
+                message: 'TDD violation: Tests must pass in GREEN phase. ' +
+                    'Fix the implementation until all tests pass before proceeding.',
+                updatedStatus: status,
+            };
+        }
+    }
+    // 6. Persist updated status
+    await saveTddStatus(changePath, taskId, status);
+    // 7. Return result
+    return {
+        action: 'continue',
+        updatedStatus: status,
+    };
+}
+//# sourceMappingURL=tdd-phase-hook.js.map

package/dist/core/init.d.ts

@@ -83,6 +83,7 @@ export declare class InitCommand {
     private displayWorkflowDiagram;
     private formatToolNames;
     private renderBanner;
+    private ensureClaudeHud;
     private startSpinner;
 }
 export {};

package/dist/core/init.js

@@ -353,6 +353,8 @@ export class InitCommand {
             symbol: PALETTE.white('▌'),
             text: PALETTE.white('AI 工具已配置'),
         });
+        // Step 4: Ensure claude-hud is installed (for version display in statusLine)
+        await this.ensureClaudeHud();
         // Success message
         this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, toolConfigResult.rootStubStatus, toolConfigResult.claudeHookSummary);
     }
@@ -1542,6 +1544,31 @@ export class InitCommand {
         console.log(PALETTE.white('Welcome to ZhuanSpec!'));
         console.log();
     }
+    async ensureClaudeHud() {
+        const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(process.env.HOME || '~', '.claude');
+        const hudConfigPath = path.join(configDir, 'plugins', 'claude-hud', 'config.json');
+        if (existsSync(hudConfigPath)) {
+            return;
+        }
+        const spinner = this.startSpinner('正在安装 claude-hud（用于版本信息展示）...');
+        try {
+            execSync('claude plugin install claude-hud', {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 30000,
+            });
+            spinner.stopAndPersist({
+                symbol: PALETTE.white('▌'),
+                text: PALETTE.white('claude-hud 安装完成'),
+            });
+        }
+        catch {
+            spinner.stopAndPersist({
+                symbol: PALETTE.midGray('▌'),
+                text: PALETTE.midGray('claude-hud 安装失败，可手动执行: claude mcp install claude-hud'),
+            });
+        }
+    }
     startSpinner(text) {
         return ora({
             text,