clawt 2.8.2 → 2.9.0

package/README.md

@@ -331,3 +331,21 @@ feature/a.b  →  feature-a-b
 ## 日志
 
 日志保存在 `~/.clawt/logs/` 目录，按日期滚动，保留 30 天。使用 `--debug` 全局选项可在终端实时查看调试日志。
+
+## 开发
+
+### 测试
+
+项目使用 [Vitest](https://vitest.dev/) 作为测试框架，搭配 `@vitest/coverage-v8` 生成覆盖率报告。
+
+```bash
+# 执行全部测试
+npm test
+
+# 监听模式（文件变更后自动重新运行）
+npm run test:watch
+
+# 执行测试并生成覆盖率报告
+npm run test:coverage
+```
+

package/docs/spec.md

@@ -27,6 +27,10 @@
   - [5.13 重置主 Worktree 工作区和暂存区](#513-重置主-worktree-工作区和暂存区)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
+  - [7.1 性能](#71-性能)
+  - [7.2 兼容性](#72-兼容性)
+  - [7.3 测试](#73-测试)
+  - [7.4 安全性](#74-安全性)
 
 ---
 
@@ -40,6 +44,7 @@
 | CLI 框架 | Commander.js                  |
 | 日志库   | winston (按日期滚动文件)       |
 | 交互式   | enquirer (选项选择/确认对话)   |
+| 测试     | Vitest + @vitest/coverage-v8               |
 | 构建     | tsup / tsc                    |
 | 分发     | pnpm 全局安装 (`pnpm add -g clawt`) |
 
@@ -1155,7 +1160,27 @@ clawt reset
 - Node.js >= 18
 - Git >= 2.15（worktree 功能稳定版本）
 
-### 7.3 安全性
+### 7.3 测试
+
+- 测试框架：Vitest，配置文件为 `vitest.config.ts`
+- 覆盖率工具：@vitest/coverage-v8，覆盖率报告格式为 text、lcov、html
+- 测试目录结构：`tests/unit/` 下按模块分组（`constants/`、`errors/`、`utils/`）
+- 测试辅助文件：
+  - `tests/helpers/setup.ts`：全局 setup，禁用 chalk 颜色输出避免 ANSI 转义码干扰断言
+  - `tests/helpers/fixtures.ts`：测试数据工厂，提供 `createWorktreeInfo()`、`createWorktreeStatus()`、`createWorktreeList()` 等工厂函数
+- 覆盖范围：`src/` 下的 `utils/`、`errors/`、`constants/` 全部关键模块，共 12 个测试文件、163 个测试用例
+- 覆盖率统计排除项：`src/index.ts`（入口文件）、`src/types/**`（类型定义）、`src/logger/**`（日志模块）
+- npm 脚本：
+  - `npm test`：执行全部测试（`vitest run`）
+  - `npm run test:watch`：监听模式（`vitest`）
+  - `npm run test:coverage`：执行测试并生成覆盖率报告（`vitest run --coverage`）
+- 测试配置特性：
+  - `restoreMocks: true`：每个测试后自动恢复 mock
+  - `clearMocks: true`：每个测试后自动清除 mock 调用记录
+  - `testTimeout: 10000`：单个测试超时 10 秒
+  - `environment: 'node'`：使用 Node.js 测试环境
+
+### 7.4 安全性
 
 - 不在日志中记录 Claude Code API 密钥等敏感信息
 - `--permission-mode bypassPermissions` 仅在 worktree 隔离环境中使用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.8.2",
+  "version": "2.9.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",
@@ -24,8 +24,10 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.1",
+    "@vitest/coverage-v8": "^4.0.18",
     "tsup": "^8.3.6",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18"
@@ -33,6 +35,9 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "postinstall": "node dist/postinstall.js",
     "release": "bash scripts/release.sh"
   }

package/tests/helpers/fixtures.ts

@@ -0,0 +1,41 @@
+import type { WorktreeInfo, WorktreeStatus } from '../../src/types/index.js';
+
+/**
+ * 创建测试用 WorktreeInfo
+ * @param {Partial<WorktreeInfo>} overrides - 覆盖字段
+ * @returns {WorktreeInfo} 测试数据
+ */
+export function createWorktreeInfo(overrides: Partial<WorktreeInfo> = {}): WorktreeInfo {
+  return {
+    path: '/Users/test/.clawt/worktrees/my-project/feature-branch',
+    branch: 'feature-branch',
+    ...overrides,
+  };
+}
+
+/**
+ * 创建测试用 WorktreeStatus
+ * @param {Partial<WorktreeStatus>} overrides - 覆盖字段
+ * @returns {WorktreeStatus} 测试数据
+ */
+export function createWorktreeStatus(overrides: Partial<WorktreeStatus> = {}): WorktreeStatus {
+  return {
+    commitCount: 3,
+    insertions: 42,
+    deletions: 10,
+    hasDirtyFiles: false,
+    ...overrides,
+  };
+}
+
+/**
+ * 创建多个测试用 WorktreeInfo
+ * @param {number} count - 数量
+ * @returns {WorktreeInfo[]} 测试数据数组
+ */
+export function createWorktreeList(count: number): WorktreeInfo[] {
+  return Array.from({ length: count }, (_, i) => createWorktreeInfo({
+    path: `/Users/test/.clawt/worktrees/my-project/branch-${i + 1}`,
+    branch: `branch-${i + 1}`,
+  }));
+}

package/tests/helpers/setup.ts

@@ -0,0 +1,2 @@
+// 禁用 chalk 颜色输出，避免 ANSI 转义码干扰断言
+process.env.FORCE_COLOR = '0';

package/tests/unit/constants/config.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { CONFIG_DEFINITIONS, DEFAULT_CONFIG, CONFIG_DESCRIPTIONS } from '../../../src/constants/config.js';
+
+describe('CONFIG_DEFINITIONS', () => {
+  it('所有配置项都有 defaultValue 和 description', () => {
+    for (const [key, def] of Object.entries(CONFIG_DEFINITIONS)) {
+      expect(def).toHaveProperty('defaultValue');
+      expect(def).toHaveProperty('description');
+      expect(typeof def.description).toBe('string');
+      expect(def.description.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('DEFAULT_CONFIG', () => {
+  it('与 CONFIG_DEFINITIONS 的 key 一致', () => {
+    const definitionKeys = Object.keys(CONFIG_DEFINITIONS).sort();
+    const configKeys = Object.keys(DEFAULT_CONFIG).sort();
+    expect(configKeys).toEqual(definitionKeys);
+  });
+
+  it('每个 key 的值等于对应 CONFIG_DEFINITIONS 的 defaultValue', () => {
+    for (const [key, def] of Object.entries(CONFIG_DEFINITIONS)) {
+      expect((DEFAULT_CONFIG as Record<string, unknown>)[key]).toBe(def.defaultValue);
+    }
+  });
+
+  it('包含预期的配置项和默认值', () => {
+    expect(DEFAULT_CONFIG.autoDeleteBranch).toBe(false);
+    expect(DEFAULT_CONFIG.claudeCodeCommand).toBe('claude');
+    expect(DEFAULT_CONFIG.autoPullPush).toBe(false);
+    expect(DEFAULT_CONFIG.confirmDestructiveOps).toBe(true);
+  });
+});
+
+describe('CONFIG_DESCRIPTIONS', () => {
+  it('与 CONFIG_DEFINITIONS 的 key 一致', () => {
+    const definitionKeys = Object.keys(CONFIG_DEFINITIONS).sort();
+    const descriptionKeys = Object.keys(CONFIG_DESCRIPTIONS).sort();
+    expect(descriptionKeys).toEqual(definitionKeys);
+  });
+
+  it('每个 key 的值等于对应 CONFIG_DEFINITIONS 的 description', () => {
+    for (const [key, def] of Object.entries(CONFIG_DEFINITIONS)) {
+      expect((CONFIG_DESCRIPTIONS as Record<string, string>)[key]).toBe(def.description);
+    }
+  });
+
+  it('所有描述值都是非空字符串', () => {
+    for (const desc of Object.values(CONFIG_DESCRIPTIONS)) {
+      expect(typeof desc).toBe('string');
+      expect(desc.length).toBeGreaterThan(0);
+    }
+  });
+});

package/tests/unit/errors/index.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { ClawtError } from '../../../src/errors/index.js';
+import { EXIT_CODES } from '../../../src/constants/index.js';
+
+describe('ClawtError', () => {
+  it('默认退出码为 EXIT_CODES.ERROR (1)', () => {
+    const error = new ClawtError('测试错误');
+    expect(error.exitCode).toBe(EXIT_CODES.ERROR);
+    expect(error.exitCode).toBe(1);
+  });
+
+  it('自定义退出码正确传递', () => {
+    const error = new ClawtError('参数错误', EXIT_CODES.ARGUMENT_ERROR);
+    expect(error.exitCode).toBe(2);
+  });
+
+  it('name 属性为 ClawtError', () => {
+    const error = new ClawtError('测试');
+    expect(error.name).toBe('ClawtError');
+  });
+
+  it('message 正确设置', () => {
+    const error = new ClawtError('具体的错误消息');
+    expect(error.message).toBe('具体的错误消息');
+  });
+
+  it('是 Error 的实例', () => {
+    const error = new ClawtError('测试');
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(ClawtError);
+  });
+});

package/tests/unit/utils/branch.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// mock logger（避免测试时写日志文件）
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+// mock formatter（避免终端输出）
+vi.mock('../../../src/utils/formatter.js', () => ({
+  printWarning: vi.fn(),
+}));
+
+// mock git（checkBranchExists）
+vi.mock('../../../src/utils/git.js', () => ({
+  checkBranchExists: vi.fn(),
+}));
+
+import { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from '../../../src/utils/branch.js';
+import { printWarning } from '../../../src/utils/formatter.js';
+import { checkBranchExists } from '../../../src/utils/git.js';
+import { ClawtError } from '../../../src/errors/index.js';
+
+const mockedCheckBranchExists = vi.mocked(checkBranchExists);
+const mockedPrintWarning = vi.mocked(printWarning);
+
+describe('sanitizeBranchName', () => {
+  it('合法分支名原样返回', () => {
+    expect(sanitizeBranchName('feature-add-login')).toBe('feature-add-login');
+  });
+
+  it('非法字符替换为 -', () => {
+    expect(sanitizeBranchName('feature/add login')).toBe('feature-add-login');
+  });
+
+  it('连续非法字符压缩为单个 -', () => {
+    expect(sanitizeBranchName('feature...add')).toBe('feature-add');
+  });
+
+  it('首尾 - 去除', () => {
+    expect(sanitizeBranchName('.feature-add.')).toBe('feature-add');
+  });
+
+  it('全部非法字符时抛出 ClawtError', () => {
+    expect(() => sanitizeBranchName('...')).toThrow(ClawtError);
+  });
+
+  it('转换时触发 printWarning', () => {
+    sanitizeBranchName('feature/test');
+    expect(mockedPrintWarning).toHaveBeenCalled();
+  });
+
+  it('合法分支名不触发 printWarning', () => {
+    sanitizeBranchName('feature-test');
+    expect(mockedPrintWarning).not.toHaveBeenCalled();
+  });
+});
+
+describe('generateBranchNames', () => {
+  it('count=1 返回 [branchName]', () => {
+    expect(generateBranchNames('feature', 1)).toEqual(['feature']);
+  });
+
+  it('count=3 返回带序号后缀的数组', () => {
+    expect(generateBranchNames('feature', 3)).toEqual([
+      'feature-1',
+      'feature-2',
+      'feature-3',
+    ]);
+  });
+
+  it('count=2 返回带序号后缀的数组', () => {
+    expect(generateBranchNames('test', 2)).toEqual(['test-1', 'test-2']);
+  });
+});
+
+describe('validateBranchesNotExist', () => {
+  it('所有分支不存在时正常通过', () => {
+    mockedCheckBranchExists.mockReturnValue(false);
+    expect(() => validateBranchesNotExist(['a', 'b', 'c'])).not.toThrow();
+  });
+
+  it('有分支存在时抛出 ClawtError', () => {
+    mockedCheckBranchExists.mockReturnValueOnce(false).mockReturnValueOnce(true);
+    expect(() => validateBranchesNotExist(['a', 'b'])).toThrow(ClawtError);
+  });
+
+  it('第一个分支存在时立即抛出', () => {
+    mockedCheckBranchExists.mockReturnValue(true);
+    expect(() => validateBranchesNotExist(['existing'])).toThrow(ClawtError);
+    expect(mockedCheckBranchExists).toHaveBeenCalledTimes(1);
+  });
+});

package/tests/unit/utils/config.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// mock node:fs
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+  writeFileSync: vi.fn(),
+}));
+
+// mock logger
+vi.mock('../../../src/logger/index.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+// mock fs 工具
+vi.mock('../../../src/utils/fs.js', () => ({
+  ensureDir: vi.fn(),
+}));
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { loadConfig, getConfigValue } from '../../../src/utils/config.js';
+import { DEFAULT_CONFIG } from '../../../src/constants/index.js';
+
+const mockedExistsSync = vi.mocked(existsSync);
+const mockedReadFileSync = vi.mocked(readFileSync);
+const mockedWriteFileSync = vi.mocked(writeFileSync);
+
+describe('loadConfig', () => {
+  it('配置文件不存在时返回默认配置', () => {
+    mockedExistsSync.mockReturnValue(false);
+    const config = loadConfig();
+    expect(config).toEqual(DEFAULT_CONFIG);
+  });
+
+  it('配置文件存在时正确合并', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReadFileSync.mockReturnValue(JSON.stringify({ autoDeleteBranch: true }));
+    const config = loadConfig();
+    expect(config.autoDeleteBranch).toBe(true);
+    // 未覆盖的字段保持默认值
+    expect(config.claudeCodeCommand).toBe(DEFAULT_CONFIG.claudeCodeCommand);
+  });
+
+  it('配置文件损坏时返回默认配置并重写', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReadFileSync.mockReturnValue('invalid json {{{');
+    const config = loadConfig();
+    expect(config).toEqual(DEFAULT_CONFIG);
+    // 应该重写默认配置
+    expect(mockedWriteFileSync).toHaveBeenCalled();
+  });
+});
+
+describe('getConfigValue', () => {
+  it('获取指定 key 的值', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReadFileSync.mockReturnValue(JSON.stringify({ autoPullPush: true }));
+    expect(getConfigValue('autoPullPush')).toBe(true);
+  });
+
+  it('未设置时返回默认值', () => {
+    mockedExistsSync.mockReturnValue(false);
+    expect(getConfigValue('confirmDestructiveOps')).toBe(true);
+  });
+});

package/tests/unit/utils/formatter.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi } from 'vitest';
+import { formatWorktreeStatus, printSuccess, printError, printWarning, printInfo } from '../../../src/utils/formatter.js';
+import { createWorktreeStatus } from '../../helpers/fixtures.js';
+
+describe('formatWorktreeStatus', () => {
+  it('有 insertions 和 deletions 时正确格式化', () => {
+    const status = createWorktreeStatus({ commitCount: 5, insertions: 100, deletions: 20 });
+    const result = formatWorktreeStatus(status);
+    expect(result).toContain('5 个提交');
+    expect(result).toContain('+100');
+    expect(result).toContain('-20');
+  });
+
+  it('无变更时显示"无变更"', () => {
+    const status = createWorktreeStatus({ insertions: 0, deletions: 0 });
+    const result = formatWorktreeStatus(status);
+    expect(result).toContain('无变更');
+  });
+
+  it('hasDirtyFiles 时显示"(未提交修改)"', () => {
+    const status = createWorktreeStatus({ hasDirtyFiles: true });
+    const result = formatWorktreeStatus(status);
+    expect(result).toContain('(未提交修改)');
+  });
+
+  it('hasDirtyFiles 为 false 时不显示"(未提交修改)"', () => {
+    const status = createWorktreeStatus({ hasDirtyFiles: false });
+    const result = formatWorktreeStatus(status);
+    expect(result).not.toContain('(未提交修改)');
+  });
+
+  it('仅有 insertions 时不显示"无变更"', () => {
+    const status = createWorktreeStatus({ insertions: 10, deletions: 0 });
+    const result = formatWorktreeStatus(status);
+    expect(result).not.toContain('无变更');
+    expect(result).toContain('+10');
+    expect(result).toContain('-0');
+  });
+});
+
+describe('print 函数', () => {
+  it('printSuccess 调用 console.log', () => {
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    printSuccess('成功消息');
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.mock.calls[0][0]).toContain('成功消息');
+  });
+
+  it('printError 调用 console.error', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    printError('错误消息');
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.mock.calls[0][0]).toContain('错误消息');
+  });
+
+  it('printWarning 调用 console.log', () => {
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    printWarning('警告消息');
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.mock.calls[0][0]).toContain('警告消息');
+  });
+
+  it('printInfo 调用 console.log', () => {
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    printInfo('普通消息');
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.mock.calls[0][0]).toBe('普通消息');
+  });
+});

package/tests/unit/utils/fs.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// mock node:fs
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  mkdirSync: vi.fn(),
+  readdirSync: vi.fn(),
+  rmdirSync: vi.fn(),
+}));
+
+import { existsSync, mkdirSync, readdirSync, rmdirSync } from 'node:fs';
+import { ensureDir, removeEmptyDir } from '../../../src/utils/fs.js';
+
+const mockedExistsSync = vi.mocked(existsSync);
+const mockedMkdirSync = vi.mocked(mkdirSync);
+const mockedReaddirSync = vi.mocked(readdirSync);
+const mockedRmdirSync = vi.mocked(rmdirSync);
+
+describe('ensureDir', () => {
+  it('目录不存在时创建', () => {
+    mockedExistsSync.mockReturnValue(false);
+    ensureDir('/tmp/test-dir');
+    expect(mockedMkdirSync).toHaveBeenCalledWith('/tmp/test-dir', { recursive: true });
+  });
+
+  it('目录已存在时不操作', () => {
+    mockedExistsSync.mockReturnValue(true);
+    ensureDir('/tmp/test-dir');
+    expect(mockedMkdirSync).not.toHaveBeenCalled();
+  });
+});
+
+describe('removeEmptyDir', () => {
+  it('空目录删除返回 true', () => {
+    mockedExistsSync.mockReturnValue(true);
+    mockedReaddirSync.mockReturnValue([]);
+    expect(removeEmptyDir('/tmp/empty-dir')).toBe(true);
+    expect(mockedRmdirSync).toHaveBeenCalledWith('/tmp/empty-dir');
+  });
+
+  it('非空目录不删除返回 false', () => {
+    mockedExistsSync.mockReturnValue(true);
+    // @ts-expect-error readdirSync 返回的类型比较复杂，这里简化处理
+    mockedReaddirSync.mockReturnValue(['file.txt']);
+    expect(removeEmptyDir('/tmp/non-empty-dir')).toBe(false);
+    expect(mockedRmdirSync).not.toHaveBeenCalled();
+  });
+
+  it('目录不存在时返回 false', () => {
+    mockedExistsSync.mockReturnValue(false);
+    expect(removeEmptyDir('/tmp/no-dir')).toBe(false);
+    expect(mockedReaddirSync).not.toHaveBeenCalled();
+  });
+});