メインコンテンツへ移動
AIチュートリアル

Jev Reviewで構造化されたGitレビューとコードベースレビューを実行する方法

Jev Reviewのインストール方法と、現在のGit変更の分析やコードベース全体のスキャン方法を解説します。段階的なレビューワークフロー、CLIコマンド、ローカルダッシュボード、アーキテクチャ、実用上の制限について説明します。

約9分で読了
Jev Reviewで構造化されたGitレビューとコードベースレビューを実行する方法

Jev Reviewの概要

Jev Reviewは、TypeSafe Jevで構築された小規模なコードレビューワークフローです。Gitの差分をレビューしたり、選択した範囲内にある無視対象ではないすべてのソースファイルをスキャンしたりして、結果を簡潔なローカルダッシュボードに表示できます。

このワークフローでは、オーケストレーションとポリシーをアプリケーションコードで管理し、範囲を限定した構造化された判断にJevを使用します。検出結果は、欠陥の存在を決定的に証明するものではなく、レビューのきっかけとして意図されています。

Jev Reviewダッシュボード

レビューワークフローの仕組み

Jev Reviewは、影響度を割り当てる前に確認対象を絞り込む段階的なプロセスに従います。

  1. リスクマトリクスを作成する。
  2. ファイルプロファイルを選択してスコアを付ける。
  3. 関連する証拠を選択する。
  4. 根本的なメカニズムを分類する。
  5. 重大度をスコアリングする。
  6. ワークフローで必要な場合、選択した検出結果をレビュアーに回す。

レビュアーは、正確性、セキュリティ、信頼性、互換性、テストカバレッジを確認します。テスト不足を判断する際には、変更されたテストや関連するテストをコンテキストとして利用できます。また、影響度をスコアリングする前に、具体的な差分ハンクまたはソース領域を選択し、構造化されたヒント、反例、判断境界、しきい値、ワークフローポリシーを適用します。

前提条件とインストール

開始する前に、Node.js 24以降とGitをインストールしてください。また、TypeSafe APIキーも必要です。

プロジェクトをクローンするか別の方法で取得し、依存関係をインストールします。

npm install

用意されているサンプルから環境ファイルを作成します。

cp .env.example .env

.envを開き、APIキーを追加します。

TYPESAFE_API_KEY=your_api_key

このファイルをダッシュボード経由で公開しないでください。Jev Reviewはダッシュボードを127.0.0.1にバインドし、環境ファイルを提供しません。

現在のGit差分をレビューする

現在のGit差分のレビュー結果をJSONで出力するには、変更レビューコマンドを実行し、Gitリポジトリへのパスを指定します。

npm run review:changes -- /path/to/git/repository

このモードは、リポジトリに現在存在する変更に集中してフィードバックを得たい場合に便利です。

後でダッシュボードから表示できるよう結果を保存するには、保存用のバリアントを使用します。

npm run review:changes:save -- /path/to/git/repository

コードベース全体をスキャンする

より広範なレビューを行うには、リポジトリまたはパッケージの範囲内にある、無視対象ではないすべてのソースファイルをスキャンします。

Jev Reviewダッシュボード

npm run review:codebase -- /path/to/git/repository-or-package

このコマンドは、コードベース全体のスキャン結果をJSONで出力します。代わりにダッシュボード用のレポートを保存するには、次を実行します。

npm run review:codebase:save -- /path/to/git/repository-or-package

現在の変更を重点的にレビューする必要がある場合は変更レビューのエントリーポイントを使用し、選択した範囲にある利用可能なソースファイルを調査する場合はコードベース全体のエントリーポイントを使用します。

ローカルダッシュボードを開く

変更レビューまたはコードベーススキャンを保存した後、ローカルダッシュボードを起動します。

npm run dashboard

ブラウザーでhttp://127.0.0.1:4317を開きます。大きなレポートは折りたたみ可能なセクションに表示されるため、ローカル環境から離れずに検出結果を確認しやすくなります。

コマンドリファレンス

  • npm run review:changes -- <path>は、現在の差分レビューをJSONで出力します。
  • npm run review:changes:save -- <path>は、現在の差分レビューをダッシュボード用に保存します。
  • npm run review:codebase -- <path>は、コードベース全体のスキャン結果をJSONで出力します。
  • npm run review:codebase:save -- <path>は、コードベース全体のスキャン結果をダッシュボード用に保存します。
  • npm run dashboardは、ローカルダッシュボードを起動します。
  • npm run checkは、プロジェクトの型チェック、依存関係の流れの検証、ダッシュボードクライアントの構文チェックを行います。

プロジェクト構成を理解する

実装はsrc/以下で、下位レイヤーのみに依存する層構造として整理されています。

src/
  domain/      config.ts, types.ts, patch.ts
  adapters/    git.ts, repository-files.ts
               report-store.ts
  review/      changes.ts, codebase.ts
               *-judgments.ts, workflow.ts
  cli/         review-*.ts, save-*.ts
  dashboard/   server.ts, public/

各レイヤーの役割は次のとおりです。

  • Domain:共有設定、レポート型、ポリシー、差分解析。
  • Adapters:Gitと完全なソースの検出、およびレポートのアトミックな保存と読み込み。
  • Review:モード固有のワークフロー、Jevの呼び出し、段階的なオーケストレーション。
  • CLI:明示的なレビューおよび保存のエントリーポイント。
  • Dashboard:ローカル専用のHTTPサーバーとシンプルなクライアント。

インポートはcliとdashboardからreviewへ、さらにadaptersとdomainへと下方向に流れます。ダッシュボード層とCLI層は互いにインポートしません。

高度な利用方法とプロジェクトチェック

ワークフローの変更を信頼して使用したり、アーキテクチャ上の変更に貢献したりする前に、プロジェクトのチェックを実行してください。

npm run check

このコマンドは型を確認し、依存関係の流れを検証し、ダッシュボードクライアントの構文をチェックします。依存関係スクリプトは、上位層へのインポート、cli と dashboard 間のインポート、または依存関係の循環を検出すると失敗します。

より対象を絞ったレビューを行うには、関連する Git の変更を加えた後で変更レポートを保存し、ダッシュボードから確認します。より広範な調査では、スキャンしたいリポジトリまたはパッケージ範囲へのパスを指定します。2つのエントリポイントにより、変更を対象とするワークフローとソース全体を対象とするワークフローを分離できます。

Jev Review は、高速で型付きの判断を組み合わせる実験であることを覚えておいてください。現在のところ、コンパイラ診断、静的解析ツール、リポジトリのインデックス作成、生成された説明には対応していません。特に、報告された重要度だけを根拠に変更を加える前には、その結果を人間によるレビューを促す材料として扱ってください。

結論

Jev Review は、現在の Git 差分を対象とする重点分析と、無視対象でないコードベース全体の範囲をスキャンする分析という、2つの実用的なレビュー方式を提供します。依存関係をインストールし、TYPESAFE_API_KEY を設定してレポートを保存し、ローカルダッシュボードを開いて構造化された検出結果を確認します。段階的な判断、証拠の選択、明示的なワークフローポリシーにより、AI 支援コードレビューを整理するための有用なローカル実験となっています。