ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/tier1_fixer.py

@@ -0,0 +1,502 @@
+"""Tier 1 Deterministic Fixer.
+
+Executes ruff-based fixes on files flagged by health scan.
+Ruff is idempotent, has its own test suite, and exits non-zero on failure.
+No custom AST transforms — only ruff-delegated fixes to eliminate regression risk.
+
+Supported rules (all ruff-native, idempotent):
+    E722  — bare-except
+    T201  — print statements
+    F401  — unused imports
+    I001  — import order (isort)
+    LOG015 — logging.* instead of structlog (flagged, not auto-fixed)
+
+Usage:
+    from ref_agents.tools.tier1_fixer import run_tier1_fixes
+    result = run_tier1_fixes(violations, project_root)
+"""
+
+import subprocess
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# Ruff rule IDs that map to each REF rule.
+# Only rules ruff can fix automatically (--fix flag).
+RUFF_FIXABLE_RULES: dict[str, list[str]] = {
+    "bare_except": ["E722"],
+    "print_statement": ["T201"],
+    "unused_imports": ["F401"],
+    "import_organisation": ["I001"],
+    "fstring_in_logger": ["G004"],
+}
+
+# Rules ruff detects but cannot safely auto-fix.
+# These stay in Tier 2 work order for developer agent.
+RUFF_DETECT_ONLY: dict[str, list[str]] = {
+    "standard_logging": ["LOG015"],
+    "missing_type_hints": ["ANN001", "ANN201"],
+}
+
+# REF rules handled by Tier 1 fixer (subset of VIOLATION_CLASSIFICATION).
+TIER1_RULES: frozenset[str] = frozenset(RUFF_FIXABLE_RULES.keys())
+
+
+@dataclass
+class FileFixResult:
+    """Result of running ruff --fix on a single file."""
+
+    file: str
+    rules_applied: list[str] = field(default_factory=list)
+    violations_fixed: int = 0
+    violations_remaining: int = 0
+    ruff_available: bool = True
+    error: str = ""
+    skipped: bool = False
+    skip_reason: str = ""
+
+
+@dataclass
+class Tier1FixResult:
+    """Aggregate result of Tier 1 fix run."""
+
+    files_processed: int = 0
+    files_fixed: int = 0
+    files_skipped: int = 0
+    total_fixed: int = 0
+    total_remaining: int = 0
+    ruff_available: bool = True
+    stale_report_root: str = ""  # Non-empty when report paths don't match project_root
+    file_results: list[FileFixResult] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def _remap_path(file_path: Path, project_root: Path) -> Path | None:
+    """Try to remap a stale absolute path into project_root by matching the longest suffix.
+
+    Example:
+        file_path   = /old/repo/src/foo/bar.py
+        project_root = /new/repo
+        candidate   = /new/repo/src/foo/bar.py  → returned if it exists
+
+    Args:
+        file_path: Absolute path that does not exist.
+        project_root: Current project root to search under.
+
+    Returns:
+        Remapped Path if found, None otherwise.
+    """
+    parts = file_path.parts
+    # Walk from longest suffix to shortest, stop at first match
+    for i in range(1, len(parts)):
+        candidate = project_root.joinpath(*parts[i:])
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _detect_stale_root(paths: list[str], project_root: Path) -> str:
+    """Return the foreign root prefix if all absolute paths share a root outside project_root.
+
+    Args:
+        paths: File path strings from violations.
+        project_root: Current project root.
+
+    Returns:
+        Foreign root string (e.g. '/Users/x/sage/ref-agents') if detected, else ''.
+    """
+    abs_paths = [Path(p) for p in paths if Path(p).is_absolute()]
+    if not abs_paths:
+        return ""
+    # All paths outside project_root
+    outside = [p for p in abs_paths if not str(p).startswith(str(project_root))]
+    if len(outside) != len(abs_paths):
+        return ""
+    # Find common ancestor by walking parts of first path vs all others
+    try:
+        reference = outside[0].parts
+        common_depth = len(reference)
+        for p in outside[1:]:
+            for i, (a, b) in enumerate(zip(reference, p.parts)):
+                if a != b:
+                    common_depth = min(common_depth, i)
+                    break
+            else:
+                common_depth = min(common_depth, len(p.parts))
+        common_parts = reference[:common_depth]
+        return (
+            str(Path(common_parts[0]).joinpath(*common_parts[1:]))
+            if common_parts
+            else str(outside[0].parent)
+        )
+    except (IndexError, OSError, ValueError):
+        return str(outside[0].parent)
+
+
+def _find_ruff(project_root: Path) -> str | None:
+    """Find ruff executable: venv first, then PATH.
+
+    Args:
+        project_root: Project root to check for venv.
+
+    Returns:
+        Path to ruff executable, or None if not found.
+    """
+    # Check common venv locations relative to project root
+    candidates = [
+        project_root / ".venv" / "bin" / "ruff",
+        project_root / "venv" / "bin" / "ruff",
+        project_root / ".venv" / "Scripts" / "ruff.exe",  # Windows
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return str(candidate)
+
+    # Fall back to PATH
+    return shutil.which("ruff")
+
+
+def _get_ruff_rules_for_violations(violations: list[dict]) -> list[str]:
+    """Extract ruff rule IDs for a list of violations.
+
+    Args:
+        violations: List of violation dicts from remediation session.
+
+    Returns:
+        Deduplicated list of ruff rule IDs to apply.
+    """
+    rules: list[str] = []
+    for v in violations:
+        rule = v.get("rule", "")
+        if rule in RUFF_FIXABLE_RULES:
+            rules.extend(RUFF_FIXABLE_RULES[rule])
+    return list(dict.fromkeys(rules))  # deduplicate, preserve order
+
+
+def _run_ruff_fix(
+    ruff: str,
+    file_path: Path,
+    rules: list[str],
+) -> tuple[int, str, str]:
+    """Run ruff --fix on a single file with specific rules.
+
+    Args:
+        ruff: Path to ruff executable.
+        file_path: File to fix.
+        rules: Ruff rule codes to apply.
+
+    Returns:
+        Tuple of (returncode, stdout, stderr).
+    """
+    select = ",".join(rules)
+    cmd = [ruff, "check", "--fix", "--select", select, str(file_path)]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        return result.returncode, result.stdout, result.stderr
+    except subprocess.TimeoutExpired:
+        return 1, "", f"ruff timed out on {file_path}"
+    except OSError as e:
+        return 1, "", str(e)
+
+
+def _run_ruff_check(
+    ruff: str,
+    file_path: Path,
+    rules: list[str],
+) -> int:
+    """Count remaining violations after fix.
+
+    Args:
+        ruff: Path to ruff executable.
+        file_path: File to check.
+        rules: Ruff rule codes to count.
+
+    Returns:
+        Number of remaining violations (0 = clean).
+    """
+    select = ",".join(rules)
+    cmd = [ruff, "check", "--select", select, str(file_path)]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode == 0:
+            return 0
+        # Count lines that look like violations (contain file:line:col)
+        return sum(1 for line in result.stdout.splitlines() if ".py:" in line)
+    except (subprocess.TimeoutExpired, OSError):
+        return -1  # unknown
+
+
+def fix_file(
+    ruff: str,
+    file_path: Path,
+    violations: list[dict],
+    project_root: Path | None = None,
+) -> FileFixResult:
+    """Apply Tier 1 ruff fixes to a single file.
+
+    Args:
+        ruff: Path to ruff executable.
+        file_path: File to fix.
+        violations: Violations for this file from remediation session.
+        project_root: Used to attempt path remapping when file_path is stale.
+
+    Returns:
+        FileFixResult with outcome details.
+    """
+    result = FileFixResult(file=str(file_path))
+
+    if not file_path.exists():
+        if project_root and file_path.is_absolute():
+            remapped = _remap_path(file_path, project_root)
+            if remapped:
+                logger.warning(
+                    "stale_path_remapped",
+                    original=str(file_path),
+                    remapped=str(remapped),
+                )
+                file_path = remapped
+                result.file = str(file_path)
+            else:
+                result.skipped = True
+                parts = file_path.parts
+                origin = (
+                    "/".join(parts[:5]) if len(parts) >= 4 else str(file_path.parent)  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+                )
+                result.skip_reason = (
+                    f"stale path: report generated in {origin}"
+                    f", not found under {project_root}"
+                )
+                logger.warning(
+                    "stale_path_not_remapped",
+                    file=str(file_path),
+                    project_root=str(project_root),
+                )
+                return result
+        else:
+            result.skipped = True
+            result.skip_reason = "File not found"
+            return result
+
+    if not file_path.suffix == ".py":
+        result.skipped = True
+        result.skip_reason = "Not a Python file (ruff fixes Python only)"
+        return result
+
+    rules = _get_ruff_rules_for_violations(violations)
+    if not rules:
+        result.skipped = True
+        result.skip_reason = "No ruff-fixable rules in violation set"
+        return result
+
+    result.rules_applied = rules
+
+    # Count violations before fix
+    before = _run_ruff_check(ruff, file_path, rules)
+
+    # Apply fix
+    returncode, stdout, stderr = _run_ruff_fix(ruff, file_path, rules)
+
+    if returncode not in (0, 1):
+        # 0 = no issues, 1 = issues found/fixed, anything else = error
+        result.error = stderr or stdout or f"ruff exited {returncode}"
+        logger.error("ruff_fix_failed", file=str(file_path), error=result.error)
+        return result
+
+    # Count violations after fix
+    after = _run_ruff_check(ruff, file_path, rules)
+    result.violations_fixed = max(0, before - after) if before >= 0 else 0
+    result.violations_remaining = max(0, after) if after >= 0 else 0
+
+    if result.violations_fixed > 0:
+        logger.info(
+            "tier1_fixed",
+            file=str(file_path),
+            fixed=result.violations_fixed,
+            remaining=result.violations_remaining,
+            rules=rules,
+        )
+
+    return result
+
+
+def run_tier1_fixes(
+    violations: list[dict],
+    project_root: Path,
+) -> Tier1FixResult:
+    """Run Tier 1 ruff fixes on all files with pending Tier 1 violations.
+
+    Groups violations by file, applies ruff --fix per file with only the
+    rules relevant to that file's violations. Verifies fix by re-checking.
+
+    Args:
+        violations: List of violation dicts from remediation session (Tier 1, pending).
+        project_root: Project root for locating ruff in venv.
+
+    Returns:
+        Tier1FixResult with per-file outcomes and aggregate counts.
+    """
+    aggregate = Tier1FixResult()
+
+    ruff = _find_ruff(project_root)
+    if not ruff:
+        aggregate.ruff_available = False
+        aggregate.errors.append(
+            "ruff not found. Install with: pip install ruff or uv add ruff"
+        )
+        logger.error("ruff_not_found", project_root=str(project_root))
+        return aggregate
+
+    logger.info("ruff_found", path=ruff)
+
+    # Group violations by file
+    by_file: dict[str, list[dict]] = {}
+    for v in violations:
+        f = v.get("file", "")
+        if f:
+            by_file.setdefault(f, []).append(v)
+
+    aggregate.files_processed = len(by_file)
+
+    # Detect stale report before processing any files
+    stale_root = _detect_stale_root(list(by_file.keys()), project_root)
+    if stale_root:
+        aggregate.stale_report_root = stale_root
+        aggregate.errors.append(
+            f"Health report was generated in a different repo: {stale_root}. "
+            f"Current project root: {project_root}. "
+            'Attempting path remapping — re-run `scan(target="health")` to fix permanently.'
+        )
+        logger.error(
+            "stale_health_report_detected",
+            report_root=stale_root,
+            project_root=str(project_root),
+        )
+
+    for file_str, file_violations in by_file.items():
+        file_path = Path(file_str)
+        # Resolve relative paths against project root
+        if not file_path.is_absolute():
+            file_path = project_root / file_path
+
+        file_result = fix_file(ruff, file_path, file_violations, project_root)
+        aggregate.file_results.append(file_result)
+
+        if file_result.skipped:
+            aggregate.files_skipped += 1
+        elif file_result.error:
+            aggregate.errors.append(f"{file_str}: {file_result.error}")
+        else:
+            if file_result.violations_fixed > 0:
+                aggregate.files_fixed += 1
+            aggregate.total_fixed += file_result.violations_fixed
+            aggregate.total_remaining += file_result.violations_remaining
+
+    logger.info(
+        "tier1_complete",
+        files_processed=aggregate.files_processed,
+        files_fixed=aggregate.files_fixed,
+        total_fixed=aggregate.total_fixed,
+        total_remaining=aggregate.total_remaining,
+    )
+
+    return aggregate
+
+
+def format_tier1_result(result: Tier1FixResult, session_id: str) -> str:
+    """Format Tier 1 fix result as agent-readable summary.
+
+    Args:
+        result: Tier1FixResult from run_tier1_fixes.
+        session_id: Remediation session ID for follow-up calls.
+
+    Returns:
+        Formatted string for MCP tool response.
+    """
+    if not result.ruff_available:
+        return (
+            "❌ Tier 1 fixes could not run: ruff not found in project venv or PATH.\n"
+            "Install ruff: `uv add ruff` or `pip install ruff`\n"
+            'Then retry: `remediate(action="execute", session_id="'
+            + session_id
+            + '", tier="tier1")`'
+        )
+
+    if result.stale_report_root:
+        stale_block = (
+            "⚠️ **Stale health report detected.**\n"
+            f"  Report was generated in: `{result.stale_report_root}`\n"
+            "  Path remapping attempted. Files that could not be remapped are listed under Skipped.\n"
+            '  Fix permanently: `scan(target="health", directory="<current_project>")`\n'
+            f'  Then restart: `remediate(action="start", directory="<current_project>")`\n'
+        )
+    else:
+        stale_block = ""
+
+    lines = [
+        "## ⚡ Tier 1 Fix Complete",
+        f"Files processed: {result.files_processed} | "
+        f"Fixed: {result.files_fixed} | "
+        f"Violations resolved: {result.total_fixed} | "
+        f"Remaining: {result.total_remaining}",
+        "",
+    ]
+
+    if stale_block:
+        lines.append(stale_block)
+
+    if result.errors:
+        lines.append("### Errors")
+        for e in result.errors:
+            lines.append(f"  - {e}")
+        lines.append("")
+
+    fixed_files = [r for r in result.file_results if r.violations_fixed > 0]
+    if fixed_files:
+        lines.append("### Fixed")
+        for r in fixed_files:
+            lines.append(
+                f"  - `{r.file}` — {r.violations_fixed} fixed, "
+                f"{r.violations_remaining} remaining "
+                f"(rules: {', '.join(r.rules_applied)})"
+            )
+        lines.append("")
+
+    skipped = [r for r in result.file_results if r.skipped]
+    if skipped:
+        lines.append("### Skipped")
+        for r in skipped:
+            lines.append(f"  - `{r.file}` — {r.skip_reason}")
+        lines.append("")
+
+    if result.total_remaining > 0:
+        lines.append(
+            f"⚠️ {result.total_remaining} violations remain after Tier 1. "
+            "These require manual developer review."
+        )
+        lines.append("")
+
+    lines.append("### Next Step")
+    if result.total_remaining == 0 and not result.errors:
+        lines.append(
+            f'Run Tier 2 approval: `remediate(action="approve", session_id="{session_id}")`'
+        )
+    else:
+        lines.append(
+            f'Check full state: `remediate(action="state", session_id="{session_id}")`'
+        )
+
+    return "\n".join(lines)