gemini-reviewer-core

README

🤖 Gemini Reviewer Core

🚀 概要 (About) - ビジネスロジックに集中させる、Git & Gemini 抽象化レイヤー

Gemini Reviewer Core は、Google Gemini API を活用し、Git リポジトリのブランチ間の差分を分析して AI コードレビューを自動生成するための コアライブラリ です。

本ライブラリは、CLI ツール や Web アプリケーション の共通基盤として設計されています。Git 操作、AI 通信といった「ビジネスロジック」に加え、HTML 変換や結果保存を行う公開層（Publisher）を提供します。これにより、利用側はインフラの実装詳細を意識することなく、レビュー結果の生成から公開までを一貫して行えます。

---

🎯 本ライブラリの価値と特徴 (Value & Key Features)

単なるレビュー用スクリプトではなく、大規模なアプリケーションにも組み込める持続可能で堅牢な基盤を提供します。

⚡ 開発効率と適応性の最大化

• プロセスの抽象化: Git 操作、SSH 認証、AI との対話、結果の整形・公開といった複雑な工程をすべて隠蔽。利用者はレビューの核心となるロジックに集中できます。
• 環境に応じた実行戦略: サーバーレス環境での安定実行（go-git）と、ローカル環境での高速実行（os/exec）を用途に応じて柔軟に切り替え可能です。
• マルチクラウド対応: GCS/S3 への公開を抽象化されたインターフェース (Publisher) で一元管理。保存先を問わず透過的に扱えます。

🔍 高度な Git 操作戦略

• 柔軟な参照解決: ブランチ名（develop）だけでなく、特定のコミットハッシュ（f921111 等）を直接指定してピンポイントなレビューが可能です。
• 安全な解決優先順位: 数字のみのブランチ名（チケット番号等）を使用している場合でも、ハッシュ値より先にリモートブランチを探索。意図しない Detached HEAD 状態を防止します。
• 強力なクリーンアップ: 実行のたびに git checkout -f および git clean -f -d を実行。以前の実行で残ったゴミやコンフリクトを強制排除し、常にクリーンな状態でレビューを開始します。
  • ※注意: --local-path 指定時は未コミットの変更が失われるためご注意ください。

📐 堅牢なアーキテクチャ設計

• DIP（依存性逆転の原則）の徹底: 厳格なクリーンアーキテクチャに基づき、ストレージの変更や AI モデルの切り替えといった将来の拡張に対する高い耐性を持っています。
• 優れたテスト容易性: インターフェース（Ports）を中心に設計されているため、モックへの差し替えが容易で、高いテストカバレッジを維持できます。

---

🧩 Git 操作戦略：アーキテクチャ設計と適応性

プロジェクトの環境に合わせて、最適なGit操作アダプターを選択可能です。

特徴	GitAdapter	GitLocalAdapter
戦略	純粋な Go 実装 (go-git)	外部コマンド (git diff)
更新	Fetch 主体 (使い捨て)	Pull 主体 (永続化)
強み	OS非依存、インメモリ操作	高速、.gitattributes 考慮済
認証	Go内での認証管理	OS標準 (SSH/Agent/Config)
制御	context.Context に完全準拠	exec.CommandContext でタイムアウト制御
適性	サーバーレス・コンテナ環境	ローカル開発・CIパイプライン

---

✨ 技術スタック (Technology Stack)

要素	技術 / ライブラリ	役割
言語	Go (Golang)	ライブラリの開発言語。
Git 操作	go-git	クローン、フェッチ、3-dot diff の取得まで完結。SSH 認証とホストキー検証を統合。
AI 推論	go-gemini-client	Gemini API へのアクセス。堅牢な通信 SDK をラッピングして提供。
Markdown to HTML	go-prompt-kit	レビュー結果を、スタイル付きの完全な HTML ドキュメントに変換。
ストレージ操作	go-remote-io	GCS/S3 等への書き込みを抽象化し、保存先を透過的に扱います。

---

承知いたしました。新しいディレクトリ構造に合わせて、役割と構成を整理し直しました。 pkg/core 内での関心の分離（AI、Git、Publisher）がより明確になったことを強調しています。

---

📐 ライブラリ構成

このライブラリは、クリーンアーキテクチャの原則に基づき、コアロジックを再利用可能なコンポーネントとして提供します。依存性の逆転（DIP）を徹底し、ビジネスロジックが特定の外部ツールに依存しない設計となっています。

gemini-reviewer-core
├── ai             # Gemini API との通信・プロンプト制御
├── git            # Git リポジトリ操作（Clone, Fetch, Diff, Cleanup）
├── ports          # ポート（インターフェース）定義の核
└── publisher      # レビュー結果の変換（Markdown→HTML）と外部公開

パッケージの役割

1. pkg/ai: Gemini API との低レイヤーな通信をカプセル化します。単なる API クライアントにとどまらず、レビュー用のシステムプロンプト管理や、AI モデルの挙動制御を担います。
2. pkg/git: リポジトリ操作の具象実装です。特に git_local.go は、OS の git コマンドを直接制御することで、ハッシュ指定による差分取得や、-f（force）オプションを用いた強力なクリーンアップ機能を提供し、CI/CD 環境での安定した動作を保証します。
3. pkg/ports: システムの「契約」を定義する最重要レイヤーです。
   • git.go: Script(ctx, sourceURL, mode) など、外部リソース取得のインターフェースを定義。
   • ai.go: AI 解析のインターフェースを定義。
   • publisher.go: Panel(..., outputPath) や Page(..., outputPath) など、成果物生成のインターフェースを定義。
4. pkg/publisher: 生成された Markdown レビューを HTML へ変換し、go-remote-io を通じてオブジェクトストレージ（GCS/S3 等）へアップロードします。引数に outputPath を取ることで、ローカル・クラウドを問わず透過的な出力管理を実現しています。

---

📜 ライセンス (License)

このプロジェクトは MIT License の下で公開されています。

---