codacy-code-review

Codacy コードレビュー

用語集： Codacy の概念（問題、検出結果、重大度、カバレッジ、ツール、パターンなど）の共通定義については、glossary.mdを参照してください。

このスキルは、Codacy のデータを活用してコードレビューを強化します。既存のコードレビュープロセス（コードレビュー用スキル、CodeRabbit、手動レビューなど）と併用でき、Codacy 固有のデータを追加します。

前提条件

• Codacy Analysis CLI（codacy-analysis）— 高速なローカル分析に使用します。セットアップについては、codacy-analysis-cliを参照してください。
• Codacy Cloud CLI（codacy）— カバレッジデータ、品質ゲートのステータス、問題の無視に使用します。セットアップについては、codacy-cloud-cliを参照してください。

両方の CLI は ~/.codacy/credentials の認証情報を共有するため、一度ログインすれば両方で利用できます。

ローカル分析とクラウド分析

このスキルでは、相互補完する 2 つの分析ソースを使用します。

ソース	提供する内容	速度
Analysis CLI（ローカル）	PR の変更に関する問題とセキュリティ上の検出結果	即時 — push やリモート分析は不要です
Cloud CLI（リモート）	カバレッジ差分、品質ゲート、重複、問題管理（無視／無視解除）	PR が push され、Codacy による分析が完了している必要があります

問題の検出には、ローカル分析を優先してください。--pr を指定すると、現在の作業ツリーをすぐに分析でき、リモート分析を待つ必要がありません。カバレッジデータと品質ゲートのステータスを補完するには Cloud CLI を使用し、問題の管理（無視／無視解除）にも使用してください。

Analysis CLI は、Codacy Cloud が実行するすべてのツールに対応しているとは限りません。プロジェクトでローカルでは利用できないツールが使われている場合（codacy-analysis analyze --inspect --output-format json で確認）、一部の検出結果は Cloud の結果にのみ表示される可能性があることを明記してください。

Codacy の PR データの仕組み

• Cloud データは PR の HEAD コミットを反映します — 表示されるリモート分析は、特定のコミットではなく、PR ブランチへの最新の push を常に対象とします。
• ローカル分析は作業ツリーを反映します — codacy-analysis analyze --pr は、現在のブランチと PR のターゲットブランチを比較し、push 前でも問題を検出します。
• 問題の無視は Cloud のみで行える操作です — Codacy ではすぐに反映されますが、その他の設定変更（パターン、ツール）は次回のリモート分析後にのみ適用されます。
• リモート分析が古い、または存在しない場合 — Cloud の PR 分析が古い、または不完全に見える場合は、codacy pull-request <provider> <org> <repo> <prNumber> --reanalyze-and-wait を使用して再分析を開始し、完了するまで待機します（10 秒ごとにポーリングし、最大 20 分）。待機せずに実行する場合は --reanalyze を使用し、後で手動で再確認してください。
• 自動検出 — リポジトリ内で実行すると、Cloud CLI は git remote からプロバイダー／組織／リポジトリを自動検出します。codacy pull-request <prNumber> のようなコマンドは、明示的なパラメーターなしで実行できます。

レビューワークフロー

プルリクエストをレビューするときは、以下の手順に従ってください。必ずすべての手順を完了し、省略しないでください。

Code Review Progress:
- [ ] Step 1: Gather PR context (title, description, linked ticket)
- [ ] Step 2: Run local analysis on PR changes
- [ ] Step 3: Fetch Cloud PR data (coverage, quality gate)
- [ ] Step 4: Check introduced issues
- [ ] Step 5: Check coverage
- [ ] Step 6: Verify alignment with ticket and PR description
- [ ] Step 7: Propose test plan and check coverage gaps
- [ ] Step 8: Summarize and suggest improvements

ステップ 1：PR のコンテキストを収集する

ソースプロバイダー（GitHub、GitLab、Bitbucket）からプルリクエストのメタデータを取得します。

• PR のタイトルと説明
• 関連するチケットまたは issue（Jira、GitHub Issues、Linear、ローカル仕様など）— 説明、ブランチ名、コミットメッセージを確認します

関連するチケットがある場合は、その内容も取得してください。

ステップ 2：PR の変更をローカルで解析する

Analysis CLI を実行して、変更されたファイルの結果をすぐに取得します。リモート解析を待つ必要はありません。

# If the PR already exists (compares against the PR's target branch)
codacy-analysis analyze --pr --fail-if-missing --output-format json

# If the PR hasn't been created yet (compares against the merge base of the current branch)
codacy-analysis analyze --diff --fail-if-missing --output-format json

プルリクエストが作成済みの場合は --pr を、PR を開く前にブランチ上の変更をレビューする場合は --diff を使用します。どちらも、変更されたファイルに対してローカルで利用可能なすべてのツールを実行します。

ここでは --fail-if-missing が重要です。 これを指定しないと、利用できないスキャナーは通知なしにスキップされ、問題が何も検出されないまま実行が 0 で終了します。何もスキャンされていないのに、「問題は持ち込まれていない」としてレビュアーに届いてしまいます。

実行がブロックされた場合（errors[].kind == "UnavailableTools"）、またはプロジェクトが初期化されていない場合は、まずインストールしてから、厳密なコマンドを再実行します（この 2 つのフラグは同時に指定できません）。

codacy-analysis init   # only if not initialized
codacy-analysis analyze --pr --install-dependencies --output-format json
codacy-analysis analyze --pr --fail-if-missing --output-format json

ローカルの結果を解析して問題を確認します。結果はすぐに利用でき、レビューの大部分をカバーします。PR に問題が持ち込まれていないと結論づける前に、toolResults が空でないこと（空の場合は何もスキャンされていません）を確認し、capability.unavailable やクラウド専用ツールがあれば、解析範囲に記載します。

ステップ 3：クラウドの PR データを取得する（カバレッジ、品質ゲート）

カバレッジ、品質ゲートのステータス、重複メトリクスは Codacy Cloud でのみ利用できます。

codacy pull-request <provider> <org> <repo> <prNumber>

以下が返されます：標準準拠のステータス、カバレッジの差分、複雑度の差分、重複の差分、変更されたファイル。

インラインのカバレッジ注釈付きの差分を表示するには：

codacy pull-request <provider> <org> <repo> <prNumber> --diff

リモート解析が古い場合や見つからない場合は、再解析を開始して完了まで待ちます：

codacy pull-request <provider> <org> <repo> <prNumber> --reanalyze-and-wait

再解析が完了するまでブロックされ（最大 20 分）、差分が報告されます。待っている間は、ステップ 2 のローカル結果を使ってレビューを続けます。完了を待たずに再解析するには、代わりに --reanalyze を使用します。

ステップ 4：持ち込まれた問題を確認する

ローカル解析（ステップ 2）とクラウドデータ（ステップ 3）の両方の結果を組み合わせます。

• ローカルの問題は通常、先に利用可能になるため、これを使ってすぐにレビューを開始します
• クラウドの問題には、ローカルで利用できないツールによる検出結果が含まれる場合があります。リモート解析の完了後に相互参照します
• 各問題の重大度、カテゴリ、ファイルの場所を記録します
• Critical と High の重大度の問題はブロッカーとして報告します

誤検知と思われる問題がある場合は、Cloud CLI を使って無視するよう提案します：

# Ignore a specific issue in this PR
codacy pull-request <provider> <org> <repo> <prNumber> --ignore-issue <issueId> --ignore-reason FalsePositive

# Ignore all issues Codacy identified as potential false positives in one go
codacy pull-request <provider> <org> <repo> <prNumber> --ignore-all-false-positives

# Unignore if needed
codacy pull-request <provider> <org> <repo> <prNumber> --unignore-issue <issueId>

同じ誤検知パターンが複数の PR で繰り返し現れる場合は、代わりに configure-codacy を使ってそのパターンを無効にするよう提案します。

ステップ 5：カバレッジを確認する

カバレッジデータは Cloud CLI（ステップ 3）から取得します。以下を確認します：

• 全体のカバレッジ差分（上がったか、下がったか）
• PR によって導入された未カバー行があるファイル
• どの行がカバーされていないか（✘ マーカー）を確認するには、--diff の出力を使用します

新たに未カバー行があるファイルは、テストが必要として報告します。

ステップ 6：整合性を確認する

チケット／Issue との整合性： コード変更が記載された要件に対応していることを確認します。チケットに記載されているものの、変更に含まれていない機能があれば記録します。チケットの範囲を超える変更があれば記録します。

PR の説明との整合性： 説明が変更内容を正確に反映していることを確認します。不一致があれば記録します。

チケットまたは PR の説明がない、不完全、または不正確な場合は、提案する具体的な改善点を記載します。

ステップ 7：テスト計画を提案する

変更されたコードとカバレッジデータに基づいて：

1. テストすべきシナリオを列挙します（正常系、境界ケース、エラーケース）
2. 各シナリオについて、PR の差分に既存のテストがあるか確認します
3. 対応するテストも Codacy のカバレッジもないシナリオを報告します

ステップ 8：概要

構造化されたレビュー概要を提示します。

## Codacy Review Summary

### Quality gate
[Pass / Fail — from Codacy PR analysis]

### Issues introduced
[List issues by severity, or "None — see Analysis coverage"]

### Analysis coverage
[Tools that ran; any skipped (with reason) or cloud-only]

### Coverage
[Delta, uncovered lines in new code]

### Alignment
- Ticket: [aligned / gaps noted]
- PR description: [accurate / suggestions]

### Test plan
[Proposed scenarios and whether tests exist]

### Suggested improvements
- PR description: [if applicable]
- Ticket/issue: [if applicable]

別のコードレビュー用スキルが有効な場合

コードレビュー用スキル（例：code-review スキル、CodeRabbit）がすでにレビューを実施している場合は、そのレビューを置き換えるのではなく、Codacy データのセクションを追加します。上記のステップ 2～7 に従い、Codacy の検出結果を末尾に追加します。