@angli/unit-test-tool 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Edit(*)",
+      "Write(*)",
+      "Read(*)",
+      "Skill(claude-api)",
+      "Skill(claude-api:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/README.md

@@ -0,0 +1,232 @@
+# TestBot（unit-test-tool）
+
+面向项目的单元测试补全工具，基于 CLI 工作流完成基线分析、推荐测试目标，并调用 Claude CLI 进行补测。
+
+## 适用场景
+
+- 需要快速提升项目单测覆盖率
+- 希望以可控参数（覆盖率目标、扫描目录、指定文件）进行补测
+- 想将“分析 → 补测 → 验证 → 汇总”串成自动化流程
+
+## 依赖与准备
+
+- 需要本地可用的 Claude CLI（用于 `run` / `start` 补测流程）
+- 在目标项目路径下可运行测试/校验命令（可通过参数覆盖）
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g @angli/unit-test-tool
+```
+
+安装后可直接使用：
+
+```bash
+testbot --help
+```
+
+## 命令概览（保留关键命令）
+
+- `testbot init`：初始化配置
+- `testbot analyze`：基线分析
+- `testbot run`：单次调用 Claude CLI 补测
+- `testbot start`：初始化 + 基线分析 + 循环补测 + 状态汇总
+- `testbot verify`：完整验证
+- `testbot status`：输出状态
+- `testbot report`：生成最终报告
+- `testbot guard`：检测异常并尝试恢复
+- `testbot schedule`：定时执行 guard
+
+## 参数说明（表格）
+
+> 说明：以下为各命令支持的参数集合，不同命令支持的参数略有差异。
+
+| 参数 | 说明 | 默认值 | 适用命令 |
+|---|---|---|---|
+| `--project <path>` | 项目路径 | `process.cwd()` 或必填 | `init`（必填）、`analyze`、`run`、`start`、`verify`、`status`、`report` |
+| `--target <number>` | 覆盖率目标 | `80` | `init`、`analyze`、`run`、`start` |
+| `--scan-dir <dir>` | 扫描目录 | `src` | `init`、`analyze`、`run`、`start` |
+| `--file <path>` | 指定目标源文件 | 无 | `run`、`start` |
+| `--topN <number>` | 推荐池大小 | `5` | `run`、`start` |
+| `--permission-mode <mode>` | Claude CLI 权限模式 | 无 | `run`、`start` |
+| `--allowed-tools <tools>` | Claude CLI 允许工具列表（逗号分隔） | 无 | `run`、`start` |
+| `--timeout <ms>` | Claude CLI 超时（毫秒） | 无 | `run`、`start` |
+| `--verify-cmd <cmd>` | 覆盖完整验证命令 | 无 | `init`、`run`、`start` |
+| `--lint-cmd <cmd>` | 覆盖 lint 命令 | 无 | `init`、`run`、`start` |
+| `--typecheck-cmd <cmd>` | 覆盖类型检查命令 | 无 | `init`、`run`、`start` |
+| `--system-append <text>` | 追加项目级 system prompt 规则 | 无 | `init` |
+| `--task-append <text>` | 追加项目级 task prompt 规则 | 无 | `init` |
+| `--retry-append <text>` | 追加项目级 retry prompt 规则 | 无 | `init` |
+| `--schedule` | 在 `start` 期间启用内置守护循环 | `false` | `start` |
+| `--guard-interval <duration>` | 守护检查间隔 | `5m` | `start` |
+| `--interval <duration>` | 定时 guard 间隔 | `5m` | `schedule` |
+| `--stale-timeout <duration>` | heartbeat 超时阈值 | `2m` | `guard`、`schedule`、`start` |
+| `--max-restart <count>` | 最大自动恢复次数 | `3` | `guard`、`schedule`、`start` |
+| `--cooldown <duration>` | 两次恢复的冷却时间 | `60s` | `guard`、`schedule`、`start` |
+
+## 日志与回放
+
+运行时产物位于目标项目的 `.unit_test_tool_workspace/` 目录。
+
+### 目录结构
+
+- `logs/`：stdout/stderr 日志、`events.jsonl`
+- `prompts/`：每个任务独立的 prompt 文件
+- `prompt-runs/`：按一次 attempt 追加的整轮 prompt 索引/引用日志
+- `reports/`：coverage summary / final report
+
+### events.jsonl 怎么看
+
+`events.jsonl` 是 JSONL 格式，一行一个事件。常见事件类型：
+
+- `cli_run_started`：选中目标文件
+- `cli_run_attempt`：开始调用 Claude CLI（含 prompt 路径）
+- `cli_run_completed`：本轮成功
+- `cli_run_failed`：本轮失败或 no-op
+- `baseline_analyzed`：基线分析完成
+
+建议优先关注 `data` 里的这些字段：
+
+- `runId`：本次运行批次（例如 `r20260403T022232Z`）
+- `taskId`：任务 ID（例如 `r20260403T022232Z-001`）
+- `attemptLabel`：尝试标记（例如 `a1`）
+- `targetBaseName`：目标文件 basename
+- `promptPath / stdoutPath / stderrPath`：任务级产物路径
+- `runPromptPath`：整轮 prompt 汇总文件路径
+
+### 文件名组成规则
+
+任务级产物文件名统一遵循：
+
+```
+{taskId}-a{attempt}-{baseName}-{pathHash}-{timestamp}.{kind}.{ext}
+```
+
+示例：
+
+```
+r20260403T022232Z-001-a1-corpus-vue-4e2b1c9a-20260403T022232Z.prompt.txt
+r20260403T022232Z-001-a1-corpus-vue-4e2b1c9a-20260403T022232Z.stdout.log
+r20260403T022232Z-001-a1-corpus-vue-4e2b1c9a-20260403T022232Z.stderr.log
+```
+
+字段含义：
+
+- `taskId`：`runId + 序号`
+- `attempt`：第几次尝试
+- `baseName`：目标文件 basename
+- `pathHash`：目标文件路径 hash（短 hash）
+- `timestamp`：本次 attempt 的时间戳
+- `kind`：`prompt` / `stdout` / `stderr`
+
+### run 级 prompt 汇总文件
+
+整轮流程的 prompt 汇总写到单个文件（不再内嵌 prompt 正文，改为记录 prompt 文件路径）：
+
+```
+run-{runId}.prompt.log
+```
+
+查看完整 prompt 内容，请到 `prompts/*.prompt.txt`。
+
+推荐排查顺序：
+
+1. `state.json` / `final-report.json`
+2. `logs/events.jsonl`
+3. `prompts/` 和 `logs/` 里的单任务产物
+4. `prompt-runs/` 里的整轮回放
+
+
+### 1) 初始化配置
+
+```bash
+testbot init --project /path/to/project --target 85 --scan-dir src
+```
+
+如需给某个项目追加测试生成规则，可在初始化时一并写入：
+
+```bash
+testbot init \
+  --project /path/to/project \
+  --target 85 \
+  --system-append "项目里大量使用 provide/inject，优先复用现有 context 装配方式" \
+  --task-append "涉及表格组件时，优先断言列配置和事件，不做整表 DOM 快照" \
+  --retry-append "如果 wrapper 测试连续失败，退回到 render 参数和事件透传断言"
+```
+
+### 2) 仅做基线分析
+
+```bash
+testbot analyze --project /path/to/project --target 80
+```
+
+### 3) 单次补测（可指定文件）
+
+```bash
+testbot run --project /path/to/project --file src/foo.ts --topN 3 --permission-mode ask
+```
+
+### 4) 一站式流程（初始化 + 分析 + 循环补测 + 状态）
+
+```bash
+testbot start --project /path/to/project --target 80 --topN 5
+```
+
+### 5) 完整验证与状态
+
+```bash
+testbot verify --project /path/to/project
+
+testbot status --project /path/to/project
+```
+
+### 7) 守护与定时恢复
+
+```bash
+testbot guard --project /path/to/project
+
+testbot schedule --project /path/to/project --interval 5m
+
+# 在 start 期间启用守护
+
+testbot start --project /path/to/project --schedule --guard-interval 5m
+```
+
+### 8) Claude CLI 项目级配置
+
+补测执行时会优先读取“待补测项目目录”下的 `.claude/settings.local.json`，并使用其中 `env` 的 `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` 覆盖全局环境变量。
+
+示例：
+
+```json
+{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "...",
+    "ANTHROPIC_BASE_URL": "..."
+  }
+}
+```
+
+### 9) config.json 中的 promptOverrides
+
+`testbot init` 写入的 `.unit_test_tool_workspace/config.json` 支持项目级 prompt 覆盖。工具会先使用内置“通用单测策略 + 案例片段库”，再追加这里的覆盖内容。
+
+示例：
+
+```json
+{
+  "projectPath": "/path/to/project",
+  "coverageTarget": 85,
+  "include": ["src/**/*"],
+  "exclude": ["node_modules/**", "dist/**", "coverage/**"],
+  "mode": "serial",
+  "concurrency": 1,
+  "promptOverrides": {
+    "systemAppend": "项目里大量使用 provide/inject，生成测试前先识别上下文注入入口。",
+    "taskAppend": "表格/列表组件优先测列配置、事件和状态切换，不做大段 DOM 快照。",
+    "retryAppend": "render/HOC 测试连续失败时，回退到参数透传和派生 props 断言。"
+  }
+}
+```

package/dist/src/cli/commands/analyze.js

@@ -0,0 +1,20 @@
+import { createContext } from '../context/create-context.js';
+import { analyzeBaseline } from '../../core/tools/analyze-baseline.js';
+import { buildIncludeFromScanDir } from '../utils/scan-dir.js';
+export function registerAnalyzeCommand(program) {
+    program
+        .command('analyze')
+        .option('--project <path>', 'project path')
+        .option('--target <number>', 'coverage target', '80')
+        .option('--scan-dir <dir>', 'scan dir (default: src)')
+        .action(async (options) => {
+        const include = buildIncludeFromScanDir(options.scanDir ?? 'src');
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: Number(options.target),
+            configOverrides: include ? { include } : undefined
+        });
+        const result = await analyzeBaseline(ctx);
+        console.log(result.summary);
+    });
+}

package/dist/src/cli/commands/guard.js

@@ -0,0 +1,26 @@
+import { createContext } from '../context/create-context.js';
+import { runGuard } from '../../core/tools/guard.js';
+import { parseDuration } from '../../utils/duration.js';
+export function registerGuardCommand(program) {
+    program
+        .command('guard')
+        .option('--project <path>', 'project path')
+        .option('--stale-timeout <duration>', 'heartbeat stale timeout (default: 2m)')
+        .option('--max-restart <count>', 'max restart attempts (default: 3)')
+        .option('--cooldown <duration>', 'restart cooldown (default: 60s)')
+        .action(async (options) => {
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: 80
+        });
+        const staleTimeoutMs = options.staleTimeout ? parseDuration(options.staleTimeout) : undefined;
+        const cooldownMs = options.cooldown ? parseDuration(options.cooldown) : undefined;
+        const maxRestart = options.maxRestart ? Number(options.maxRestart) : undefined;
+        const result = await runGuard(ctx, {
+            staleTimeoutMs: staleTimeoutMs,
+            maxRestart,
+            cooldownMs
+        });
+        console.log(result.summary);
+    });
+}

package/dist/src/cli/commands/init.js

@@ -0,0 +1,39 @@
+import { createContext } from '../context/create-context.js';
+import { buildIncludeFromScanDir } from '../utils/scan-dir.js';
+export function registerInitCommand(program) {
+    program
+        .command('init')
+        .requiredOption('--project <path>', 'project path')
+        .option('--target <number>', 'coverage target', '80')
+        .option('--scan-dir <dir>', 'scan dir (default: src)')
+        .option('--verify-cmd <cmd>', 'override full verify command')
+        .option('--lint-cmd <cmd>', 'override lint command')
+        .option('--typecheck-cmd <cmd>', 'override typecheck command')
+        .option('--system-append <text>', 'append project-level system prompt guidance')
+        .option('--task-append <text>', 'append project-level task prompt guidance')
+        .option('--retry-append <text>', 'append project-level retry prompt guidance')
+        .action(async (options) => {
+        const include = buildIncludeFromScanDir(options.scanDir ?? 'src');
+        const commandOverrides = {
+            ...(options.verifyCmd ? { verifyFull: options.verifyCmd } : {}),
+            ...(options.lintCmd ? { lint: options.lintCmd } : {}),
+            ...(options.typecheckCmd ? { typecheck: options.typecheckCmd } : {})
+        };
+        const promptOverrides = {
+            ...(options.systemAppend ? { systemAppend: options.systemAppend } : {}),
+            ...(options.taskAppend ? { taskAppend: options.taskAppend } : {}),
+            ...(options.retryAppend ? { retryAppend: options.retryAppend } : {})
+        };
+        const ctx = await createContext({
+            projectPath: options.project,
+            coverageTarget: Number(options.target),
+            configOverrides: {
+                ...(include ? { include } : {}),
+                ...(Object.keys(commandOverrides).length > 0 ? { commandOverrides } : {}),
+                ...(Object.keys(promptOverrides).length > 0 ? { promptOverrides } : {})
+            }
+        });
+        await ctx.fileSystem.writeJson(ctx.paths.configPath, ctx.config);
+        console.log('config saved');
+    });
+}

package/dist/src/cli/commands/run.js

@@ -0,0 +1,72 @@
+import { createContext } from '../context/create-context.js';
+import { buildIncludeFromScanDir } from '../utils/scan-dir.js';
+import { runWithClaudeCli } from '../../core/tools/run-with-claude-cli.js';
+import { startLifecycle } from '../../utils/process-lifecycle.js';
+export function registerRunCommand(program) {
+    program
+        .command('run')
+        .option('--project <path>', 'project path')
+        .option('--target <number>', 'coverage target', '80')
+        .option('--scan-dir <dir>', 'scan dir (default: src)')
+        .option('--file <path>', 'explicit target source file')
+        .option('--topN <number>', 'recommendation pool size', '5')
+        .option('--permission-mode <mode>', 'Claude CLI permission mode')
+        .option('--allowed-tools <tools>', 'comma-separated Claude CLI allowed tools')
+        .option('--timeout <ms>', 'Claude CLI timeout in ms')
+        .option('--verify-cmd <cmd>', 'override full verify command')
+        .option('--lint-cmd <cmd>', 'override lint command')
+        .option('--typecheck-cmd <cmd>', 'override typecheck command')
+        .action(async (options) => {
+        const include = buildIncludeFromScanDir(options.scanDir ?? 'src');
+        const commandOverrides = {
+            ...(options.verifyCmd ? { verifyFull: options.verifyCmd } : {}),
+            ...(options.lintCmd ? { lint: options.lintCmd } : {}),
+            ...(options.typecheckCmd ? { typecheck: options.typecheckCmd } : {})
+        };
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: Number(options.target),
+            configOverrides: {
+                ...(include ? { include } : {}),
+                ...(Object.keys(commandOverrides).length > 0 ? { commandOverrides } : {})
+            }
+        });
+        await ctx.fileSystem.writeJson(ctx.paths.configPath, ctx.config);
+        const lifecycle = await startLifecycle(ctx, {
+            command: 'run',
+            argv: process.argv.slice(2)
+        });
+        try {
+            const result = await runWithClaudeCli(ctx, {
+                targetFile: options.file,
+                topN: Number(options.topN),
+                permissionMode: options.permissionMode,
+                allowedTools: parseAllowedTools(options.allowedTools),
+                timeoutMs: options.timeout ? Number(options.timeout) : undefined
+            });
+            console.log(result.summary);
+            if (result.artifacts?.finalReportPath) {
+                console.log(`report: ${result.artifacts.finalReportPath}`);
+            }
+            await lifecycle.stop();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await ctx.lifecycleStore.patch({
+                status: 'crashed',
+                lastError: message,
+                updatedAt: ctx.clock.nowIso()
+            });
+            throw error;
+        }
+    });
+}
+function parseAllowedTools(value) {
+    if (!value)
+        return undefined;
+    const tools = value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return tools.length > 0 ? tools : undefined;
+}

package/dist/src/cli/commands/schedule.js

@@ -0,0 +1,29 @@
+import { createContext } from '../context/create-context.js';
+import { parseDuration } from '../../utils/duration.js';
+import { runSchedule } from '../../core/tools/guard.js';
+const DEFAULT_INTERVAL_MS = 5 * 60_000;
+export function registerScheduleCommand(program) {
+    program
+        .command('schedule')
+        .option('--project <path>', 'project path')
+        .option('--interval <duration>', 'guard interval (default: 5m)')
+        .option('--stale-timeout <duration>', 'heartbeat stale timeout (default: 2m)')
+        .option('--max-restart <count>', 'max restart attempts (default: 3)')
+        .option('--cooldown <duration>', 'restart cooldown (default: 60s)')
+        .action(async (options) => {
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: 80
+        });
+        const intervalMs = options.interval ? parseDuration(options.interval) ?? DEFAULT_INTERVAL_MS : DEFAULT_INTERVAL_MS;
+        const staleTimeoutMs = options.staleTimeout ? parseDuration(options.staleTimeout) : undefined;
+        const cooldownMs = options.cooldown ? parseDuration(options.cooldown) : undefined;
+        const maxRestart = options.maxRestart ? Number(options.maxRestart) : undefined;
+        console.log(`[schedule] interval=${intervalMs}ms`);
+        await runSchedule(ctx, intervalMs, {
+            staleTimeoutMs,
+            maxRestart,
+            cooldownMs
+        });
+    });
+}

package/dist/src/cli/commands/start.js

@@ -0,0 +1,102 @@
+import { createContext } from '../context/create-context.js';
+import { analyzeBaseline } from '../../core/tools/analyze-baseline.js';
+import { runLoop } from '../../core/tools/run-loop.js';
+import { reportStatus } from '../../core/reporter/index.js';
+import { buildIncludeFromScanDir } from '../utils/scan-dir.js';
+import { startLifecycle } from '../../utils/process-lifecycle.js';
+import { runSchedule } from '../../core/tools/guard.js';
+import { parseDuration } from '../../utils/duration.js';
+const DEFAULT_GUARD_INTERVAL_MS = 5 * 60_000;
+export function registerStartCommand(program) {
+    program
+        .command('start')
+        .option('--project <path>', 'project path')
+        .option('--target <number>', 'coverage target', '80')
+        .option('--topN <number>', 'recommendation pool size', '5')
+        .option('--scan-dir <dir>', 'scan dir (default: src)')
+        .option('--file <path>', 'explicit target source file')
+        .option('--permission-mode <mode>', 'Claude CLI permission mode')
+        .option('--allowed-tools <tools>', 'comma-separated Claude CLI allowed tools')
+        .option('--timeout <ms>', 'Claude CLI timeout in ms')
+        .option('--verify-cmd <cmd>', 'override full verify command')
+        .option('--lint-cmd <cmd>', 'override lint command')
+        .option('--typecheck-cmd <cmd>', 'override typecheck command')
+        .option('--schedule', 'run built-in guard schedule')
+        .option('--guard-interval <duration>', 'guard interval (default: 5m)')
+        .option('--stale-timeout <duration>', 'heartbeat stale timeout (default: 2m)')
+        .option('--max-restart <count>', 'max restart attempts (default: 3)')
+        .option('--cooldown <duration>', 'restart cooldown (default: 60s)')
+        .action(async (options) => {
+        const include = buildIncludeFromScanDir(options.scanDir ?? 'src');
+        const commandOverrides = {
+            ...(options.verifyCmd ? { verifyFull: options.verifyCmd } : {}),
+            ...(options.lintCmd ? { lint: options.lintCmd } : {}),
+            ...(options.typecheckCmd ? { typecheck: options.typecheckCmd } : {})
+        };
+        console.log('[1/4] 初始化配置...');
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: Number(options.target),
+            configOverrides: {
+                ...(include ? { include } : {}),
+                ...(Object.keys(commandOverrides).length > 0 ? { commandOverrides } : {})
+            }
+        });
+        await ctx.fileSystem.writeJson(ctx.paths.configPath, ctx.config);
+        console.log(`[1/4] 初始化完成：${ctx.paths.configPath}`);
+        const lifecycle = await startLifecycle(ctx, {
+            command: 'start',
+            argv: process.argv.slice(2)
+        });
+        try {
+            if (options.schedule) {
+                const intervalMs = options.guardInterval ? parseDuration(options.guardInterval) ?? DEFAULT_GUARD_INTERVAL_MS : DEFAULT_GUARD_INTERVAL_MS;
+                const staleTimeoutMs = options.staleTimeout ? parseDuration(options.staleTimeout) : undefined;
+                const cooldownMs = options.cooldown ? parseDuration(options.cooldown) : undefined;
+                const maxRestart = options.maxRestart ? Number(options.maxRestart) : undefined;
+                await runSchedule(ctx, intervalMs, {
+                    staleTimeoutMs,
+                    maxRestart,
+                    cooldownMs
+                });
+            }
+            console.log('[2/4] 开始基线分析...');
+            const baseline = await analyzeBaseline(ctx);
+            console.log(`[2/4] ${baseline.summary}`);
+            console.log('[3/4] 调用 Claude CLI 补测...');
+            const runResult = await runLoop(ctx, {
+                targetFile: options.file,
+                topN: Number(options.topN),
+                permissionMode: options.permissionMode,
+                allowedTools: parseAllowedTools(options.allowedTools),
+                timeoutMs: options.timeout ? Number(options.timeout) : undefined
+            });
+            console.log(`[3/4] ${runResult.summary}`);
+            console.log('[4/4] 输出状态...');
+            const status = await reportStatus(ctx);
+            console.log(`[4/4] ${status.summary}`);
+            if (runResult.artifacts?.finalReportPath) {
+                console.log(`[4/4] report generated: ${runResult.artifacts.finalReportPath}`);
+            }
+            await lifecycle.stop();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await ctx.lifecycleStore.patch({
+                status: 'crashed',
+                lastError: message,
+                updatedAt: ctx.clock.nowIso()
+            });
+            throw error;
+        }
+    });
+}
+function parseAllowedTools(value) {
+    if (!value)
+        return undefined;
+    const tools = value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return tools.length > 0 ? tools : undefined;
+}

package/dist/src/cli/commands/status.js

@@ -0,0 +1,27 @@
+import { createContext } from '../context/create-context.js';
+import { reportStatus, buildFinalReport } from '../../core/reporter/index.js';
+export function registerStatusCommand(program) {
+    program
+        .command('status')
+        .option('--project <path>', 'project path')
+        .action(async (options) => {
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: 80
+        });
+        const result = await reportStatus(ctx);
+        console.log(result.summary);
+    });
+    program
+        .command('report')
+        .option('--project <path>', 'project path')
+        .action(async (options) => {
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: 80
+        });
+        const report = await buildFinalReport(ctx);
+        await ctx.reportStore.saveFinalReport(report);
+        console.log('report generated');
+    });
+}

package/dist/src/cli/commands/verify.js

@@ -0,0 +1,15 @@
+import { createContext } from '../context/create-context.js';
+import { verifyAll } from '../../core/tools/verify-all.js';
+export function registerVerifyCommand(program) {
+    program
+        .command('verify')
+        .option('--project <path>', 'project path')
+        .action(async (options) => {
+        const ctx = await createContext({
+            projectPath: options.project ?? process.cwd(),
+            coverageTarget: 80
+        });
+        const result = await verifyAll(ctx);
+        console.log(result.summary);
+    });
+}