外部ツール統合
Upsilon の強みは、既存の開発ツールと統合する能力にあります。このドキュメントでは、外部ツール統合のセットアップとカスタマイズ方法を説明します。
概要
外部ツールは AI 駆動レビューを補完する本格的な解析を提供:
- 実際のコンパイラ: 正確な構文と型チェック
- 確立されたリンター: 実績のあるコード品質ルール
- 言語固有ツール: 深い言語知識
- コミュニティ標準: 業界で受け入れられたベストプラクティス
自動検出
Upsilon は利用可能な場合に外部ツールを自動検出・有効化:
# ツールの可用性は起動時にチェックされる
available_tools = []
if shutil.which("mypy"):
available_tools.append("mypy")
if shutil.which("ruff"):
available_tools.append("ruff")
Python ツール
mypy - 静的型チェック
インストール:
pip install mypy
検出内容:
- 型注釈エラー
- 型の不一致
- 型情報の欠落
- 互換性のない代入
出力例:
def greet(name: str) -> str:
return f"Hello, {name}"
# mypy がキャッチ:
greet(123) # Argument 1 to "greet" has incompatible type "int"; expected "str"
pyproject.toml での設定:
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
ruff - 高速 Python リンター
インストール:
pip install ruff
検出内容:
- コードスタイル違反(PEP 8)
- 未使用のインポートと変数
- 潜在的バグとアンチパターン
- パフォーマンス問題
問題例:
import os # ruff: 未使用インポート
import sys
def calculate():
x = 1 # ruff: 未使用変数
return 2 + 2
# ruff: 行が長すぎます(88文字超)
very_long_variable_name = some_function_with_many_parameters(param1, param2, param3, param4)
設定:
[tool.ruff]
line-length = 88
select = ["E", "F", "W", "I"]
ignore = ["E501"] # このプロジェクトでは行長を無視
Python コンパイラ
検出内容:
- 構文エラー
- インデンテーションエラー
- 無効な Python 構造
例:
def broken_function() # コロンが欠けている
print("これはコンパイルされません")
if condition # コロンが欠けている
print("構文エラー")
JavaScript/TypeScript ツール
ESLint
インストール:
npm install -g eslint
# またはプロジェクト固有:
npm install --save-dev eslint
検出内容:
- コード品質問題
- スタイル違反
- 潜在的バグ
- ベストプラクティス違反
設定例 (.eslintrc.js):
module.exports = {
extends: ['eslint:recommended'],
rules: {
'no-unused-vars': 'warn',
'no-console': 'warn',
'prefer-const': 'error'
}
};
問題例:
let unused = "variable"; // ESLint: 'unused' は値が割り当てられているが使用されていない
console.log("debug"); // ESLint: 予期しない console 文
var old = "style"; // ESLint: var より const/let を推奨
システム言語
Rust (rustc)
インストール:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
検出内容:
- コンパイルエラー
- 型安全性違反
- 所有権と借用の問題
- パフォーマンス警告
例:
fn main() {
let x = 5;
let y = &x;
drop(x); // エラー: 借用されているため `x` からムーブできない
println!("{}", y);
}
Go (go build)
インストール:
# https://golang.org/dl/ から Go をインストール
go version
検出内容:
- コンパイルエラー
- 型の不一致
- 未使用のインポートと変数
- 競合状態(-race フラグ付き)
例:
package main
import (
"fmt"
"os" // Go: インポートされているが使用されていない: "os"
)
func main() {
x := 5 // Go: x が宣言されているが使用されていない
fmt.Println("Hello")
}
Julia
インストール:
# https://julialang.org/downloads/ からダウンロード
julia --version
検出内容:
- 構文エラー
- 型安定性警告
- パフォーマンスヒント
- メソッドの曖昧性
例:
function calculate(x)
if x > 0
return x * 2 # Julia: 'end' キーワードが欠けている
end
end
カスタムツール統合
新しい外部ツールの追加
カスタムツールクラスを作成:
class CustomLinterTool(ExternalTool):
def __init__(self):
super().__init__(
name="custom_linter",
command="custom-linter --format=json {file}",
languages=["python", "javascript"],
parser="json",
timeout=30
)
def _parse_json_output(self, stdout: str, stderr: str) -> List[Dict[str, Any]]:
# ツールの出力形式用のカスタム解析ロジック
issues = []
try:
data = json.loads(stdout)
for item in data.get('violations', []):
issues.append({
'type': item['rule'],
'message': item['message'],
'line': item['line'],
'severity': 'error' if item['level'] == 'error' else 'warning'
})
except json.JSONDecodeError:
pass
return issues
設定ベースツール
pyproject.toml でツールを定義:
[tool.upsilon.external-tools.pylint]
command = "pylint --output-format=json {file}"
languages = ["python"]
parser = "json"
timeout = 45
enabled = true
[tool.upsilon.external-tools.shellcheck]
command = "shellcheck --format=json {file}"
languages = ["shell"]
parser = "json"
timeout = 15
enabled = true
ツール出力解析
JSON 形式解析
多くのモダンツールは JSON 出力をサポート:
def _parse_json_output(self, stdout: str, stderr: str) -> List[Dict[str, Any]]:
issues = []
if stdout.strip():
try:
data = json.loads(stdout)
for item in data:
issues.append(self._normalize_json_issue(item))
except json.JSONDecodeError:
# テキスト解析にフォールバック
issues.extend(self._parse_text_output(stdout, stderr))
return issues
テキスト形式解析
テキスト出力のみのツール用:
def _parse_text_output(self, stdout: str, stderr: str) -> List[Dict[str, Any]]:
issues = []
output = (stdout + "\n" + stderr).strip()
for line in output.split('\n'):
# 一般的パターン: file.py:123:45: error: message
match = re.match(r'([^:]+):(\d+):(\d+):\s*(error|warning):\s*(.+)', line)
if match:
issues.append({
'file': match.group(1),
'line': int(match.group(2)),
'column': int(match.group(3)),
'severity': match.group(4),
'message': match.group(5),
'type': match.group(4)
})
return issues
ベストプラクティス
ツール選択
- 確立されたツールを使用: 活発なコミュニティを持つ広く採用されたツールを選ぶ
- 言語固有ツール: 特定言語用に設計されたツールを選択
- 補完的解析: 異なるタイプの解析(スタイル、型、セキュリティ)を組み合わせ
パフォーマンス最適化
- タイムアウトを設定: 遅いツールがブロックするのを防止
- 増分解析を使用: 一部のツールは変更されたファイルのみの解析をサポート
- ツールインストールチェックをキャッシュ: 繰り返し
which呼び出しを避ける
エラーハンドリング
- グレースフル劣化: 一部のツールが失敗しても継続
- 明確なエラーメッセージ: ユーザーがツール問題を理解できるよう支援
- フォールバック戦略: 外部ツール失敗時に組み込みツールを使用
ツール設定
- 既存設定を尊重: プロジェクトの既存ツール設定を使用
- 合理的なデフォルト: 未設定ツールに適切なデフォルトを提供
- 簡単なオーバーライド: プロジェクトごとのツールカスタマイズを許可
トラブルシューティング
ツールが見つからない
# ツールがインストールされているかチェック
which mypy
# 欠けている場合はインストール
pip install mypy
権限エラー
# ツールに実行権限があることを確認
chmod +x /path/to/tool
設定競合
# ツール固有の設定ファイルをチェック
ls -la .mypy.ini pyproject.toml .eslintrc.*
タイムアウト問題
# 設定でタイムアウトを増加
[tool.upsilon.external-tools.slow-tool]
timeout = 120 # 2分
統合ワークフロー例
-
ツールをインストール:
pip install mypy ruff
npm install -g eslint -
Upsilon を設定:
[tool.upsilon.rules]
check_security = true # 外部ツールを有効化 -
レビューを実行:
upsilon review src/ --verbose -
ツール結果を確認:
📋 レビュー結果
├── main.py (python) - ⚠️ 3 警告
│ ├── mypy: 変数 'data' の型注釈が欠けています
│ ├── ruff: 未使用インポート 'sys'
│ └── ruff: 行が長すぎます(92 > 88文字)
外部ツール統合により、Upsilon は AI 解析と実績のある開発ツールを組み合わせる強力なオーケストレーターになります。