springclean 0.1.0__py3-none-any.whl

springclean/__init__.py

@@ -0,0 +1,3 @@
+"""Spring Clean GitHub repository audit tool."""
+
+__version__ = "0.1.0"

springclean/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

springclean/cli.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .env import github_token
+from .errors import SpringCleanError
+from .github import GitHubClient
+from .repo_refs import parse_repo_reference
+from .reports import DEFAULT_STALE_DAYS, audit_repo
+from .tui import run_browser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    try:
+        if args.command is None:
+            run_browser(Path(args.reports_dir))
+            return 0
+
+        if not args.branch and not args.pr:
+            parser.error("Choose at least one report: --branch and/or --pr.")
+
+        if args.stale_days < 1:
+            parser.error("--stale-days must be greater than zero.")
+
+        owner, repo = parse_repo(args.repo)
+        token = github_token()
+        if not token:
+            raise SpringCleanError("Missing GITHUB_TOKEN. Add it to .env or set it in your shell.")
+        client = GitHubClient(token=token)
+        audit_repo(
+            client=client,
+            owner=owner,
+            repo=repo,
+            include_branches=args.branch,
+            include_prs=args.pr,
+            out_dir=Path(args.out),
+            stale_days=args.stale_days,
+        )
+    except SpringCleanError as exc:
+        print(f"springclean: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="springclean",
+        description="Spring Clean writes and browses GitHub repository cleanup reports.",
+        epilog="Run without a subcommand to open the terminal browser.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--reports-dir",
+        dest="reports_dir",
+        default="reports",
+        help="Reports directory used by the terminal browser. Defaults to ./reports.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    repo_parser = subparsers.add_parser("repo", help="Audit one repository.")
+    repo_parser.add_argument("repo", help="Repository in owner/name format.")
+    repo_parser.add_argument("--branch", dest="branch", action="store_true", help="Write branch report.")
+    repo_parser.add_argument(
+        "--pr",
+        dest="pr",
+        action="store_true",
+        help="Write open and draft pull request report.",
+    )
+    repo_parser.add_argument(
+        "--out",
+        default="reports",
+        help="Output directory for report files. Defaults to ./reports.",
+    )
+    repo_parser.add_argument(
+        "--stale-days",
+        type=int,
+        default=DEFAULT_STALE_DAYS,
+        help=f"Days without activity before a branch or PR is stale. Defaults to {DEFAULT_STALE_DAYS}.",
+    )
+
+    return parser
+
+
+def parse_repo(value: str) -> tuple[str, str]:
+    return parse_repo_reference(value)

springclean/env.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .errors import SpringCleanError
+
+
+def github_token() -> str | None:
+    return os.environ.get("GITHUB_TOKEN") or load_dotenv().get("GITHUB_TOKEN")
+
+
+def load_dotenv(path: Path = Path(".env")) -> dict[str, str]:
+    if not path.exists():
+        return {}
+
+    values = {}
+    for line_number, raw_line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            raise SpringCleanError(f"Invalid .env line {line_number}: expected KEY=value.")
+
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            raise SpringCleanError(f"Invalid .env line {line_number}: missing key.")
+        values[key] = unquote_env_value(value)
+
+    return values
+
+
+def unquote_env_value(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        return value[1:-1]
+    return value

springclean/errors.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class SpringCleanError(Exception):
+    """Expected operational error."""

springclean/github.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .errors import SpringCleanError
+
+API_ROOT = "https://api.github.com"
+API_VERSION = "2022-11-28"
+RATE_LIMIT_RETRY_CODES = {403, 429}
+RATE_LIMIT_RETRIES = 2
+
+
+@dataclass
+class GitHubClient:
+    token: str
+    api_root: str = API_ROOT
+    rate_limit_retries: int = RATE_LIMIT_RETRIES
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        url = self._url(path, params)
+        request = Request(url, headers=self._headers())
+        attempt = 0
+
+        while True:
+            try:
+                with urlopen(request, timeout=30) as response:
+                    self._maybe_wait_for_rate_limit(response.headers)
+                    body = response.read().decode("utf-8")
+                    break
+            except HTTPError as exc:
+                if self._should_retry_rate_limit(exc, attempt):
+                    attempt += 1
+                    continue
+                self._raise_http_error(exc)
+            except URLError as exc:
+                raise SpringCleanError(f"Could not reach GitHub API: {exc.reason}") from exc
+
+        if not body:
+            return None
+        return json.loads(body)
+
+    def paged(self, path: str, params: dict[str, Any] | None = None) -> list[Any]:
+        params = dict(params or {})
+        params["per_page"] = 100
+        page = 1
+        items: list[Any] = []
+
+        while True:
+            params["page"] = page
+            batch = self.get(path, params)
+            if not isinstance(batch, list):
+                raise SpringCleanError(f"Expected a list response from {path}")
+            if not batch:
+                break
+            items.extend(batch)
+            if len(batch) < 100:
+                break
+            page += 1
+
+        return items
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {self.token}",
+            "User-Agent": "springclean",
+            "X-GitHub-Api-Version": API_VERSION,
+        }
+
+    def _url(self, path: str, params: dict[str, Any] | None) -> str:
+        url = f"{self.api_root}{path}"
+        if params:
+            url = f"{url}?{urlencode(params)}"
+        return url
+
+    def _maybe_wait_for_rate_limit(self, headers: Any) -> None:
+        sleep_for = self._rate_limit_sleep_seconds(headers)
+        if sleep_for is None:
+            return
+
+        print(f"GitHub rate limit reached. Sleeping for {sleep_for}s.", file=sys.stderr)
+        time.sleep(sleep_for)
+
+    def _should_retry_rate_limit(self, exc: HTTPError, attempt: int) -> bool:
+        if exc.code not in RATE_LIMIT_RETRY_CODES or attempt >= self.rate_limit_retries:
+            return False
+        sleep_for = self._rate_limit_sleep_seconds(exc.headers)
+        if sleep_for is None:
+            return False
+
+        print(f"GitHub rate limit reached. Sleeping for {sleep_for}s before retrying.", file=sys.stderr)
+        time.sleep(sleep_for)
+        return True
+
+    def _rate_limit_sleep_seconds(self, headers: Any) -> int | None:
+        retry_after = self._int_header(headers, "Retry-After")
+        if retry_after is not None:
+            return max(0, retry_after)
+
+        remaining = self._header(headers, "X-RateLimit-Remaining")
+        reset = self._int_header(headers, "X-RateLimit-Reset")
+        if remaining != "0" or reset is None:
+            return None
+
+        return max(0, reset - int(time.time())) + 1
+
+    def _int_header(self, headers: Any, name: str) -> int | None:
+        value = self._header(headers, name)
+        if value in (None, ""):
+            return None
+        try:
+            return int(value)
+        except ValueError:
+            return None
+
+    def _header(self, headers: Any, name: str) -> str | None:
+        if headers is None:
+            return None
+        value = headers.get(name)
+        if value is not None:
+            return value
+        lower_name = name.lower()
+        for key, candidate in getattr(headers, "items", lambda: [])():
+            if key.lower() == lower_name:
+                return candidate
+        return None
+
+    def _raise_http_error(self, exc: HTTPError) -> None:
+        detail = ""
+        try:
+            payload = json.loads(exc.read().decode("utf-8"))
+            detail = payload.get("message", "")
+        except Exception:
+            detail = exc.reason
+
+        if exc.code == 401:
+            raise SpringCleanError("GitHub authentication failed. Check GITHUB_TOKEN.") from exc
+        if exc.code == 403:
+            raise SpringCleanError(f"GitHub API returned 403: {detail}") from exc
+        if exc.code == 404:
+            raise SpringCleanError(f"GitHub resource not found or not accessible: {detail}") from exc
+        raise SpringCleanError(f"GitHub API returned {exc.code}: {detail}") from exc

springclean/repo_refs.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from .errors import SpringCleanError
+
+
+def parse_repo_reference(value: str) -> tuple[str, str]:
+    repo_ref = value.strip()
+    if not repo_ref:
+        raise SpringCleanError("Repository must be in owner/name format.")
+
+    if repo_ref.startswith("git@github.com:"):
+        repo_ref = repo_ref.removeprefix("git@github.com:")
+    elif "://" in repo_ref:
+        parsed = urlparse(repo_ref)
+        if parsed.netloc.lower() not in {"github.com", "www.github.com"}:
+            raise SpringCleanError("GitHub URL must use github.com.")
+        repo_ref = parsed.path.strip("/")
+
+    parts = [part for part in repo_ref.split("/") if part]
+    if len(parts) < 2:
+        raise SpringCleanError("Repository must be in owner/name format, for example marioribeiro/springclean.")
+
+    owner = parts[0]
+    repo = parts[1].removesuffix(".git")
+    if not owner or not repo:
+        raise SpringCleanError("Repository must be in owner/name format, for example marioribeiro/springclean.")
+    return owner, repo