@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/commands/review.js

@@ -0,0 +1,472 @@
+import { execSync } from 'child_process';
+import { promises as fs, readdirSync, existsSync } from 'fs';
+import path from 'path';
+import { FileSystemUtils } from '../utils/file-system.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';
+export class ReviewCommand {
+    async execute(changeName, options) {
+        if (!changeName) {
+            const selected = await this.selectChangeInteractively();
+            if (!selected) {
+                throw new Error('No change selected. Usage: zhuanspec review <change-id>');
+            }
+            changeName = selected;
+        }
+        const repoRoot = process.cwd();
+        const changeDir = path.join(repoRoot, 'zhuanspec', 'changes', changeName);
+        const metricsDir = path.join(changeDir, 'metrics');
+        const proposalPath = path.join(changeDir, 'proposal.md');
+        const tasksPath = path.join(changeDir, 'tasks.md');
+        const changeSpecsDir = path.join(changeDir, 'specs');
+        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`);
+        }
+        const issues = [];
+        const requirementNames = await this.collectRequirementNames(changeSpecsDir);
+        const touchedFiles = await this.collectTouchedFiles(repoRoot);
+        const touchedContent = await this.collectTouchedFileContent(repoRoot, 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.
+        for (const file of touchedFiles) {
+            if (file.endsWith('.ts') || (file.endsWith('.js') && !file.includes('node_modules'))) {
+                const content = await fs.readFile(path.join(repoRoot, 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
+        const sonarIssues = await this.fetchSonarIssues(repoRoot);
+        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(repoRoot);
+        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(repoRoot, 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.
+        const codeReviewResult = await codeReviewResultCheck(changeName);
+        const unitTestResult = await unitTestResultCheck(changeName);
+        const specConsistencyResult = await specConsistencyResultCheck(changeName);
+        await generateReviewReport(changeName, {
+            codeReview: codeReviewResult,
+            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));
+        if (options?.json) {
+            console.log(JSON.stringify(summary, null, 2));
+        }
+        else {
+            this.printSummary(changeName, summary);
+        }
+        process.exitCode = summary.passed ? 0 : 1;
+    }
+    async selectChangeInteractively() {
+        const changesDir = path.join(process.cwd(), 'zhuanspec', 'changes');
+        let entries = [];
+        try {
+            entries = await fs.readdir(changesDir, { withFileTypes: true });
+        }
+        catch {
+            throw new Error("No zhuanspec changes directory found. Run 'zhuanspec init' first.");
+        }
+        const changes = entries
+            .filter((entry) => entry.isDirectory() && entry.name !== 'archive' && !entry.name.startsWith('.'))
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+        if (changes.length === 0) {
+            throw new Error('No active changes found. Create one first with zhuanspec new change <name>.');
+        }
+        if (!process.stdin.isTTY) {
+            throw new Error(`Missing change name. Available changes: ${changes.join(', ')}`);
+        }
+        const { select } = await import('@inquirer/prompts');
+        try {
+            return await select({
+                message: '选择要执行 review 的变更',
+                choices: changes.map((id) => ({ name: id, value: id })),
+            });
+        }
+        catch {
+            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 collectTouchedFiles(repoRoot) {
+        try {
+            const output = execSync('git diff --name-only', { cwd: repoRoot, encoding: 'utf-8' });
+            return output
+                .split('\n')
+                .map((item) => item.trim())
+                .filter((item) => item.length > 0 && !item.startsWith('zhuanspec/changes/archive/'));
+        }
+        catch {
+            return [];
+        }
+    }
+    async collectTouchedFileContent(repoRoot, files) {
+        const result = [];
+        for (const file of files) {
+            try {
+                const full = 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
+     */
+    async fetchSonarIssues(repoRoot) {
+        try {
+            const branch = execSync('git branch --show-current', {
+                cwd: repoRoot,
+                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/commands/validate.d.ts

@@ -8,6 +8,7 @@ interface ExecuteOptions {
     noInteractive?: boolean;
     interactive?: boolean;
     concurrency?: string;
+    autoFix?: boolean;
 }
 export declare class ValidateCommand {
     execute(itemName: string | undefined, options?: ExecuteOptions): Promise<void>;
@@ -16,6 +17,19 @@ export declare class ValidateCommand {
     private printNonInteractiveHint;
     private validateDirectItem;
     private validateByType;
+    /**
+     * Attempt to auto-fix common validation issues.
+     * Returns true if any fixes were applied.
+     */
+    private tryAutoFix;
+    /**
+     * Add a section skeleton to proposal.md
+     */
+    private addProposalSectionSkeleton;
+    /**
+     * Add review gate section to tasks.md
+     */
+    private addReviewGateToTasks;
     private printReport;
     private printNextSteps;
     /**