commitcheck

commitcheck

Git 仓库近期历史记录的提交规范检查器。它会读取最近 50 条提交，并检查主题行长度、占位主题、DCO Signed-off-by 尾注、格式错误的尾注，以及每条提交是否遵循仓库实际采用的提交信息规范。每条发现都会标明规则和对应提交的短 SHA。

安装

npx @reneturcios/commitcheck check [path]

也可以全局安装：

npm install -g @reneturcios/commitcheck

需要 Node 20 或更高版本，并且 git 位于 PATH 中。

CLI

commitcheck check [path] [--json]   # check a repo (default path: .)
commitcheck mcp                     # run the MCP server on stdio
commitcheck --version               # print the version

退出码：判定为 CLEAN 时为 0，判定为 FINDINGS 时为 1，用法错误或目标不可读时为 2，读取器提前关闭输出管道时为 141（即 shell 可见的 SIGPIPE 终止）。

发现会按照 git log 的顺序输出，最新的排在最前；对于给定的历史记录，输出顺序是确定的。

MCP

MCP 服务提供一个工具：

• check_commits，参数为 path：运行与 CLI 相同的检查，并以 JSON 格式返回完整报告。

规则

规则	严重性	含义
SUBJECT-TOO-LONG	medium	主题行超过 72 个字符。
SUBJECT-VAGUE	low	主题为空或为占位内容，例如 wip、fix、update、changes 或 .
NO-SIGNOFF	medium	在历史记录遵循 DCO 规范的仓库中（见下文），该提交没有 Signed-off-by 尾注。
CONVENTION-BREAK	low	主题不符合该范围内占主导地位的提交信息风格（见下文）。
MERGE-COMMIT	info	合并提交，仅作为背景信息报告。合并提交的严重性永远不会高于 info。
TRAILER-MALFORMED	low	Signed-off-by 行不包含电子邮件格式，例如 Signed-off-by: Jane Doe 缺少 <[email protected]>。

当该范围内没有 medium 级别的发现时，判定为 CLEAN，否则判定为 FINDINGS。low 和 info 级别的发现会报告，但不会改变判定结果。

简明说明自适应规则

commitcheck 不会强加固定的风格。两项规范检查都会根据正在检查的范围学习：

• DCO / sign-off。 仅当仓库明确使用 sign-off 时，提交才会被标记为 NO-SIGNOFF：该范围内至少一半的其他提交带有格式正确的 Signed-off-by 尾注。如果仓库不使用 sign-off，则不会有提交因缺少它而被标记。格式错误的 sign-off 行不计作 sign-off。
• 提交信息规范。 会跟踪两种风格：conventional 主题（type: summary 或 type(scope): summary）和首字母大写的祈使句主题（Add the thing）。当某种风格在该范围内至少 70% 的非合并提交中出现时，它就是占主导地位的风格；不符合该风格的提交会被标记为 CONVENTION-BREAK。如果没有任何风格达到 70%，则不会标记风格问题。

限制

• 只检查最近 50 条提交。
• 风格检测基于统计。历史记录较短或风格混杂时，可能无法确定占主导地位的风格，此时不会产生规范相关的发现。
• 只检查 sign-off 是否存在，不验证签名有效性。commitcheck 会确认是否存在带有电子邮件格式的 Signed-off-by 尾注；但不会验证签署者是否为作者，也不会验证签名是否真实。
• 根据 Merge ... 主题行检测合并提交，这是 git 的默认格式；以 Merge 开头的手写主题也会被报告为合并提交。