メインコンテンツまでスキップ

中核概念

このドキュメントでは、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. 結果集約​

  • 問題重複排除: 重複する発見を削除
  • 重要度優先順位: 重要度順にソート
  • コンテキスト強化: 提案と説明を追加

設定概念​

ツール選択戦略​

  1. 自動検出: ツールが自動的に発見される
  2. 可用性チェック: インストールされたツールのみ使用
  3. 言語フィルタリング: サポートされた言語でのみツール実行
  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 には高速モデル、詳細解析には強力なモデル

メモリ使用量​

  • ストリーミング処理: 大きなコードベースを段階的に処理
  • 一時ファイルクリーンアップ: 中間ファイルの自動クリーンアップ
  • リソース制限: 設定可能なメモリと時間制約

次: 外部ツール統合 →