alissa-tools-github-genloop 0.1.0__py3-none-any.whl

alissa/tools/github/genloop/github.py

@@ -0,0 +1,286 @@
+"""The GitHub surface the seat drives, all through `gh api` (which keeps its
+own auth): the branch read in the plans repository, the PR open with body and
+trailers, the reviewer request, the `plan-lint` check-run read, the plan-PR
+listing for the day counter, closing an invalid plan, and the comments a
+rule is written from.
+
+The seat touches ONE repository on GitHub -- the plans repository. The fed
+repos are the pass session's to read (with `gh api`, never cloned); nothing
+here reads or writes them.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import re
+import subprocess
+import urllib.parse
+from dataclasses import dataclass
+from typing import Any, Sequence
+
+from .proc import CommandError, run
+
+log = logging.getLogger(__name__)
+
+LINT_CHECK_NAME = "plan-lint"
+# A plan PR thread longer than this many pages of 100 comments is read only up to here.
+COMMENT_PAGES_MAX = 10
+_STATUS_RE = re.compile(r"HTTP (\d{3})")
+
+
+def http_status(exc: CommandError) -> int | None:
+    match = _STATUS_RE.search(exc.stderr or "")
+    return int(match.group(1)) if match else None
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    number: int
+    title: str
+    body: str
+    state: str
+    merged: bool
+    head_ref: str
+    head_sha: str
+    author: str
+    url: str
+    created_at: str
+    closed_at: str
+
+    @classmethod
+    def from_payload(cls, data: dict) -> "PullRequest | None":
+        try:
+            number = int(data["number"])
+        except (KeyError, TypeError, ValueError):
+            return None
+        head: dict = data["head"] if isinstance(data.get("head"), dict) else {}
+        user: dict = data["user"] if isinstance(data.get("user"), dict) else {}
+        return cls(
+            number=number,
+            title=str(data.get("title") or ""),
+            body=str(data.get("body") or ""),
+            state=str(data.get("state") or ""),
+            merged=bool(data.get("merged_at")) or bool(data.get("merged")),
+            head_ref=str(head.get("ref") or ""),
+            head_sha=str(head.get("sha") or ""),
+            author=str(user.get("login") or ""),
+            url=str(data.get("html_url") or ""),
+            created_at=str(data.get("created_at") or ""),
+            closed_at=str(data.get("closed_at") or ""),
+        )
+
+
+@dataclass(frozen=True)
+class Comment:
+    id: int
+    author: str
+    body: str
+    url: str
+    created_at: str
+
+
+class GitHub:
+    def __init__(self, *, timeout: int = 60):
+        self.timeout = timeout
+
+    # -- transport -------------------------------------------------------------
+
+    def _api(self, *args: str, body: dict | None = None) -> Any:
+        argv = ["gh", "api", *args]
+        if body is not None:
+            argv += ["--input", "-"]
+            out = self._run_stdin(argv, json.dumps(body))
+        else:
+            out = self._run(argv)
+        out = out.strip()
+        if not out:
+            return None
+        try:
+            return json.loads(out)
+        except json.JSONDecodeError as exc:
+            raise CommandError(argv, 0, f"expected JSON, got: {out[:300]}") from exc
+
+    def _run(self, argv: Sequence[str]) -> str:
+        try:
+            return run(argv, timeout=self.timeout)
+        except OSError as exc:
+            raise CommandError(argv, -1, f"could not execute {argv[0]!r}: {exc}") from exc
+
+    def _run_stdin(self, argv: Sequence[str], stdin: str) -> str:
+        log.debug("exec: %s", " ".join(argv))
+        try:
+            proc = subprocess.run(list(argv), input=stdin, capture_output=True, text=True, timeout=self.timeout)
+        except subprocess.TimeoutExpired as exc:
+            raise CommandError(argv, -1, f"timed out after {self.timeout}s") from exc
+        except OSError as exc:
+            raise CommandError(argv, -1, f"could not execute {argv[0]!r}: {exc}") from exc
+        if proc.returncode != 0:
+            raise CommandError(argv, proc.returncode, proc.stderr)
+        return proc.stdout
+
+    # -- identity --------------------------------------------------------------
+
+    def current_login(self) -> str:
+        data = self._api("user")
+        login = data.get("login") if isinstance(data, dict) else None
+        if not isinstance(login, str) or not login:
+            raise CommandError(["gh", "api", "user"], 0, "no login in the answer")
+        return login
+
+    # -- reads -----------------------------------------------------------------
+
+    def default_branch(self, repo: str) -> str:
+        data = self._api(f"repos/{repo}")
+        branch = data.get("default_branch") if isinstance(data, dict) else None
+        if not isinstance(branch, str) or not branch:
+            raise CommandError(["gh", "api", f"repos/{repo}"], 0, "no default_branch in the answer")
+        return branch
+
+    def branch_sha(self, repo: str, branch: str) -> str | None:
+        """The branch's head commit, or None when the branch does not exist."""
+        try:
+            data = self._api(f"repos/{repo}/branches/{urllib.parse.quote(branch, safe='')}")
+        except CommandError as exc:
+            if http_status(exc) == 404:
+                return None
+            raise
+        commit = data.get("commit") if isinstance(data, dict) else None
+        sha = commit.get("sha") if isinstance(commit, dict) else None
+        return sha if isinstance(sha, str) and sha else None
+
+    def read_file(self, repo: str, path: str, ref: str) -> str | None:
+        """A file's text at `ref`, or None when absent."""
+        try:
+            data = self._api(
+                "-X", "GET", f"repos/{repo}/contents/{urllib.parse.quote(path)}", "-f", f"ref={ref}",
+            )
+        except CommandError as exc:
+            if http_status(exc) == 404:
+                return None
+            raise
+        if not isinstance(data, dict) or data.get("type") != "file":
+            return None
+        content = data.get("content")
+        if not isinstance(content, str):
+            return None
+        return base64.b64decode(content).decode("utf-8", "replace")
+
+    def list_dir(self, repo: str, path: str, ref: str) -> list[str] | None:
+        """The file names directly under `path` at `ref`, or None when absent."""
+        try:
+            data = self._api(
+                "-X", "GET", f"repos/{repo}/contents/{urllib.parse.quote(path)}", "-f", f"ref={ref}",
+            )
+        except CommandError as exc:
+            if http_status(exc) == 404:
+                return None
+            raise
+        if not isinstance(data, list):
+            return None
+        return sorted(str(e.get("name")) for e in data if isinstance(e, dict) and e.get("type") == "file")
+
+    def pulls_for_branch(self, repo: str, branch: str) -> list[PullRequest]:
+        owner = repo.split("/", 1)[0]
+        data = self._api(
+            "-X", "GET", f"repos/{repo}/pulls", "-f", f"head={owner}:{branch}", "-f", "state=all",
+            "-f", "per_page=10",
+        )
+        return [pr for pr in (PullRequest.from_payload(d) for d in (data or []) if isinstance(d, dict)) if pr]
+
+    def list_pulls(self, repo: str, *, state: str, per_page: int = 50) -> list[PullRequest]:
+        data = self._api(
+            "-X", "GET", f"repos/{repo}/pulls", "-f", f"state={state}", "-f", "sort=updated",
+            "-f", "direction=desc", "-f", f"per_page={per_page}",
+        )
+        return [pr for pr in (PullRequest.from_payload(d) for d in (data or []) if isinstance(d, dict)) if pr]
+
+    def lint_run(self, repo: str, sha: str) -> dict | None:
+        """The newest `plan-lint` check run on `sha` (by id), or None."""
+        data = self._api(
+            "-X", "GET", f"repos/{repo}/commits/{sha}/check-runs", "-f", f"check_name={LINT_CHECK_NAME}",
+            "-f", "per_page=100",
+        )
+        runs = data.get("check_runs") if isinstance(data, dict) else None
+        named = [r for r in (runs if isinstance(runs, list) else [])
+                 if isinstance(r, dict) and r.get("name") == LINT_CHECK_NAME]
+        if not named:
+            return None
+        return max(named, key=lambda r: int(r.get("id") or 0))
+
+    def issue_comments(self, repo: str, number: int) -> list[Comment]:
+        """Every comment, oldest first, page by page (up to
+        `COMMENT_PAGES_MAX` pages of 100)."""
+        items: list = []
+        for page in range(1, COMMENT_PAGES_MAX + 1):
+            data = self._api("-X", "GET", f"repos/{repo}/issues/{number}/comments", "-f", "per_page=100",
+                             "-f", f"page={page}")
+            batch = data if isinstance(data, list) else []
+            items.extend(batch)
+            if len(batch) < 100:
+                break
+        out: list[Comment] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            user: dict = item["user"] if isinstance(item.get("user"), dict) else {}
+            try:
+                out.append(Comment(
+                    id=int(item["id"]), author=str(user.get("login") or ""), body=str(item.get("body") or ""),
+                    url=str(item.get("html_url") or ""), created_at=str(item.get("created_at") or ""),
+                ))
+            except (KeyError, TypeError, ValueError):
+                continue
+        return out
+
+    def plans_opened_on(self, repo: str, login: str, day: str) -> int:
+        """D10's day counter: open-or-merged plan PRs by `login` opened on the
+        UTC `day` (`YYYY-MM-DD`), a GitHub search."""
+        data = self._api(
+            "-X", "GET", "search/issues", "-f", f"q=repo:{repo} is:pr author:{login} created:{day}",
+            "-f", "per_page=100",
+        )
+        items = data.get("items") if isinstance(data, dict) else None
+        if not isinstance(items, list):
+            raise CommandError(["gh", "api", "search/issues"], 0, "search answered no items")
+        count = 0
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            pull: dict = item["pull_request"] if isinstance(item.get("pull_request"), dict) else {}
+            if item.get("state") == "open" or pull.get("merged_at"):
+                count += 1
+        return count
+
+    # -- writes ----------------------------------------------------------------
+
+    def open_pr(self, repo: str, *, head: str, base: str, title: str, body: str) -> PullRequest:
+        data = self._api(
+            "-X", "POST", f"repos/{repo}/pulls",
+            body={"head": head, "base": base, "title": title, "body": body, "draft": False},
+        )
+        pr = PullRequest.from_payload(data) if isinstance(data, dict) else None
+        if pr is None:
+            raise CommandError(["gh", "api", f"repos/{repo}/pulls"], 0, "PR create answered no number")
+        return pr
+
+    def request_reviewers(self, repo: str, number: int, logins: Sequence[str]) -> None:
+        self._api(
+            "-X", "POST", f"repos/{repo}/pulls/{number}/requested_reviewers", body={"reviewers": list(logins)},
+        )
+
+    def comment(self, repo: str, number: int, body: str) -> None:
+        self._api("-X", "POST", f"repos/{repo}/issues/{number}/comments", body={"body": body})
+
+    def close_pr(self, repo: str, number: int) -> None:
+        self._api("-X", "PATCH", f"repos/{repo}/pulls/{number}", body={"state": "closed"})
+
+    def delete_branch(self, repo: str, branch: str) -> None:
+        """Delete a branch; one that is already gone is not an error."""
+        try:
+            self._api("-X", "DELETE", f"repos/{repo}/git/refs/heads/{urllib.parse.quote(branch, safe='')}")
+        except CommandError as exc:
+            if http_status(exc) in (404, 422):
+                return
+            raise