@zhuan-ai/zhuanspec 2.2.5 → 2.5.0

package/dist/commands/progress.js

@@ -0,0 +1,349 @@
+/**
+ * Progress Command - Display current execution status
+ *
+ * This command reads progress.json and tasks.md to show:
+ * - Current phase and wave status
+ * - Task completion percentage with visual progress bar
+ * - Estimated remaining time
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { PHASE_ORDER } from '../utils/phase-utils.js';
+import { initializeProgress } from '../core/hooks/record-progress.js';
+export class ProgressCommand {
+    /**
+     * Recover damaged progress.json using three-tier fallback strategy
+     * @param filePath - Path to progress.json file
+     * @returns Recovered ProgressData or null if unrecoverable
+     */
+    async recoverProgressJson(filePath) {
+        const content = await FileSystemUtils.readFile(filePath);
+        // Layer 1: Standard JSON parse
+        try {
+            return JSON.parse(content);
+        }
+        catch {
+            // Continue to Layer 2
+        }
+        // Layer 2: Extract first top-level JSON object (handle trailing corruption)
+        try {
+            // Find the first complete JSON object
+            const objectStart = content.indexOf('{');
+            if (objectStart === -1)
+                return null;
+            // Track brace depth to find object boundary
+            let depth = 0;
+            let objectEnd = -1;
+            for (let i = objectStart; i < content.length; i++) {
+                if (content[i] === '{')
+                    depth++;
+                else if (content[i] === '}') {
+                    depth--;
+                    if (depth === 0) {
+                        objectEnd = i + 1;
+                        break;
+                    }
+                }
+            }
+            if (objectEnd > objectStart) {
+                const objectContent = content.slice(objectStart, objectEnd);
+                return JSON.parse(objectContent);
+            }
+        }
+        catch {
+            // Continue to Layer 3
+        }
+        // Layer 3: Minimal field extraction using regex
+        const phaseMatch = content.match(/"phase"\s*:\s*"([^"]+)"/);
+        const currentTaskMatch = content.match(/"currentTask"\s*:\s*"([^"]+)"/);
+        const totalTasksMatch = content.match(/"totalTasks"\s*:\s*(\d+)/);
+        const changeIdMatch = content.match(/"changeId"\s*:\s*"([^"]+)"/);
+        const sessionIdMatch = content.match(/"sessionId"\s*:\s*"([^"]+)"/);
+        if (phaseMatch || changeIdMatch) {
+            return {
+                changeId: changeIdMatch?.[1] || '',
+                sessionId: sessionIdMatch?.[1] || '',
+                startedAt: '',
+                lastUpdatedAt: '',
+                phase: phaseMatch?.[1] || 'unknown',
+                currentNode: phaseMatch?.[1] || 'unknown',
+                currentTask: currentTaskMatch?.[1] || '',
+                completedTasks: [],
+                totalTasks: totalTasksMatch ? parseInt(totalTasksMatch[1], 10) : 0,
+            };
+        }
+        return null;
+    }
+    /**
+     * Show progress for a specific change
+     * Usage: zhuanspec progress show <change-id>
+     */
+    async show(changeId, options) {
+        const cwd = process.cwd();
+        const zhuanspecDir = path.join(cwd, 'zhuanspec');
+        const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+        const metricsDir = path.join(changeDir, 'metrics');
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        // Read progress.json with recovery support
+        const progressPath = path.join(metricsDir, 'progress.json');
+        let progress = null;
+        if (await FileSystemUtils.fileExists(progressPath)) {
+            progress = await this.recoverProgressJson(progressPath);
+        }
+        // Read tasks.md
+        const tasksPath = path.join(changeDir, 'tasks.md');
+        let tasks = [];
+        let waves = [];
+        if (await FileSystemUtils.fileExists(tasksPath)) {
+            const tasksContent = await FileSystemUtils.readFile(tasksPath);
+            tasks = this.parseTasks(tasksContent);
+            waves = this.computeWaves(tasks);
+        }
+        if (options?.json) {
+            this.outputJson(changeId, progress, tasks, waves);
+        }
+        else {
+            this.outputFormatted(changeId, progress, tasks, waves);
+        }
+    }
+    async execute(options) {
+        const cwd = process.cwd();
+        const zhuanspecDir = path.join(cwd, 'zhuanspec');
+        // Check if zhuanspec directory exists
+        if (!await FileSystemUtils.fileExists(zhuanspecDir)) {
+            console.log('ℹ️ No ZhuanSpec project found in current directory');
+            return;
+        }
+        // Get active change from environment or find most recent
+        const changeId = process.env.ZHUANSPEC_CHANGE_ID || await this.findMostRecentChange(zhuanspecDir);
+        if (!changeId) {
+            console.log('ℹ️ No active ZhuanSpec change');
+            return;
+        }
+        const changeDir = path.join(zhuanspecDir, 'changes', changeId);
+        const metricsDir = path.join(changeDir, 'metrics');
+        // Read progress.json with recovery support
+        const progressPath = path.join(metricsDir, 'progress.json');
+        let progress = null;
+        if (await FileSystemUtils.fileExists(progressPath)) {
+            progress = await this.recoverProgressJson(progressPath);
+        }
+        // Read tasks.md
+        const tasksPath = path.join(changeDir, 'tasks.md');
+        let tasks = [];
+        let waves = [];
+        if (await FileSystemUtils.fileExists(tasksPath)) {
+            const tasksContent = await FileSystemUtils.readFile(tasksPath);
+            tasks = this.parseTasks(tasksContent);
+            waves = this.computeWaves(tasks);
+        }
+        if (options?.json) {
+            this.outputJson(changeId, progress, tasks, waves);
+        }
+        else {
+            this.outputFormatted(changeId, progress, tasks, waves);
+        }
+    }
+    async findMostRecentChange(zhuanspecDir) {
+        const changesDir = path.join(zhuanspecDir, 'changes');
+        if (!await FileSystemUtils.fileExists(changesDir)) {
+            return null;
+        }
+        const entries = await fs.readdir(changesDir, { withFileTypes: true });
+        const changeDirs = entries
+            .filter(e => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'archive')
+            .map(e => e.name);
+        if (changeDirs.length === 0) {
+            return null;
+        }
+        // Return most recently modified
+        const changeStats = await Promise.all(changeDirs.map(async (name) => {
+            const dirPath = path.join(changesDir, name);
+            const stats = await fs.stat(dirPath);
+            return { name, mtime: stats.mtime.getTime() };
+        }));
+        changeStats.sort((a, b) => b.mtime - a.mtime);
+        return changeStats[0].name;
+    }
+    parseTasks(content) {
+        const tasks = [];
+        const lines = content.split('\n');
+        let currentWave = 0;
+        for (const line of lines) {
+            // Match wave headers: ### Wave 1, ### Wave 2, etc.
+            const waveMatch = line.match(/^###\s*Wave\s*(\d+)/i);
+            if (waveMatch) {
+                currentWave = parseInt(waveMatch[1], 10);
+                continue;
+            }
+            // Match new format task lines: - [ ] X.Y description or - [x] X.Y description
+            const newFormatMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
+            if (newFormatMatch) {
+                const statusChar = newFormatMatch[1];
+                const taskId = newFormatMatch[2];
+                const description = newFormatMatch[3].trim();
+                tasks.push({
+                    taskId,
+                    status: statusChar === 'x' ? 'completed' : 'pending',
+                    wave: currentWave,
+                    description: description.split('@')[0].trim(), // Remove @skill/@depends tags
+                });
+                continue;
+            }
+            // Match legacy format task headers: #### T1: description or #### T2: description
+            const legacyMatch = line.match(/^####\s*(T\d+)\s*:\s*(.+)$/);
+            if (legacyMatch) {
+                const taskId = legacyMatch[1];
+                const rawDescription = legacyMatch[2].trim();
+                // Check if description ends with ✅ (completed marker)
+                const isCompleted = rawDescription.endsWith('✅');
+                const description = isCompleted
+                    ? rawDescription.slice(0, -1).trim()
+                    : rawDescription;
+                tasks.push({
+                    taskId,
+                    status: isCompleted ? 'completed' : 'pending',
+                    wave: currentWave,
+                    description: description.split('@')[0].trim(), // Remove @skill/@depends tags
+                });
+            }
+        }
+        return tasks;
+    }
+    computeWaves(tasks) {
+        const wavesMap = new Map();
+        for (const task of tasks) {
+            if (!wavesMap.has(task.wave)) {
+                wavesMap.set(task.wave, {
+                    waveId: task.wave,
+                    tasks: [],
+                    completedTasks: [],
+                    status: 'pending',
+                });
+            }
+            const wave = wavesMap.get(task.wave);
+            wave.tasks.push(task);
+            if (task.status === 'completed') {
+                wave.completedTasks.push(task);
+            }
+        }
+        // Determine wave status
+        for (const [, wave] of wavesMap) {
+            if (wave.completedTasks.length === wave.tasks.length) {
+                wave.status = 'completed';
+            }
+            else if (wave.completedTasks.length > 0) {
+                wave.status = 'in_progress';
+            }
+            else {
+                wave.status = 'pending';
+            }
+        }
+        return Array.from(wavesMap.values()).sort((a, b) => a.waveId - b.waveId);
+    }
+    outputJson(changeId, progress, tasks, waves) {
+        const output = {
+            changeId,
+            phase: progress?.phase || 'unknown',
+            currentTask: progress?.currentTask || null,
+            tasks: {
+                total: tasks.length,
+                completed: tasks.filter(t => t.status === 'completed').length,
+                pending: tasks.filter(t => t.status === 'pending').length,
+            },
+            waves: waves.map(w => ({
+                waveId: w.waveId,
+                status: w.status,
+                totalTasks: w.tasks.length,
+                completedTasks: w.completedTasks.length,
+            })),
+            progress: progress,
+        };
+        console.log(JSON.stringify(output, null, 2));
+    }
+    outputFormatted(changeId, progress, tasks, waves) {
+        const phase = progress?.phase || 'unknown';
+        const currentTask = progress?.currentTask || '';
+        const completedCount = tasks.filter(t => t.status === 'completed').length;
+        const totalTasks = tasks.length;
+        // Phase index
+        const phases = ['idle', 'propose', 'apply', 'review', 'archive'];
+        const phaseIndex = phases.indexOf(phase) + 1;
+        // Progress percentage
+        const percentage = totalTasks > 0 ? (completedCount / totalTasks) * 100 : 0;
+        const progressBar = this.generateProgressBar(percentage, 12);
+        // Duration
+        const durationMs = progress?.stats?.durationMs?.[phase] || 0;
+        const durationMin = Math.round(durationMs / 60000);
+        const estimatedRemaining = totalTasks > 0 && completedCount > 0
+            ? Math.round((durationMin / completedCount) * (totalTasks - completedCount))
+            : 0;
+        console.log('');
+        console.log(`📊 变更进度: ${changeId}`);
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('');
+        console.log(`Phase: ${phase} (${phaseIndex}/${phases.length})`);
+        console.log('');
+        // Wave status
+        for (const wave of waves) {
+            const waveStatusEmoji = wave.status === 'completed' ? '✅' : wave.status === 'in_progress' ? '🔄' : '⏳';
+            const waveStatusText = wave.status === 'completed' ? '完成' : wave.status === 'in_progress' ? '进行中' : '待开始';
+            console.log(`Wave ${wave.waveId}: ${waveStatusEmoji} ${waveStatusText}`);
+            for (const task of wave.tasks) {
+                const taskStatusEmoji = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
+                const isCurrent = task.taskId === currentTask;
+                const currentIndicator = isCurrent ? '  ← 当前' : '';
+                console.log(`  ${taskStatusEmoji} ${task.taskId} ${task.description}${currentIndicator}`);
+            }
+            console.log('');
+        }
+        // Overall progress
+        console.log(`整体: ${progressBar} ${percentage.toFixed(1)}% (${completedCount}/${totalTasks})`);
+        // Duration info
+        if (durationMin > 0) {
+            console.log(`耗时: ${durationMin}m | 预计剩余: ~${estimatedRemaining}m`);
+        }
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('');
+        // Next task
+        const nextTask = tasks.find(t => t.status === 'pending');
+        if (nextTask) {
+            console.log(`➡️ 下一个任务: ${nextTask.taskId}`);
+        }
+        else if (completedCount === totalTasks && totalTasks > 0) {
+            console.log('✅ 全部任务完成，准备进入 Review 阶段');
+        }
+    }
+    generateProgressBar(percentage, blocks) {
+        const filled = Math.round((percentage / 100) * blocks);
+        const empty = blocks - filled;
+        return '█'.repeat(filled) + '░'.repeat(empty);
+    }
+    /**
+     * Set phase for a change
+     * Usage: zhuanspec progress set-phase <change-id> <phase>
+     */
+    async setPhase(changeId, phase) {
+        const cwd = process.cwd();
+        const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+        if (!await FileSystemUtils.directoryExists(changeDir)) {
+            throw new Error(`Change '${changeId}' not found`);
+        }
+        // Validate phase
+        const normalizedPhase = phase.toLowerCase();
+        if (!PHASE_ORDER.includes(normalizedPhase)) {
+            throw new Error(`Invalid phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+        }
+        // Update progress.json
+        await initializeProgress(changeId, normalizedPhase);
+        // Read and display result
+        const progressPath = path.join(changeDir, 'metrics', 'progress.json');
+        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+        console.log(`\n✓ Phase set: ${changeId} -> ${normalizedPhase}`);
+        console.log(`✓ Progress file: ${progressPath}\n`);
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/commands/review.d.ts

@@ -0,0 +1,32 @@
+export declare class ReviewCommand {
+    execute(changeName?: string, options?: {
+        json?: boolean;
+        testCommand?: string;
+        coverageThreshold?: string;
+    }): Promise<void>;
+    private selectChangeInteractively;
+    private collectRequirementNames;
+    private collectTouchedFiles;
+    private collectTouchedFileContent;
+    private runTests;
+    private buildSummary;
+    private buildSpecConsistency;
+    private printSummary;
+    /**
+     * Fetch Sonar issues using MCP
+     */
+    private fetchSonarIssues;
+    /**
+     * Collect all Scenarios from delta specs
+     */
+    private collectScenarios;
+    /**
+     * Find test files in the project
+     */
+    private findTestFiles;
+    /**
+     * Convert Scenario name to possible test method names
+     */
+    private scenarioToTestMethodNames;
+}
+//# sourceMappingURL=review.d.ts.map