versionbump

versionbump

选择下一个版本号通常依赖记忆来判断：“感觉应该是次要版本。” versionbump 将其变成计算过程。你只需提供当前版本、该版本之后的提交，以及该版本之后的公共 API 表面变更，它就会机械地应用语义化版本规则，然后列出选择该级别的依据，供任何人核查：

• Major — 某个提交被标记为破坏性变更，或某个 API 条目被移除或发生不兼容变更。下一个版本为 (X+1).0.0。
• Minor — 没有破坏性信号，但有 feat 提交，或新增了 API 条目。下一个版本为 X.(Y+1).0。
• Patch — 没有破坏性或功能信号，但存在提交。下一个版本为 X.Y.(Z+1)。
• None — 完全没有提交，也没有 API 变更。下一个版本保持当前版本不变。

按顺序匹配，首条匹配的规则优先；但依据会完整列出，而不只是列出胜出的规则：reasons 会按固定顺序列出每个破坏性提交、每项破坏性 API 变更、每个功能提交和每个新增 API 条目；每组内部按照输入顺序排列。Patch 升级会附带唯一一条原因：no breaking or feature signals; <n> commit(s) present；None 升级会附带 no commits and no API changes supplied。

功能检测采用精确匹配：只有类型恰好为 feat（区分大小写）的提交才算功能提交；其他所有提交类型都属于 Patch 级别，除非被标记为破坏性变更。当前版本必须是严格的 MAJOR.MINOR.PATCH 语义化版本，不得带预发布或构建后缀。格式错误的输入（例如无效的版本字符串、缺少类型的提交、包含未知类型的 API 变更）会触发校验错误，并指出出错路径（例如 commits[1].type must be a non-empty string）；不会给出不完整的建议。计算是纯本地操作：不访问网络、不需要配置，也不会读取你传入的输入之外的文件。

CLI

npx @reneturcios/versionbump recommend --input args.json
npx @reneturcios/versionbump --version

args.json 包含完整的参数对象：

{
  "current_version": "1.4.2",
  "commits": [
    { "type": "feat" },
    { "type": "fix", "breaking": true }
  ],
  "api_changes": [
    { "kind": "added", "name": "exportReport" }
  ]
}

每个提交的 breaking 默认值为 false，api_changes 的默认值为 []。建议结果以 JSON 格式打印：

{
  "current_version": "1.4.2",
  "next_version": "2.0.0",
  "bump": "major",
  "reasons": [
    "commit[1] of type \"fix\" is marked breaking",
    "commit[0] is a feature (\"feat\")",
    "API entry \"exportReport\" was added"
  ]
}

退出代码：成功时为 0，发生运行时错误（包括输入文件无法读取或无效，或输入无效）时为 1，发生用法错误时为 2。

MCP 服务

npx -y @reneturcios/versionbump mcp

MCP 客户端配置：

{
  "mcpServers": {
    "versionbump": {
      "command": "npx",
      "args": ["-y", "@reneturcios/versionbump", "mcp"]
    }
  }
}

工具

• recommend_version_bump — 根据提交类型和 API 表面变更建议下一个语义化版本，并列出所选升级级别的依据。

  • current_version（字符串，必需）— 严格的 MAJOR.MINOR.PATCH 语义化版本，例如 "1.4.2"
  • commits（数组，必需，可为空）— 由 {type, breaking?} 对象组成的提交列表；type 为 Conventional Commits 类型，breaking 默认值为 false
  • api_changes（数组，可选，默认值为 []）— 由 {kind, name} 对象组成的 API 变更列表，其中 kind 为 "removed"、"changed" 或 "added" 之一

  返回 {current_version, next_version, bump, reasons}。

Docker

docker run -i ghcr.io/cloudcorprecords/versionbump
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/versionbump recommend --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios