@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/hooks/review-hooks.js

@@ -0,0 +1,345 @@
+/**
+ * Review Hooks - Result Checkers for Review Phase
+ *
+ * Three independent hooks for Review phase (Phase 3):
+ * 1. code-review-result: Check code-review-expert skill output
+ * 2. unit-test-result: Check generate-mockito-unit-test-skill output
+ * 3. spec-consistency-result: Check spec-code-consistency output
+ *
+ * Each hook:
+ * - Reads skill output file
+ * - Extracts key metrics (Critical count, coverage, consistency)
+ * - Decides if fix loop is needed
+ * - Controls loop count (max 3)
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { getBeijingTime } from './record-progress.js';
+// Output file paths for skill results
+const SKILL_OUTPUT_DIR = 'zhuanspec/.skill-outputs';
+const CODE_REVIEW_OUTPUT = 'code-review-result.json';
+const UNIT_TEST_OUTPUT = 'unit-test-result.json';
+const SPEC_CONSISTENCY_OUTPUT = 'spec-consistency-result.json';
+// Loop control
+const MAX_LOOP_COUNT = 3;
+export async function codeReviewResultCheck(changeId, skillOutput) {
+    const output = skillOutput || await readSkillOutput(changeId, CODE_REVIEW_OUTPUT);
+    if (!output) {
+        return {
+            pass: false,
+            needFix: false,
+            loopCount: 0,
+            metrics: { error: 'No skill output found' },
+            nextAction: 'stop',
+            fixPrompt: 'Code review skill output not found. Please run code-review-expert skill first.',
+        };
+    }
+    const loopCount = (output.loopCount || 0) + 1;
+    // Check Critical issues
+    if (output.criticalCount > 0) {
+        if (loopCount > MAX_LOOP_COUNT) {
+            // Loop limit reached, stop and report
+            return {
+                pass: false,
+                needFix: true,
+                loopCount: loopCount,
+                metrics: {
+                    criticalCount: output.criticalCount,
+                    importantCount: output.importantCount,
+                    loopExceeded: true,
+                },
+                nextAction: 'stop',
+                fixPrompt: formatFixPrompt(output.issues.filter(i => i.level === 'critical'), loopCount),
+            };
+        }
+        // Need fix loop
+        return {
+            pass: false,
+            needFix: true,
+            loopCount: loopCount,
+            metrics: {
+                criticalCount: output.criticalCount,
+                importantCount: output.importantCount,
+                criticalIssues: output.issues.filter(i => i.level === 'critical'),
+            },
+            nextAction: 'fix',
+            fixPrompt: formatFixPrompt(output.issues.filter(i => i.level === 'critical'), loopCount),
+        };
+    }
+    // PASS: No critical issues
+    return {
+        pass: true,
+        needFix: false,
+        loopCount: loopCount,
+        metrics: {
+            criticalCount: 0,
+            importantCount: output.importantCount,
+            infoCount: output.infoCount,
+            sonarStatus: output.sonarStatus,
+        },
+        nextAction: 'continue',
+    };
+}
+export async function unitTestResultCheck(changeId, skillOutput) {
+    const output = skillOutput || await readSkillOutput(changeId, UNIT_TEST_OUTPUT);
+    if (!output) {
+        return {
+            pass: false,
+            needFix: false,
+            loopCount: 0,
+            metrics: { error: 'No skill output found' },
+            nextAction: 'stop',
+            fixPrompt: 'Unit test skill output not found. Please run generate-mockito-unit-test-skill first.',
+        };
+    }
+    const loopCount = (output.loopCount || 0) + 1;
+    // Check test pass and coverage
+    const testFailed = !output.testPassed || output.passRate < 100;
+    const coverageLow = output.coverage < output.coverageThreshold;
+    if (testFailed || coverageLow) {
+        if (loopCount > MAX_LOOP_COUNT) {
+            return {
+                pass: false,
+                needFix: true,
+                loopCount: loopCount,
+                metrics: {
+                    testPassed: output.testPassed,
+                    passRate: output.passRate,
+                    coverage: output.coverage,
+                    coverageThreshold: output.coverageThreshold,
+                    loopExceeded: true,
+                },
+                nextAction: 'stop',
+                fixPrompt: formatUnitTestFixPrompt(output, loopCount),
+            };
+        }
+        return {
+            pass: false,
+            needFix: true,
+            loopCount: loopCount,
+            metrics: {
+                testPassed: output.testPassed,
+                passRate: output.passRate,
+                coverage: output.coverage,
+                coverageThreshold: output.coverageThreshold,
+                failedTests: output.failedTests,
+            },
+            nextAction: 'fix',
+            fixPrompt: formatUnitTestFixPrompt(output, loopCount),
+        };
+    }
+    // PASS: Tests passed and coverage meets threshold
+    return {
+        pass: true,
+        needFix: false,
+        loopCount: loopCount,
+        metrics: {
+            testPassed: true,
+            passRate: output.passRate,
+            coverage: output.coverage,
+            newTestsGenerated: output.newTestsGenerated,
+        },
+        nextAction: 'continue',
+    };
+}
+export async function specConsistencyResultCheck(changeId, skillOutput) {
+    const output = skillOutput || await readSkillOutput(changeId, SPEC_CONSISTENCY_OUTPUT);
+    if (!output) {
+        return {
+            pass: false,
+            needFix: false,
+            loopCount: 0,
+            metrics: { error: 'No skill output found' },
+            nextAction: 'stop',
+            fixPrompt: 'Spec-consistency skill output not found. Please run spec-code-consistency check first.',
+        };
+    }
+    const loopCount = (output.loopCount || 0) + 1;
+    // Check consistency coverage
+    const hasUncovered = output.uncoveredScenarios.length > 0;
+    if (hasUncovered) {
+        if (loopCount > MAX_LOOP_COUNT) {
+            return {
+                pass: false,
+                needFix: true,
+                loopCount: loopCount,
+                metrics: {
+                    consistencyRate: output.consistencyRate,
+                    totalScenarios: output.totalScenarios,
+                    coveredScenarios: output.coveredScenarios,
+                    loopExceeded: true,
+                },
+                nextAction: 'stop',
+                fixPrompt: formatConsistencyFixPrompt(output, loopCount),
+            };
+        }
+        return {
+            pass: false,
+            needFix: true,
+            loopCount: loopCount,
+            metrics: {
+                consistencyRate: output.consistencyRate,
+                uncoveredScenarios: output.uncoveredScenarios,
+            },
+            nextAction: 'fix',
+            fixPrompt: formatConsistencyFixPrompt(output, loopCount),
+        };
+    }
+    // PASS: All scenarios covered
+    return {
+        pass: true,
+        needFix: false,
+        loopCount: loopCount,
+        metrics: {
+            consistencyRate: 100,
+            totalRequirements: output.totalRequirements,
+            totalScenarios: output.totalScenarios,
+            coveredScenarios: output.coveredScenarios,
+            mapping: output.mapping,
+        },
+        nextAction: 'continue',
+    };
+}
+// ============================================================
+// Helper Functions
+// ============================================================
+async function readSkillOutput(changeId, filename) {
+    const cwd = process.cwd();
+    const outputPath = path.join(cwd, SKILL_OUTPUT_DIR, changeId, filename);
+    try {
+        if (await FileSystemUtils.fileExists(outputPath)) {
+            const content = await FileSystemUtils.readFile(outputPath);
+            return JSON.parse(content);
+        }
+    }
+    catch {
+        // File not found or parse error
+    }
+    return null;
+}
+function formatFixPrompt(issues, loopCount) {
+    const issueList = issues.map(i => `- [${i.level.toUpperCase}] ${i.file}${i.line ? `:${i.line}` : ''}: ${i.message}`).join('\n');
+    return `
+🔄 Code Review Fix Loop (${loopCount}/${MAX_LOOP_COUNT})
+
+发现 ${issues.length} 个 Critical 问题需要修复：
+
+${issueList}
+
+请修复以上问题后，重新调用 code-review-expert skill 进行验证。
+`;
+}
+function formatUnitTestFixPrompt(output, loopCount) {
+    const failedList = output.failedTests.length > 0
+        ? `\n失败的测试：\n${output.failedTests.map(t => `- ${t}`).join('\n')}`
+        : '';
+    return `
+🔄 Unit Test Fix Loop (${loopCount}/${MAX_LOOP_COUNT})
+
+测试状态：
+- 通过率：${output.passRate}%
+- 覆盖率：${output.coverage}%（阈值：${output.coverageThreshold}%）
+${failedList}
+
+请补充单元测试或修复失败的测试，然后重新调用 generate-mockito-unit-test-skill。
+`;
+}
+function formatConsistencyFixPrompt(output, loopCount) {
+    const uncoveredList = output.uncoveredScenarios.map(s => `- ${s.requirementId}/${s.scenarioId}: ${s.description}`).join('\n');
+    return `
+🔄 Spec-Code Consistency Fix Loop (${loopCount}/${MAX_LOOP_COUNT})
+
+发现 ${output.uncoveredScenarios.length} 个未覆盖的 Scenario：
+
+${uncoveredList}
+
+请选择修复方向：
+1. 添加代码实现以覆盖这些 Scenario
+2. 或更新 Spec 描述以反映当前实现状态
+
+然后重新运行 spec-code-consistency 检查。
+`;
+}
+// ============================================================
+// Write Skill Output (for skill to call)
+// ============================================================
+export async function writeCodeReviewOutput(changeId, output) {
+    await writeSkillOutput(changeId, CODE_REVIEW_OUTPUT, output);
+}
+export async function writeUnitTestOutput(changeId, output) {
+    await writeSkillOutput(changeId, UNIT_TEST_OUTPUT, output);
+}
+export async function writeSpecConsistencyOutput(changeId, output) {
+    await writeSkillOutput(changeId, SPEC_CONSISTENCY_OUTPUT, output);
+}
+// Export generic write function for subagent use
+export { writeSkillOutput };
+async function writeSkillOutput(changeId, filename, data) {
+    const cwd = process.cwd();
+    const outputDir = path.join(cwd, SKILL_OUTPUT_DIR, changeId);
+    await FileSystemUtils.createDirectory(outputDir);
+    const outputPath = path.join(outputDir, filename);
+    await FileSystemUtils.writeFile(outputPath, JSON.stringify(data, null, 2));
+}
+export async function generateReviewReport(changeId, results) {
+    const report = `# Review Report: ${changeId}
+
+**执行时间**: ${getBeijingTime()}
+**执行者**: AI
+
+---
+
+## 1. Code Review 结果
+
+| 指标 | 结果 |
+|------|------|
+| Critical 问题 | ${results.codeReview.metrics.criticalCount || 0} |
+| Important 问题 | ${results.codeReview.metrics.importantCount || 0} |
+| Info 问题 | ${results.codeReview.metrics.infoCount || 0} |
+| 循环次数 | ${results.codeReview.loopCount} |
+| 状态 | ${results.codeReview.pass ? '✅ PASS' : '❌ FAIL'} |
+
+---
+
+## 2. 单测验证结果
+
+| 指标 | 结果 |
+|------|------|
+| 测试通过率 | ${results.unitTest.metrics.passRate || 0}% |
+| 覆盖率 | ${results.unitTest.metrics.coverage || 0}% |
+| 新增单测 | ${(results.unitTest.metrics.newTestsGenerated || []).length} 个 |
+| 循环次数 | ${results.unitTest.loopCount} |
+| 状态 | ${results.unitTest.pass ? '✅ PASS' : '❌ FAIL'} |
+
+---
+
+## 3. Spec-Code 一致性认证
+
+| 指标 | 结果 |
+|------|------|
+| Requirements 数量 | ${results.specConsistency.metrics.totalRequirements || 0} |
+| Scenario 数量 | ${results.specConsistency.metrics.totalScenarios || 0} |
+| 一致性覆盖率 | ${results.specConsistency.metrics.consistencyRate || 0}% |
+| 循环次数 | ${results.specConsistency.loopCount} |
+| 状态 | ${results.specConsistency.pass ? '✅ PASS' : '❌ FAIL'} |
+
+---
+
+## 总体结论
+
+**状态**: ${results.codeReview.pass && results.unitTest.pass && results.specConsistency.pass ? 'PASS' : 'FAIL'}
+**可归档**: ${results.codeReview.pass && results.unitTest.pass && results.specConsistency.pass ? '是' : '否'}
+
+${results.codeReview.pass && results.unitTest.pass && results.specConsistency.pass
+        ? '**下一步**: 进入阶段 4（归档变更）'
+        : '**下一步**: 根据以上报告继续修复问题'}
+`;
+    // Write report to change directory
+    const cwd = process.cwd();
+    const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+    const reportPath = path.join(changeDir, 'review-report.md');
+    await FileSystemUtils.writeFile(reportPath, report);
+    return report;
+}
+export { MAX_LOOP_COUNT, };
+//# sourceMappingURL=review-hooks.js.map

package/dist/core/hooks/review-orchestrator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Review Orchestrator - 三轨并行 Review 调度
+ *
+ * 使用 Agent 工具启动 3 个 subagent 并行执行：
+ * 1. Code Review subagent - 调用 code-review-expert skill
+ * 2. Unit Test subagent - 调用 generate-mockito-unit-test skill
+ * 3. Spec-Code Consistency subagent - 执行一致性检查
+ *
+ * 每个 subagent 内部自闭环修复（最多3轮），最后汇总报告
+ */
+export interface ReviewOrchestratorOptions {
+    changeId: string;
+    parallel?: boolean;
+}
+export interface SubagentReport {
+    track: 'code-review' | 'unit-test' | 'spec-consistency';
+    reportFile: string;
+    passed: boolean;
+    loopCount: number;
+}
+/**
+ * Orchestrate three-track parallel review
+ *
+ * Note: This function returns prompts for subagents.
+ * The actual parallel execution should be done using Agent tool in the main conversation.
+ */
+export declare function orchestrateReview(options: ReviewOrchestratorOptions): Promise<{
+    codeReviewPrompt: string;
+    unitTestPrompt: string;
+    specConsistencyPrompt: string;
+}>;
+/**
+ * Collect subagent reports and generate final review report
+ */
+export declare function collectReports(changeId: string, reports: SubagentReport[]): Promise<string>;
+/**
+ * Check if all three tracks passed
+ */
+export declare function allTracksPassed(reports: SubagentReport[]): boolean;
+//# sourceMappingURL=review-orchestrator.d.ts.map

package/dist/core/hooks/review-orchestrator.js

@@ -0,0 +1,146 @@
+/**
+ * Review Orchestrator - 三轨并行 Review 调度
+ *
+ * 使用 Agent 工具启动 3 个 subagent 并行执行：
+ * 1. Code Review subagent - 调用 code-review-expert skill
+ * 2. Unit Test subagent - 调用 generate-mockito-unit-test skill
+ * 3. Spec-Code Consistency subagent - 执行一致性检查
+ *
+ * 每个 subagent 内部自闭环修复（最多3轮），最后汇总报告
+ */
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { generateReviewReport } from './review-hooks.js';
+/**
+ * Generate subagent prompts with self-contained loop instructions
+ */
+function generateCodeReviewPrompt(changeId) {
+    return `
+执行 Code Review，发现 Critical 问题时启动修复循环：
+
+## 任务目标
+对 changeId=${changeId} 的代码变更进行生产级代码评审
+
+## 自闭环指令
+1. 执行 code-review-expert skill 进行代码审查
+2. 如果发现 Critical 问题，立即修复
+3. 修复后重新检查（最多3轮）
+4. 输出 code-review-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+
+## 输出格式
+{
+  "criticalCount": number,
+  "importantCount": number,
+  "infoCount": number,
+  "issues": [...],
+  "loopCount": number,
+  "finalStatus": "PASS" | "FAIL"
+}
+`;
+}
+function generateUnitTestPrompt(changeId) {
+    return `
+执行单元测试验证，失败时启动修复循环：
+
+## 任务目标
+为 changeId=${changeId} 的代码变更生成并验证单元测试
+
+## 自闭环指令
+1. 执行 generate-mockito-unit-test skill 生成单测
+2. 运行单测，检查通过率和覆盖率
+3. 如果失败或不达标，立即修复
+4. 修复后重新测试（最多3轮）
+5. 输出 unit-test-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+
+## 输出格式
+{
+  "testPassed": boolean,
+  "passRate": number,
+  "coverage": number,
+  "newTestsGenerated": [...],
+  "failedTests": [...],
+  "loopCount": number,
+  "finalStatus": "PASS" | "FAIL"
+}
+`;
+}
+function generateSpecConsistencyPrompt(changeId) {
+    return `
+执行 Spec-Code 一致性检查，发现未覆盖 Scenario 时启动修复循环：
+
+## 任务目标
+验证 changeId=${changeId} 的代码实现与 Spec Requirement 一致
+
+## 自闭环指令
+1. 解析 specs/*.md 中的所有 Requirement 和 Scenario
+2. 检查代码实现是否覆盖每个 Scenario
+3. 如果发现未覆盖，立即补充代码或更新 Spec
+4. 修复后重新检查（最多3轮）
+5. 输出 spec-consistency-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+
+## 输出格式
+{
+  "consistencyRate": number,
+  "totalRequirements": number,
+  "totalScenarios": number,
+  "coveredScenarios": number,
+  "uncoveredScenarios": [...],
+  "loopCount": number,
+  "finalStatus": "PASS" | "FAIL"
+}
+`;
+}
+/**
+ * Orchestrate three-track parallel review
+ *
+ * Note: This function returns prompts for subagents.
+ * The actual parallel execution should be done using Agent tool in the main conversation.
+ */
+export async function orchestrateReview(options) {
+    const { changeId } = options;
+    // Ensure output directory exists
+    const cwd = process.cwd();
+    const outputDir = path.join(cwd, 'zhuanspec', '.skill-outputs', changeId);
+    await FileSystemUtils.createDirectory(outputDir);
+    return {
+        codeReviewPrompt: generateCodeReviewPrompt(changeId),
+        unitTestPrompt: generateUnitTestPrompt(changeId),
+        specConsistencyPrompt: generateSpecConsistencyPrompt(changeId),
+    };
+}
+/**
+ * Collect subagent reports and generate final review report
+ */
+export async function collectReports(changeId, reports) {
+    const cwd = process.cwd();
+    const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+    // Generate review report
+    const reportContent = await generateReviewReport(changeId, {
+        codeReview: {
+            pass: reports.find(r => r.track === 'code-review')?.passed ?? false,
+            needFix: false,
+            loopCount: reports.find(r => r.track === 'code-review')?.loopCount ?? 0,
+            metrics: {},
+        },
+        unitTest: {
+            pass: reports.find(r => r.track === 'unit-test')?.passed ?? false,
+            needFix: false,
+            loopCount: reports.find(r => r.track === 'unit-test')?.loopCount ?? 0,
+            metrics: {},
+        },
+        specConsistency: {
+            pass: reports.find(r => r.track === 'spec-consistency')?.passed ?? false,
+            needFix: false,
+            loopCount: reports.find(r => r.track === 'spec-consistency')?.loopCount ?? 0,
+            metrics: {},
+        },
+    });
+    return reportContent;
+}
+/**
+ * Check if all three tracks passed
+ */
+export function allTracksPassed(reports) {
+    return reports.every(r => r.passed);
+}
+//# sourceMappingURL=review-orchestrator.js.map

package/dist/core/hooks/summarize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stop Hook - Summarize Session Progress
+ *
+ * This hook runs when Claude Code session stops or pauses:
+ * 1. Summarize current wave completion status
+ * 2. Update ZHUANSPEC_CURRENT_TASK for next task
+ * 3. Check if tasks.md is complete → trigger Review phase
+ * 4. Generate events.json entries for key events
+ */
+interface SummarizeOptions {
+    json?: boolean;
+}
+export declare function summarizeHook(options: SummarizeOptions): Promise<void>;
+export {};
+//# sourceMappingURL=summarize.d.ts.map