中核概念
このドキュメントでは、Upsilon で使用される主要な概念と用語について説明します。
問題の種類と重要度レベル
Upsilon はコードの問題を異なる種類と重要度レベルに分類して、修正の優先順位付けを支援します。
重要度レベル
- error 🚫: コードの実行を妨げる、または失敗を引き起こす重大な問題
- warning ⚠️: 対処すべきだが実行を妨げない問題
- info ℹ️: 提案や軽微な改善点
一般的な問題タイプ
構文問題
- syntax_error: 言語の構文規則に違反するコード
- compilation_error: コンパイルに失敗するコード
- missing_colon: Python 固有の欠けているコロンエラー
- indentation_error: 不正なインデンテーション(Python)
コード品質問題
- unused_import: 使用されていないインポートモジュール/パッケージ
- unused_variable: 宣言されたが使用されない変数
- unreachable_code: 実行されることのないコード
- duplicate_code: リファクタリング可能な重複コードブロック
スタイル問題
- naming_convention: 命名規則に従わない変数/関数
- line_too_long: 推奨長を超える行
- missing_docstring: ドキュメントのない関数/クラス
- inconsistent_formatting: 一貫性のないコードフォーマット
論理問題
- potential_bug: バグを引き起こす可能性のあるコードパターン
- type_mismatch: 型注釈の不整合
- null_pointer: 潜在的な null/undefined アクセス
- infinite_loop: 永続的に実行される可能性のあるループ
セキュリティ問題
- hardcoded_secret: ソースコード内の API キーやパスワード
- sql_injection: SQL インジェクションの潜在的脆弱性
- path_traversal: 安全でないファイルパス操作
- unsafe_deserialization: 危険なデータ逆シリアル化
パフォーマンス問題
- inefficient_algorithm: 時間計算量の悪いアルゴリズム
- memory_leak: 潜在的なメモリリーク
- blocking_io: 非同期コードでのブロッキング I/O 操作
- excessive_allocation: 不要なオブジェクト作成
問題オブジェクトの例
{
"type": "unused_import",
"message": "インポートされたモジュール 'os' が使用されていません",
"severity": "warning",
"line": 1,
"column": 8,
"file": "src/main.py",
"tool": "ruff",
"suggestion": "未使用のインポート文を削除してください"
}
ツールカテゴリ
組み込みツール
外部依存関係なしで動作する基本解析ツール:
SpellChecker
- 目的: コメントと文字列のタイポを検出
- 言語: すべて(言語構文に基づいてテキストを抽出)
- 設定: スペルチェック用言語設定
- 例: "teh" → "the", "recieve" → "receive"
SyntaxChecker
- 目的: 言語コンパイラを使用した基本構文検証
- 言語: Python(組み込み)、その他は外部ツールを推奨
- 方法: Python では
compile()関数を使用 - 例: 欠けているコロン、無効な構文
ImportAnalyzer
- 目的: 基本インポートパターン解析
- 言語: Python、JavaScript、TypeScript
- 例: 相対インポート、欠けているファイル拡張子
外部ツール
包括的な解析を提供する本格的なツール:
Python ツール
-
mypy: 静的型チェック
- 型の不一致、欠けている注釈を検出
- コマンド:
mypy --output=json {file}
-
ruff: 高速 Python リンター・フォーマッター
- コード品質、スタイル、パフォーマンス問題
- コマンド:
ruff check --output-format=json {file}
-
python compiler: 構文検証
- Python の組み込みコンパイルを使用
- コマンド:
python -m py_compile {file}
JavaScript/TypeScript ツール
- eslint: 包括的リンティング
- コード品質、スタイル、潜在的バグ
- コマンド:
eslint --format=json {file}
システム言語ツール
-
rustc: Rust コンパイラ
- コンパイルエラー、警告、提案
- コマンド:
rustc --emit=metadata --crate-type lib {file}
-
go build: Go コンパイラ
- コンパイルと型チェック
- コマンド:
go build -o /dev/null {file}
-
julia: Julia コンパイラ
- 構文と型チェック
- コマンド:
julia --check-bounds=yes --check-syntax=yes {file}
レビューワークフロー
1. ファイル処理
入力ファイル → 言語検出 → ツール選択 → 解析
2. ツール実行
- 並列実行: 複数ツールが同時実行
- タイムアウト処理: ツールのハングを防止
- エラー分離: 一つのツール失敗が他に影響しない
3. LLM 解析
ツール結果 + ソースコード → Claude 解析 → 関数呼び出し → 最終レポート
4. 結果集約
- 問題重複排除: 重複する発見を削除
- 重要度優先順位: 重要度順にソート
- コンテキスト強化: 提案と説明を追加
設定概念
ツール選択戦略
- 自動検出: ツールが自動的に発見される
- 可用性チェック: インストールされたツールのみ使用
- 言語フィルタリング: サポートされた言語でのみツール実行
- グレースフル劣化: 欠けているツールがワークフローを破らない
プロンプトカスタマイズ
Upsilon は複数のプロンプトテンプレートを使用:
- system_prompt: AI の役割と行動を設定
- review_prompt: コードレビュー要求のテンプレート
- tool_selection_prompt: ツール選択決定をガイド
- summary_prompt: 最終レビュー要約をフォーマット
モック vs リアルモード
- モックモード(デフォルト): テスト用の高速で決定論的なレスポンス
- リアルモード: 本格的解析用の実際の Claude API 呼び出し
出力形式
テキスト形式(人間可読)
📋 レビュー結果
├── main.py (python) - ✅ 問題なし
└── utils.py (python) - ⚠️ 2 警告
├── 🔍 問題
│ ├── 15行目: 未使用インポート 'sys'
│ └── 23行目: 関数にドキュメント文字列がありません
└── 💡 推奨事項
└── ドキュメントを追加し、未使用インポートを削除してください
JSON 形式(機械可読)
[
{
"file_path": "utils.py",
"language": "python",
"issues": [
{
"type": "unused_import",
"message": "未使用インポート 'sys'",
"severity": "warning",
"line": 15,
"tool": "ruff"
}
],
"summary": "2 警告が見つかりました",
"overall_score": 8,
"recommendations": ["ドキュメントを追加", "未使用インポートを削除"]
}
]
パフォーマンス考慮事項
実行速度
- ツールキャッシュ: ファイル内容ハッシュによる結果キャッシュ
- 並列処理: 複数ツールの同時実行
- タイムアウト管理: 遅いツールがブロックするのを防止
トークン管理
- 内容チャンク化: 大きなファイルを LLM 処理用に分割
- 選択的解析: CI/CD で変更されたコードに焦点
- モデル選択: pre-commit には高速モデル、詳細解析には強力なモデル
メモリ使用量
- ストリーミング処理: 大きなコードベースを段階的に処理
- 一時ファイルクリーンアップ: 中間ファイルの自動クリーンアップ
- リソース制限: 設定可能なメモリと時間制約
次: 外部ツール統合 →