pr-review-comments

PR レビューコメント

GitHub Pull Request に、各ファイルと行に紐付けたレビュー指摘の JSON 配列をインラインコメントとして投稿します。 認証済みの gh CLI を使って GitHub API を呼び出すため、トークンを扱う必要はありません。

前提条件

• gh CLI がインストールされ、認証済みであること（gh auth status）。スクリプトは gh repo view でリポジトリを自動検出します。上書きするには --repo OWNER/REPO を渡してください。
• コメントを投稿する PR 番号。
• JSON ファイル：オブジェクトの配列。各オブジェクトに必須のキーは file、line です。 メッセージは summary と failure_scenario（本文にまとめて記載）、または明示的な body から取得します。完全なスキーマとサンプルについては、references/json-schema.md を参照してください。

主な制約：コメントできるのは差分の行のみ

GitHub がインラインコメントを受け付けるのは、対象行が PR の差分に含まれている場合だけです。 line は新しいファイルの行番号です（削除された行には side: "LEFT" を使用してください）。 スクリプトは PR の差分を取得し、すべての指摘を実際のハンクと照合して検証します。差分の範囲外にあるものはスキップし、何も通知されずに失われることがないよう、最後に報告します。変更されておらず、差分に含まれない行に行コメントを付ける方法はありません。

ワークフロー

1. JSON のパスと PR 番号を確認します。リポジトリが明らかでない場合は、gh repo view を実行します。
2. 何が投稿され、何がスキップされるかを確認するため、まずドライランを実行します。

   scripts/post_pr_comments.py --pr <N> --json <path> --dry-run
   

3. 「Postable」／「Skipped」の件数をユーザーと確認します。差分の移動が原因で行がスキップされた場合は、JSON の行番号が古くなっている可能性があるため、投稿前に調整してください。
4. モードを選んで実際に投稿します（以下を参照）。

   # Grouped (default): one PR review bundling all comments
   scripts/post_pr_comments.py --pr <N> --json <path> --event COMMENT
   
   # Individual: one separate inline comment per finding
   scripts/post_pr_comments.py --pr <N> --json <path> --mode individual
   

5. 作成されたレビュー／コメントの URL と、スキップされた指摘があればその一覧を報告します。

モードの選択

モード	エンドポイント	使用する状況
grouped（デフォルト）	POST /pulls/{n}/reviews	複数の指摘を 1 つのレビューとして投稿する場合。通知は 1 件です。--event APPROVE | REQUEST_CHANGES | COMMENT を設定できます。
individual	POST /pulls/{n}/comments	個別のコメントを段階的に追加する場合、または各指摘を個別のスレッド／通知にする場合。

ユーザーが判定や個別のスレッドを希望しない限り、--event COMMENT を指定して grouped をデフォルトとして使用します。

オプションのリファレンス

--pr N              PR number (required)
--json PATH         JSON array of findings (required)
--repo OWNER/REPO   Override auto-detected repo
--mode grouped|individual   Default: grouped
--event COMMENT|APPROVE|REQUEST_CHANGES   Grouped-mode verdict (default COMMENT)
--review-body TEXT  Top-level summary body for the grouped review
--commit SHA        Commit to anchor to (default: PR head SHA)
--dry-run           Validate and print payloads without posting

注意事項

• 複数行範囲のコメント：JSON オブジェクトで line とあわせて start_line（および任意の start_side）を指定すると、スクリプトがそのまま渡します。
• 見慣れない PR に実際に投稿する前には、必ず --dry-run を実行してください。行番号が古いことが最もよくある失敗で、ドライランなら副作用なく「skipped」として検出できます。
• スクリプトを確実な方法として使用してください。この用途で gh api の呼び出しを手作業で組み立てないでください。差分の検証、リポジトリ／コミットの検出、本文の一貫した組み立てを処理します。