gatefile

gatefile

隠れたコントリビューションのゲートを抽出し、マシンが読み取れるファイルにします。

すべてのリポジトリには、外部のコントリビューター向けの本当のルールが隠れています。作業を始める前にコメントする、アサインされるまで待つ、コミットにサインオフする、保証を受ける、CLA に署名する、といったルールです。現在は、PR が自動でクローズされて初めてそれらのルールに気づきます。gatefile は、リポジトリ内のドキュメントからルールを抽出し、ツール（Greenlight など）や CI が利用できる機械可読形式の contribution-gates.json にまとめます。

問題

コントリビューターがイシューを選び、コードを書いて PR を開くと、ボットが「アサインされていません」「保証を受けていない作成者は自動でクローズされます」「Signed-off-by がありません」といった理由で PR をクローズします。ルールは最初から CONTRIBUTING.md に記載されていましたが、文章の中に埋もれており、リポジトリごとに異なっていました。メンテナーは同じ指摘を繰り返し、コントリビューターは同じように夜の時間を無駄にします。

gatefile の機能

1. 抽出：CONTRIBUTING.md、PR およびイシューのテンプレート、DCO/CLA のワークフローファイル、lefthook フック、CLA ファイル（GitHub API またはローカルディレクトリから）を読み取り、見つかった各ゲートを、根拠となる実際の引用行とともに出力します。
2. 検証：コミット済みの contribution-gates.json と新たに抽出した結果を比較し、差異（STALE、MISSING、SEVERITY_CHANGED）を報告します。差異がある場合は終了コード 1 を返すため、CI で強制できます。
3. バッジ：ゲートの内容を人間向けの平易な言葉で伝える README のスニペットを生成します。

contribution-gates.json の形式

{
  "version": 1,
  "repo": "shadcn-labs/pdfcn",
  "generatedFrom": ["CONTRIBUTING.md"],
  "gates": [
    {
      "id": "claim_first",
      "kind": "claim_first",
      "severity": "blocker",
      "evidence": "Comment before starting work, and check the thread first in case someone else is already working on it.",
      "source": "CONTRIBUTING.md"
    }
  ],
  "conventions": {
    "branchNaming": "Name your branch feat/block-name",
    "prTitleFormat": "PR titles should follow Conventional Commits",
    "requiredChecks": []
  }
}

ゲートの種類

kind	severity	意味
claim_first	blocker	作業を始める前にイシューへコメントする
assignment_required	blocker	PR を開く前にアサインされるまで待つ
discuss_first	blocker	コーディングする前にディスカッションまたはイシューを開く
issue_first	blocker	すべての PR をイシューに紐付ける
vouch_required	blocker	既存のメンバーから保証を受ける
collaborators_only	blocker	リポジトリのコラボレーターのみ PR を開ける
no_direct_prs	blocker	直接の PR は受け付けない
dco_required	warn	コミットに Signed-off-by トレーラー（DCO）が必要
cla_required	warn	コントリビューターライセンス契約への署名が必要

重大度：blocker のゲートがあると、レビュー前に PR がクローズまたは却下されることがあります。warn のゲートは PR を開いた後でも対応できます。根拠には必ずソースファイルからの実際の引用を使い、約 140 文字に短縮します。引用を捏造することはありません。

Docker で実行

gatefile は GHCR のコンテナイメージとしても提供されています：ghcr.io/cloudcorprecords/gatefile。

stdio MCP サーバーとして使用します：

docker run -i ghcr.io/cloudcorprecords/gatefile

デフォルトの mcp 引数の代わりに、イメージ名の後に任意の CLI コマンドを渡せます：

docker run ghcr.io/cloudcorprecords/gatefile <command> [args]

使い方

CLI

# Extract gates from a repo (GitHub API, GITHUB_TOKEN optional)
gatefile extract shadcn-labs/pdfcn

# Extract from a local clone instead (fully offline)
gatefile extract local --local ./pdfcn --out contribution-gates.json

# Validate the committed file against fresh docs, exit 1 on drift
gatefile validate shadcn-labs/pdfcn --file contribution-gates.json

# Print a README snippet for humans
gatefile badge shadcn-labs/pdfcn

MCP サーバー

MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "gatefile": {
      "command": "node",
      "args": ["/path/to/gatefile/dist/mcp.js"]
    }
  }
}

ツール：

tool	inputs	戻り値
extract_gates	repo または localPath	contribution-gates.json オブジェクト全体
validate_gates	recorded、repo または localPath	{ ok, drift[] }
gates_badge	repo または localPath	README の Markdown スニペット

CI の例

GitHub Actions のワークフローで、ゲートファイルの内容を最新かつ正確に保ちます：

name: gates
on:
  pull_request:
    paths: ["CONTRIBUTING.md", ".github/**", "contribution-gates.json"]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx -y gatefile extract ${{ github.repository }} --out /tmp/fresh.json
      - run: npx -y gatefile validate ${{ github.repository }} --file contribution-gates.json

開発

npm install
npm test        # tsx --test, offline, 23 tests
npm run build   # tsc to dist/
npm run dev -- extract owner/repo --json

TypeScript ESM、Node 20 以降、スキーマには zod、GitHub API にはネイティブの fetch を使用します。テストでは test/fixtures/ にある実例に基づくフィクスチャを使用します。これらは、ドキュメント化されたケース（作業開始前のコメント、DCO、イシュー必須の組み合わせ、アサイン必須、保証のみ、制限なし）をモデルにしています。

ライセンス

MIT、Rene Turcios 2026。

ツールキット

このツールは、オープンソースへの貢献作業におけるライフサイクルを構成する4つのツールのうちの1つです。すべて @reneturcios npm スコープで公開されており、各ツールは CLI と MCP サーバー（<tool> mcp）として利用できます。

1. gatefile（npx @reneturcios/gatefile）は、リポジトリの貢献条件を抽出し、コミット対象の contribution-gates.json にまとめます。
2. greenlight（npx @reneturcios/greenlight）は、issue を事前チェックして（GO / RISKY / TAKEN / GATED / STALE）、check と scan で gatefile の出力を利用し、その後、issue を確保して準備し、PR を作成します。
3. claimcheck（npx @reneturcios/claimcheck）は、期限切れの claim と、fork に置かれたままの修正を監視します。
4. prwatch（npx @reneturcios/prwatch）は、今すぐ対応が必要なものを基準に、オープン中の PR をトリアージします。