contribpath

contribpath

CONTRIBUTING ガイドは美しく書かれていても、新しいコントリビューターを行き詰まらせることがあります。ドキュメントとリポジトリの実際の要件にずれが生じるためです。たとえば、ガイドに CI が適用する DCO への署名が記載されていなかったり、リリースボットが要求する changeset に触れていなかったりします。contribpath はこのずれを測定します。ドキュメントのテキストと、リポジトリに実際に存在するゲートを渡してください。各ゲートには ID、ドキュメントに記載されるラベル、同等のものとして扱われる別の表現を指定します。すると、どのゲートが記載されているか、どれが不足しているか、カバレッジがどの程度か、そして判定結果が報告されます。

照合方法は、意図的にシンプルで監査可能なものにしています。すべてを小文字に変換し、ドキュメントにラベルまたは空でないキーワードのいずれかが部分文字列として含まれていれば、そのゲートは記載済みと判定されます。空のキーワードは意図的に無視されます。空文字列はどのドキュメントにも部分文字列として含まれるため、これを数えるとすべてのゲートがカバー済みと判定され、このツールが見つけようとしている不足箇所が隠れてしまうからです。どちらか一方の条件を満たせば十分です。ラベルが一度も登場しないゲートでもキーワードでカバーできます。また、キーワードがないゲートはラベルだけでカバーできます。

カバレッジは Math.round(100 * documented / gate_count) で計算されるため、3 件中 2 件のゲートが記載されている場合、66 ではなく 67 になります。カバレッジが 100 の場合は complete、60 以上の場合は partial、60 未満の場合は sparse と判定されます。記載済みゲートと不足しているゲートのリストには、ゲートを指定した順に ID が含まれるため、呼び出し元が指定したゲートリストと照らし合わせられます。

呼び出し元がドキュメントからトピックも抽出している場合、それらを documented_topics として渡すと、どのゲートにも対応しないトピックを見つけられます。トピックは、そのゲートの ID と完全に一致するか、大文字と小文字を区別せずにゲートのラベルと一致すると、そのゲートに対応します。どのゲートにも一致しないトピックは、入力順のまま extra_topics としてそのまま返されます。トピックが指定されていない場合、extra_topics は空です。

ゲート ID の重複は、該当する ID を示すエラーになります。同じゲートに対する項目が 2 つあると、カバレッジの数値に意味がなくなるためです。不正な入力、つまり 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 サーバー

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