Code Reviewer Colony

# Code Review Principles

Guidelines for reviewing code changes to ensure high maintainability, correctness, and safety.

---

## 1. Readability & Maintainability

- **Intent-Revealing Names**: Variables, functions, and classes must clearly describe their purpose. Avoid cryptic abbreviations.
- **Single Responsibility (SRP)**: Each function and class should do one thing. Keep functions short (prefer < 30 lines).
- **Control Flow**: Avoid deep nesting (prefer early returns). Minimize complex conditional logic.
- **Structure & Naming**: Refer to the architecture guidelines in [architectural-patterns.md](../../code-builder-colony/references/architectural-patterns.md).

## 2. Defensive Programming & Safety

- **Error Handling**: Never swallow exceptions silently. Use structured error boundaries and log relevant details safely (no secrets/PII).
- **Input Validation**: Validate all inputs at the boundary. Do not trust external data.
- **Null & Boundary Safety**: Guard against null pointer exceptions, index out-of-bounds, and undefined values.

## 3. Testability

- **Decoupling**: Keep business logic separated from external side-effects (DB, API) so it is easy to unit test.
- **Mocking**: Minimize complex mocking setups by keeping interfaces clean and simple.

## 4. Performance & Efficiency

- **Avoid Redundant Work**: Watch out for unnecessary DB queries (e.g., N+1), file I/O inside loops, or redundant API calls.
- **Resource Management**: Ensure files, database connections, and sockets are properly closed or disposed of.


#!/usr/bin/env python3
import argparse
import re
import sys

def parse_args():
    parser = argparse.ArgumentParser(
        description="Analyze a git diff and suggest appropriate reviewer sub-skills."
    )
    parser.add_argument(
        "--diff-file",
        help="Path to a file containing git diff output. If not provided, reads from stdin."
    )
    parser.add_argument(
        "--git",
        nargs="?",
        const="HEAD",
        help="Run 'git diff' on the specified ref (defaults to HEAD)."
    )
    return parser.parse_args()


def get_diff_content(args):
    if args.git:
        import subprocess
        try:
            cmd = ["git", "diff", args.git]
            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
            return result.stdout
        except subprocess.CalledProcessError as e:
            print(f"Error running git command: {e}", file=sys.stderr)
            sys.exit(1)
        except FileNotFoundError:
            print("Error: 'git' command not found in PATH.", file=sys.stderr)
            sys.exit(1)
    elif args.diff_file:
        try:
            with open(args.diff_file, "r", encoding="utf-8") as f:
                return f.read()
        except Exception as e:
            print(f"Error reading diff file: {e}", file=sys.stderr)
            sys.exit(1)
    else:
        # Read from stdin
        if sys.stdin.isatty():
            print("No input provided. Pipe a diff to stdin or use --git / --diff-file.", file=sys.stderr)
            sys.exit(1)
        return sys.stdin.read()


def analyze_diff(diff_text):
    # Regex to capture file paths in git diff
    # Format: a/path/to/file b/path/to/file or rename from/to
    file_headers = re.findall(r"^diff --git a/(.*?) b/(.*?)$", diff_text, re.MULTILINE)
    
    modified_files = []
    for a_path, b_path in file_headers:
        if b_path not in modified_files:
            modified_files.append(b_path)
            
    # Check for renamed/deleted/added files in the diff headers
    new_files = re.findall(r"^new file mode \d+\nindex .*?\n--- /dev/null\n\+\+\+ b/(.*?)$", diff_text, re.MULTILINE)
    deleted_files = re.findall(r"^deleted file mode \d+\nindex .*?\n--- a/(.*?)\n\+\+\+ /dev/null$", diff_text, re.MULTILINE)

    categories = {
        "audit-