contribpath

contribpath

CONTRIBUTING 指南即便写得很出色，也仍可能让新贡献者不知所措，因为文档与仓库的实际要求会出现偏差：指南没有提到 CI 强制要求的 DCO 签署，或发布机器人要求的 changeset。contribpath 用于衡量这种偏差。你提供文档文本和仓库实际设有的关卡——每个关卡都包含一个 id、在文档中会出现的标签，以及任何同样可计入的替代表述——它会报告哪些关卡已有文档说明、哪些缺失、覆盖率是多少，以及最终判定。

匹配方式刻意保持简单且可审计。所有内容都会转换为小写；如果文档包含关卡标签，或至少包含一个非空关键词作为子字符串，该关卡就算已有文档说明。空关键词会被有意忽略：空字符串是每份文档的子字符串，若将其计入，就会把每个关卡都标记为已覆盖，从而掩盖这个工具要找出的缺口。任一信号单独成立就足够——即使标签从未出现，只要关键词匹配，该关卡仍可算作已覆盖；如果关卡没有任何关键词，仅凭标签也能算作已覆盖。

覆盖率按 Math.round(100 * documented / gate_count) 计算，因此三个关卡中有两个已说明时，结果是 67，而不是 66。覆盖率为 100 时，判定为 complete；达到 60 时，判定为 partial；低于 60 时，判定为 sparse。已说明和缺失列表会按照关卡的输入顺序列出各关卡 id，因此报告顺序与调用方提供的关卡列表一致。

如果调用方还从文档中提取了主题，可以通过 documented_topics 传入，以找出完全没有对应关卡的主题。如果主题与某个关卡的 id 完全一致，或忽略大小写后与该关卡标签相同，则视为匹配；没有匹配任何关卡的主题会按原样、按输入顺序放入 extra_topics。未提供主题时，extra_topics 为空。

重复的关卡 id 会导致错误，并指出对应的 id——同一关卡有两条记录会使覆盖率失去意义。格式错误的输入——缺少 document、其值不是字符串、缺少或为空的 gates 数组、关卡缺少 id 或 label、其值为空或不是字符串、keywords 的值不是字符串数组，或 documented_topics 中的条目不是非空字符串——会导致验证错误，并指出出错路径，不返回部分结果。未知的额外字段会被忽略，包括关卡条目中的字段。计算是纯本地操作：不会访问网络，不需要配置，也不会读取或修改任何仓库。contribpath 只比较你提供的内容；从仓库中提取关卡则是另一项工作。

CLI

npx @reneturcios/contribpath check --input args.json
npx @reneturcios/contribpath --version

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

{
  "document": "Please sign off your commits (DCO) and add a changeset.",
  "gates": [
    { "id": "dco", "label": "Developer Certificate of Origin", "keywords": ["dco", "sign off"] },
    { "id": "changeset", "label": "Changeset" },
    { "id": "cla", "label": "Contributor License Agreement", "keywords": ["cla"] }
  ],
  "documented_topics": ["dco", "Changeset", "Code of Conduct"]
}

结果会以 JSON 格式打印：

{
  "documented": ["dco", "changeset"],
  "missing": ["cla"],
  "extra_topics": ["Code of Conduct"],
  "coverage_percent": 67,
  "verdict": "partial",
  "gate_count": 3
}

空的 document 字符串是有效输入：所有关卡都会被标记为缺失，判定为 sparse。退出码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP server

npx -y @reneturcios/contribpath mcp

MCP 客户端配置：

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

工具

• check_contributing_coverage — 根据仓库实际的贡献关卡检查 CONTRIBUTING 文档。

  • document（字符串，必填，可为空）— 要检查的贡献指南文本
  • gates（数组，必填，至少包含 1 项）— 仓库实际设有的贡献关卡；每项都是一个对象，包含：
    • id（字符串，必填，不能为空）— 关卡标识符
    • label（字符串，必填，不能为空）— 在文档中会出现的关卡标签
    • keywords（字符串数组，可选）— 同样可用于判定关卡已有文档说明的替代表述
  • documented_topics（字符串数组，可选）— 调用方从文档中提取的主题，用于与关卡集合进行匹配

  返回 {documented, missing, extra_topics, coverage_percent, verdict, gate_count}。

Docker

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

License

MIT — Copyright (c) 2026 Rene Turcios