@zjex/git-workflow 0.4.0 → 0.4.2

package/CODE_DOCUMENTATION.md

@@ -1,169 +0,0 @@
-# 代码文档说明
-
-## 已添加详细注释的文件
-
-### ✅ src/commands/commit.ts
-
-**功能**: 交互式提交命令，支持 AI 自动生成和手动编写
-
-**注释内容**:
-
-- 模块级注释：说明 Conventional Commits 和 Gitmoji 规范
-- 函数注释：每个函数都有 JSDoc 注释
-- 步骤标记：用 `==========` 分隔不同的处理步骤
-- 行内注释：关键逻辑都有说明
-
-**关键函数**:
-
-- `commit()`: 主函数，处理整个提交流程
-- `buildManualCommitMessage()`: 手动构建 commit message
-- `parseGitStatus()`: 解析 git 状态
-- `formatFileStatus()`: 格式化文件状态显示
-
-### ✅ src/index.ts
-
-**功能**: 主入口文件，CLI 应用初始化和命令注册
-
-**注释内容**:
-
-- 模块级注释：说明文件职责
-- 全局错误处理：Ctrl+C、未捕获异常、Promise 拒绝
-- 版本信息：构建时注入
-- 交互式主菜单：ASCII Logo 和命令选择
-- CLI 命令注册：所有命令的注册和配置
-
-## 其他文件状态
-
-### ✅ 无错误的文件（已通过 TypeScript 检查）
-
-- src/ai-service.ts
-- src/config.ts
-- src/utils.ts
-- src/update-notifier.ts
-- src/commands/branch.ts
-- src/commands/help.ts
-- src/commands/init.ts
-- src/commands/release.ts
-- src/commands/stash.ts
-- src/commands/tag.ts
-- src/commands/update.ts
-
-## 代码质量改进
-
-### 1. 类型安全
-
-- 所有函数都有明确的返回类型
-- 使用 TypeScript 的类型推导
-- 接口定义清晰（如 `FileStatus`）
-
-### 2. 错误处理
-
-- 全局错误捕获
-- 优雅的 Ctrl+C 处理
-- 详细的错误提示信息
-- 提供手动执行命令
-
-### 3. 用户体验
-
-- 提交前检查暂存文件
-- 清晰的步骤分隔
-- 彩色输出和 emoji
-- 交互式选择界面
-
-### 4. 代码组织
-
-- 模块化设计
-- 单一职责原则
-- 清晰的函数命名
-- 详细的注释说明
-
-## 关键改进点
-
-### commit.ts
-
-1. **修复了 `message` 变量未初始化问题**
-
-   - 初始化为空字符串
-   - 确保所有代码路径都会赋值
-
-2. **添加提交前检查**
-
-   - 再次验证是否有暂存文件
-   - 避免空提交
-
-3. **改进错误提示**
-
-   - 显示完整错误信息
-   - 提供手动执行命令
-
-4. **修复 refactor 对齐问题**
-   - 针对 ♻️ emoji 特殊处理
-   - 动态调整间距
-
-### index.ts
-
-1. **完善错误处理**
-
-   - 捕获所有类型的错误
-   - 优雅退出
-
-2. **添加模块说明**
-   - 清晰的文件职责
-   - 详细的功能说明
-
-## 建议
-
-如果需要给其他文件添加详细注释，可以按照以下优先级：
-
-1. **高优先级**（核心业务逻辑）:
-
-   - src/ai-service.ts - AI commit 生成
-   - src/config.ts - 配置管理
-   - src/commands/tag.ts - Tag 管理
-
-2. **中优先级**（常用功能）:
-
-   - src/commands/branch.ts - 分支管理
-   - src/commands/stash.ts - Stash 管理
-   - src/update-notifier.ts - 更新检查
-
-3. **低优先级**（辅助功能）:
-   - src/utils.ts - 工具函数
-   - src/commands/help.ts - 帮助信息
-   - src/commands/init.ts - 初始化配置
-
-## 注释规范
-
-### JSDoc 注释格式
-
-```typescript
-/**
- * 函数简短描述
- *
- * 详细说明（可选）
- *
- * @param paramName 参数说明
- * @returns 返回值说明
- */
-```
-
-### 行内注释
-
-```typescript
-// 简短说明当前代码的作用
-const result = doSomething();
-```
-
-### 步骤标记
-
-```typescript
-// ========== 步骤 1: 处理输入 ==========
-// ========== 步骤 2: 验证数据 ==========
-```
-
-## 总结
-
-✅ 核心文件已添加详细注释
-✅ 所有文件通过 TypeScript 检查
-✅ 代码质量和可维护性显著提升
-✅ 用户体验得到改善

package/TESTING.md

@@ -1,436 +0,0 @@
-# 测试体系说明
-
-## 为什么需要测试？
-
-在开发 CLI 工具时，测试能够：
-
-1. **防止回归** - 确保新功能不会破坏现有功能
-2. **提高信心** - 重构代码时更有底气
-3. **文档作用** - 测试用例本身就是最好的使用示例
-4. **快速反馈** - 比手动测试快得多
-
-## 测试框架选择
-
-我们选择 **Vitest** 的原因：
-
-- ✅ 快速 - 基于 Vite，启动和运行都很快
-- ✅ 兼容 Jest - API 与 Jest 几乎完全兼容
-- ✅ ESM 原生支持 - 无需额外配置
-- ✅ TypeScript 支持 - 开箱即用
-- ✅ UI 界面 - 提供可视化测试界面
-- ✅ 覆盖率报告 - 内置覆盖率工具
-
-## 测试结构
-
-```
-tests/
-├── utils.test.ts      # 工具函数测试
-├── tag.test.ts        # Tag 功能测试
-├── commit.test.ts     # Commit 功能测试
-└── README.md          # 测试指南
-```
-
-## 当前测试覆盖
-
-### Tag 功能 ✅
-
-- [x] 前缀提取（v, g, release-, 无前缀）
-- [x] Tag 分组逻辑
-- [x] 显示逻辑（最多 5 个）
-- [x] 列宽计算
-- [x] 省略号显示
-
-### Commit 功能 ✅
-
-- [x] 提交类型定义
-- [x] 提交消息格式
-- [x] Refactor 对齐处理
-- [x] Emoji 使用
-
-### Utils 功能 ✅
-
-- [x] 字符串操作
-- [x] 基本工具函数
-
-## 运行测试
-
-### 基本命令
-
-```bash
-# 运行所有测试（单次）
-npm test
-
-# 监听模式（开发时使用）
-npm run test:watch
-
-# 可视化界面
-npm run test:ui
-
-# 生成覆盖率报告
-npm run test:coverage
-```
-
-### 运行特定测试
-
-```bash
-# 只运行 tag 相关测试
-npx vitest tests/tag.test.ts
-
-# 只运行匹配的测试
-npx vitest -t "前缀提取"
-
-# 运行并查看详细输出
-npx vitest --reporter=verbose
-```
-
-## 编写测试
-
-### 基本示例
-
-```typescript
-import { describe, it, expect } from "vitest";
-
-describe("功能模块", () => {
-  it("应该做某事", () => {
-    const result = someFunction();
-    expect(result).toBe(expectedValue);
-  });
-});
-```
-
-### 测试分组
-
-```typescript
-describe("Tag 功能", () => {
-  describe("前缀提取", () => {
-    it("应该提取 v 前缀", () => {
-      // 测试代码
-    });
-
-    it("应该处理无前缀", () => {
-      // 测试代码
-    });
-  });
-
-  describe("Tag 分组", () => {
-    it("应该按前缀分组", () => {
-      // 测试代码
-    });
-  });
-});
-```
-
-### Mock 外部依赖
-
-```typescript
-import { vi } from "vitest";
-import { execSync } from "child_process";
-
-// Mock 整个模块
-vi.mock("child_process");
-
-it("应该调用 git 命令", () => {
-  const mockExecSync = vi.mocked(execSync);
-  mockExecSync.mockReturnValue("v0.1.0\nv0.2.0");
-
-  // 测试代码...
-
-  expect(mockExecSync).toHaveBeenCalledWith("git tag -l");
-});
-```
-
-### 测试异步代码
-
-```typescript
-it("应该异步获取数据", async () => {
-  const result = await fetchData();
-  expect(result).toBeDefined();
-});
-```
-
-## CI/CD 集成
-
-### GitHub Actions
-
-已配置 `.github/workflows/test.yml`：
-
-```yaml
-name: Test
-
-on:
-  push:
-    branches: [main, dev]
-  pull_request:
-    branches: [main, dev]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x]
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - name: Install dependencies
-        run: npm ci
-      - name: Run tests
-        run: npm test
-      - name: Build
-        run: npm run build
-```
-
-### Pre-commit Hook
-
-已配置 `.husky/pre-commit`，每次提交前自动运行测试：
-
-```bash
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-# 运行测试
-npm test
-```
-
-如果测试失败，提交会被阻止。
-
-## 测试最佳实践
-
-### 1. 测试应该独立
-
-每个测试不应该依赖其他测试的结果：
-
-```typescript
-// ❌ 不好 - 依赖全局状态
-let result;
-it("测试 1", () => {
-  result = doSomething();
-});
-it("测试 2", () => {
-  expect(result).toBe(expected); // 依赖测试 1
-});
-
-// ✅ 好 - 每个测试独立
-it("测试 1", () => {
-  const result = doSomething();
-  expect(result).toBe(expected);
-});
-it("测试 2", () => {
-  const result = doSomething();
-  expect(result).toBe(expected);
-});
-```
-
-### 2. 使用描述性的测试名称
-
-```typescript
-// ❌ 不好
-it("测试 1", () => {});
-
-// ✅ 好
-it("应该正确提取 v 前缀", () => {});
-it("无前缀时应该返回 (无前缀)", () => {});
-```
-
-### 3. 测试边界情况
-
-```typescript
-describe("Tag 显示", () => {
-  it("应该显示少于 5 个的所有 tag", () => {
-    // 测试 1-4 个 tag
-  });
-
-  it("应该只显示最后 5 个 tag", () => {
-    // 测试正好 5 个 tag
-  });
-
-  it("超过 5 个时应该显示省略号", () => {
-    // 测试 6+ 个 tag
-  });
-
-  it("应该处理空数组", () => {
-    // 测试 0 个 tag
-  });
-});
-```
-
-### 4. 使用 beforeEach/afterEach
-
-```typescript
-import { beforeEach, afterEach } from "vitest";
-
-describe("测试套件", () => {
-  beforeEach(() => {
-    // 每个测试前执行
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    // 每个测试后执行
-    vi.restoreAllMocks();
-  });
-
-  it("测试 1", () => {});
-  it("测试 2", () => {});
-});
-```
-
-### 5. 测试覆盖率目标
-
-- **核心功能** - 100% 覆盖
-- **工具函数** - 90%+ 覆盖
-- **UI 交互** - 关键路径覆盖
-
-## 添加新功能时的测试流程
-
-1. **先写测试（TDD）**
-
-   ```typescript
-   // 1. 写测试
-   it("应该支持新功能", () => {
-     const result = newFeature();
-     expect(result).toBe(expected);
-   });
-
-   // 2. 运行测试（应该失败）
-   // npm test
-
-   // 3. 实现功能
-   function newFeature() {
-     // 实现代码
-   }
-
-   // 4. 运行测试（应该通过）
-   // npm test
-   ```
-
-2. **或先实现后测试**
-
-   ```typescript
-   // 1. 实现功能
-   function newFeature() {
-     // 实现代码
-   }
-
-   // 2. 写测试
-   it("应该支持新功能", () => {
-     const result = newFeature();
-     expect(result).toBe(expected);
-   });
-
-   // 3. 运行测试
-   // npm test
-   ```
-
-3. **提交前检查**
-   ```bash
-   # 运行所有测试
-   npm test
-   # 检查覆盖率
-   npm run test:coverage
-   # 构建验证
-   npm run build
-   ```
-
-## 调试测试
-
-### 使用 console.log
-
-```typescript
-it("调试测试", () => {
-  const result = someFunction();
-  console.log("result:", result); // 会在测试输出中显示
-  expect(result).toBe(expected);
-});
-```
-
-### 使用 test.only
-
-```typescript
-// 只运行这一个测试
-it.only("调试这个测试", () => {
-  // 测试代码
-});
-```
-
-### 使用 UI 界面
-
-```bash
-npm run test:ui
-```
-
-在浏览器中查看测试结果，可以：
-
-- 查看测试树
-- 查看失败详情
-- 重新运行单个测试
-- 查看覆盖率
-
-## 常见问题
-
-### Q: 测试运行很慢怎么办？
-
-A: 使用监听模式，只运行改动的测试：
-
-```bash
-npm run test:watch
-```
-
-### Q: 如何跳过某个测试？
-
-A: 使用 `it.skip`：
-
-```typescript
-it.skip("暂时跳过这个测试", () => {
-  // 测试代码
-});
-```
-
-### Q: 如何测试 CLI 交互？
-
-A: Mock inquirer 的 prompt：
-
-```typescript
-import { vi } from "vitest";
-import { select } from "@inquirer/prompts";
-
-vi.mock("@inquirer/prompts");
-
-it("应该选择正确的选项", async () => {
-  vi.mocked(select).mockResolvedValue("option1");
-  // 测试代码
-});
-```
-
-### Q: 如何测试 git 命令？
-
-A: Mock child_process：
-
-```typescript
-import { vi } from "vitest";
-import { execSync } from "child_process";
-
-vi.mock("child_process");
-
-it("应该执行 git 命令", () => {
-  vi.mocked(execSync).mockReturnValue("success");
-  // 测试代码
-});
-```
-
-## 未来计划
-
-- [ ] 增加集成测试
-- [ ] 增加 E2E 测试
-- [ ] 提高测试覆盖率到 90%+
-- [ ] 添加性能测试
-- [ ] 添加快照测试
-
-## 参考资料
-
-- [Vitest 官方文档](https://vitest.dev/)
-- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
-- [Jest Cheat Sheet](https://github.com/sapegin/jest-cheat-sheet)