@zhuan-ai/zhuanspec 2.9.5 → 2.11.2

package/dist/commands/review.js

@@ -1,10 +1,7 @@
-import { execSync } from 'child_process';
-import { promises as fs, readdirSync, existsSync } from 'fs';
+import { promises as fs } from 'fs';
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { GitRepoDetector } from '../utils/git-repo-detector.js';
-import { mcp__sonar__get_Sonar_Query } from '../mcp/index.js';
-import { writeCodeReviewOutput, writeUnitTestOutput, writeSpecConsistencyOutput, codeReviewResultCheck, unitTestResultCheck, specConsistencyResultCheck, generateReviewReport, } from '../core/hooks/review-hooks.js';
+import { codeReviewResultCheck, unitTestResultCheck, specConsistencyResultCheck, generateReviewReport, } from '../core/hooks/review-hooks.js';
 export class ReviewCommand {
     async execute(changeName, options) {
         if (!changeName) {
@@ -16,136 +13,46 @@ export class ReviewCommand {
         }
         const cwd = process.cwd();
         const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeName);
-        const metricsDir = path.join(changeDir, 'metrics');
+        const reviewDir = path.join(changeDir, 'review');
         const proposalPath = path.join(changeDir, 'proposal.md');
         const tasksPath = path.join(changeDir, 'tasks.md');
-        const changeSpecsDir = path.join(changeDir, 'specs');
+        // Check proposal and tasks exist
         const proposalExists = await FileSystemUtils.fileExists(proposalPath);
         const tasksExists = await FileSystemUtils.fileExists(tasksPath);
         if (!proposalExists || !tasksExists) {
             throw new Error(`Change '${changeName}' is not ready for review. Missing proposal.md or tasks.md`);
         }
-        // Detect all git repositories (parent + children)
-        const allRepos = GitRepoDetector.detectAllGitRepos(cwd);
-        const issues = [];
-        const requirementNames = await this.collectRequirementNames(changeSpecsDir);
-        // Use GitRepoDetector to get all changed files across all detected repos
-        const touchedFiles = GitRepoDetector.getAllChanges(cwd).filter((file) => !file.startsWith('zhuanspec/changes/archive/'));
-        const touchedContent = await this.collectTouchedFileContent(cwd, touchedFiles);
-        // Track whether every requirement has at least one weak signal in changed code.
-        for (const req of requirementNames) {
-            const normalized = req.toLowerCase();
-            const matched = touchedContent.some((content) => content.includes(normalized));
-            if (!matched) {
-                issues.push({
-                    severity: 'important',
-                    message: `Requirement may not be mapped to implementation: ${req}`,
-                    source: 'specCompliance',
-                });
-            }
-        }
-        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-        const incompleteTasks = (tasksContent.match(/^-\s*\[\s\]\s+/gm) ?? []).length;
-        if (incompleteTasks > 0) {
-            issues.push({
-                severity: 'critical',
-                message: `Found ${incompleteTasks} incomplete tasks in tasks.md`,
-                source: 'specCompliance',
-            });
-        }
-        // Very lightweight code-quality checks.
-        // touchedFiles now contains absolute paths from GitRepoDetector
-        for (const file of touchedFiles) {
-            if (file.endsWith('.ts') || (file.endsWith('.js') && !file.includes('node_modules'))) {
-                const content = await fs.readFile(file, 'utf-8');
-                if (content.includes('TODO') || content.includes('FIXME')) {
-                    issues.push({
-                        severity: 'minor',
-                        message: `Found TODO/FIXME in ${file}`,
-                        source: 'codeQuality',
-                    });
-                }
-            }
-        }
-        // Sonar MCP integration - fetch issues from SonarQube (use first detected repo if available)
-        const sonarIssues = await this.fetchSonarIssues(allRepos);
-        for (const issue of sonarIssues) {
-            const severity = issue.type === 'BUG' || issue.type === 'VULNERABILITY' ? 'critical' : 'important';
-            issues.push({
-                severity,
-                message: `Sonar ${issue.type}: ${issue.message} (${issue.file}${issue.line ? ':' + issue.line : ''})`,
-                source: 'codeQuality',
-            });
-        }
-        // Scenario→Test mapping validation
-        const scenarios = await this.collectScenarios(changeSpecsDir);
-        const testFiles = await this.findTestFiles(cwd);
-        for (const scenario of scenarios) {
-            const testPatterns = this.scenarioToTestMethodNames(scenario.name);
-            const matched = testFiles.some(tf => testPatterns.some(p => tf.toLowerCase().includes(p.toLowerCase())));
-            if (!matched) {
-                issues.push({
-                    severity: 'important',
-                    message: `Scenario "${scenario.name}" 未找到对应测试文件`,
-                    source: 'specCompliance',
-                });
-            }
-        }
-        const testCommand = options?.testCommand?.trim() || 'npm test';
-        const testResult = this.runTests(cwd, testCommand);
-        const coverageThreshold = Number(options?.coverageThreshold ?? 80);
-        if (testResult.coverage !== null && testResult.coverage < coverageThreshold) {
-            issues.push({
-                severity: 'important',
-                message: `Coverage ${testResult.coverage}% is below threshold ${coverageThreshold}%`,
-                source: 'unitTests',
-            });
-        }
-        if (testResult.failed > 0) {
-            issues.push({
-                severity: 'critical',
-                message: `Unit tests failed: ${testResult.failed}`,
-                source: 'unitTests',
-            });
-        }
-        const summary = this.buildSummary(issues, testResult, testCommand);
-        const consistency = this.buildSpecConsistency(requirementNames, scenarios, touchedFiles, testFiles);
-        // Persist skill-compatible outputs so hooks and command share one result chain.
-        await writeCodeReviewOutput(changeName, {
-            criticalCount: summary.summary.critical,
-            importantCount: summary.summary.important,
-            infoCount: summary.summary.minor,
-            issues: summary.issues.map((issue) => ({
-                level: issue.severity === 'minor' ? 'info' : issue.severity,
-                file: issue.source,
-                message: issue.message,
-            })),
-            sonarStatus: sonarIssues.length > 0 ? 'pass' : 'skip',
-            loopCount: 0,
-        });
-        await writeUnitTestOutput(changeName, {
-            testPassed: testResult.failed === 0,
-            passRate: testResult.failed === 0 ? 100 : 0,
-            coverage: testResult.coverage ?? 0,
-            coverageThreshold,
-            newTestsGenerated: [],
-            failedTests: testResult.failed > 0 ? ['test-command-failed'] : [],
-            loopCount: 0,
-        });
-        await writeSpecConsistencyOutput(changeName, {
-            consistencyRate: consistency.consistencyRate,
-            totalRequirements: consistency.totalRequirements,
-            totalScenarios: consistency.totalScenarios,
-            coveredScenarios: consistency.coveredScenarios,
-            uncoveredScenarios: consistency.uncoveredScenarios.map((scenario, idx) => ({
-                requirementId: `REQ-${String(idx + 1).padStart(3, '0')}`,
-                scenarioId: `SC-${String(idx + 1).padStart(3, '0')}`,
-                description: scenario.name,
-            })),
-            mapping: consistency.mapping,
-            loopCount: 0,
-        });
-        // Build unified review-report.md from hook checkers.
+        // === Task completion hard gate ===
+        if (tasksExists) {
+            const tasksContent = await fs.readFile(tasksPath, 'utf-8');
+            const uncompletedTasks = tasksContent.match(/^- \[ \] .+$/gm) || [];
+            if (uncompletedTasks.length > 0 && !options?.force) {
+                throw new Error(`Change '${changeName}' has ${uncompletedTasks.length} uncompleted tasks. ` +
+                    `Please complete all tasks before review. Use --force to override.\n` +
+                    uncompletedTasks.map(t => `  ${t.trim()}`).join('\n'));
+            }
+            if (uncompletedTasks.length > 0 && options?.force) {
+                console.log(`⚠️ Force mode: skipping ${uncompletedTasks.length} uncompleted tasks`);
+            }
+        }
+        // Check skill output JSON files exist
+        const codeReviewJsonPath = path.join(reviewDir, 'code-review-result.json');
+        const unitTestJsonPath = path.join(reviewDir, 'unit-test-result.json');
+        const missingFiles = [];
+        if (!(await FileSystemUtils.fileExists(codeReviewJsonPath))) {
+            missingFiles.push('code-review-result.json（需先运行 code-review-expert skill）');
+        }
+        if (!(await FileSystemUtils.fileExists(unitTestJsonPath))) {
+            missingFiles.push('unit-test-result.json（需先运行 generate-mockito-unit-test skill）');
+        }
+        if (missingFiles.length > 0) {
+            console.error(`❌ skill 输出缺失，请先执行以下步骤：`);
+            missingFiles.forEach((f, i) => console.error(`  ${i + 1}. ${f}`));
+            console.error(`  ${missingFiles.length + 1}. spec-consistency-result.json（运行 zhuanspec validate <id> --strict 后由 AI 写入）`);
+            process.exitCode = 1;
+            return;
+        }
+        // Read hook results and generate report
         const codeReviewResult = await codeReviewResultCheck(changeName);
         const unitTestResult = await unitTestResultCheck(changeName);
         const specConsistencyResult = await specConsistencyResultCheck(changeName);
@@ -154,16 +61,25 @@ export class ReviewCommand {
             unitTest: unitTestResult,
             specConsistency: specConsistencyResult,
         });
-        await FileSystemUtils.createDirectory(metricsDir);
-        await FileSystemUtils.writeFile(path.join(metricsDir, 'review.json'), JSON.stringify(summary, null, 2));
-        await FileSystemUtils.writeFile(path.join(metricsDir, 'tests.json'), JSON.stringify(testResult, null, 2));
+        // Output results
+        const overallPass = codeReviewResult.pass && unitTestResult.pass && specConsistencyResult.pass;
         if (options?.json) {
-            console.log(JSON.stringify(summary, null, 2));
+            console.log(JSON.stringify({
+                passed: overallPass,
+                codeReview: codeReviewResult,
+                unitTest: unitTestResult,
+                specConsistency: specConsistencyResult,
+            }, null, 2));
         }
         else {
-            this.printSummary(changeName, summary);
-        }
-        process.exitCode = summary.passed ? 0 : 1;
+            console.log(`Review report for ${changeName}`);
+            console.log(`Overall: ${overallPass ? 'PASS ✅' : 'FAIL ❌'}`);
+            console.log(`Code Review: ${codeReviewResult.pass ? 'PASS' : 'FAIL'} (critical=${codeReviewResult.metrics.criticalCount ?? 0})`);
+            console.log(`Unit Test: ${unitTestResult.pass ? 'PASS' : 'FAIL'} (coverage=${unitTestResult.metrics.coverage ?? 0}%)`);
+            console.log(`Spec-Code: ${specConsistencyResult.pass ? 'PASS' : 'FAIL'} (consistency=${specConsistencyResult.metrics.consistencyRate ?? 0}%)`);
+            console.log(`Report: ${path.join('zhuanspec/changes', changeName, 'review/review-report.md')}`);
+        }
+        process.exitCode = overallPass ? 0 : 1;
     }
     async selectChangeInteractively() {
         const changesDir = path.join(process.cwd(), 'zhuanspec', 'changes');
@@ -195,278 +111,5 @@ export class ReviewCommand {
             return null;
         }
     }
-    async collectRequirementNames(changeSpecsDir) {
-        const requirements = [];
-        const walk = async (dir) => {
-            let entries = [];
-            try {
-                entries = await fs.readdir(dir, { withFileTypes: true });
-            }
-            catch {
-                return;
-            }
-            for (const entry of entries) {
-                const full = path.join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    await walk(full);
-                    continue;
-                }
-                if (entry.isFile() && entry.name === 'spec.md') {
-                    const content = await fs.readFile(full, 'utf-8');
-                    const matches = content.match(/^###\s+(Requirement|需求):\s+(.+)$/gim) ?? [];
-                    for (const line of matches) {
-                        const parts = line.split(':');
-                        const name = parts.slice(1).join(':').trim();
-                        if (name)
-                            requirements.push(name);
-                    }
-                }
-            }
-        };
-        await walk(changeSpecsDir);
-        return Array.from(new Set(requirements));
-    }
-    async collectTouchedFileContent(repoRoot, files) {
-        const result = [];
-        for (const file of files) {
-            try {
-                const full = path.isAbsolute(file) ? file : path.join(repoRoot, file);
-                const stat = await fs.stat(full);
-                if (!stat.isFile())
-                    continue;
-                const content = await fs.readFile(full, 'utf-8');
-                result.push(content.toLowerCase());
-            }
-            catch {
-                // ignore unreadable files
-            }
-        }
-        return result;
-    }
-    runTests(repoRoot, command) {
-        try {
-            const output = execSync(command, { cwd: repoRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-            const coverageMatch = output.match(/(\d+(?:\.\d+)?)%\s*(?:\|)?\s*Statements/i);
-            return {
-                passed: 1,
-                failed: 0,
-                coverage: coverageMatch ? Number(coverageMatch[1]) : null,
-            };
-        }
-        catch (error) {
-            const stdout = error?.stdout?.toString?.() ?? '';
-            const stderr = error?.stderr?.toString?.() ?? '';
-            const combined = `${stdout}\n${stderr}`;
-            const coverageMatch = combined.match(/(\d+(?:\.\d+)?)%\s*(?:\|)?\s*Statements/i);
-            return {
-                passed: 0,
-                failed: 1,
-                coverage: coverageMatch ? Number(coverageMatch[1]) : null,
-            };
-        }
-    }
-    buildSummary(issues, testResult, command) {
-        const critical = issues.filter((i) => i.severity === 'critical').length;
-        const important = issues.filter((i) => i.severity === 'important').length;
-        const minor = issues.filter((i) => i.severity === 'minor').length;
-        return {
-            passed: critical === 0 && testResult.failed === 0,
-            summary: { critical, important, minor },
-            checks: {
-                specCompliance: !issues.some((i) => i.source === 'specCompliance' && i.severity === 'critical'),
-                codeQuality: !issues.some((i) => i.source === 'codeQuality' && i.severity === 'critical'),
-                unitTests: testResult.failed === 0,
-            },
-            test: {
-                passed: testResult.passed,
-                failed: testResult.failed,
-                coverage: testResult.coverage,
-                command,
-            },
-            issues,
-            generatedAt: new Date().toISOString(),
-        };
-    }
-    buildSpecConsistency(requirementNames, scenarios, touchedFiles, testFiles) {
-        const normalizedTouched = touchedFiles.map((file) => file.toLowerCase());
-        const normalizedTests = testFiles.map((file) => file.toLowerCase());
-        const mapping = [];
-        const uncoveredScenarios = [];
-        scenarios.forEach((scenario, idx) => {
-            const patterns = this.scenarioToTestMethodNames(scenario.name).map((p) => p.toLowerCase());
-            const testCovered = normalizedTests.some((testFile) => patterns.some((p) => testFile.includes(p)));
-            const codeCovered = normalizedTouched.some((codeFile) => patterns.some((p) => codeFile.includes(p)));
-            const status = testCovered && codeCovered
-                ? 'covered'
-                : (testCovered || codeCovered ? 'partial' : 'missing');
-            mapping.push({
-                requirementId: `REQ-${String((idx % Math.max(requirementNames.length, 1)) + 1).padStart(3, '0')}`,
-                scenarioId: `SC-${String(idx + 1).padStart(3, '0')}`,
-                codeFile: touchedFiles[0] || '',
-                status,
-            });
-            if (status !== 'covered') {
-                uncoveredScenarios.push(scenario);
-            }
-        });
-        const totalScenarios = scenarios.length;
-        const coveredScenarios = totalScenarios - uncoveredScenarios.length;
-        const consistencyRate = totalScenarios === 0 ? 100 : Math.round((coveredScenarios / totalScenarios) * 100);
-        return {
-            consistencyRate,
-            totalRequirements: requirementNames.length,
-            totalScenarios,
-            coveredScenarios,
-            uncoveredScenarios,
-            mapping,
-        };
-    }
-    printSummary(changeName, summary) {
-        console.log(`Review report for ${changeName}`);
-        console.log(`Passed: ${summary.passed ? 'YES' : 'NO'}`);
-        console.log(`Issues: critical=${summary.summary.critical}, important=${summary.summary.important}, minor=${summary.summary.minor}`);
-        console.log(`Tests: passed=${summary.test.passed}, failed=${summary.test.failed}, coverage=${summary.test.coverage ?? 'N/A'}`);
-        if (summary.issues.length > 0) {
-            console.log('Findings:');
-            for (const item of summary.issues) {
-                console.log(`- [${item.severity}] (${item.source}) ${item.message}`);
-            }
-        }
-    }
-    /**
-     * Fetch Sonar issues using MCP
-     * Uses the first detected repository's branch for SonarQube queries
-     */
-    async fetchSonarIssues(allRepos) {
-        // If no repos detected, skip Sonar queries
-        if (allRepos.length === 0) {
-            return [];
-        }
-        try {
-            // Use the first detected repository's branch
-            const primaryRepo = allRepos[0];
-            const branch = execSync('git branch --show-current', {
-                cwd: primaryRepo,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'ignore'],
-            }).trim();
-            // Query different types
-            const types = ['BUG', 'VULNERABILITY', 'CODE_SMELL'];
-            const allIssues = [];
-            for (const type of types) {
-                try {
-                    const result = await mcp__sonar__get_Sonar_Query({
-                        branchName: branch,
-                        staticType: type,
-                    });
-                    if (result && Array.isArray(result)) {
-                        for (const issue of result) {
-                            allIssues.push({
-                                type: type,
-                                severity: issue.severity || 'MAJOR',
-                                message: issue.message || '',
-                                file: issue.file || '',
-                                line: issue.line,
-                            });
-                        }
-                    }
-                }
-                catch {
-                    // Sonar MCP might not be configured, skip silently
-                }
-            }
-            return allIssues;
-        }
-        catch {
-            // Git command failed or Sonar not available
-            return [];
-        }
-    }
-    /**
-     * Collect all Scenarios from delta specs
-     */
-    async collectScenarios(changeSpecsDir) {
-        const scenarios = [];
-        const walk = async (dir) => {
-            let entries = [];
-            try {
-                entries = await fs.readdir(dir, { withFileTypes: true });
-            }
-            catch {
-                return;
-            }
-            for (const entry of entries) {
-                const full = path.join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    await walk(full);
-                    continue;
-                }
-                if (entry.isFile() && entry.name === 'spec.md') {
-                    const content = await fs.readFile(full, 'utf-8');
-                    // Match Scenario headers
-                    const matches = content.matchAll(/^####\s+(Scenario|场景)[：:]\s+(.+)$/gim);
-                    for (const match of matches) {
-                        const name = match[2].trim();
-                        scenarios.push({ name, specFile: full });
-                    }
-                }
-            }
-        };
-        await walk(changeSpecsDir);
-        return scenarios;
-    }
-    /**
-     * Find test files in the project
-     */
-    async findTestFiles(repoRoot) {
-        const testFiles = [];
-        const testDirs = ['test', 'tests', 'src/test', 'spec', '__tests__'];
-        for (const testDir of testDirs) {
-            const fullDir = path.join(repoRoot, testDir);
-            try {
-                if (!existsSync(fullDir))
-                    continue;
-                const walk = (dir) => {
-                    const entries = readdirSync(dir, { withFileTypes: true });
-                    for (const entry of entries) {
-                        const full = path.join(dir, entry.name);
-                        if (entry.isDirectory()) {
-                            walk(full);
-                        }
-                        else if (entry.isFile() && (entry.name.endsWith('.test.ts') ||
-                            entry.name.endsWith('.test.js') ||
-                            entry.name.endsWith('.spec.ts') ||
-                            entry.name.endsWith('.spec.js') ||
-                            entry.name.includes('Test'))) {
-                            testFiles.push(path.relative(repoRoot, full));
-                        }
-                    }
-                };
-                walk(fullDir);
-            }
-            catch {
-                // Directory doesn't exist or can't be read
-            }
-        }
-        return testFiles;
-    }
-    /**
-     * Convert Scenario name to possible test method names
-     */
-    scenarioToTestMethodNames(scenarioName) {
-        const name = scenarioName.replace(/[:：]/g, '').trim();
-        return [
-            // snake_case
-            name.replace(/\s+/g, '_').toLowerCase(),
-            // camelCase
-            name.replace(/\s+/g, '').toLowerCase(),
-            // PascalCase
-            name.split(/\s+/).map(w => w[0]?.toUpperCase() + w.slice(1).toLowerCase()).join(''),
-            // Remove Chinese characters for keyword matching
-            name.replace(/[^\w\s]/g, '').trim().toLowerCase(),
-            // Key words from scenario name
-            ...name.split(/\s+/).filter(w => w.length > 3),
-        ].filter(n => n.length > 0);
-    }
 }
 //# sourceMappingURL=review.js.map

package/dist/core/completions/command-registry.js

@@ -124,6 +124,10 @@ export const COMMAND_REGISTRY = [
         positionalType: 'change-id',
         flags: [
             COMMON_FLAGS.json,
+            {
+                name: 'force',
+                description: 'Skip task completion check and force review',
+            },
             {
                 name: 'test-command',
                 description: 'Test command to execute (default: npm test)',

package/dist/core/hooks/collect-knowledge.d.ts

@@ -1,16 +1,24 @@
 /**
  * PostToolUse Hook - Collect Knowledge
  *
- * This hook runs after Write/Edit operations to:
- * 1. Detect pitfall keywords in content or conversation
- * 2. Extract and save troubleshooting knowledge
- * 3. Record implicit conventions discovered
+ * Fires after Write/Edit in Apply phase. Injects a lightweight prompt
+ * into Claude's context so the LLM can decide (with user confirmation)
+ * whether the change is worth capturing as project knowledge.
+ *
+ * Design principle: no keyword matching, no auto-save — the LLM decides.
  */
 interface CollectKnowledgeOptions {
     json?: boolean;
     file?: string;
-    content?: string;
+}
+interface HookOutput {
+    continue: boolean;
+    systemMessage?: string;
+    hookSpecificOutput?: {
+        additionalContext?: string;
+    };
 }
 export declare function collectKnowledgeHook(options: CollectKnowledgeOptions): Promise<void>;
+export declare function runCollectKnowledge(filePath: string): Promise<HookOutput>;
 export {};
 //# sourceMappingURL=collect-knowledge.d.ts.map