coldteadotai/pr-lens

PR Lens – プルリクエストの視覚的レビュー

何ができるか

• プルリクエスト（PR）が開かれると、PR Lens は変更のアニメーション付きアーキテクチャ図を含むコメントを投稿します。この図は、追加・変更・削除されたファイル、サービス、コンポーネント（緑／琥珀／赤）とそれらの間のデータフローを示します。
• コメントはインタラクティブです：<details> セクションに展開され、全体の「影響範囲」、新規コードパス、または廃止された部分に焦点を当てられます。
• 各図はフルサイズのキャンバスで開け、パン・ズームが可能で、ライト／ダークテーマを切り替えられます。ウォークスルーモードでは、変更を1ステップずつ進め、影響を受けたノードとルートを強調表示します。

導入方法

1. GitHub App – 任意のリポジトリに coldtea‑pr‑lens アプリをインストールします。アプリは各PRを自動分析し、SVGをレンダリングし、プッシュごとにコメントを更新します。
2. GitHub Action – CIで同じ分析を実行するワークフロー（.github/workflows/pr‑lens.yml）を追加します。独自のLLM APIキー（デフォルトはGemini、OpenAIまたは任意の /chat/completions エンドポイントも利用可能）を使用します。
3. CLI – @coldtea/pr‑lens‑cli をローカルで実行して、diffを分析し、SVGをレンダリングし、markdownコメントを生成し、生成されたグラフを検証したり、システムの永続的なマップをエクスポートできます。
4. エージェントスキル – スキル（npx skills add coldteadotai/pr‑lens）をインストールすることで、コーディングアシスタント（Claude、Gemini、Copilotなど）がグラフドキュメントを自動生成し、コメントを投稿できるようになります。

主要コンポーネント

パッケージ	役割
@coldtea/pr‑lens‑schema	すべての部分で共有されるグラフ契約を定義するJSONスキーマ
@coldtea/pr‑lens‑renderer	JSONグラフを決定論的でアニメーション付きのSVG（ライト／ダークペア）に変換
@coldtea/pr‑lens‑cli	LLMとやり取りしてgit diffをグラフに変換し、SVGをレンダリングし、コメントを構築し、検証し、マップをエクスポート可能
pr‑lens GitHub Action	CIフレンドリーなラッパーでCLIを実行し、静的コメントを投稿
@coldtea/pr‑lens‑agent‑skill	コーディングエージェントにグラフ生成と投稿を教える小さな「スキル」

設定

• .github/pr‑lens.yml ファイルを追加して、ファイルの名前変更、除外、グループ化、ランをピン留めなどを行います。このファイルはコードの進化に伴っても有効なオーバーレイです。
• CLIは自動的に .pr‑lens/ フォルダ（git無視）を作成し、一時ファイルを保存します。コミットする可能性がある唯一のアーティファクトはエクスポートされたマップ（.github/pr‑lens.map.json）です。

なぜ重要か 大きなPRのレビューは精神的に負担が大きいです。PR Lens はテキストのdiffを、システムのどの部分が影響を受け、データがどのように移動するかを示す視覚的マップに変換し、コードの一行一行を読む前に影響を把握できるようにします。

実際の例を見る場所

• 「Hall of Fame」にリンクされたライブ例（例：React Hooks、Node fetch、Kubernetes Ingress、vLLM）。それぞれがPR Lensでレンダリングされた実世界のPRを示しています。
• Web UI（prlens.dev）がインタラクティブキャンバスをホストしています。

導入手順

# GitHub Appをインストールする（またはActionを追加する）
# またはローカルで実行する：
export GEMINI_API_KEY=YOUR_KEY   # または OPENAI_API_KEY
npx @coldtea/pr-lens-cli analyze --base origin/main
npx @coldtea/pr-lens-cli render .pr-lens/graph.json
open .pr-lens/*-dark-*.svg

ライセンス – MIT。