code-review

code-review

説明：コード品質分析、静的解析、セキュリティスキャン、ベストプラクティスの適用を自動化します

カテゴリー：コード品質保証

複雑さ：高（複数ツールの統合＋分析）

---

目的

コードの品質、セキュリティ、保守性、およびアーキテクチャ決定（ADR）と仕様（SPEC）への準拠を確認するため、包括的なコードレビューを実施します。コードが本番環境に到達する前に問題を特定します。

---

機能

1. 静的解析

• Lint：pylint、ruff、flake8 との統合
• 型チェック：型安全性を確保する mypy、pyright
• コードスタイル：PEP 8 準拠、フォーマットの問題
• 複雑度メトリクス：循環的複雑度、認知的複雑度
• コードスメル：コードの重複、長いメソッド、ゴッドクラス

2. セキュリティ脆弱性スキャン

• 依存関係の脆弱性：bandit、safety によるチェック
• セキュリティのアンチパターン：SQL インジェクション、XSS、CSRF のリスク
• シークレットの検出：ハードコードされた認証情報、API キー
• OWASP Top 10：一般的なセキュリティ脆弱性
• CWE マッピング：共通脆弱性タイプ一覧（CWE）への参照

3. ベストプラクティスの適用

• デザインパターン：適切なパターンの使用
• SOLID 原則：違反の検出
• DRY 原則：コード重複の分析
• エラー処理：例外管理のレビュー
• リソース管理：メモリーリーク、ファイルハンドルのリーク

4. コードカバレッジ分析

• 行カバレッジ：実行された行の割合
• 分岐カバレッジ：条件分岐経路のカバレッジ
• 関数カバレッジ：テスト済み関数と未テスト関数
• 不足箇所の特定：カバーされていない重要な経路

5. アーキテクチャ準拠

• ADR 検証：コードがアーキテクチャ決定に沿っていることを確認
• SPEC 準拠：実装が仕様と一致していることを確認
• 依存関係のルール：循環依存がなく、適切なレイヤー構成であること
• API 契約の遵守：CTR の定義との一致

6. パフォーマンス分析

• 非効率なアルゴリズム：O(n) で実現可能な処理に O(n²) を使用
• メモリー使用量：過剰な割り当て
• データベースクエリ：N+1 クエリの問題
• キャッシュの機会：コストの高い処理の繰り返し

7. ドキュメント品質

• Docstring のカバレッジ：ドキュメントの欠落または不備
• コメントの品質：古くなったコメントや誤解を招くコメント
• API ドキュメント：公開メソッドのドキュメント
• 型ヒント：型注釈の欠落

8. 自動修正の提案

• 自動修正可能な問題：フォーマット、インポート、簡単なリファクタリング
• リファクタリングの推奨事項：メソッドの抽出、条件式の簡略化
• パフォーマンス最適化：より高速な代替手段の提案
• セキュリティパッチ：一般的な脆弱性の修正

---

コードレビューワークフロー

graph TD
    A[Code Submission] --> B[Static Analysis]
    B --> C{Linting Pass?}
    C -->|Fail| D[Report Linting Issues]
    C -->|Pass| E[Type Checking]

    E --> F{Type Safety?}
    F -->|Fail| G[Report Type Errors]
    F -->|Pass| H[Security Scan]

    H --> I{Security Issues?}
    I -->|Critical| J[Block Merge]
    I -->|Warning| K[Flag for Review]
    I -->|Pass| L[Complexity Analysis]

    L --> M{Complexity High?}
    M -->|Yes| N[Suggest Refactoring]
    M -->|No| O[Coverage Analysis]

    O --> P{Coverage < 90%?}
    P -->|Yes| Q[Request More Tests]
    P -->|No| R[ADR Compliance]

    R --> S{ADR Violations?}
    S -->|Yes| T[Report Violations]
    S -->|No| U[SPEC Compliance]

    U --> V{SPEC Mismatch?}
    V -->|Yes| W[Report Mismatches]
    V -->|No| X[Generate Review Report]

    D --> X
    G --> X
    J --> X
    K --> X
    N --> X
    Q --> X
    T --> X
    W --> X

    X --> Y[Review Complete]

---

使用方法

単一ファイルのレビュー

code-review analyze --file src/auth/service.py

出力：

=== Code Review Report: src/auth/service.py ===

Issues Found: 8

[CRITICAL] Security Issue (Line 45)
- SQL Injection vulnerability in user_login()
- Direct string concatenation in SQL query
- CWE-89: SQL Injection
→ Fix: Use parameterized queries

[ERROR] Type Safety (Line 78)
- Missing return type annotation for validate_token()
- mypy: Function return type cannot be inferred
→ Fix: Add return type hint -> bool

[WARNING] Complexity (Line 112-156)
- Cyclomatic complexity: 12 (threshold: 10)
- Method authenticate_user() too complex
→ Suggestion: Extract validation logic to separate methods

[WARNING] Code Duplication (Lines 201-215, 234-248)
- 15 lines duplicated with 95% similarity
→ Suggestion: Extract common logic to validate_password_strength()

[INFO] Documentation (Line 89)
- Missing docstring for public method reset_password()
→ Suggestion: Add docstring with parameter and return descriptions

[INFO] Performance (Line 167)
- N+1 query detected in get_user_permissions()
→ Suggestion: Use JOIN or prefetch related data

Coverage: 87% (Below 90% threshold)
- Uncovered lines: 45-47, 89-91, 134-136
→ Action: Add tests for error handling paths

ADR Compliance: 1 violation
- ADR-003 requires JWT tokens, code uses session cookies
→ Action: Update implementation to use JWT

Total Score: 72/100 (Acceptable with improvements)

モジュール全体のレビュー

code-review analyze --module src/auth

変更されたファイルのレビュー（Git）

code-review analyze --diff HEAD~1..HEAD

自動修正を伴うレビュー

code-review analyze --file src/auth/service.py --auto-fix

---

分析カテゴリー

1. セキュリティ分析

ツール：bandit、safety、semgrep

チェック項目：

• SQL インジェクションの脆弱性
• XSS 攻撃の経路
• CSRF トークンの検証
• ハードコードされたシークレット
• 安全でない乱数
• パストラバーサルのリスク
• コマンドインジェクション
• 安全でないデシリアライゼーション
• 脆弱な暗号化

重大度レベル：

• CRITICAL：直ちに対処が必要なセキュリティリスク（マージをブロック）
• HIGH：深刻な脆弱性（修正が必要）
• MEDIUM：潜在的なセキュリティ問題（レビューが必要）
• LOW：セキュリティのベストプラクティス違反

例：

# CRITICAL: SQL Injection
query = f"SELECT * FROM users WHERE username = '{username}'"  # ❌

# FIX
query = "SELECT * FROM users WHERE username = %s"
cursor.execute(query, (username,))  # ✓

# CRITICAL: Hardcoded Secret
API_KEY = "sk-1234567890abcdef"  # ❌

# FIX
API_KEY = os.environ.get('API_KEY')  # ✓

---

2. コード品質分析

ツール：pylint、ruff、radon

チェック項目：

• PEP 8 準拠
• 循環的複雑度
• 保守性指数
• コードの重複
• デッドコード
• 未使用のインポート／変数
• マジックナンバー
• 長い関数／クラス

複雑度のしきい値：

• A（1～5）：単純で、保守しやすい
• B（6～10）：中程度の複雑さ
• C（11～20）：複雑度が高い（リファクタリングを推奨）
• D（21～50）：複雑度が非常に高い（リファクタリングが必要）
• F（>50）：複雑度が極めて高い（直ちにリファクタリング）

例：

# Complexity: 12 (High)
def process_order(order):  # ❌
    if order.status == 'pending':
        if order.payment_verified:
            if order.items_available:
                if order.shipping_valid:
                    # ... nested logic
                    pass

# FIX: Complexity: 4 (Simple)
def process_order(order):  # ✓
    if not can_process_order(order):
        return False

    return execute_order_processing(order)

def can_process_order(order):
    return (order.status == 'pending' and
            order.payment_verified and
            order.items_available and
            order.shipping_valid)

---

3. 型安全性の分析

ツール：mypy、pyright

チェック項目：

• 型ヒントの不足
• 型の不整合
• 無効な型キャスト
• Optional 値の処理
• ジェネリック型の使用
• プロトコルへの準拠

例：

# Type error: Missing return type
def calculate_total(items):  # ❌
    return sum(item.price for item in items)

# FIX
def calculate_total(items: list[Item]) -> Decimal:  # ✓
    return sum(item.price for item in items)

# Type error: None not handled
def get_user(user_id: int) -> User:  # ❌
    return database.query(User).get(user_id)  # May return None

# FIX
def get_user(user_id: int) -> User | None:  # ✓
    return database.query(User).get(user_id)

---

4. パフォーマンスの分析

チェック項目：

• 非効率なアルゴリズム
• メモリーリーク
• N+1 クエリーの問題
• 不要なループ
• キャッシュの不足
• ブロッキング I/O 操作
• 大規模なメモリー割り当て

例：

# Performance issue: N+1 queries
def get_users_with_permissions():  # ❌
    users = User.query.all()
    for user in users:
        user.permissions = Permission.query.filter_by(user_id=user.id).all()
    return users

# FIX: Single query with JOIN
def get_users_with_permissions():  # ✓
    return User.query.options(
        joinedload(User.permissions)
    ).all()

# Performance issue: Inefficient algorithm O(n²)
def find_duplicates(items):  # ❌
    duplicates = []
    for i, item1 in enumerate(items):
        for item2 in items[i+1:]:
            if item1 == item2:
                duplicates.append(item1)
    return duplicates

# FIX: O(n) with set
def find_duplicates(items):  # ✓
    seen = set()
    duplicates = set()
    for item in items:
        if item in seen:
            duplicates.add(item)
        seen.add(item)
    return list(duplicates)

---

5. ベストプラクティスの分析

チェック項目：

• SOLID 原則
• DRY（繰り返しを避ける）
• KISS（シンプルに保つ）
• YAGNI（今必要でないものは作らない）
• エラー処理のパターン
• リソース管理
• ロギングの実践

例：

# Violation: Single Responsibility Principle
class UserManager:  # ❌
    def create_user(self, data):
        # Validates data
        # Saves to database
        # Sends email
        # Logs action
        pass

# FIX: Separate responsibilities
class UserValidator:  # ✓
    def validate(self, data): pass

class UserRepository:
    def save(self, user): pass

class EmailService:
    def send_welcome_email(self, user): pass

class AuditLogger:
    def log_user_creation(self, user): pass

---

6. ドキュメントの分析

チェック項目：

• docstring の不足
• 不完全な docstring
• 古くなったコメント
• 型ヒントのドキュメント
• API ドキュメント
• 使用例

例：

# Poor documentation
def process(data):  # ❌
    # Process the data
    return result

# Good documentation
def process_user_registration(  # ✓
    user_data: dict[str, Any]
) -> User:
    """
    Process new user registration with validation and persistence.

    Args:
        user_data: Dictionary containing user registration information
            Required keys: username, email, password
            Optional keys: full_name, phone_number

    Returns:
        User: Newly created user instance with assigned ID

    Raises:
        ValidationError: If user_data fails validation
        DatabaseError: If user cannot be persisted
        DuplicateUserError: If username or email already exists

    Example:
        >>> user = process_user_registration({
        ...     'username': 'johndoe',
        ...     'email': '[email protected]',
        ...     'password': 'SecureP@ss123'
        ... })
        >>> user.id
        12345
    """
    validated_data = UserValidator.validate(user_data)
    user = User.create(validated_data)
    return UserRepository.save(user)

---

7. ADR 準拠の分析

チェック項目：

• アーキテクチャ上の決定事項の遵守
• 技術スタックへの準拠
• デザインパターンの使用
• API 設計標準
• データフローのパターン

例：

# ADR-003: All authentication must use JWT tokens

# Violation
@app.route('/login', methods=['POST'])  # ❌
def login():
    # ... authentication logic
    session['user_id'] = user.id  # Using sessions, not JWT
    return jsonify({'success': True})

# Compliant
@app.route('/login', methods=['POST'])  # ✓
def login():
    # ... authentication logic
    token = jwt.encode(
        {'user_id': user.id, 'exp': datetime.utcnow() + timedelta(hours=1)},
        SECRET_KEY,
        algorithm='HS256'
    )
    return jsonify({'token': token})

---

8. SPEC 準拠の分析

チェック項目：

• 実装が仕様と一致しているか
• API シグネチャが正しいか
• データ構造がスキーマと一致しているか
• ビジネスロジックが正しいか
• エラー処理が仕様どおりか

例：

# SPEC-AUTH-V1: Password validation requirements

# SPEC violation: Missing uppercase requirement
def validate_password(password: str) -> bool:  # ❌
    return (
        len(password) >= 8 and
        any(c.islower() for c in password) and
        any(c.isdigit() for c in password)
    )

# SPEC compliant
def validate_password(password: str) -> bool:  # ✓
    return (
        8 <= len(password) <= 20 and
        any(c.isupper() for c in password) and  # Missing requirement
        any(c.islower() for c in password) and
        any(c.isdigit() for c in password) and
        any(c in '!@#$%^&*' for c in password)
    )

---

レビュースコアの計算

score = (
    security_score * 0.30 +      # 30% weight
    quality_score * 0.25 +        # 25% weight
    type_safety_score * 0.15 +    # 15% weight
    coverage_score * 0.15 +       # 15% weight
    documentation_score * 0.10 +  # 10% weight
    performance_score * 0.05      # 5% weight
)

# Score categories
90-100: Excellent (merge approved)
80-89:  Good (minor improvements recommended)
70-79:  Acceptable (improvements required)
60-69:  Needs work (significant issues)
<60:    Poor (major rework needed)

---

ツールへのアクセス

必須ツール：

• Read：ソースコードファイルを読み取る
• Bash：分析ツール（pylint、mypy、bandit）を実行する
• Grep：パターンや違反箇所を検索する
• Glob：コードファイルを検索する

必須ライブラリ：

• pylint
• ruff
• mypy / pyright
• bandit
• safety
• radon
• coverage
• semgrep

---

統合ポイント

test-automation との連携

• テストカバレッジがしきい値を満たしているか確認する
• テストされていないコードパスを特定する
• テストの品質を検証する

doc-validator との連携

• コードドキュメントの品質をチェックする
• コード内のトレーサビリティ参照を検証する
• コードコメントが標準に従っていることを確認する

security-audit との連携

• セキュリティ脆弱性の検出結果を共有する
• セキュリティ修正を調整する
• セキュリティ指標を追跡する

refactor-flow との連携

• リファクタリングの機会を特定する
• 複雑度の指標を提供する
• コードの改善案を提示する

---

自動修正機能

安全な自動修正（自動適用）

• インポートの並べ替え
• コードのフォーマット（black、autopep8）
• 行末の空白の削除
• 空行の不足の修正
• 未使用インポートの削除
• 簡単な型ヒントの追加

修正案（承認が必要）

• メソッド抽出のリファクタリング
• 複雑度の低減
• パフォーマンスの最適化
• セキュリティ脆弱性の修正
• ドキュメントの追加

---

CI/CD 統合

# .github/workflows/code-review.yml
name: Automated Code Review

on: [pull_request]

jobs:
  code-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run code review
        run: |
          code-review analyze --diff origin/main..HEAD

      - name: Check quality gate
        run: |
          if [ $CODE_REVIEW_SCORE -lt 70 ]; then
            echo "Code quality below threshold"
            exit 1
          fi

---

ベストプラクティス

1. 早い段階から頻繁にレビューする：PR の段階まで待たない
2. 重大な問題は直ちに修正する：まずセキュリティと正確性に対処する
3. 指標を継続的に追跡する：コード品質の傾向を監視する
4. CI/CD で自動化する：品質の低いコードがマージされるのを防ぐ
5. 問題に優先順位を付ける：影響の大きい問題に注力する
6. 背景を説明する：問題が重要な理由を説明する
7. 解決策を提示する：問題を特定するだけにとどめない
8. 厳格さのバランスを取る：軽微なスタイルの問題で進行を妨げない

---

制限事項

1. ビジネスロジックの意図は理解できません
2. 誤検出が発生する場合があります（人によるレビューが必要です）
3. すべてのセキュリティ脆弱性を検出できるわけではありません
4. パフォーマンス分析で検出できるのは、明白なパターンに限られます
5. ADR/SPEC への準拠には、ルールを手動で定義する必要があります
6. ツールのインストールと設定が必要です

---

今後の機能強化

1. AI を活用したコードの理解と提案
2. 過去のコードレビューからの学習
3. プロジェクト固有の標準に対応したカスタムルールエンジン
4. 視覚的なコード品質ダッシュボード
5. 依存関係の自動更新
6. バグの予測検出
7. コードスメルの傾向分析

---

成功基準

• 重大なセキュリティ脆弱性がゼロ
• コード品質スコアが80/100以上
• 型安全性：公開APIの型ヒントが100%
• カバレッジが90%以上
• 複雑度：複雑度が10を超える関数がない
• ADR違反がゼロ
• SPECとの不一致がゼロ

---

注意事項

• レビューレポートはreports/code-review/に保存されます
• 過去のメトリクスはmetrics/code-quality.jsonで追跡されます
• 別途設定されていない限り、自動修正には承認が必要です
• セキュリティ上の問題がある場合、マージは常にブロックされます
• .code-review.yml設定でプロジェクトごとにカスタマイズできます