anvil-dev-framework 0.1.6

package/global/lib/hygiene_service.py

@@ -0,0 +1,712 @@
+#!/usr/bin/env python3
+"""
+Repository Hygiene Service (ANV-237)
+
+Detects stale PRs, orphan branches, and accumulated stashes to help
+maintain repository health. Integrates with /orient, /healthcheck,
+and provides data for /cleanup command.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+
+# Issue reference patterns for linking stashes/branches to Linear issues
+ISSUE_PATTERNS = [
+    r"(ANV-\d+)",  # Direct reference
+    r"feature/(ANV-\d+)",  # Branch name
+    r"\[(ANV-\d+)\]",  # Bracketed reference
+]
+
+
+@dataclass
+class HygieneConfig:
+    """Configuration for hygiene checks."""
+
+    enabled: bool = True
+    stash_threshold: int = 5  # Warn when stash count exceeds this
+    stash_age_days: int = 7  # Suggest cleanup for stashes older than this
+    check_linear_sync: bool = True  # Cross-reference PR/Linear status
+    check_merge_conflicts: bool = True  # Check PRs for conflicts
+    auto_prune_remotes: bool = True  # Run git fetch --prune automatically
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "HygieneConfig":
+        """Create config from dictionary (e.g., from anvil.yaml)."""
+        return cls(
+            enabled=data.get("enabled", True),
+            stash_threshold=data.get("stash_threshold", 5),
+            stash_age_days=data.get("stash_age_days", 7),
+            check_linear_sync=data.get("check_linear_sync", True),
+            check_merge_conflicts=data.get("check_merge_conflicts", True),
+            auto_prune_remotes=data.get("auto_prune_remotes", True),
+        )
+
+    @classmethod
+    def default(cls) -> "HygieneConfig":
+        """Return default configuration."""
+        return cls()
+
+
+@dataclass
+class StashInfo:
+    """Information about a git stash entry."""
+
+    index: int
+    message: str
+    branch: str
+    date: Optional[datetime]
+    issue_refs: list[str] = field(default_factory=list)
+
+    @property
+    def age_days(self) -> Optional[int]:
+        """Return age in days, or None if date unknown."""
+        if self.date is None:
+            return None
+        # Handle timezone-aware dates from git
+        now = datetime.now(timezone.utc)
+        if self.date.tzinfo is None:
+            # Date is naive, make it UTC
+            date = self.date.replace(tzinfo=timezone.utc)
+        else:
+            date = self.date
+        delta = now - date
+        return delta.days
+
+    def is_old(self, threshold_days: int) -> bool:
+        """Check if stash is older than threshold."""
+        age = self.age_days
+        return age is not None and age > threshold_days
+
+
+@dataclass
+class BranchInfo:
+    """Information about a local branch."""
+
+    name: str
+    last_commit: str
+    last_commit_date: Optional[datetime]
+    tracking_branch: Optional[str]  # The remote tracking branch
+    is_gone: bool  # True if remote was deleted
+
+    @property
+    def issue_refs(self) -> list[str]:
+        """Extract issue references from branch name."""
+        return extract_issue_refs(self.name)
+
+
+@dataclass
+class PRInfo:
+    """Information about a GitHub pull request."""
+
+    number: int
+    title: str
+    branch: str
+    mergeable: str  # MERGEABLE, CONFLICTING, UNKNOWN
+    linked_issues: list[str] = field(default_factory=list)
+    issue_statuses: dict[str, str] = field(default_factory=dict)  # issue_key -> status
+
+    @property
+    def is_stale(self) -> bool:
+        """Check if PR is for a Done Linear issue."""
+        return any(
+            status.lower() == "done" for status in self.issue_statuses.values()
+        )
+
+    @property
+    def has_conflicts(self) -> bool:
+        """Check if PR has merge conflicts."""
+        return self.mergeable == "CONFLICTING"
+
+
+@dataclass
+class HygieneReport:
+    """Complete hygiene check results."""
+
+    stash_count: int
+    stash_threshold: int
+    old_stashes: list[StashInfo]  # Stashes older than threshold
+    all_stashes: list[StashInfo]  # All stashes for reference
+    orphan_branches: list[BranchInfo]  # Branches with gone remotes
+    stale_prs: list[PRInfo]  # PRs for Done Linear issues
+    conflict_prs: list[PRInfo]  # PRs with merge conflicts
+    timestamp: datetime
+    errors: list[str] = field(default_factory=list)  # Any errors during checks
+
+    @property
+    def has_issues(self) -> bool:
+        """Check if any hygiene issues were found."""
+        return (
+            self.stash_count > self.stash_threshold
+            or len(self.old_stashes) > 0
+            or len(self.orphan_branches) > 0
+            or len(self.stale_prs) > 0
+            or len(self.conflict_prs) > 0
+        )
+
+    @property
+    def stash_status(self) -> str:
+        """Return status indicator for stash count."""
+        if self.stash_count <= self.stash_threshold:
+            return "PASS"
+        return "WARN"
+
+    @property
+    def branch_status(self) -> str:
+        """Return status indicator for orphan branches."""
+        if len(self.orphan_branches) == 0:
+            return "PASS"
+        else:
+            return "FAIL"
+
+    @property
+    def pr_status(self) -> str:
+        """Return status indicator for PRs."""
+        if len(self.stale_prs) > 0:
+            return "FAIL"
+        elif len(self.conflict_prs) > 0:
+            return "WARN"
+        else:
+            return "PASS"
+
+
+def extract_issue_refs(text: str) -> list[str]:
+    """Extract Linear issue references from text."""
+    refs = set()
+    for pattern in ISSUE_PATTERNS:
+        matches = re.findall(pattern, text, re.IGNORECASE)
+        refs.update(match.upper() for match in matches)
+    return sorted(refs)
+
+
+def run_command(cmd: list[str], timeout: int = 30) -> tuple[str, str, int]:
+    """Run a command and return stdout, stderr, returncode."""
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        return result.stdout, result.stderr, result.returncode
+    except subprocess.TimeoutExpired:
+        return "", "Command timed out", 1
+    except FileNotFoundError:
+        return "", f"Command not found: {cmd[0]}", 1
+
+
+def get_stash_list() -> list[StashInfo]:
+    """Get list of all stashes with metadata."""
+    stashes = []
+
+    # Get stash list with dates
+    stdout, stderr, rc = run_command(
+        ["git", "stash", "list", "--date=iso-strict"]
+    )
+
+    if rc != 0 or not stdout.strip():
+        return stashes
+
+    for line in stdout.strip().split("\n"):
+        if not line:
+            continue
+
+        # Parse format: stash@{2026-01-11T12:00:00-05:00}: On branch-name: message
+        # Or: stash@{0}: On branch-name: message (if no date format)
+        match = re.match(
+            r"stash@\{(\d+)\}:\s*(?:On\s+)?([^:]+):\s*(.+)",
+            line,
+        )
+        if not match:
+            # Try alternative format with ISO date
+            match = re.match(
+                r"stash@\{([^}]+)\}:\s*(?:On\s+)?([^:]+):\s*(.+)",
+                line,
+            )
+
+        if match:
+            index_or_date = match.group(1)
+            branch = match.group(2).strip()
+            message = match.group(3).strip()
+
+            # Determine index and date
+            try:
+                index = int(index_or_date)
+                date = None
+            except ValueError:
+                # It's a date string, need to get index separately
+                index = len(stashes)
+                try:
+                    date = datetime.fromisoformat(index_or_date.replace("Z", "+00:00"))
+                except ValueError:
+                    date = None
+
+            issue_refs = extract_issue_refs(f"{branch} {message}")
+
+            stashes.append(
+                StashInfo(
+                    index=index,
+                    message=message,
+                    branch=branch,
+                    date=date,
+                    issue_refs=issue_refs,
+                )
+            )
+
+    # If we couldn't get dates, try to get them from reflog
+    if stashes and all(s.date is None for s in stashes):
+        stdout2, _, _ = run_command(
+            ["git", "reflog", "show", "stash", "--date=iso-strict", "--format=%gd|%ci"]
+        )
+        if stdout2:
+            date_lines = stdout2.strip().split("\n")
+            for i, line in enumerate(date_lines):
+                if i < len(stashes) and "|" in line:
+                    try:
+                        date_str = line.split("|")[1].strip()
+                        # Git format: "2026-01-11 12:00:00 -0500"
+                        # ISO format: "2026-01-11T12:00:00-0500"
+                        stashes[i].date = datetime.fromisoformat(
+                            date_str.replace(" ", "T", 1).replace(" ", "")
+                        )
+                    except (ValueError, IndexError):
+                        pass
+
+    return stashes
+
+
+def get_orphan_branches(auto_prune: bool = True) -> list[BranchInfo]:
+    """Get list of local branches with deleted remotes."""
+    branches = []
+
+    # Optionally prune remotes first
+    if auto_prune:
+        run_command(["git", "fetch", "--prune"], timeout=60)
+
+    # Get branch list with tracking info
+    stdout, stderr, rc = run_command(["git", "branch", "-vv"])
+
+    if rc != 0:
+        return branches
+
+    for line in stdout.strip().split("\n"):
+        if not line.strip():
+            continue
+
+        # Check if this branch has a gone remote
+        if ": gone]" not in line:
+            continue
+
+        # Parse format: * branch-name    abc1234 [origin/branch: gone] commit message
+        # Or:           branch-name    abc1234 [origin/branch: gone] commit message
+        line = line.lstrip("* ").strip()
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+
+        branch_name = parts[0]
+        commit_hash = parts[1]
+
+        # Extract tracking branch
+        tracking_match = re.search(r"\[([^\]:]+):", line)
+        tracking_branch = tracking_match.group(1) if tracking_match else None
+
+        # Get commit date
+        commit_date = None
+        date_stdout, _, _ = run_command(
+            ["git", "log", "-1", "--format=%ci", commit_hash]
+        )
+        if date_stdout.strip():
+            try:
+                commit_date = datetime.fromisoformat(
+                    date_stdout.strip().replace(" ", "T").replace(" ", "")
+                )
+            except ValueError:
+                pass
+
+        branches.append(
+            BranchInfo(
+                name=branch_name,
+                last_commit=commit_hash,
+                last_commit_date=commit_date,
+                tracking_branch=tracking_branch,
+                is_gone=True,
+            )
+        )
+
+    return branches
+
+
+def get_open_prs() -> list[PRInfo]:
+    """Get list of open PRs with mergeable status."""
+    prs = []
+
+    # Check if gh CLI is available
+    stdout, stderr, rc = run_command(
+        [
+            "gh",
+            "pr",
+            "list",
+            "--state",
+            "open",
+            "--json",
+            "number,title,headRefName,mergeable",
+            "--limit",
+            "50",
+        ]
+    )
+
+    if rc != 0:
+        return prs
+
+    try:
+        pr_data = json.loads(stdout)
+    except json.JSONDecodeError:
+        return prs
+
+    for pr in pr_data:
+        linked_issues = extract_issue_refs(f"{pr.get('title', '')} {pr.get('headRefName', '')}")
+
+        prs.append(
+            PRInfo(
+                number=pr.get("number", 0),
+                title=pr.get("title", ""),
+                branch=pr.get("headRefName", ""),
+                mergeable=pr.get("mergeable", "UNKNOWN"),
+                linked_issues=linked_issues,
+            )
+        )
+
+    return prs
+
+
+def get_linear_issue_status(issue_key: str) -> Optional[str]:
+    """Get Linear issue status. Returns None if unavailable.
+
+    NOTE: This depends on the external Linear skill installed at
+    ~/.claude/skills/linear-skill/. If not present, returns None gracefully.
+    Install the skill via: cp -r path/to/linear-skill ~/.claude/skills/
+    """
+    script_path = os.path.expanduser("~/.claude/skills/linear-skill/scripts/linear.py")
+
+    if not os.path.exists(script_path):
+        return None
+
+    stdout, stderr, rc = run_command(
+        ["python3", script_path, "get-issue", "--id", issue_key],
+        timeout=10,
+    )
+
+    if rc != 0:
+        return None
+
+    try:
+        data = json.loads(stdout)
+        return data.get("state", {}).get("name")
+    except json.JSONDecodeError:
+        return None
+
+
+def check_pr_staleness(prs: list[PRInfo], check_linear: bool = True) -> None:
+    """Update PRs with Linear issue statuses to detect staleness."""
+    if not check_linear:
+        return
+
+    for pr in prs:
+        for issue_key in pr.linked_issues:
+            status = get_linear_issue_status(issue_key)
+            if status:
+                pr.issue_statuses[issue_key] = status
+
+
+def generate_hygiene_report(config: Optional[HygieneConfig] = None) -> HygieneReport:
+    """Generate complete hygiene report."""
+    if config is None:
+        config = HygieneConfig.default()
+
+    errors: list[str] = []
+
+    # Get stashes
+    try:
+        all_stashes = get_stash_list()
+    except Exception as e:
+        all_stashes = []
+        errors.append(f"Failed to get stashes: {e}")
+
+    old_stashes = [s for s in all_stashes if s.is_old(config.stash_age_days)]
+
+    # Get orphan branches
+    try:
+        orphan_branches = get_orphan_branches(auto_prune=config.auto_prune_remotes)
+    except Exception as e:
+        orphan_branches = []
+        errors.append(f"Failed to get branches: {e}")
+
+    # Get PRs
+    try:
+        all_prs = get_open_prs()
+    except Exception as e:
+        all_prs = []
+        errors.append(f"Failed to get PRs: {e}")
+
+    # Check PR staleness against Linear
+    if config.check_linear_sync:
+        try:
+            check_pr_staleness(all_prs, check_linear=True)
+        except Exception as e:
+            errors.append(f"Failed to check Linear sync: {e}")
+
+    stale_prs = [pr for pr in all_prs if pr.is_stale]
+    conflict_prs = [pr for pr in all_prs if pr.has_conflicts and not pr.is_stale]
+
+    return HygieneReport(
+        stash_count=len(all_stashes),
+        stash_threshold=config.stash_threshold,
+        old_stashes=old_stashes,
+        all_stashes=all_stashes,
+        orphan_branches=orphan_branches,
+        stale_prs=stale_prs,
+        conflict_prs=conflict_prs,
+        timestamp=datetime.now(timezone.utc),
+        errors=errors,
+    )
+
+
+def load_config_from_file(config_path: Optional[Path] = None) -> HygieneConfig:
+    """Load hygiene config from anvil.yaml."""
+    if config_path is None:
+        # Try common locations
+        candidates = [
+            Path(".claude/anvil.yaml"),
+            Path("anvil.yaml"),
+        ]
+        for candidate in candidates:
+            if candidate.exists():
+                config_path = candidate
+                break
+
+    if config_path is None or not config_path.exists():
+        return HygieneConfig.default()
+
+    try:
+        import yaml
+
+        with open(config_path) as f:
+            data = yaml.safe_load(f) or {}
+        hygiene_config = data.get("hygiene", {})
+        return HygieneConfig.from_dict(hygiene_config)
+    except ImportError:
+        return HygieneConfig.default()  # yaml not available
+    except Exception:
+        return HygieneConfig.default()
+
+
+def format_report_text(report: HygieneReport) -> str:
+    """Format hygiene report as text for display."""
+    lines = []
+    lines.append("## Repository Hygiene Report")
+    lines.append("")
+    lines.append(f"**Generated**: {report.timestamp.strftime('%Y-%m-%d %H:%M')}")
+    lines.append("")
+
+    # Summary table
+    lines.append("| Check | Status | Details |")
+    lines.append("|-------|--------|---------|")
+    lines.append(
+        f"| Stashes | {report.stash_status} | "
+        f"{report.stash_count} total (threshold: {report.stash_threshold}) |"
+    )
+    lines.append(
+        f"| Orphan branches | {report.branch_status} | "
+        f"{len(report.orphan_branches)} with gone remotes |"
+    )
+    lines.append(
+        f"| Stale PRs | {report.pr_status} | "
+        f"{len(report.stale_prs)} for Done issues, "
+        f"{len(report.conflict_prs)} with conflicts |"
+    )
+    lines.append("")
+
+    # Old stashes
+    if report.old_stashes:
+        lines.append(f"### Old Stashes ({len(report.old_stashes)})")
+        lines.append("")
+        for stash in report.old_stashes:
+            age = f"{stash.age_days}d" if stash.age_days else "?"
+            refs = ", ".join(stash.issue_refs) if stash.issue_refs else "no refs"
+            lines.append(f"- `stash@{{{stash.index}}}`: {stash.message} ({age}, {refs})")
+        lines.append("")
+
+    # Orphan branches
+    if report.orphan_branches:
+        lines.append(f"### Orphan Branches ({len(report.orphan_branches)})")
+        lines.append("")
+        for branch in report.orphan_branches:
+            refs = ", ".join(branch.issue_refs) if branch.issue_refs else ""
+            lines.append(f"- `{branch.name}` ({branch.last_commit[:7]}) {refs}")
+        lines.append("")
+
+    # Stale PRs
+    if report.stale_prs:
+        lines.append(f"### Stale PRs ({len(report.stale_prs)})")
+        lines.append("")
+        for pr in report.stale_prs:
+            done_issues = [k for k, v in pr.issue_statuses.items() if v.lower() == "done"]
+            lines.append(f"- PR #{pr.number}: {pr.title}")
+            lines.append(f"  - Done issues: {', '.join(done_issues)}")
+            lines.append(f"  - Suggestion: `gh pr close {pr.number}`")
+        lines.append("")
+
+    # Conflict PRs
+    if report.conflict_prs:
+        lines.append(f"### PRs with Conflicts ({len(report.conflict_prs)})")
+        lines.append("")
+        for pr in report.conflict_prs:
+            lines.append(f"- PR #{pr.number}: {pr.title}")
+            lines.append("  - Suggestion: Rebase or close if obsolete")
+        lines.append("")
+
+    # Errors
+    if report.errors:
+        lines.append("### Errors During Check")
+        lines.append("")
+        for error in report.errors:
+            lines.append(f"- {error}")
+        lines.append("")
+
+    # Recommendation
+    if report.has_issues:
+        lines.append("---")
+        lines.append("Run `/cleanup` to address these issues.")
+
+    return "\n".join(lines)
+
+
+def format_report_json(report: HygieneReport) -> str:
+    """Format hygiene report as JSON."""
+    data = {
+        "timestamp": report.timestamp.isoformat(),
+        "stash_count": report.stash_count,
+        "stash_threshold": report.stash_threshold,
+        "has_issues": report.has_issues,
+        "old_stashes": [
+            {
+                "index": s.index,
+                "message": s.message,
+                "branch": s.branch,
+                "age_days": s.age_days,
+                "issue_refs": s.issue_refs,
+            }
+            for s in report.old_stashes
+        ],
+        "orphan_branches": [
+            {
+                "name": b.name,
+                "last_commit": b.last_commit,
+                "issue_refs": b.issue_refs,
+            }
+            for b in report.orphan_branches
+        ],
+        "stale_prs": [
+            {
+                "number": p.number,
+                "title": p.title,
+                "branch": p.branch,
+                "linked_issues": p.linked_issues,
+                "issue_statuses": p.issue_statuses,
+            }
+            for p in report.stale_prs
+        ],
+        "conflict_prs": [
+            {
+                "number": p.number,
+                "title": p.title,
+                "branch": p.branch,
+            }
+            for p in report.conflict_prs
+        ],
+        "errors": report.errors,
+    }
+    return json.dumps(data, indent=2)
+
+
+def main():
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Repository Hygiene Service")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Run hygiene check and display report",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON instead of text",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        help="Path to config file (anvil.yaml)",
+    )
+    parser.add_argument(
+        "--stash-threshold",
+        type=int,
+        help="Override stash count threshold",
+    )
+    parser.add_argument(
+        "--stash-age",
+        type=int,
+        help="Override stash age threshold (days)",
+    )
+    parser.add_argument(
+        "--no-linear",
+        action="store_true",
+        help="Skip Linear API checks",
+    )
+    parser.add_argument(
+        "--no-prune",
+        action="store_true",
+        help="Skip git fetch --prune",
+    )
+
+    args = parser.parse_args()
+
+    if not args.check:
+        parser.print_help()
+        return
+
+    # Load config
+    config = load_config_from_file(args.config)
+
+    # Apply overrides
+    if args.stash_threshold is not None:
+        config.stash_threshold = args.stash_threshold
+    if args.stash_age is not None:
+        config.stash_age_days = args.stash_age
+    if args.no_linear:
+        config.check_linear_sync = False
+    if args.no_prune:
+        config.auto_prune_remotes = False
+
+    # Generate report
+    report = generate_hygiene_report(config)
+
+    # Output
+    if args.json:
+        print(format_report_json(report))
+    else:
+        print(format_report_text(report))
+
+
+if __name__ == "__main__":
+    main()