arbiter-dev 0.2.0__py3-none-any.whl

arbiter/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Arbiter analyzers — pluggable code quality analysis tools."""

arbiter/analyzers/base.py

@@ -0,0 +1,44 @@
+"""Base analyzer interface and shared data models."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """A single quality finding from any analyzer."""
+
+    file_path: str
+    line: int
+    severity: str  # CRITICAL, HIGH, MEDIUM, LOW
+    rule_id: str
+    message: str
+    tool: str  # which analyzer produced this
+
+
+# Default paths to exclude from analysis
+DEFAULT_EXCLUDE_PATHS = [
+    "node_modules", "__pycache__", ".venv", "venv", "dist", "build",
+    ".git", ".tox", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+    "vendor", "third_party", "generated",
+]
+
+
+class Analyzer(ABC):
+    """Abstract base for code quality analyzers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique analyzer name."""
+
+    @abstractmethod
+    def analyze_repo(self, repo_path: Path, exclude_paths: list[str] | None = None) -> list[Finding]:
+        """Analyze an entire repository. Returns list of findings."""
+
+    def is_available(self) -> bool:
+        """Check if the underlying tool is installed."""
+        return True

arbiter/analyzers/complexity_analyzer.py

@@ -0,0 +1,66 @@
+"""Complexity Analyzer — Cyclomatic complexity via radon CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from arbiter.analyzers.base import Analyzer, Finding
+
+# Map radon CC grades to severity
+_GRADE_SEVERITY = {
+    "A": "LOW",       # 1-5 (simple)
+    "B": "LOW",       # 6-10 (well structured)
+    "C": "MEDIUM",    # 11-20 (slightly complex)
+    "D": "HIGH",      # 21-30 (more complex)
+    "E": "CRITICAL",  # 31-40 (complex)
+    "F": "CRITICAL",  # 41+ (very complex)
+}
+
+
+class ComplexityAnalyzer(Analyzer):
+    """Runs radon cc and parses JSON output."""
+
+    @property
+    def name(self) -> str:
+        return "complexity"
+
+    def is_available(self) -> bool:
+        try:
+            subprocess.run(["radon", "--version"], capture_output=True, timeout=5)
+            return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
+    def analyze_repo(self, repo_path: Path, exclude_paths: list[str] | None = None) -> list[Finding]:
+        result = subprocess.run(
+            ["radon", "cc", "--json", "--min", "C", str(repo_path)],
+            capture_output=True, text=True, timeout=120,
+        )
+        if not result.stdout.strip():
+            return []
+
+        try:
+            data = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return []
+
+        findings: list[Finding] = []
+        for file_path, blocks in data.items():
+            if not isinstance(blocks, list):
+                continue
+            for block in blocks:
+                grade = block.get("rank", "A")
+                cc = block.get("complexity", 0)
+                name = block.get("name", "?")
+                lineno = block.get("lineno", 0)
+                findings.append(Finding(
+                    file_path=file_path,
+                    line=lineno,
+                    severity=_GRADE_SEVERITY.get(grade, "MEDIUM"),
+                    rule_id=f"CC-{grade}",
+                    message=f"{name}: cyclomatic complexity {cc} (grade {grade})",
+                    tool="radon",
+                ))
+        return findings

arbiter/analyzers/dead_code_analyzer.py

@@ -0,0 +1,52 @@
+"""Dead Code Analyzer — Unused code detection via Vulture."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from arbiter.analyzers.base import Analyzer, Finding
+
+
+class DeadCodeAnalyzer(Analyzer):
+    """Runs vulture and parses text output."""
+
+    @property
+    def name(self) -> str:
+        return "vulture"
+
+    def is_available(self) -> bool:
+        try:
+            subprocess.run(["vulture", "--version"], capture_output=True, timeout=5)
+            return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
+    def analyze_repo(self, repo_path: Path, exclude_paths: list[str] | None = None) -> list[Finding]:
+        result = subprocess.run(
+            ["vulture", str(repo_path), "--min-confidence", "80"],
+            capture_output=True, text=True, timeout=120,
+        )
+        if not result.stdout.strip():
+            return []
+
+        findings: list[Finding] = []
+        # vulture output: filepath:line: message (confidence%)
+        pattern = re.compile(r"^(.+?):(\d+):\s+(.+?)\s+\((\d+)% confidence\)$")
+        for line in result.stdout.strip().split("\n"):
+            m = pattern.match(line.strip())
+            if not m:
+                continue
+            filepath, lineno, message, confidence = m.groups()
+            conf = int(confidence)
+            severity = "HIGH" if conf >= 90 else "MEDIUM"
+            findings.append(Finding(
+                file_path=filepath,
+                line=int(lineno),
+                severity=severity,
+                rule_id=f"DEAD-{conf}",
+                message=message,
+                tool="vulture",
+            ))
+        return findings

arbiter/analyzers/duplication_analyzer.py

@@ -0,0 +1,96 @@
+"""Duplication Analyzer — AST-based near-duplicate function detection.
+
+Uses Python's ast module to normalize function bodies and detect
+functions with identical or near-identical structure.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+from collections import defaultdict
+from pathlib import Path
+
+from arbiter.analyzers.base import Analyzer, Finding
+
+
+class DuplicationAnalyzer(Analyzer):
+    """Detects duplicate functions via AST hashing."""
+
+    @property
+    def name(self) -> str:
+        return "duplication"
+
+    def analyze_repo(self, repo_path: Path, exclude_paths: list[str] | None = None) -> list[Finding]:
+        # Collect function AST hashes across all Python files
+        hash_to_locations: dict[str, list[tuple[str, int, str]]] = defaultdict(list)
+
+        for py_file in repo_path.rglob("*.py"):
+            if _should_skip(py_file, exclude_paths):
+                continue
+            try:
+                source = py_file.read_text(encoding="utf-8", errors="ignore")
+                tree = ast.parse(source)
+            except (SyntaxError, ValueError):
+                continue
+
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    body_hash = _hash_function_body(node)
+                    if body_hash:
+                        rel_path = str(py_file.relative_to(repo_path))
+                        hash_to_locations[body_hash].append(
+                            (rel_path, node.lineno, node.name)
+                        )
+
+        # Report groups with 2+ identical functions
+        findings: list[Finding] = []
+        for body_hash, locations in hash_to_locations.items():
+            if len(locations) < 2:
+                continue
+            severity = "HIGH" if len(locations) >= 3 else "MEDIUM"
+            names = ", ".join(f"{loc[2]}@{loc[0]}:{loc[1]}" for loc in locations)
+            for file_path, lineno, func_name in locations:
+                findings.append(Finding(
+                    file_path=file_path,
+                    line=lineno,
+                    severity=severity,
+                    rule_id=f"DUP-{len(locations)}",
+                    message=f"Duplicate function body ({len(locations)} copies): {names}",
+                    tool="duplication",
+                ))
+        return findings
+
+
+def _hash_function_body(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str | None:
+    """Hash the normalized AST of a function body.
+
+    Normalizes by:
+    - Stripping all variable names (replaced with positional placeholders)
+    - Stripping docstrings
+    - Only hashing functions with 3+ statements (skip trivial functions)
+    """
+    body = node.body
+
+    # Skip docstring if present
+    if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
+        body = body[1:]
+
+    if len(body) < 5:
+        return None  # Skip small functions (< 5 statements)
+
+    # Dump AST and hash it
+    try:
+        dump = ast.dump(ast.Module(body=body, type_ignores=[]))
+        return hashlib.sha256(dump.encode()).hexdigest()[:16]
+    except Exception:
+        return None
+
+
+def _should_skip(path: Path, extra_excludes: list[str] | None = None) -> bool:
+    """Skip test files, venvs, and other non-source directories."""
+    parts = path.parts
+    skip_dirs = {"__pycache__", ".venv", "venv", ".git", "node_modules", ".tox"}
+    if extra_excludes:
+        skip_dirs.update(extra_excludes)
+    return any(p in skip_dirs for p in parts) or path.name.startswith("test_")

arbiter/analyzers/ruff_analyzer.py

@@ -0,0 +1,78 @@
+"""Ruff Analyzer — Lint analysis via ruff CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from arbiter.analyzers.base import Analyzer, Finding
+
+# Map ruff rule prefixes to severity levels
+_SEVERITY_MAP = {
+    "F": "MEDIUM",   # Pyflakes (unused imports, undefined names)
+    "E": "MEDIUM",   # pycodestyle errors
+    "W": "LOW",      # pycodestyle warnings
+    "B": "HIGH",     # flake8-bugbear (likely bugs)
+    "S": "HIGH",     # flake8-bandit (security)
+    "C": "MEDIUM",   # conventions
+    "I": "LOW",      # isort
+    "N": "LOW",      # naming
+    "D": "LOW",      # docstrings
+    "SIM": "MEDIUM", # simplify
+    "UP": "LOW",     # pyupgrade
+}
+
+
+def _severity_for_rule(rule_id: str) -> str:
+    """Map a ruff rule ID to a severity level."""
+    for prefix, severity in _SEVERITY_MAP.items():
+        if rule_id.startswith(prefix):
+            return severity
+    return "MEDIUM"
+
+
+class RuffAnalyzer(Analyzer):
+    """Runs ruff check and parses JSON output."""
+
+    @property
+    def name(self) -> str:
+        return "ruff"
+
+    def is_available(self) -> bool:
+        try:
+            subprocess.run(["ruff", "--version"], capture_output=True, timeout=5)
+            return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
+    def analyze_repo(self, repo_path: Path, exclude_paths: list[str] | None = None) -> list[Finding]:
+        cmd = ["ruff", "check", "--output-format", "json"]
+        if exclude_paths:
+            for ep in exclude_paths:
+                cmd.extend(["--exclude", ep])
+        cmd.append(str(repo_path))
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=120,
+        )
+        # ruff returns exit code 1 when findings exist — that's expected
+        if not result.stdout.strip():
+            return []
+
+        try:
+            data = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return []
+
+        findings: list[Finding] = []
+        for item in data:
+            code = item.get("code", "")
+            findings.append(Finding(
+                file_path=item.get("filename", ""),
+                line=item.get("location", {}).get("row", 0),
+                severity=_severity_for_rule(code),
+                rule_id=code,
+                message=item.get("message", ""),
+                tool="ruff",
+            ))
+        return findings

arbiter/analyzers/security_analyzer.py

@@ -0,0 +1,64 @@
+"""Security Analyzer — Security findings via Bandit CLI."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from arbiter.analyzers.base import Analyzer, Finding
+
+# Map Bandit severity to Arbiter severity (one level up)
+_SEVERITY_MAP = {
+    "HIGH": "CRITICAL",
+    "MEDIUM": "HIGH",
+    "LOW": "MEDIUM",
+}
+
+
+class SecurityAnalyzer(Analyzer):
+    """Runs bandit and parses JSON output."""
+
+    @property
+    def name(self) -> str:
+        return "bandit"
+
+    def is_available(self) -> bool:
+        try:
+            subprocess.run(["bandit", "--version"], capture_output=True, timeout=5)
+            return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
+    def analyze_repo(self, repo_path: Path, exclude_paths: list[str] | None = None) -> list[Finding]:
+        result = subprocess.run(
+            [
+                "bandit", "-r", str(repo_path),
+                "-f", "json",
+                "--exclude", "*/tests/*,*/__pycache__/*",
+                "-ll",  # LOW and above
+            ],
+            capture_output=True, text=True, timeout=600,
+        )
+        # bandit returns exit code 1 when findings exist
+        output = result.stdout.strip()
+        if not output:
+            return []
+
+        try:
+            data = json.loads(output)
+        except json.JSONDecodeError:
+            return []
+
+        findings: list[Finding] = []
+        for item in data.get("results", []):
+            sev = item.get("issue_severity", "LOW")
+            findings.append(Finding(
+                file_path=item.get("filename", ""),
+                line=item.get("line_number", 0),
+                severity=_SEVERITY_MAP.get(sev, "MEDIUM"),
+                rule_id=item.get("test_id", ""),
+                message=item.get("issue_text", ""),
+                tool="bandit",
+            ))
+        return findings

arbiter/api.py

@@ -0,0 +1,173 @@
+"""Arbiter API — stdlib HTTP server with JSON endpoints.
+
+No FastAPI, no Flask — just http.server + json.
+
+Endpoints:
+    GET  /api/score          Current repo score
+    GET  /api/agents         Agent leaderboard
+    GET  /api/trend          Quality trend over time
+    GET  /api/worst          Worst files
+    GET  /api/commits        Recent commits with scores
+    GET  /api/health         System health
+    GET  /                   Dashboard (HTML)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+from arbiter.store import Store
+
+logger = logging.getLogger(__name__)
+
+_DASHBOARD_DIR = Path(__file__).resolve().parent.parent.parent / "dashboard"
+
+
+class ArbiterHandler(BaseHTTPRequestHandler):
+    """HTTP request handler for Arbiter API."""
+
+    store: Store  # Set by run_server
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        path = parsed.path.rstrip("/")
+        params = parse_qs(parsed.query)
+
+        routes = {
+            "/api/score": self._handle_score,
+            "/api/agents": self._handle_agents,
+            "/api/trend": self._handle_trend,
+            "/api/worst": self._handle_worst,
+            "/api/commits": self._handle_commits,
+            "/api/health": self._handle_health,
+        }
+
+        handler = routes.get(path)
+        if handler:
+            handler(params)
+        elif path.startswith("/api/agents/") and path.count("/") == 4 and path.endswith("/trend"):
+            # /api/agents/{name}/trend
+            agent_name = path.split("/")[3]
+            self._handle_agent_trend(params, agent_name)
+        elif path.startswith("/api/commits/") and path.count("/") == 3:
+            # /api/commits/{hash}
+            commit_hash = path.split("/")[3]
+            self._handle_commit_detail(params, commit_hash)
+        elif path == "/api/fleet":
+            self._handle_fleet(params)
+        elif path == "" or path == "/index.html":
+            self._serve_dashboard()
+        else:
+            self._send_404()
+
+    def _handle_score(self, params: dict) -> None:
+        trend = self.store.get_trend(days=1)
+        if trend:
+            latest = trend[-1]
+            self._send_json(latest)
+        else:
+            self._send_json({"error": "No data. Run 'arbiter analyze' first."}, status=404)
+
+    def _handle_agents(self, params: dict) -> None:
+        board = self.store.get_agent_leaderboard()
+        self._send_json([
+            {
+                "agent": a.agent_name,
+                "avg_score": a.avg_score,
+                "commit_count": a.commit_count,
+                "total_loc": a.total_loc,
+                "trend": a.trend,
+            }
+            for a in board
+        ])
+
+    def _handle_trend(self, params: dict) -> None:
+        days = int(params.get("days", ["30"])[0])
+        trend = self.store.get_trend(days=days)
+        self._send_json(trend)
+
+    def _handle_worst(self, params: dict) -> None:
+        limit = int(params.get("limit", ["20"])[0])
+        worst = self.store.get_worst_files(limit=limit)
+        self._send_json([
+            {
+                "file_path": f.file_path,
+                "finding_count": f.finding_count,
+                "worst_severity": f.worst_severity,
+                "last_agent": f.last_agent,
+            }
+            for f in worst
+        ])
+
+    def _handle_commits(self, params: dict) -> None:
+        agent = params.get("agent", [None])[0]
+        limit = int(params.get("limit", ["50"])[0])
+        commits = self.store.get_recent_commits(agent=agent, limit=limit)
+        self._send_json(commits)
+
+    def _handle_agent_trend(self, params: dict, agent_name: str) -> None:
+        days = int(params.get("days", ["30"])[0])
+        trend = self.store.get_agent_trend(agent_name, days=days)
+        self._send_json(trend)
+
+    def _handle_fleet(self, params: dict) -> None:
+        report = self.store.get_fleet_report()
+        self._send_json(report)
+
+    def _handle_commit_detail(self, params: dict, commit_hash: str) -> None:
+        commits = self.store.get_recent_commits(limit=500)
+        match = [c for c in commits if c.get("commit_hash", "").startswith(commit_hash)]
+        if match:
+            self._send_json(match[0])
+        else:
+            self._send_json({"error": "Commit not found"}, status=404)
+
+    def _handle_health(self, params: dict) -> None:
+        self._send_json({"status": "ok", "version": "0.2.0"})
+
+    def _serve_dashboard(self) -> None:
+        index = _DASHBOARD_DIR / "index.html"
+        if not index.exists():
+            self._send_response(200, "text/html", b"<h1>Arbiter</h1><p>Dashboard not found. Place index.html in dashboard/</p>")
+            return
+        content = index.read_bytes()
+        self._send_response(200, "text/html", content)
+
+    def _send_json(self, data: Any, status: int = 200) -> None:
+        body = json.dumps(data, indent=2, default=str).encode("utf-8")
+        self._send_response(status, "application/json", body)
+
+    def _send_response(self, status: int, content_type: str, body: bytes) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_404(self) -> None:
+        self._send_json({"error": "Not found"}, status=404)
+
+    def log_message(self, format: str, *args: Any) -> None:
+        logger.info(format, *args)
+
+
+def run_server(host: str = "0.0.0.0", port: int = 8080, db_path: str | None = None) -> None:
+    """Start the Arbiter HTTP server."""
+    store = Store(db_path or "arbiter_data.db")
+    ArbiterHandler.store = store
+
+    server = HTTPServer((host, port), ArbiterHandler)
+    print(f"Arbiter dashboard: http://{host}:{port}/")
+    print(f"Arbiter API:       http://{host}:{port}/api/")
+    print(f"Database:          {db_path or 'arbiter_data.db'}")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nShutting down.")
+        server.shutdown()

arbiter/bus_bridge.py

@@ -0,0 +1,82 @@
+"""Bus Bridge — Posts quality milestones to founder-mode coordination bus.
+
+Only used when Arbiter runs in the founder-mode context.
+Uses subprocess to call bus_writer (no import dependency on founder-mode).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+# Default bus path for founder-mode
+_DEFAULT_BUS_PATH = Path.home() / "workspace" / "founder-mode" / "_state" / "coordination" / "messages.tsv"
+
+
+def post_quality_milestone(
+    score: float,
+    grade: str,
+    findings: int,
+    repo_name: str = "",
+    *,
+    bus_path: str | Path | None = None,
+    founder_mode_root: str | Path | None = None,
+) -> bool:
+    """Post a quality scan milestone to the coordination bus.
+
+    Returns True if the message was posted successfully.
+    """
+    label = f"{repo_name}: " if repo_name else ""
+    message = f"Arbiter scan complete: {label}{score:.1f} ({grade}), {findings} findings"
+    return _post_bus_message("MILESTONE", message, bus_path=bus_path, founder_mode_root=founder_mode_root)
+
+
+def post_quality_alert(
+    score: float,
+    threshold: float,
+    repo_name: str = "",
+    *,
+    bus_path: str | Path | None = None,
+    founder_mode_root: str | Path | None = None,
+) -> bool:
+    """Post a quality alert when score drops below threshold."""
+    label = f"{repo_name}: " if repo_name else ""
+    message = f"Quality alert: {label}score {score:.1f} below threshold {threshold:.1f}"
+    return _post_bus_message("STATUS", message, bus_path=bus_path, founder_mode_root=founder_mode_root)
+
+
+def _post_bus_message(
+    msg_type: str,
+    message: str,
+    *,
+    bus_path: str | Path | None = None,
+    founder_mode_root: str | Path | None = None,
+) -> bool:
+    """Post a message to the coordination bus via bus_writer."""
+    fm_root = Path(founder_mode_root) if founder_mode_root else Path.home() / "workspace" / "founder-mode"
+
+    cmd = [
+        sys.executable, "-m", "founder_mode.bus.bus_writer",
+        "arbiter", "all", msg_type, message,
+    ]
+
+    env_additions = {}
+    if bus_path:
+        env_additions["BUS_PATH"] = str(bus_path)
+
+    try:
+        import os
+        env = {**os.environ, **env_additions}
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=10,
+            cwd=str(fm_root),
+            env=env,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return False