LLM Code Reviewer

ローカルLLMを使用してプロジェクトのコードレビューを自動実行するDockerベースのツールです。

特徴

• 🤖 ローカルLLM（LM Studio、OpenWebUI対応）を使用した高度なコードレビュー
• 🎯 カスタマイズ可能なレビュー焦点（セキュリティ、パフォーマンス、PEP8等）
• 🌍 多言語対応（日本語・英語、デフォルトは日本語）
• 🔧 カスタムシステムプロンプトのサポート
• 🚀 ROS2プロジェクト向けに最適化（Python、C++対応）
• 📦 Dockerコンテナで実行し、環境を分離
• 📊 大規模ファイルの自動分割（コンテキスト長を考慮）
• 🎨 JSON形式での詳細な結果出力
• 🚫 除外パターンのサポート（SVNリポジトリ対応）
• 📈 リアルタイム進捗表示（パーセント表示）
• 🔗 ファイルバッチング：小さいファイルを自動的にグループ化して、ファイル間の依存関係を考慮したレビュー
• 📚 リポジトリ概要の共有：他ファイルの概要をプロンプトに含め、断片的なレビューを防止
• 🧠 LangGraphによるレビュー・フロー制御：ファイル収集から結果出力までをグラフで管理し、全体文脈を維持
• 🗂️ Coverage Ledger とレポート：各レビューリクエストの対象チャンクを JSONL で記録し、未レビューの漏れを可視化
• 🪢 行数ベースの決定的チャンク分割：チャンク ID と行番号を安定化し、差分レビューや再実行時の再現性を向上

必要要件

• Docker
• LM Studio（または互換性のあるLLM API）
• 実行中のLLMモデル（推奨: qwen3-coder-30b）

インストール

Dockerイメージのビルド

docker build -t llm-code-reviewer .

使用方法

基本的な使い方

docker run -v /path/to/your/code:/code llm-code-reviewer

カスタム設定での使用

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --api-url http://192.168.50.136:1234/v1 \
  --model qwen/qwen3-coder-30b \
  --context-length 262144 \
  --output /code/review-results.json \
  --repo-overview-tokens 1500 \
  --repo-overview-lines 25

レビュー焦点のカスタマイズ

# セキュリティとパフォーマンスに焦点を当てたレビュー
docker run -v /path/to/your/code:/code llm-code-reviewer \
  --review-focus security \
  --review-focus performance

# PEP8チェックを含む包括的なレビュー
docker run -v /path/to/your/code:/code llm-code-reviewer \
  --review-focus pep8 \
  --review-focus bugs \
  --review-focus maintainability

カスタムシステムプロンプトの使用

# コマンドラインで直接指定
docker run -v /path/to/your/code:/code llm-code-reviewer \
  --system-prompt "あなたは20年の経験を持つシニアエンジニアです。厳格にレビューしてください。"

# ファイルから読み込み
docker run -v /path/to/your/code:/code \
  -v /path/to/prompt.txt:/prompt.txt \
  llm-code-reviewer \
  --prompt-file /prompt.txt

英語でのレビュー

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --language en

除外パターンの指定

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --exclude "*.pyc" \
  --exclude "build/*" \
  --exclude "install/*"

OpenWebUI APIの使用

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --api-url http://your-openwebui-server:3000/v1 \
  --api-key your-api-key-here \
  --model your-model-name

ファイルバッチングの調整

デフォルトでは、10000トークン（約40KB）以下のファイルは同じディレクトリ内でまとめてレビューされます。 これにより、グローバル変数やファイル間の依存関係を考慮したレビューが可能になります。

バッチサイズの制限：

• 最大5ファイル/バッチ
• コンテキスト長の30%まで使用（プロンプトオーバーヘッドを考慮）
• APIタイムアウト：5分（大規模バッチに対応）

バッチングを無効化する場合：

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --batch-threshold 999999

より小さいファイルのみバッチングする場合：

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --batch-threshold 5000

リポジトリ概要を活用したクロスファイルレビュー

リポジトリ内の主要ファイルや定義をプロンプトへ共有し、LLMが断片ではなくプロジェクト全体を踏まえてレビューできるようになりました。

docker run -v /path/to/your/code:/code llm-code-reviewer \
  --repo-overview-tokens 2000 \
  --repo-overview-lines 30

--repo-overview-tokens ではプロンプトに割り当てる最大トークン数を、--repo-overview-lines ではファイルごとの抜粋行数を制御できます。プロジェクトが大きい場合は適宜値を調整してください。

LangGraphによるレビュー・オーケストレーション

本ツールでは LangGraph を使って、以下のステップを明示的なノードとして制御しています。

1. ファイル収集：対象ファイルを検出してスコープを確定。
2. 概要生成：リポジトリ全体の要約を構築し、レビュー時に常に共有。
3. バッチ作成：LangGraphの状態にバッチ情報を保持し、クロスファイルレビューを最適化。
4. レビュー実行：各バッチに対して概要とコンテキストを付与しながらレビュー。
5. 結果出力：最終ノードでJSON出力と進捗レポートを完結。

LangGraphを採用したことで、ワークフローがグラフとして可視化可能になり、処理の一部を差し替えたり、追加の検証ステップを挿入する拡張が容易になりました。

リポジトリ概要はLangGraphの状態として保持されるため、すべてのレビュー・ノードが同じプロジェクトコンテキストを参照しながら指摘内容を判断できます。

Coverage Ledger とレポート

レビューした内容を客観的に追跡するために、各 API コールごとに coverage/ledger.jsonl へ JSON レコードを追記します。レコードには以下が含まれます。

• 参照したコミット SHA（取得できた場合）
• モデル名・API URL・プロンプトハッシュ・概算トークン数
• 対象となったファイルチャンク（path, sha256, start_line, end_line, chunk_id）とステータス（ok / timeout / error）

レビュー対象から除外したファイルや読み込みに失敗したファイルは、coverage.record_skip を通じて Ledger に理由付きで登録されます。最終レポートで「除外」「非UTF-8」「サイズ超過」などの扱いが可視化され、レビュー漏れと意図的な除外を切り分けられます。

処理完了時には LangGraph の最終ノードで coverage/report.json と coverage/report.md を生成します。Markdown レポートには以下の表が含まれ、レビュー状況を一目で把握できます。

1. 未レビューセグメント（理由付き）
2. レビュー済みセグメント（最後にレビューしたチャンク ID・モデル・時刻）
3. 指摘の多いディレクトリ Top N
4. 重大度別ヒストグラムとリスクスコア分布

併せてディレクトリ／ファイル単位のカバレッジ集計を出力し、JSON には同じ情報とチャンク単位の統計が格納されます。バッジ形式の coverage/badge.json も出力され、CI などで利用できます。

--fail-on-miss を指定すると、未レビューのチャンクが 1 つでも残っている場合に非ゼロ終了します。CI のゲートとして活用でき、漏れのないレビューを機械的に保証できます。

コマンドライン引数

引数	デフォルト値	説明
--api-url	http://192.168.50.136:1234/v1	LLM APIのベースURL
--model	qwen/qwen3-coder-30b	使用するモデル名
--context-length	262144	モデルのコンテキスト長（トークン数）
--code-dir	/code	レビュー対象のコードディレクトリ
--output	/code/review-results.json	結果の出力ファイルパス
--exclude	（複数指定可）	除外パターン（グロブ形式）
--review-focus	bugs, performance, maintainability	レビューの焦点（複数指定可）
--language	ja	出力言語（ja または en）
--system-prompt	-	カスタムシステムプロンプト
--prompt-file	-	システムプロンプトを含むファイルのパス
--api-key	-	API認証キー（OpenWebUI等で必要な場合）
--debug	False	デバッグモードを有効化（詳細なログ出力）
--batch-threshold	10000	バッチ処理の閾値（トークン数）。この値より小さいファイルはまとめてレビュー
--repo-overview-tokens	0	各レビューリクエストに添付するリポジトリ概要の最大トークン数（0で無効）
--repo-overview-lines	20	概要に含める各ファイルの抜粋最大行数
--fail-on-miss	False	未レビューのチャンクが残っている場合に非ゼロ終了コードを返す

レビュー焦点のオプション

オプション	説明
security	セキュリティ脆弱性（SQLインジェクション、XSS、バッファオーバーフロー等）
performance	パフォーマンスの問題（不要なループ、メモリリーク、非効率なアルゴリズム等）
pep8	PEP8コーディング規約の違反（Pythonファイルのみ）
ros2	ROS2固有の問題（ノードの設計、トピック/サービスの使用方法等）
bugs	潜在的なバグとロジックエラー
maintainability	保守性（コードの可読性、複雑度、ドキュメンテーション等）
general	一般的なコード品質の問題

出力形式

結果はJSON形式で出力されます：

• risk_score は 1〜10 の整数で、不具合の危険度を表します（10: 修正必須、1: 様子見で問題なし）。

{
  "total_files": 10,
  "files_with_issues": 3,
  "results": [
    {
      "file": "src/example.py",
      "reviews": [
        {
          "line": 42,
          "severity": "warning",
          "risk_score": 7,
          "message": "潜在的なnullポインタ参照の可能性があります。line 42の変数がNoneでないことを確認してください。"
        },
        {
          "line": 15,
          "severity": "info",
          "risk_score": 3,
          "message": "PEP8: 関数名は小文字とアンダースコアを使用してください（myFunction → my_function）"
        }
      ]
    }
  ]
}

サポートされるファイル形式

• Python (.py)
• C++ (.cpp, .cc, .cxx, .hpp, .h)
• C (.c, .h)
• ROS2 Launch (.launch)
• YAML (.yaml, .yml)
• XML (.xml)

デフォルトの除外パターン

以下のパターンはデフォルトで除外されます：

• *.pyc, *.pyo
• __pycache__/*
• .svn/*, .git/*
• build/*, install/*, log/*

LM Studioの設定

1. LM Studioを起動
2. モデルをロード（推奨：qwen3-coder-30b）
3. ローカルサーバーを起動
4. サーバーのIPアドレスとポートを確認（例：http://192.168.50.136:1234）
5. このツールから接続

OpenWebUIの設定

1. OpenWebUIサーバーを起動
2. APIキーを取得（設定画面から）
3. 使用するモデルを選択
4. このツールから--api-urlと--api-keyを指定して接続

進捗表示

実行中は、以下のような進捗表示が出力されます：

10個のファイルが見つかりました

[1/10 (10.0%)] レビュー中: src/example.py
[バッチ 2/5 (40.0%)] 3ファイルをまとめてレビュー中:
  - src/utils.py
  - src/helper.py
  - src/config.py
[5/10 (50.0%)] レビュー中: src/main.cpp
...

小さいファイルは自動的にバッチ処理され、関連ファイルを一緒にレビューします。

使用例

基本的なレビュー

docker run -v ~/my-ros2-project:/code llm-code-reviewer

セキュリティとPEP8に焦点を当てたレビュー

docker run -v ~/my-ros2-project:/code llm-code-reviewer \
  --review-focus security \
  --review-focus pep8

カスタムプロンプトでの厳格なレビュー

docker run -v ~/my-ros2-project:/code llm-code-reviewer \
  --system-prompt "あなたは経験豊富なROS2エンジニアです。バグ、セキュリティ問題、パフォーマンスの問題を見逃さず、厳格にレビューしてください。" \
  --review-focus security \
  --review-focus performance \
  --review-focus ros2

トラブルシューティング

API接続エラー

LM Studioが起動していることと、指定したURLが正しいことを確認してください。また、ネットワーク設定でポートがブロックされていないか確認してください。

タイムアウトエラー

大きなファイルや複雑なコードの場合、レビューに時間がかかることがあります。現在のAPIタイムアウトは5分（300秒）に設定されています。それでもタイムアウトが発生する場合は、reviewer.pyのAPI_TIMEOUT_SECONDS定数を調整してください。

メモリ不足

大規模プロジェクトの場合、十分なGPUメモリが必要です。qwen3-coder-30bモデルには大容量のGPUメモリ（推奨128GB以上）が必要です。

日本語出力が文字化けする

Docker環境のロケール設定を確認してください。UTF-8がサポートされていることを確認してください。

貢献

プルリクエストを歓迎します。大きな変更の場合は、まずissueを開いて変更内容を議論してください。

ブランチ運用について

• 既定ブランチは main です。作業を始める前に git checkout main → git pull で最新化してください。
• 機能追加や修正は、main から派生したフィーチャーブランチ（例：feature/coverage-ledger）を作成して行います。
• 変更がまとまったら main 向けに Pull Request を作成し、目的と主要な変更点、テスト結果を記載してください。
• マージ後は再度 main を最新化し、次の作業用ブランチを切ることで main を常に安定させられます。

ライセンス

MIT License

作者

Devin AI (@y1618)