@zjex/git-workflow 0.2.23 → 0.3.0

package/TESTING.md

@@ -0,0 +1,436 @@
+# 测试体系说明
+
+## 为什么需要测试？
+
+在开发 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)

package/dist/index.js

@@ -674,7 +674,7 @@ async function listTags(prefix) {
   }
   const grouped = /* @__PURE__ */ new Map();
   tags.forEach((tag) => {
-    const prefix2 = tag.replace(/[0-9].*/, "") || "\u65E0\u524D\u7F00";
+    const prefix2 = tag.replace(/[0-9].*/, "") || "(\u65E0\u524D\u7F00)";
     if (!grouped.has(prefix2)) {
       grouped.set(prefix2, []);
     }
@@ -1442,11 +1442,28 @@ async function init() {
       ],
       theme
     });
+    const detailedDescription = await select4({
+      message: "\u662F\u5426\u751F\u6210\u8BE6\u7EC6\u7684\u4FEE\u6539\u70B9\u63CF\u8FF0?",
+      choices: [
+        {
+          name: "\u662F\uFF08\u5305\u542B\u4FEE\u6539\u70B9\u5217\u8868\uFF0C\u63A8\u8350\uFF09",
+          value: true,
+          description: "\u5982\uFF1Afeat(auth): \u6DFB\u52A0\u7528\u6237\u767B\u5F55\u529F\u80FD\n\n- \u5B9E\u73B0\u7528\u6237\u540D\u5BC6\u7801\u767B\u5F55\u63A5\u53E3\n- \u6DFB\u52A0\u767B\u5F55\u72B6\u6001\u9A8C\u8BC1\u4E2D\u95F4\u4EF6"
+        },
+        {
+          name: "\u5426\uFF08\u4EC5\u751F\u6210\u6807\u9898\uFF09",
+          value: false,
+          description: "\u5982\uFF1Afeat(auth): \u6DFB\u52A0\u7528\u6237\u767B\u5F55\u529F\u80FD"
+        }
+      ],
+      theme
+    });
     config2.aiCommit = {
       enabled: true,
       provider: aiProvider,
       apiKey: apiKey || void 0,
-      language
+      language,
+      detailedDescription
     };
     const defaultModels = {
       github: "gpt-4o-mini",
@@ -1790,9 +1807,62 @@ function getGitDiff() {
     return "";
   }
 }
-function buildPrompt(diff, language) {
+function buildPrompt(diff, language, detailedDescription = false) {
   const isZh = language === "zh-CN";
-  const systemPrompt = isZh ? `\u4F60\u662F\u4E00\u4E2A\u4E13\u4E1A\u7684 Git commit message \u751F\u6210\u52A9\u624B\u3002\u8BF7\u6839\u636E\u63D0\u4F9B\u7684 git diff \u751F\u6210\u7B26\u5408 Conventional Commits \u89C4\u8303\u7684 commit message\u3002
+  if (detailedDescription) {
+    const systemPrompt = isZh ? `\u4F60\u662F\u4E00\u4E2A\u4E13\u4E1A\u7684 Git commit message \u751F\u6210\u52A9\u624B\u3002\u8BF7\u6839\u636E\u63D0\u4F9B\u7684 git diff \u751F\u6210\u7B26\u5408 Conventional Commits \u89C4\u8303\u7684\u8BE6\u7EC6 commit message\u3002
+
+\u683C\u5F0F\u8981\u6C42\uFF1A
+1. \u7B2C\u4E00\u884C\uFF1A<type>(<scope>): <subject>
+2. \u7A7A\u884C
+3. \u8BE6\u7EC6\u63CF\u8FF0\uFF1A\u5217\u51FA\u4E3B\u8981\u4FEE\u6539\u70B9\uFF0C\u6BCF\u4E2A\u4FEE\u6539\u70B9\u4E00\u884C\uFF0C\u4EE5 "- " \u5F00\u5934
+
+\u89C4\u5219\uFF1A
+- type \u5FC5\u987B\u662F\u4EE5\u4E0B\u4E4B\u4E00\uFF1Afeat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+- scope \u662F\u53EF\u9009\u7684\uFF0C\u8868\u793A\u5F71\u54CD\u8303\u56F4
+- subject \u7528\u4E2D\u6587\u63CF\u8FF0\uFF0C\u7B80\u6D01\u660E\u4E86\uFF0C\u4E0D\u8D85\u8FC7 50 \u5B57
+- \u8BE6\u7EC6\u63CF\u8FF0\u8981\u5217\u51FA 3-6 \u4E2A\u4E3B\u8981\u4FEE\u6539\u70B9\uFF0C\u6BCF\u4E2A\u4FEE\u6539\u70B9\u7B80\u6D01\u660E\u4E86
+- \u5982\u679C\u4FEE\u6539\u8F83\u5C11\uFF0C\u53EF\u4EE5\u53EA\u5217\u51FA 2-3 \u4E2A\u4FEE\u6539\u70B9
+- \u4E0D\u8981\u6709\u5176\u4ED6\u89E3\u91CA\u6216\u591A\u4F59\u5185\u5BB9
+
+\u793A\u4F8B\uFF1A
+feat(auth): \u6DFB\u52A0\u7528\u6237\u767B\u5F55\u529F\u80FD
+
+- \u5B9E\u73B0\u7528\u6237\u540D\u5BC6\u7801\u767B\u5F55\u63A5\u53E3
+- \u6DFB\u52A0\u767B\u5F55\u72B6\u6001\u9A8C\u8BC1\u4E2D\u95F4\u4EF6
+- \u5B8C\u5584\u767B\u5F55\u9519\u8BEF\u5904\u7406\u903B\u8F91
+- \u66F4\u65B0\u7528\u6237\u8BA4\u8BC1\u76F8\u5173\u6587\u6863` : `You are a professional Git commit message generator. Generate a detailed commit message following Conventional Commits specification based on the provided git diff.
+
+Format requirements:
+1. First line: <type>(<scope>): <subject>
+2. Empty line
+3. Detailed description: List main changes, one per line, starting with "- "
+
+Rules:
+- type must be one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+- scope is optional, indicates the affected area
+- subject should be concise, no more than 50 characters
+- Detailed description should list 3-6 main changes, each change should be concise
+- If changes are minimal, list 2-3 changes
+- No explanations or extra content
+
+Example:
+feat(auth): add user login functionality
+
+- Implement username/password login API
+- Add login status validation middleware
+- Improve login error handling logic
+- Update user authentication documentation`;
+    const userPrompt = isZh ? `\u8BF7\u6839\u636E\u4EE5\u4E0B git diff \u751F\u6210\u8BE6\u7EC6\u7684 commit message\uFF08\u5305\u542B\u4FEE\u6539\u70B9\u5217\u8868\uFF09\uFF1A
+
+${diff}` : `Generate a detailed commit message (including change list) based on the following git diff:
+
+${diff}`;
+    return `${systemPrompt}
+
+${userPrompt}`;
+  } else {
+    const systemPrompt = isZh ? `\u4F60\u662F\u4E00\u4E2A\u4E13\u4E1A\u7684 Git commit message \u751F\u6210\u52A9\u624B\u3002\u8BF7\u6839\u636E\u63D0\u4F9B\u7684 git diff \u751F\u6210\u7B26\u5408 Conventional Commits \u89C4\u8303\u7684 commit message\u3002
 
 \u89C4\u5219\uFF1A
 1. \u683C\u5F0F\uFF1A<type>(<scope>): <subject>
@@ -1819,14 +1889,15 @@ Examples:
 - feat(auth): add user login functionality
 - fix(api): resolve data fetching failure
 - docs(readme): update installation guide`;
-  const userPrompt = isZh ? `\u8BF7\u6839\u636E\u4EE5\u4E0B git diff \u751F\u6210 commit message\uFF1A
+    const userPrompt = isZh ? `\u8BF7\u6839\u636E\u4EE5\u4E0B git diff \u751F\u6210 commit message\uFF1A
 
 ${diff}` : `Generate a commit message based on the following git diff:
 
 ${diff}`;
-  return `${systemPrompt}
+    return `${systemPrompt}
 
 ${userPrompt}`;
+  }
 }
 async function callGitHubAPI(prompt, apiKey, model, maxTokens) {
   const response = await fetch(AI_PROVIDERS.github.endpoint, {
@@ -1921,18 +1992,31 @@ async function callOllamaAPI(prompt, model, maxTokens) {
     );
   }
 }
+function cleanAIResponse(response) {
+  const lines = response.split("\n").map((line) => line.trim()).filter((line) => line);
+  const uniqueLines = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const line of lines) {
+    if (!seen.has(line)) {
+      seen.add(line);
+      uniqueLines.push(line);
+    }
+  }
+  return uniqueLines.join("\n");
+}
 async function generateAICommitMessage(config2) {
   const aiConfig = config2.aiCommit || {};
   const provider = aiConfig.provider || "github";
   const language = aiConfig.language || "zh-CN";
-  const maxTokens = aiConfig.maxTokens || 200;
+  const detailedDescription = aiConfig.detailedDescription !== false;
+  const maxTokens = aiConfig.maxTokens || (detailedDescription ? 400 : 200);
   const diff = getGitDiff();
   if (!diff) {
     throw new Error("\u6CA1\u6709\u68C0\u6D4B\u5230\u4EE3\u7801\u66F4\u6539");
   }
-  const maxDiffLength = 4e3;
+  const maxDiffLength = detailedDescription ? 6e3 : 4e3;
   const truncatedDiff = diff.length > maxDiffLength ? diff.slice(0, maxDiffLength) + "\n..." : diff;
-  const prompt = buildPrompt(truncatedDiff, language);
+  const prompt = buildPrompt(truncatedDiff, language, detailedDescription);
   const providerInfo = AI_PROVIDERS[provider];
   if (!providerInfo) {
     throw new Error(`\u4E0D\u652F\u6301\u7684 AI \u63D0\u4F9B\u5546: ${provider}`);
@@ -1944,18 +2028,24 @@ async function generateAICommitMessage(config2) {
       `${providerInfo.name} \u9700\u8981 API key\u3002\u8BF7\u8FD0\u884C 'gw init' \u914D\u7F6E AI commit\uFF0C\u6216\u5728 .gwrc.json \u4E2D\u8BBE\u7F6E aiCommit.apiKey`
     );
   }
+  let response;
   switch (provider) {
     case "github":
-      return await callGitHubAPI(prompt, apiKey, model, maxTokens);
+      response = await callGitHubAPI(prompt, apiKey, model, maxTokens);
+      break;
     case "openai":
-      return await callOpenAIAPI(prompt, apiKey, model, maxTokens);
+      response = await callOpenAIAPI(prompt, apiKey, model, maxTokens);
+      break;
     case "claude":
-      return await callClaudeAPI(prompt, apiKey, model, maxTokens);
+      response = await callClaudeAPI(prompt, apiKey, model, maxTokens);
+      break;
     case "ollama":
-      return await callOllamaAPI(prompt, model, maxTokens);
+      response = await callOllamaAPI(prompt, model, maxTokens);
+      break;
     default:
       throw new Error(`\u4E0D\u652F\u6301\u7684 AI \u63D0\u4F9B\u5546: ${provider}`);
   }
+  return cleanAIResponse(response);
 }
 function isAICommitAvailable(config2) {
   const aiConfig = config2.aiCommit;
@@ -2496,7 +2586,7 @@ process.on("SIGTERM", () => {
   console.log("");
   process.exit(0);
 });
-var version = true ? "0.2.23" : "0.0.0-dev";
+var version = true ? "0.3.0" : "0.0.0-dev";
 async function mainMenu() {
   console.log(
     colors.green(`

package/docs/.vitepress/cache/deps/_metadata.json

@@ -0,0 +1,52 @@
+{
+  "hash": "cb9fc065",
+  "configHash": "e91271f8",
+  "lockfileHash": "eae41063",
+  "browserHash": "fa434d50",
+  "optimized": {
+    "vue": {
+      "src": "../../../../node_modules/vue/dist/vue.runtime.esm-bundler.js",
+      "file": "vue.js",
+      "fileHash": "69cff841",
+      "needsInterop": false
+    },
+    "vitepress > @vue/devtools-api": {
+      "src": "../../../../node_modules/@vue/devtools-api/dist/index.js",
+      "file": "vitepress___@vue_devtools-api.js",
+      "fileHash": "5ad8b965",
+      "needsInterop": false
+    },
+    "vitepress > @vueuse/core": {
+      "src": "../../../../node_modules/@vueuse/core/index.mjs",
+      "file": "vitepress___@vueuse_core.js",
+      "fileHash": "9696f0e0",
+      "needsInterop": false
+    },
+    "vitepress > @vueuse/integrations/useFocusTrap": {
+      "src": "../../../../node_modules/@vueuse/integrations/useFocusTrap.mjs",
+      "file": "vitepress___@vueuse_integrations_useFocusTrap.js",
+      "fileHash": "6cc36968",
+      "needsInterop": false
+    },
+    "vitepress > mark.js/src/vanilla.js": {
+      "src": "../../../../node_modules/mark.js/src/vanilla.js",
+      "file": "vitepress___mark__js_src_vanilla__js.js",
+      "fileHash": "08475884",
+      "needsInterop": false
+    },
+    "vitepress > minisearch": {
+      "src": "../../../../node_modules/minisearch/dist/es/index.js",
+      "file": "vitepress___minisearch.js",
+      "fileHash": "1cb3d774",
+      "needsInterop": false
+    }
+  },
+  "chunks": {
+    "chunk-2CLQ7TTZ": {
+      "file": "chunk-2CLQ7TTZ.js"
+    },
+    "chunk-LE5NDSFD": {
+      "file": "chunk-LE5NDSFD.js"
+    }
+  }
+}