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

外部ツール統合

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

ベストプラクティス​

ツール選択​

  1. 確立されたツールを使用: 活発なコミュニティを持つ広く採用されたツールを選ぶ
  2. 言語固有ツール: 特定言語用に設計されたツールを選択
  3. 補完的解析: 異なるタイプの解析(スタイル、型、セキュリティ)を組み合わせ

パフォーマンス最適化​

  1. タイムアウトを設定: 遅いツールがブロックするのを防止
  2. 増分解析を使用: 一部のツールは変更されたファイルのみの解析をサポート
  3. ツールインストールチェックをキャッシュ: 繰り返し which 呼び出しを避ける

エラーハンドリング​

  1. グレースフル劣化: 一部のツールが失敗しても継続
  2. 明確なエラーメッセージ: ユーザーがツール問題を理解できるよう支援
  3. フォールバック戦略: 外部ツール失敗時に組み込みツールを使用

ツール設定​

  1. 既存設定を尊重: プロジェクトの既存ツール設定を使用
  2. 合理的なデフォルト: 未設定ツールに適切なデフォルトを提供
  3. 簡単なオーバーライド: プロジェクトごとのツールカスタマイズを許可

トラブルシューティング​

ツールが見つからない​

# ツールがインストールされているかチェック
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分

統合ワークフロー例​

  1. ツールをインストール:

    pip install mypy ruff
    npm install -g eslint
  2. Upsilon を設定:

    [tool.upsilon.rules]
    check_security = true # 外部ツールを有効化
  3. レビューを実行:

    upsilon review src/ --verbose
  4. ツール結果を確認:

    📋 レビュー結果
    ├── main.py (python) - ⚠️ 3 警告
    │ ├── mypy: 変数 'data' の型注釈が欠けています
    │ ├── ruff: 未使用インポート 'sys'
    │ └── ruff: 行が長すぎます(92 > 88文字)

外部ツール統合により、Upsilon は AI 解析と実績のある開発ツールを組み合わせる強力なオーケストレーターになります。