nex/openspec/specs/git-hooks/spec.md

git-hooks

Purpose

定义仓库原生 Git hooks 的安装、校验、测试与跨平台执行规则，确保提交前快速检查和提交信息格式校验符合项目规范。

Requirements

Requirement: pre-commit hook 快速检查

pre-commit hook SHALL 在 git commit 执行前对 staged files 进行快速检查。非代码检查（冲突标记、大文件告警、LFS 指针）SHALL 在 _hooks-pre-commit 中直接实现；代码检查（Go 后端、Go versionctl、前端）SHALL 根据 staged 文件类型有条件地委托给已有 Makefile target（_backend-lint、_versionctl-lint、_frontend-check），不再内联独立的 lint 命令。

Scenario: 无 Go 和前端文件变更时跳过代码检查

• WHEN staged files 中既无 .go 文件也无 .ts/.tsx/.scss 文件
• THEN pre-commit hook SHALL 跳过代码检查委托，仅执行非代码检查

Scenario: Go 文件变更时委托后端 lint

• WHEN staged files 中包含 backend/*.go 文件
• THEN pre-commit hook SHALL 委托 _backend-lint target 进行 Go 代码检查
• THEN _backend-lint SHALL 复用 backend/.golangci.yml 配置
• THEN 若 lint 报告任何错误，commit SHALL 被阻止

Scenario: versionctl Go 文件变更时委托 versionctl lint

• WHEN staged files 中包含 versionctl/*.go 文件
• THEN pre-commit hook SHALL 委托 _versionctl-lint target 进行 Go 代码检查
• THEN _versionctl-lint SHALL 复用 versionctl/.golangci.yml 配置
• THEN 若 lint 报告任何错误，commit SHALL 被阻止

Scenario: 前端文件变更时委托前端检查

• WHEN staged files 中包含 .ts、.tsx 或 .scss 文件
• THEN pre-commit hook SHALL 委托 _frontend-check target 进行前端代码检查
• THEN _frontend-check SHALL 运行 bun run check（包含 tsc -b TypeScript 类型检查、ESLint 和 Prettier 格式检查）
• THEN 若检查报告任何错误，commit SHALL 被阻止

Scenario: 冲突标记检测

• WHEN staged files 中包含 <<<<<<<、======= 或 >>>>>>> 冲突标记
• THEN pre-commit hook SHALL 报告错误并列出包含冲突的文件名
• THEN commit SHALL 被阻止

Scenario: 大文件告警

• WHEN staged files 中存在超过 500KB 的文本文件
• THEN pre-commit hook SHALL 输出警告信息（不阻止提交），提示检查是否误提交

Scenario: LFS 指针校验

• WHEN staged files 匹配 .gitattributes 中 filter=lfs 的路径模式
• THEN pre-commit hook SHALL 检查 staged 内容是否为 LFS 指针格式（version https://git-lfs.github.com/spec/v1）
• THEN 若内容不是 LFS 指针格式，commit SHALL 被阻止，并提示安装 git-lfs
• THEN 若 staged files 不匹配任何 filter=lfs 路径模式，SHALL 跳过此检查

Scenario: commit 被阻止时显示修复提示

• WHEN pre-commit hook 检查失败
• THEN hook SHALL 输出明确的修复提示（如 make lint 修复代码问题、手动解决冲突标记等）

Requirement: commit-msg hook 校验提交信息格式

commit-msg hook SHALL 在 git commit 输入提交信息后校验格式，确保首行符合项目规范。提交描述按项目规范应使用中文，但 hook SHALL NOT 通过 Python/CJK 字符集检测强制判断描述语言，以避免引入新的运行时依赖。

Scenario: 合法格式通过

• WHEN 提交信息首行格式为 <类型>: <描述>，类型为 feat、fix、refactor、docs、style、test、chore 之一
• THEN commit-msg hook SHALL 通过，commit 正常执行

Scenario: 非法类型被拒绝

• WHEN 提交信息首行使用的类型不在允许列表中（如 update: xxx）
• THEN commit-msg hook SHALL 报告错误，显示允许的类型列表，commit SHALL 被阻止

Scenario: 缺少冒号空格被拒绝

• WHEN 提交信息首行为 feat:xxx（冒号后无空格）或 feat xxx
• THEN commit-msg hook SHALL 报告格式错误，commit SHALL 被阻止

Scenario: 首行过长告警

• WHEN 提交信息首行超过 72 个字符
• THEN commit-msg hook SHALL 输出警告（不阻止提交），提示首行应简短

Scenario: Merge commit 自动放行

• WHEN 提交信息首行以 Merge 开头
• THEN commit-msg hook SHALL 直接通过，不进行格式校验

Scenario: 格式错误时显示示例

• WHEN commit-msg hook 检查失败
• THEN hook SHALL 输出包含正确格式示例的错误信息（如 feat: 添加供应商批量管理功能）

Scenario: 不执行字符集检测

• WHEN 提交信息首行格式合法且类型合法，但描述部分不包含 CJK 字符（如 feat: add hook tests）
• THEN commit-msg hook SHALL 通过
• THEN hook SHALL NOT 调用 python3 或其他额外运行时做 Unicode/CJK 检测

Scenario: 多行格式校验

• WHEN 提交信息忽略 # 注释行后，第三行及之后存在任一非空详细说明行
• THEN commit-msg hook SHALL 检查第二行是否为空行
• THEN 若第二行非空行，commit SHALL 被阻止，提示首行后应空行再写详细描述

Scenario: 模板注释不参与校验

• WHEN 提交信息文件中包含 prepare-commit-msg 写入的 # 注释模板
• THEN commit-msg hook SHALL 忽略这些注释行
• THEN 注释行 SHALL NOT 导致首行格式、多行空行分隔校验失败

Requirement: hooks-install 安装命令

make hooks-install SHALL 将 scripts/git-hooks/ 下的 hook 脚本安装到 .git/hooks/，不覆盖 Git LFS 管理的 hook。

Scenario: 安装所有 hook 脚本

• WHEN 执行 make hooks-install
• THEN scripts/git-hooks/pre-commit SHALL 被复制到 .git/hooks/pre-commit
• THEN scripts/git-hooks/commit-msg SHALL 被复制到 .git/hooks/commit-msg
• THEN scripts/git-hooks/prepare-commit-msg SHALL 被复制到 .git/hooks/prepare-commit-msg
• THEN 所有复制文件 SHALL 被设置为可执行（chmod +x）

Scenario: 不覆盖 LFS 管理的 hook

• WHEN .git/hooks/post-checkout、.git/hooks/post-commit、.git/hooks/post-merge、.git/hooks/pre-push 已由 Git LFS 管理
• THEN make hooks-install SHALL NOT 覆盖或修改这些文件

Scenario: 重复安装幂等

• WHEN make hooks-install 被执行多次
• THEN hook 文件 SHALL 被正确覆盖更新，不会产生重复或损坏

Scenario: hooks-check 验证安装状态

• WHEN 执行 make hooks-check
• THEN 命令 SHALL 检查 .git/hooks/pre-commit、.git/hooks/commit-msg、.git/hooks/prepare-commit-msg 是否存在且可执行
• THEN SHALL 输出每个 hook 的安装状态

Scenario: 安装前验证 source 文件存在

• WHEN 执行 make hooks-install
• THEN 命令 SHALL 在复制前验证每个 source 文件（scripts/git-hooks/<hook-name>）是否存在
• THEN 若 source 文件不存在，命令 SHALL 报告错误并返回非零退出码

Requirement: hooks-test 回归测试命令

make hooks-test SHALL 运行仓库内 hook 回归测试，覆盖 commit-msg 格式校验和 pre-commit staged-file 检查，不污染真实 git index。

Scenario: 运行 hook 回归测试

• WHEN 执行 make hooks-test
• THEN SHALL 运行 scripts/git-hooks/test-hooks.sh
• THEN 测试 SHALL 使用临时 GIT_INDEX_FILE 构造 staged fixture
• THEN 若任一 hook 行为不符合预期，命令 SHALL 返回非零退出码

Requirement: 跨平台可用

pre-commit 和 commit-msg hook 脚本 SHALL 可在 macOS 和 Windows（Git Bash）上正常执行。

Scenario: macOS 上正常执行

• WHEN hook 脚本在 macOS 上被 git 调用
• THEN #!/bin/sh shebang SHALL 被系统正确解析
• THEN exec make SHALL 正确调用 Makefile target

Scenario: Windows Git Bash 上正常执行

• WHEN hook 脚本在 Windows 的 Git Bash 环境中被 git 调用
• THEN Git for Windows 自带的 sh.exe SHALL 正确解析 #!/bin/sh
• THEN exec make SHALL 正确调用 Makefile target（依赖 Git Bash/MINGW64 环境中 make 可用）
• THEN Go 和 Bun 工具链 SHALL 通过 PATH 可被 Makefile 调用

Requirement: pre-commit 核心逻辑在 Makefile 中复用

pre-commit hook 的检查逻辑 SHALL 通过 Makefile target 调用项目已有工具链，不重复实现。非代码检查（冲突标记、大文件、LFS 指针）SHALL 在 _hooks-pre-commit 中直接实现；代码检查 SHALL 委托 _backend-lint、_versionctl-lint、_frontend-check target。

Scenario: Go lint 委托后端 lint target

• WHEN pre-commit 需要检查 Go 文件
• THEN SHALL 委托 _backend-lint 或 _versionctl-lint target（根据文件路径 backend/ vs versionctl/）
• THEN SHALL NOT 在 _hooks-pre-commit 中内联 golangci-lint 命令

Scenario: 前端检查委托前端 check target

• WHEN pre-commit 需要检查前端文件
• THEN SHALL 委托 _frontend-check target
• THEN SHALL NOT 在 _hooks-pre-commit 中内联 eslint 或 prettier 命令

Scenario: 终端直接调试

• WHEN 开发者执行 make _hooks-pre-commit
• THEN SHALL 执行与 pre-commit hook 完全相同的检查逻辑
• THEN 输出 SHALL 与 hook 触发时一致