busfactor

busfactor

每个代码库中都有一些文件，实际上只有一个人真正了解。如果这个人不在——休假、生病，或离开团队——这些文件就没人敢安全地修改。busfactor 会找出风险所在。你为每个文件提供作者及各作者提交的次数，以及审查过该文件更改的人，它就会给出一份基于事实的地图：

• 逐文件条目 — 对每个文件，列出其 total_commits、不同作者的数量、top_author 及该作者在文件提交中所占的 top_share，以及 external_reviewers：审查者中并非该文件作者的人数。文件作者之一的审查不算外部审查，因此，如果文件只由编写者审查，则会显示为从未经过审查。
• 两个标记，一个列表 — 当文件的最高作者占比达到阈值（默认值为 0.8）时，该文件会被标记为 dominated；当文件没有外部审查者时，则会被标记为 never_reviewed。同时满足两项条件的文件会被标记为 at_risk，而 at_risk_files 会收集且仅收集这些文件路径。该列表仅说明贡献集中度和审查覆盖情况，不对相关人员作出任何评价。
• 汇总计数 — 分析的文件数、存在风险的文件数、只有一位作者的文件数，以及从未经过外部审查的文件数。

在进行任何计算之前，同一文件中的重复作者名称会合并，并将其提交次数相加；审查者名称会去重。最高作者占比会四舍五入到小数点后四位，判定是否被一位作者主导时，会将这个经过舍入的占比（即报告显示的数字）与阈值比较，因此，报告占比恰好等于阈值的文件始终会被标记为主导。结果中的所有列表都会按升序排序，因此相同的数据始终会生成完全相同的地图。格式错误的输入——例如文件列表缺失或为空、路径重复、作者没有提交记录——会导致验证错误，并指出出错路径（例如 files[1].authors[0].commits must be an integer >= 1），且不会生成部分地图。计算是纯本地操作：不会联网、无需配置，也不会读取你传入的输入以外的任何文件。

CLI

npx @reneturcios/busfactor analyze --input args.json
npx @reneturcios/busfactor --version

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

{
  "files": [
    { "path": "src/solo.ts", "authors": [{ "name": "amy", "commits": 10 }] },
    {
      "path": "src/shared.ts",
      "authors": [
        { "name": "amy", "commits": 5 },
        { "name": "bob", "commits": 5 }
      ],
      "reviewers": ["amy", "cleo"]
    }
  ]
}

每个文件的 reviewers 默认为 []，threshold 默认为 0.8。这里，src/solo.ts 只有一位作者且未经审查，而 src/shared.ts 的贡献由两位作者平分，并由 cleo 进行了外部审查。地图会以 JSON 格式输出：

{
  "files": [
    {
      "path": "src/shared.ts",
      "total_commits": 10,
      "distinct_authors": 2,
      "top_author": "amy",
      "top_share": 0.5,
      "external_reviewers": 1,
      "never_reviewed": false,
      "dominated": false,
      "at_risk": false
    },
    {
      "path": "src/solo.ts",
      "total_commits": 10,
      "distinct_authors": 1,
      "top_author": "amy",
      "top_share": 1,
      "external_reviewers": 0,
      "never_reviewed": true,
      "dominated": true,
      "at_risk": true
    }
  ],
  "at_risk_files": ["src/solo.ts"],
  "summary": {
    "total_files": 2,
    "at_risk_count": 1,
    "single_author_count": 1,
    "never_reviewed_count": 1
  }
}

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

MCP 服务

npx -y @reneturcios/busfactor mcp

MCP 客户端配置：

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

工具

• analyze_bus_factor — 根据作者和审查数据，列出只有一位作者且从未经过审查的文件。

  • files（数组，必填，至少一个）— 文件对象数组，每个对象的形式为 {path, authors, reviewers?}；path 在集合中必须唯一，每个 authors 条目都是 {name, commits} 对，且提交次数至少为 1；reviewers 列出审查过该文件更改的人名
  • threshold（数字，可选，默认值为 0.8）— 文件被视为由一位作者主导时所需达到的最高作者占比；必须 > 0 且 <= 1

  返回 {files, at_risk_files, summary}。

Docker

docker run -i ghcr.io/cloudcorprecords/busfactor
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/busfactor analyze --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