gemini-reviewer-core

README

🤖 Gemini Reviewer Core

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

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

CLI ツール や Web アプリケーション の共通基盤として設計されています。単なる機能の羅列ではなく、「Git 操作 → 差分抽出 → AI 推論 → 結果公開」というレビューのワークフローそのものを集約して提供します。これにより、利用側はインフラの実装詳細を意識することなく、一貫したレビュー体験をユーザーに提供できます。

---

🎯 価値と特徴 (Value & Key Features)

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

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

• ワークフローの共通化: レビューの「手順」が Core パッケージに集約されているため、CLI でも Web でも全く同一のロジック・品質でレビューが動作します。
• 環境に応じた実行戦略: サーバーレス環境（go-git）と、ローカル環境（os/exec）を用途に応じて柔軟に切り替え可能です。
• マルチクラウド対応: GCS/S3 への公開を ports で抽象化。保存先を問わず透過的に扱えます。

🔍 高度な Git 操作戦略

• 柔軟な参照解決: ブランチ名だけでなく、コミットハッシュ（f921111 等）を直接指定したピンポイントなレビューが可能です。
• 安全な解決優先順位: 数字のみのブランチ名（チケット番号等）でも、ハッシュ値より先にリモートブランチを探索。意図しない Detached HEAD を防止します。
• 強力なクリーンアップ: 実行のたびに git checkout -f および git clean -f -d を実行。常にクリーンな状態でレビューを開始します。

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

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

---

📂 プロジェクト構造 (Project Structure)

本ライブラリは、「核心的な契約（Ports）」「実行ロジック（Workflow/Runner）」「具体的な実装（Adapters）」をパッケージレベルで厳密に分離しています。

📦 パッケージの責務

カテゴリ	パッケージ	役割と責務
Core (契約)	ports	すべてのインターフェースとデータ構造を定義。プロジェクトの「憲法」です。
Logic (実行)	workflow	レビューの全体工程（Git → AI → Publish）を制御するオーケストレーターです。
	runner	「レビュー生成」や「結果公開」といった、各工程の具体的な実行ロジックです。
Adapter (実装)	git	リポジトリ操作の実体。go-git または Local CLI を切り替え可能です。
	ai	Gemini API との通信を担当。プロンプト制御を隠蔽します。
	publisher	結果の HTML 変換や、マルチクラウドストレージへの保存を担当します。

🖇 パッケージツリー

gemini-reviewer-core
├── ports/          # 核心：Interface 定義 (ai.go, git.go, publisher.go, workflow.go)
├── runner/         # 実行：単一工程のロジック (review.go, publish.go)
├── workflow/       # 指揮：全体のパイプライン制御 (workflow.go)
├── ai/             # 実装：Gemini API アダプター
├── git/            # 実装：Git 操作アダプター (Local/Go-Git)
└── publisher/      # 実装：成果物出力アダプター (Markdown/Storage)

---

🔄 シーケンスフロー (Sequence Flow)

sequenceDiagram
    participant App as Application (CLI/Web)
    participant WF as Workflow
    participant RR as ReviewRunner
    participant Git as GitService (Local/Go-Git)
    participant AI as CodeReviewAI (Gemini)
    participant PR as PublishRunner
    participant Pub as Publisher (HTML Output)
    participant Conv as Converter (go-prompt-kit)
    participant Store as OutputWriter (GCS/S3)
    participant Noti as Notifier (Slack)

    App->>WF: Run(ctx, ReviewRequest)

    rect rgb(240, 248, 255)
        Note over WF, RR: 【フェーズ1】レビュー実行
        WF->>RR: Run(ctx, req)
        RR->>Git: CloneOrUpdate / Fetch
        RR->>Git: CheckRefExists
        RR->>Git: GetCodeDiff

        alt 差分あり
            RR->>AI: ReviewCodeDiff(model, prompt)
            AI-->>RR: Markdown Content
        else 差分なし
            RR->>RR: Generate Skip Report (Markdown)
        end

        RR->>Git: Cleanup
        RR-->>WF: ReviewProcessOutcome (Markdown + Status)
    end

    rect rgb(255, 245, 238)
        Note over WF, PR: 【フェーズ2】結果公開と通知
        WF->>PR: Run(ctx, outcome)

        alt Outcome にエラーあり
            PR->>PR: Generate Error Report (Markdown)
        end

        PR->>Pub: Publish(ctx, uri, markdown, req)

        Note over Pub, Conv: メタ情報(日時/リポジトリ)を付与
        Pub->>Conv: Run(Combined Markdown)
        Conv-->>Pub: HTML (io.Reader)
        Pub->>Store: Write(uri, html_reader, content_type)
        Pub-->>PR: Done

        PR->>PR: Generate Signed URL (30min expiry)
        PR->>Noti: Notify (SignedURL, storageURI)

        PR-->>WF: ReviewResult
    end

    WF-->>App: Pipeline Completed

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

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

特徴	GitAdapter	GitLocalAdapter
戦略	純粋な Go 実装 (go-git)	外部コマンド (git)
更新	Fetch 主体 (エフェメラル)	Fetch & Reset 主体 (状態管理)
強み	OS 非依存、インメモリ操作	強力なクリーンアップ、高速な差分抽出
認証	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 変換	go-prompt-kit	レビュー結果を、スタイル付きの完全な HTML ドキュメントに変換。
Storage 操作	go-remote-io	GCS/S3 等への書き込みを抽象化し、保存先を透過的に扱います。

---

📜 ライセンス (License)

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

---