@angli/unit-test-tool 0.1.0

package/dist/src/core/tools/run-with-claude-cli.js

@@ -0,0 +1,645 @@
+import { createHash } from 'node:crypto';
+import fg from 'fast-glob';
+import path from 'node:path';
+import { executeClaudeCli } from '../executor/claude-cli-executor.js';
+import { verifyAll } from './verify-all.js';
+import { rulePlanner } from '../planner/rule-planner.js';
+import { buildFinalReport } from '../reporter/index.js';
+export async function runWithClaudeCli(ctx, input = {}) {
+    ctx.logger.info('[run] step=select-target status=start');
+    const coverageSummary = await ctx.reportStore.loadCoverageSummary();
+    const target = input.targetFile
+        ? await buildTaskFromExplicitTarget(ctx, input.targetFile)
+        : await pickRecommendedTask(ctx, input.topN ?? 5, coverageSummary?.coverageSnapshot, input.excludeTargets);
+    if (!target) {
+        ctx.logger.warn('[run] step=select-target status=empty');
+        return {
+            ok: false,
+            phase: 'WRITING_TESTS',
+            summary: '没有找到可执行的补测目标。请先运行 analyze 或通过 --file 指定目标文件。',
+            nextAction: 'analyze'
+        };
+    }
+    const beforeSnapshot = await captureTestSnapshot(ctx);
+    const firstAttemptTimestamp = ctx.clock.nowIso();
+    const promptText = buildExecutionPrompt(ctx, target.task);
+    const promptPath = await persistPrompt(ctx, target.task.taskId, 1, promptText, target.task.targetFile, firstAttemptTimestamp);
+    const stdoutPath = buildTaskOutputPath(ctx, target.task.taskId, 1, 'stdout', target.task.targetFile, firstAttemptTimestamp);
+    const stderrPath = buildTaskOutputPath(ctx, target.task.taskId, 1, 'stderr', target.task.targetFile, firstAttemptTimestamp);
+    const runPromptPath = await appendRunPrompt(ctx, target.task.taskId, 1, target.task.targetFile, firstAttemptTimestamp, promptPath);
+    await appendRunEvent(ctx, {
+        taskId: target.task.taskId,
+        targetFile: target.task.targetFile,
+        attemptCount: 1,
+        promptPath,
+        status: 'passed',
+        summary: 'prompt recorded'
+    }, 'cli_run_attempt', {
+        promptPreview: buildPreview(promptText),
+        stdoutPath,
+        stderrPath,
+        runPromptPath
+    });
+    ctx.logger.info(`[run] step=select-target status=ok taskId=${target.task.taskId} target=${target.task.targetFile}`);
+    await ctx.eventStore.append({
+        eventType: 'cli_run_started',
+        phase: 'WRITING_TESTS',
+        taskId: target.task.taskId,
+        message: `selected ${target.task.targetFile}`,
+        data: {
+            targetFile: target.task.targetFile,
+            recommendedTargets: target.recommendedTargets,
+            promptPath,
+            attemptCount: 1
+        },
+        timestamp: ctx.clock.nowIso()
+    });
+    await ctx.stateStore.save({
+        phase: 'WRITING_TESTS',
+        status: 'running',
+        currentTaskId: target.task.taskId,
+        coverageSnapshot: undefined,
+        totals: {
+            pending: 0,
+            running: 1,
+            passed: 0,
+            failed: 0,
+            blocked: 0
+        },
+        lastAction: 'run',
+        nextSuggestedAction: 'verify',
+        updatedAt: ctx.clock.nowIso()
+    });
+    ctx.logger.info(`[run] step=claude-cli status=start attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile}`);
+    const firstRun = await executeClaudeCli({
+        cwd: ctx.projectPath,
+        prompt: promptText,
+        allowedTools: input.allowedTools,
+        permissionMode: input.permissionMode,
+        outputFormat: 'text',
+        timeoutMs: input.timeoutMs,
+        onProgress: (elapsedMs) => {
+            ctx.logger.info(`[run] step=claude-cli status=waiting attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${elapsedMs}`);
+        },
+        taskMeta: {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            strategy: target.task.strategy,
+            attemptCount: 1
+        }
+    });
+    const firstStdoutPath = await persistOutput(ctx, target.task.taskId, 1, 'stdout', target.task.targetFile, firstAttemptTimestamp, firstRun.stdout);
+    const firstStderrPath = await persistOutput(ctx, target.task.taskId, 1, 'stderr', target.task.targetFile, firstAttemptTimestamp, firstRun.stderr);
+    if (firstRun.stdout?.trim()) {
+        ctx.logger.info(`[run] step=claude-cli status=stdout attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(firstRun.stdout)}`);
+    }
+    if (firstRun.stderr?.trim()) {
+        ctx.logger.warn(`[run] step=claude-cli status=stderr attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(firstRun.stderr)}`);
+    }
+    if (!firstRun.ok) {
+        const stderrText = firstRun.stderr?.trim() || '';
+        const stdoutText = firstRun.stdout?.trim() || '';
+        ctx.logger.error(`[run] step=claude-cli status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} category=${firstRun.failureCategory ?? 'unknown'}`);
+        if (stderrText) {
+            ctx.logger.error(`[run] step=claude-cli status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(stderrText)}`);
+        }
+        if (stdoutText) {
+            ctx.logger.error(`[run] step=claude-cli status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(stdoutText)}`);
+        }
+        const failureMessage = stderrText || stdoutText || 'unknown error';
+        await appendRunEvent(ctx, {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            attemptCount: 1,
+            promptPath,
+            status: 'cli_failed',
+            stdout: stdoutText || undefined,
+            stderr: stderrText || undefined,
+            summary: `Claude CLI 执行失败：${firstRun.failureCategory ?? 'unknown'}。`
+        }, 'cli_run_failed', {
+            stdoutPath: firstStdoutPath,
+            stderrPath: firstStderrPath
+        });
+        await markRunFailed(ctx, target.task, failureMessage);
+        return {
+            ok: false,
+            phase: 'WRITING_TESTS',
+            summary: `Claude CLI 执行失败：${firstRun.failureCategory ?? 'unknown'}。`,
+            nextAction: 'manual-intervention',
+            targetFile: target.task.targetFile,
+            artifacts: {
+                stderr: stderrText || undefined,
+                stdout: stdoutText || undefined
+            }
+        };
+    }
+    ctx.logger.info(`[run] step=claude-cli status=done attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${firstRun.durationMs}`);
+    ctx.logger.info('[run] step=verify status=start attempt=1');
+    const verifyResult = await verifyAll(ctx);
+    if (verifyResult.ok) {
+        ctx.logger.info('[run] step=verify status=ok attempt=1');
+        const noOpResult = await validateTestChanges(ctx, target.task, beforeSnapshot);
+        if (!noOpResult.ok) {
+            await appendRunEvent(ctx, {
+                taskId: target.task.taskId,
+                targetFile: target.task.targetFile,
+                attemptCount: 1,
+                promptPath,
+                changedTestFiles: noOpResult.changedTestFiles,
+                relatedTestFiles: noOpResult.relatedTestFiles,
+                verifyResult: 'passed',
+                status: 'noop',
+                summary: noOpResult.summary
+            }, 'cli_run_failed', {
+                stdoutPath: firstStdoutPath,
+                stderrPath: firstStderrPath
+            });
+            await markRunFailed(ctx, target.task, noOpResult.summary);
+            return noOpResult;
+        }
+        await appendRunEvent(ctx, {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            attemptCount: 1,
+            promptPath,
+            changedTestFiles: noOpResult.changedTestFiles,
+            relatedTestFiles: noOpResult.relatedTestFiles,
+            verifyResult: 'passed',
+            status: 'passed',
+            summary: `Claude CLI 已完成 ${target.task.targetFile} 的补测并通过全量验证。`
+        }, 'cli_run_completed', {
+            stdoutPath: firstStdoutPath,
+            stderrPath: firstStderrPath
+        });
+        await markRunPassed(ctx, target.task);
+        return await buildSuccessResult(ctx, target.task.targetFile, target.recommendedTargets, noOpResult.changedTestFiles, noOpResult.relatedTestFiles);
+    }
+    ctx.logger.warn(`[run] step=verify status=failed attempt=1 taskId=${target.task.taskId} target=${target.task.targetFile}`);
+    ctx.logger.info(`[run] step=claude-cli status=start attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile}`);
+    const retryAttemptTimestamp = ctx.clock.nowIso();
+    const retryPromptText = buildRetryExecutionPrompt(ctx, target.task, verifyResult.artifacts?.stderr);
+    const retryPromptPath = await persistPrompt(ctx, target.task.taskId, 2, retryPromptText, target.task.targetFile, retryAttemptTimestamp);
+    const retryStdoutPath = buildTaskOutputPath(ctx, target.task.taskId, 2, 'stdout', target.task.targetFile, retryAttemptTimestamp);
+    const retryStderrPath = buildTaskOutputPath(ctx, target.task.taskId, 2, 'stderr', target.task.targetFile, retryAttemptTimestamp);
+    const retryRunPromptPath = await appendRunPrompt(ctx, target.task.taskId, 2, target.task.targetFile, retryAttemptTimestamp, retryPromptPath);
+    await appendRunEvent(ctx, {
+        taskId: target.task.taskId,
+        targetFile: target.task.targetFile,
+        attemptCount: 2,
+        promptPath: retryPromptPath,
+        status: 'passed',
+        verifyResult: 'failed',
+        summary: 'retry prompt recorded'
+    }, 'cli_run_attempt', {
+        promptPreview: buildPreview(retryPromptText),
+        stdoutPath: retryStdoutPath,
+        stderrPath: retryStderrPath,
+        runPromptPath: retryRunPromptPath
+    });
+    const retryRun = await executeClaudeCli({
+        cwd: ctx.projectPath,
+        prompt: retryPromptText,
+        allowedTools: input.allowedTools,
+        permissionMode: input.permissionMode,
+        outputFormat: 'text',
+        timeoutMs: input.timeoutMs,
+        onProgress: (elapsedMs) => {
+            ctx.logger.info(`[run] step=claude-cli status=waiting attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${elapsedMs}`);
+        },
+        taskMeta: {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            strategy: target.task.strategy,
+            attemptCount: 2
+        }
+    });
+    const retryStdoutSaved = await persistOutput(ctx, target.task.taskId, 2, 'stdout', target.task.targetFile, retryAttemptTimestamp, retryRun.stdout);
+    const retryStderrSaved = await persistOutput(ctx, target.task.taskId, 2, 'stderr', target.task.targetFile, retryAttemptTimestamp, retryRun.stderr);
+    if (retryRun.stdout?.trim()) {
+        ctx.logger.info(`[run] step=claude-cli status=stdout attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(retryRun.stdout)}`);
+    }
+    if (retryRun.stderr?.trim()) {
+        ctx.logger.warn(`[run] step=claude-cli status=stderr attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(retryRun.stderr)}`);
+    }
+    if (!retryRun.ok) {
+        const stderrText = retryRun.stderr?.trim() || '';
+        const stdoutText = retryRun.stdout?.trim() || '';
+        ctx.logger.error(`[run] step=claude-cli status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} category=${retryRun.failureCategory ?? 'unknown'}`);
+        if (stderrText) {
+            ctx.logger.error(`[run] step=claude-cli status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stderr=${truncateLog(stderrText)}`);
+        }
+        if (stdoutText) {
+            ctx.logger.error(`[run] step=claude-cli status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} stdout=${truncateLog(stdoutText)}`);
+        }
+        const failureMessage = stderrText || stdoutText || 'unknown error';
+        await appendRunEvent(ctx, {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            attemptCount: 2,
+            promptPath: retryPromptPath,
+            status: 'cli_failed',
+            verifyResult: 'failed',
+            stdout: stdoutText || undefined,
+            stderr: stderrText || undefined,
+            summary: `Claude CLI 重试失败：${retryRun.failureCategory ?? 'unknown'}。`
+        }, 'cli_run_failed', {
+            stdoutPath: retryStdoutSaved,
+            stderrPath: retryStderrSaved
+        });
+        await markRunFailed(ctx, target.task, failureMessage);
+        return {
+            ok: false,
+            phase: 'WRITING_TESTS',
+            summary: `Claude CLI 重试失败：${retryRun.failureCategory ?? 'unknown'}。`,
+            nextAction: 'manual-intervention',
+            targetFile: target.task.targetFile,
+            artifacts: {
+                stderr: stderrText || undefined,
+                stdout: stdoutText || undefined
+            }
+        };
+    }
+    ctx.logger.info(`[run] step=claude-cli status=done attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile} elapsedMs=${retryRun.durationMs}`);
+    ctx.logger.info('[run] step=verify status=start attempt=2');
+    const retriedVerify = await verifyAll(ctx);
+    if (!retriedVerify.ok) {
+        ctx.logger.error(`[run] step=verify status=failed attempt=2 taskId=${target.task.taskId} target=${target.task.targetFile}`);
+        await appendRunEvent(ctx, {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            attemptCount: 2,
+            promptPath: retryPromptPath,
+            status: 'verify_failed',
+            verifyResult: 'failed',
+            summary: 'Claude CLI 已重试一次，但全量验证仍失败。'
+        }, 'cli_run_failed', {
+            stdoutPath: retryStdoutSaved,
+            stderrPath: retryStderrSaved
+        });
+        await markRunFailed(ctx, target.task, retriedVerify.artifacts?.stderr);
+        return {
+            ok: false,
+            phase: 'VERIFYING_FULL',
+            summary: 'Claude CLI 已重试一次，但全量验证仍失败。',
+            nextAction: 'manual-intervention',
+            targetFile: target.task.targetFile,
+            artifacts: retriedVerify.artifacts
+        };
+    }
+    const noOpResult = await validateTestChanges(ctx, target.task, beforeSnapshot);
+    if (!noOpResult.ok) {
+        await appendRunEvent(ctx, {
+            taskId: target.task.taskId,
+            targetFile: target.task.targetFile,
+            attemptCount: 2,
+            promptPath: retryPromptPath,
+            changedTestFiles: noOpResult.changedTestFiles,
+            relatedTestFiles: noOpResult.relatedTestFiles,
+            verifyResult: 'passed',
+            status: 'noop',
+            summary: noOpResult.summary
+        }, 'cli_run_failed', {
+            stdoutPath: retryStdoutSaved,
+            stderrPath: retryStderrSaved
+        });
+        await markRunFailed(ctx, target.task, noOpResult.summary);
+        return noOpResult;
+    }
+    await appendRunEvent(ctx, {
+        taskId: target.task.taskId,
+        targetFile: target.task.targetFile,
+        attemptCount: 2,
+        promptPath: retryPromptPath,
+        changedTestFiles: noOpResult.changedTestFiles,
+        relatedTestFiles: noOpResult.relatedTestFiles,
+        verifyResult: 'passed',
+        status: 'passed',
+        summary: `Claude CLI 已完成 ${target.task.targetFile} 的补测并通过全量验证。`
+    }, 'cli_run_completed', {
+        stdoutPath: retryStdoutSaved,
+        stderrPath: retryStderrSaved
+    });
+    await markRunPassed(ctx, target.task);
+    return await buildSuccessResult(ctx, target.task.targetFile, target.recommendedTargets, noOpResult.changedTestFiles, noOpResult.relatedTestFiles);
+}
+async function pickRecommendedTask(ctx, topN, coverageSnapshot, excludeTargets = []) {
+    const testDirNames = await detectTestDirNames(ctx);
+    ctx.logger.info('[run] step=scan status=start');
+    ctx.logger.debug('[run] step=scan params', { include: ctx.config.include, exclude: ctx.config.exclude });
+    const files = await fg(ctx.config.include, {
+        cwd: ctx.projectPath,
+        ignore: ctx.config.exclude,
+        onlyFiles: true,
+        absolute: false
+    });
+    const candidates = files
+        .filter((file) => !isTestFile(file) && !excludeTargets.includes(file))
+        .map((file) => ({ targetFile: file }));
+    ctx.logger.info(`[run] step=scan status=ok total=${files.length} candidates=${candidates.length} topN=${topN}`);
+    ctx.logger.info(`[run] step=rank status=start candidates=${candidates.length}`);
+    const ranked = await rulePlanner(ctx, candidates, coverageSnapshot);
+    const shortlist = ranked.slice(0, topN);
+    const selected = shortlist[0];
+    if (!selected)
+        return undefined;
+    return {
+        task: toTaskItem(selected, testDirNames),
+        recommendedTargets: shortlist.map((item) => item.targetFile)
+    };
+}
+async function buildTaskFromExplicitTarget(ctx, targetFile) {
+    const testDirNames = await detectTestDirNames(ctx);
+    const ranked = await rulePlanner(ctx, [{ targetFile }]);
+    const selected = ranked[0];
+    if (!selected)
+        return undefined;
+    return {
+        task: toTaskItem(selected, testDirNames),
+        recommendedTargets: [selected.targetFile]
+    };
+}
+function toTaskItem(candidate, testDirNames) {
+    return {
+        taskId: candidate.taskId,
+        targetFile: candidate.targetFile,
+        testFiles: candidate.analyzerFacts.existingTest.testFilePaths,
+        score: candidate.baseScore,
+        reasons: candidate.reasons,
+        estimatedDifficulty: candidate.estimatedDifficulty,
+        strategy: candidate.suggestedStrategy ?? 'pure-logic',
+        status: 'pending',
+        attemptCount: 0,
+        testDirNames,
+        analyzerFacts: candidate.analyzerFacts
+    };
+}
+function buildExecutionPrompt(ctx, task) {
+    return [
+        ctx.prompts.buildSystemPrompt(),
+        ctx.prompts.buildTaskPrompt(task),
+        ctx.prompts.buildEditBoundaryPrompt(task),
+        '直接在当前工作区完成修改。完成后请给出简洁摘要，包括修改了哪些测试文件、验证结果和遗留问题。'
+    ].join('\n\n');
+}
+function buildRetryExecutionPrompt(ctx, task, failure) {
+    const failureText = Array.isArray(failure) ? failure.join('\n') : failure ?? '未知验证失败';
+    return [
+        buildExecutionPrompt(ctx, task),
+        ctx.prompts.buildRetryPrompt(task, failureText),
+        '下面是上一轮全量验证失败日志，请只针对这些失败修复测试，不要扩展范围：',
+        failureText
+    ].join('\n\n');
+}
+function truncateLog(text, maxLen = 2000) {
+    if (text.length <= maxLen)
+        return JSON.stringify(text);
+    return JSON.stringify(`${text.slice(0, maxLen)}...<truncated>`);
+}
+async function persistPrompt(ctx, taskId, attemptCount, prompt, targetFile, timestamp) {
+    await ctx.fileSystem.ensureDir(ctx.paths.promptsDir);
+    const fileName = buildRunArtifactName(taskId, attemptCount, targetFile, timestamp, 'prompt');
+    const promptPath = path.join(ctx.paths.promptsDir, fileName);
+    await ctx.fileSystem.writeText(promptPath, prompt);
+    return promptPath;
+}
+async function appendRunPrompt(ctx, taskId, attemptCount, targetFile, timestamp, promptPath) {
+    await ctx.fileSystem.ensureDir(ctx.paths.promptRunsDir);
+    const runPromptPath = path.join(ctx.paths.promptRunsDir, `run-${ctx.runId}.prompt.log`);
+    const attemptLabel = `a${attemptCount}`;
+    const content = [
+        '===== TASK PROMPT START =====',
+        `taskId: ${taskId}`,
+        `attempt: ${attemptCount}`,
+        `attemptLabel: ${attemptLabel}`,
+        `targetFile: ${targetFile}`,
+        `timestamp: ${timestamp}`,
+        `promptPath: ${promptPath}`,
+        `promptFile: ${path.basename(promptPath)}`,
+        '===== TASK PROMPT END =====',
+        ''
+    ].join('\n');
+    await ctx.fileSystem.appendText(runPromptPath, content);
+    return runPromptPath;
+}
+async function appendRunEvent(ctx, record, eventType = 'cli_run_attempt', extraData) {
+    const targetBaseName = path.basename(record.targetFile, path.extname(record.targetFile));
+    const attemptLabel = `a${record.attemptCount}`;
+    await ctx.eventStore.append({
+        eventType,
+        phase: record.status === 'verify_failed' ? 'VERIFYING_FULL' : record.status === 'passed' ? 'DONE' : 'WRITING_TESTS',
+        taskId: record.taskId,
+        message: record.summary,
+        data: {
+            runId: ctx.runId,
+            taskId: record.taskId,
+            attemptLabel,
+            targetBaseName,
+            targetFile: record.targetFile,
+            attemptCount: record.attemptCount,
+            promptPath: record.promptPath,
+            changedTestFiles: record.changedTestFiles,
+            relatedTestFiles: record.relatedTestFiles,
+            verifyResult: record.verifyResult,
+            status: record.status,
+            stdout: record.stdout ? truncateLog(record.stdout, 500) : undefined,
+            stderr: record.stderr ? truncateLog(record.stderr, 500) : undefined,
+            ...extraData
+        },
+        timestamp: ctx.clock.nowIso()
+    });
+}
+function buildPreview(prompt, maxLen = 240) {
+    const compact = prompt.replace(/\s+/g, ' ').trim();
+    return compact.length <= maxLen ? compact : `${compact.slice(0, maxLen)}...`;
+}
+function buildRunArtifactName(taskId, attemptCount, targetFile, timestamp, suffix) {
+    const baseName = path.basename(targetFile, path.extname(targetFile));
+    const safeBaseName = baseName.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-');
+    const pathHash = hashContent(normalizePath(targetFile)).slice(0, 8);
+    const safeTimestamp = formatArtifactTimestamp(timestamp);
+    return `${taskId}-a${attemptCount}-${safeBaseName}-${pathHash}-${safeTimestamp}.${suffix}${suffix === 'prompt' ? '.txt' : '.log'}`;
+}
+function formatArtifactTimestamp(timestamp) {
+    return timestamp.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+function buildTaskOutputPath(ctx, taskId, attemptCount, stream, targetFile, timestamp) {
+    return path.join(ctx.paths.logsPath, buildRunArtifactName(taskId, attemptCount, targetFile, timestamp, stream));
+}
+async function persistOutput(ctx, taskId, attemptCount, stream, targetFile, timestamp, content) {
+    if (!content?.trim())
+        return undefined;
+    await ctx.fileSystem.ensureDir(ctx.paths.logsPath);
+    const outputPath = buildTaskOutputPath(ctx, taskId, attemptCount, stream, targetFile, timestamp);
+    await ctx.fileSystem.writeText(outputPath, content);
+    return outputPath;
+}
+async function captureTestSnapshot(ctx) {
+    const files = await fg(buildTestSnapshotPatterns(ctx.config.testDirNames), {
+        cwd: ctx.projectPath,
+        ignore: ctx.config.exclude,
+        onlyFiles: true,
+        absolute: false
+    });
+    const snapshotEntries = await Promise.all(files.map(async (file) => {
+        const content = await ctx.fileSystem.readText(path.join(ctx.projectPath, file));
+        return [file, hashContent(content ?? '')];
+    }));
+    return Object.fromEntries(snapshotEntries);
+}
+async function validateTestChanges(ctx, task, beforeSnapshot) {
+    const afterSnapshot = await captureTestSnapshot(ctx);
+    const changedTestFiles = Object.keys(afterSnapshot)
+        .filter((file) => beforeSnapshot[file] !== afterSnapshot[file])
+        .sort();
+    const relatedTestFiles = findRelatedTestFiles(task, changedTestFiles);
+    if (relatedTestFiles.length > 0) {
+        ctx.logger.info(`[run] step=test-change status=ok taskId=${task.taskId} target=${task.targetFile} changed=${relatedTestFiles.join(',')}`);
+        return {
+            ok: true,
+            phase: 'DONE',
+            summary: '检测到目标相关测试变更。',
+            targetFile: task.targetFile,
+            changedTestFiles,
+            relatedTestFiles
+        };
+    }
+    ctx.logger.warn(`[run] step=test-change status=noop taskId=${task.taskId} target=${task.targetFile} changed=${changedTestFiles.join(',') || 'none'}`);
+    return {
+        ok: false,
+        phase: 'WRITING_TESTS',
+        summary: `Claude CLI 未产出 ${task.targetFile} 的相关测试变更，本次视为 no-op。`,
+        nextAction: 'manual-intervention',
+        targetFile: task.targetFile,
+        artifacts: {
+            changedTestFiles: changedTestFiles.length > 0 ? changedTestFiles : undefined,
+            relatedTestFiles: relatedTestFiles.length > 0 ? relatedTestFiles : undefined
+        },
+        changedTestFiles,
+        relatedTestFiles
+    };
+}
+function findRelatedTestFiles(task, changedTestFiles) {
+    if (changedTestFiles.length === 0)
+        return [];
+    const existingMatches = new Set(task.testFiles);
+    const baseName = path.basename(task.targetFile, path.extname(task.targetFile));
+    const targetDir = path.dirname(task.targetFile);
+    const normalizedTargetDir = normalizePath(targetDir);
+    const moduleDirName = path.basename(targetDir);
+    return changedTestFiles.filter((file) => {
+        if (existingMatches.has(file))
+            return true;
+        const normalizedFile = normalizePath(file);
+        const fileName = path.basename(file);
+        const fileBaseName = path.basename(fileName, path.extname(fileName));
+        if (fileBaseName === baseName || fileBaseName === `${baseName}.test` || fileBaseName === `${baseName}.spec`) {
+            return true;
+        }
+        if (normalizedFile.startsWith(`${normalizedTargetDir}/`))
+            return true;
+        if (normalizedFile.includes(`/${moduleDirName}/`) && isTestFile(file))
+            return true;
+        return false;
+    });
+}
+function buildTestSnapshotPatterns(testDirNames) {
+    const configured = testDirNames?.filter(Boolean) ?? ['__test__', '__tests__'];
+    return [
+        '**/*.test.*',
+        '**/*.spec.*',
+        ...configured.map((dir) => `**/${dir}/**/*.*`)
+    ];
+}
+function hashContent(content) {
+    return createHash('sha1').update(content).digest('hex');
+}
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+async function markRunFailed(ctx, task, error, loopSummary) {
+    const message = Array.isArray(error) ? error.join('\n') : error ?? 'unknown error';
+    await ctx.stateStore.save({
+        phase: 'BLOCKED',
+        status: 'failed',
+        currentTaskId: task.taskId,
+        lastError: message,
+        loopSummary,
+        totals: {
+            pending: 0,
+            running: 0,
+            passed: 0,
+            failed: 1,
+            blocked: 0
+        },
+        lastAction: 'run',
+        nextSuggestedAction: 'manual-intervention',
+        updatedAt: ctx.clock.nowIso()
+    });
+    await ctx.eventStore.append({
+        eventType: 'cli_run_failed',
+        phase: 'BLOCKED',
+        taskId: task.taskId,
+        message,
+        timestamp: ctx.clock.nowIso()
+    });
+}
+async function markRunPassed(ctx, task, loopSummary) {
+    await ctx.stateStore.save({
+        phase: 'DONE',
+        status: 'done',
+        currentTaskId: task.taskId,
+        loopSummary,
+        totals: {
+            pending: 0,
+            running: 0,
+            passed: 1,
+            failed: 0,
+            blocked: 0
+        },
+        lastAction: 'run',
+        nextSuggestedAction: 'report',
+        updatedAt: ctx.clock.nowIso()
+    });
+    await ctx.eventStore.append({
+        eventType: 'cli_run_completed',
+        phase: 'DONE',
+        taskId: task.taskId,
+        message: `completed ${task.targetFile}`,
+        timestamp: ctx.clock.nowIso()
+    });
+}
+async function buildSuccessResult(ctx, targetFile, recommendedTargets, changedTestFiles, relatedTestFiles) {
+    const report = await buildFinalReport(ctx);
+    await ctx.reportStore.saveFinalReport(report);
+    return {
+        ok: true,
+        phase: 'DONE',
+        summary: `Claude CLI 已完成 ${targetFile} 的补测并通过全量验证。`,
+        nextAction: 'report',
+        targetFile,
+        artifacts: {
+            finalReportPath: ctx.paths.finalReportPath,
+            recommendedTargets,
+            changedTestFiles,
+            relatedTestFiles
+        }
+    };
+}
+function isTestFile(file) {
+    return /(\.test|\.spec)\.[jt]sx?$/.test(file) || file.includes('__test__/') || file.includes('__tests__/');
+}
+async function detectTestDirNames(ctx) {
+    if (ctx.cache.detectedTestDirNames)
+        return ctx.cache.detectedTestDirNames;
+    const configured = ctx.config.testDirNames?.filter(Boolean) ?? ['__test__', '__tests__'];
+    const jestConfigPath = path.join(ctx.projectPath, 'jest.config.js');
+    const jestConfig = await ctx.fileSystem.readText(jestConfigPath);
+    if (!jestConfig) {
+        ctx.cache.detectedTestDirNames = configured;
+        return configured;
+    }
+    const detected = configured.filter((dir) => jestConfig.includes(dir));
+    const result = detected.length > 0 ? detected : configured;
+    ctx.cache.detectedTestDirNames = result;
+    return result;
+}