alissa-tools-github-revloop 0.12.0__py3-none-any.whl

alissa/tools/github/revloop/config.py

@@ -0,0 +1,212 @@
+"""Daemon configuration.
+
+Settings come from three layers, later winning over earlier:
+
+1. the defaults on `Config`
+2. a JSON config file (see `resolve_config_path`)
+3. CLI arguments
+
+`workspace_root` is deliberately **not** a config key — it is a property of the
+running process, not of the settings. That lets one config file drive several
+daemons over different workspaces on the same machine, each pointed with
+`--workspace-root` and narrowed with `--repo`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+# What to do when a PR has a pending review request but no matching Alissa
+# review task (CR2 is implementer-side, so a third-party PR may not have one).
+ON_MISSING_SPAWN = "spawn_anyway"  # review anyway, PR URL carries the context
+ON_MISSING_SKIP = "skip"  # ignore the PR until a review task appears
+ON_MISSING_CREATE = "warn_and_spawn"  # spawn, but log loudly
+
+_MISSING_MODES = {ON_MISSING_SPAWN, ON_MISSING_SKIP, ON_MISSING_CREATE}
+
+# What to do when a review arrives for a repo that has no worktree hub yet.
+HUB_SKIP = "skip"
+HUB_ADD = "add"  # `alissa code workspace add <org>/<repo>`
+
+_HUB_MODES = {HUB_SKIP, HUB_ADD}
+
+CONFIG_FILENAME = "revloop.config.json"
+
+# Keys accepted in the config file. workspace_root is excluded on purpose.
+CONFIG_KEYS = (
+    "hub_template",
+    "poll_interval",
+    "round_cap",
+    "repos",
+    "agent_profile",
+    "reviewer_login",
+    "state_path",
+    "on_missing_review_task",
+    "on_missing_hub",
+    "dry_run",
+)
+
+MIN_POLL_INTERVAL = 10  # the search API allows 30 req/min
+
+
+def default_state_path(workspace_root: Path) -> Path:
+    return Path(workspace_root) / ".revloop" / "state.db"
+
+
+@dataclass(frozen=True)
+class Config:
+    # A property of the process, supplied by --workspace-root (default: cwd).
+    workspace_root: Path
+
+    hub_template: str = "{root}/{repo}/main"
+    poll_interval: int = 60
+    round_cap: int = 10  # CR9 default
+
+    # Empty tuple means "every repo that requests a review from me".
+    repos: tuple[str, ...] = ()
+
+    agent_profile: str = "claude"
+    reviewer_login: str | None = None  # None -> resolve once via `gh api user`
+
+    # None means "derive from the workspace" -- read `state_db` for the
+    # resolved location, never this field.
+    state_path: Path | None = None
+
+    on_missing_review_task: str = ON_MISSING_SPAWN
+    on_missing_hub: str = HUB_SKIP
+    dry_run: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "workspace_root", Path(self.workspace_root).expanduser().resolve()
+        )
+
+    @property
+    def state_db(self) -> Path:
+        """Where the spawn ledger lives. Defaults inside the workspace so two
+        daemons watching different workspaces never share one."""
+        if self.state_path is None:
+            return default_state_path(self.workspace_root)
+        return Path(self.state_path).expanduser()
+
+    @property
+    def manifest_path(self) -> Path:
+        return self.workspace_root / "alissa-workspace.yaml"
+
+    def hub_for(self, owner: str, repo: str) -> Path:
+        return Path(
+            self.hub_template.format(
+                root=str(self.workspace_root), owner=owner, repo=repo
+            )
+        ).expanduser()
+
+    def watches(self, full_name: str) -> bool:
+        return not self.repos or full_name in self.repos
+
+    @classmethod
+    def build(
+        cls,
+        workspace_root: Path,
+        file_data: Mapping[str, Any] | None = None,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> "Config":
+        """Merge the layers and validate. `overrides` entries that are None mean
+        "not specified on the CLI" and fall through to the file / defaults."""
+        raw: dict[str, Any] = dict(file_data or {})
+
+        if "workspace_root" in raw:
+            raise ValueError(
+                "workspace_root is not a config key — it is a property of the "
+                "running process. Pass --workspace-root (or run the daemon from "
+                "the workspace), and remove it from the config file."
+            )
+
+        # Allow "_"-prefixed keys as inline comments, since JSON has none.
+        unknown = {k for k in set(raw) - set(CONFIG_KEYS) if not k.startswith("_")}
+        if unknown:
+            raise ValueError(
+                f"unknown config key(s): {', '.join(sorted(unknown))}. "
+                f"Valid keys: {', '.join(CONFIG_KEYS)}"
+            )
+
+        for key, value in (overrides or {}).items():
+            if value is not None:
+                raw[key] = value
+
+        mode = raw.get("on_missing_review_task", ON_MISSING_SPAWN)
+        if mode not in _MISSING_MODES:
+            raise ValueError(
+                f"on_missing_review_task must be one of {sorted(_MISSING_MODES)}, got {mode!r}"
+            )
+
+        hub_mode = raw.get("on_missing_hub", HUB_SKIP)
+        if hub_mode not in _HUB_MODES:
+            raise ValueError(
+                f"on_missing_hub must be one of {sorted(_HUB_MODES)}, got {hub_mode!r}"
+            )
+
+        repos = tuple(raw.get("repos", ()))
+        if hub_mode == HUB_ADD and not repos:
+            # Anyone who can request a review could otherwise cause an arbitrary
+            # repo to be cloned onto this machine and opened as an agent's cwd.
+            raise ValueError(
+                "on_missing_hub='add' requires a non-empty repos allowlist "
+                "(config `repos`, or one or more --repo flags) — auto-cloning "
+                "whatever repo requests a review is unbounded"
+            )
+
+        cap = int(raw.get("round_cap", cls.round_cap))
+        if cap < 1:
+            raise ValueError(f"round_cap must be >= 1, got {cap}")
+
+        interval = int(raw.get("poll_interval", 60))
+        if interval < MIN_POLL_INTERVAL:
+            raise ValueError(
+                f"poll_interval must be >= {MIN_POLL_INTERVAL} seconds, got {interval}"
+            )
+
+        state_path = raw.get("state_path")
+        return cls(
+            workspace_root=Path(workspace_root),
+            hub_template=raw.get("hub_template", cls.hub_template),
+            poll_interval=interval,
+            round_cap=cap,
+            repos=repos,
+            agent_profile=raw.get("agent_profile", "claude"),
+            reviewer_login=raw.get("reviewer_login"),
+            state_path=Path(state_path).expanduser() if state_path else None,
+            on_missing_review_task=mode,
+            on_missing_hub=hub_mode,
+            dry_run=bool(raw.get("dry_run", False)),
+        )
+
+
+def load_config_file(path: Path) -> dict[str, Any]:
+    data = json.loads(Path(path).expanduser().read_text())
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a JSON object, got {type(data).__name__}")
+    return data
+
+
+def resolve_config_path(
+    explicit: Path | None, workspace_root: Path, cwd: Path | None = None
+) -> Path | None:
+    """Find the config file: explicit path, then cwd, then the workspace root.
+
+    Returns None when no config file exists — CLI arguments and defaults alone
+    are a valid way to run. An explicit path that does not exist is an error.
+    """
+    if explicit is not None:
+        path = Path(explicit).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError(f"config file not found: {path}")
+        return path
+
+    cwd = Path.cwd() if cwd is None else Path(cwd)
+    for candidate in (cwd / CONFIG_FILENAME, Path(workspace_root) / CONFIG_FILENAME):
+        if candidate.is_file():
+            return candidate
+    return None

alissa/tools/github/revloop/ghclient.py

@@ -0,0 +1,263 @@
+"""GitHub access via `gh api`.
+
+Note: this targets gh 2.4.0, which predates `gh search`. Every query goes
+through `gh api` against the REST v3 endpoints instead.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from .proc import CommandError, run, run_json
+
+log = logging.getLogger(__name__)
+
+# States that count as "I have reviewed this". PENDING is a draft review that
+# was never submitted, so it does not close a round.
+SUBMITTED_STATES = {"APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"}
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    owner: str
+    repo: str
+    number: int
+    title: str
+    author: str
+    head_sha: str
+    draft: bool
+    url: str
+    # "open" or "closed"; merged PRs report state "closed" AND merged True.
+    state: str = "open"
+    merged: bool = False
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.owner}/{self.repo}"
+
+    @property
+    def slug(self) -> str:
+        return f"{self.owner}/{self.repo}#{self.number}"
+
+    @property
+    def is_terminal(self) -> bool:
+        """Closed or merged: no round can ever be owed on this PR again."""
+        return self.merged or self.state != "open"
+
+
+@dataclass(frozen=True)
+class IssueComment:
+    """An issue comment on a PR (a PR is an issue). Distinct from Review:
+    issue comments live on the issues endpoints and never create review
+    records, so posting one can never disturb round counting."""
+
+    id: int
+    author: str
+    body: str
+
+
+@dataclass(frozen=True)
+class Review:
+    author: str
+    state: str
+    commit_id: str
+    submitted_at: str
+    url: str
+    body: str = ""
+
+    @property
+    def is_substantive(self) -> bool:
+        """A real review round, not a side effect of an inline comment.
+
+        Posting a standalone inline comment on a PR creates its own review
+        record with an empty body, so review records outnumber rounds. The
+        round-closing review always carries the verdict write-up in its body.
+        """
+        return bool(self.body.strip())
+
+
+class RateLimited(RuntimeError):
+    pass
+
+
+class IdentityMismatch(RuntimeError):
+    """Configured reviewer identity disagrees with the gh token."""
+
+
+class GitHub:
+    def __init__(self, login: str | None = None):
+        self._login = login
+
+    def token_login(self) -> str:
+        """Who the gh token actually belongs to. `gh api --jq` prints scalars
+        raw (unquoted), so this is deliberately not parsed as JSON."""
+        return run(["gh", "api", "user", "--jq", ".login"]).strip()
+
+    @property
+    def login(self) -> str:
+        if self._login is None:
+            self._login = self.token_login()
+        return self._login
+
+    def verify_identity(self) -> str:
+        """`review-requested:@me` resolves server-side from the gh token, but
+        round counting filters reviews by `self.login`. If a configured
+        reviewer_login disagrees with the token, the daemon would search one
+        account's queue and count another's reviews — every round would look
+        like round 1 and respawn forever. Fail loudly instead."""
+        actual = self.token_login()
+        if self._login is not None and self._login != actual:
+            raise IdentityMismatch(
+                f"configured reviewer_login={self._login!r} but the gh token "
+                f"belongs to {actual!r}. `@me` follows the token, so round "
+                f"counting would break. Fix reviewer_login (or set it to null "
+                f"to auto-detect), or re-authenticate gh."
+            )
+        self._login = actual
+        return actual
+
+    def _api(self, *args: str, timeout: int = 60):
+        try:
+            return run_json(["gh", "api", *args], timeout=timeout)
+        except CommandError as exc:
+            blob = exc.stderr.lower()
+            if "rate limit" in blob or "403" in blob:
+                raise RateLimited(exc.stderr.strip()[:300]) from exc
+            raise
+
+    def review_requests(self, repos: tuple[str, ...] = ()) -> list[tuple[str, str, int]]:
+        """PRs with a review pending from me.
+
+        `draft:false` enforces CR1 -- draft PRs are never reviewed. GitHub
+        clears the request once a review is submitted and re-adds it when the
+        implementer re-requests, so this doubles as the CR9 round edge-trigger.
+        """
+        query = "is:open is:pr draft:false review-requested:@me"
+        for full_name in repos:
+            query += f" repo:{full_name}"
+
+        payload = self._api(
+            "-X",
+            "GET",
+            "search/issues",
+            "-f",
+            f"q={query}",
+            "-f",
+            "per_page=100",
+        )
+        items = (payload or {}).get("items", [])
+
+        out: list[tuple[str, str, int]] = []
+        for item in items:
+            # repository_url looks like https://api.github.com/repos/<owner>/<repo>
+            parts = item.get("repository_url", "").rstrip("/").split("/")
+            if len(parts) < 2:
+                log.warning("could not parse repo from %s", item.get("repository_url"))
+                continue
+            out.append((parts[-2], parts[-1], int(item["number"])))
+        return out
+
+    def pull_request(self, owner: str, repo: str, number: int) -> PullRequest:
+        data = self._api(f"repos/{owner}/{repo}/pulls/{number}")
+        return PullRequest(
+            owner=owner,
+            repo=repo,
+            number=number,
+            title=data.get("title", ""),
+            author=(data.get("user") or {}).get("login", ""),
+            head_sha=(data.get("head") or {}).get("sha", ""),
+            draft=bool(data.get("draft")),
+            url=data.get("html_url", ""),
+            state=data.get("state") or "open",
+            merged=bool(data.get("merged")),
+        )
+
+    def reviews(self, owner: str, repo: str, number: int) -> list[Review]:
+        data = (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/pulls/{number}/reviews",
+                "-f",
+                "per_page=100",
+            )
+            or []
+        )
+        return [
+            Review(
+                author=(r.get("user") or {}).get("login", ""),
+                state=r.get("state", ""),
+                commit_id=r.get("commit_id") or "",
+                submitted_at=r.get("submitted_at") or "",
+                url=r.get("html_url", ""),
+                body=r.get("body") or "",
+            )
+            for r in data
+        ]
+
+    def my_reviews(self, owner: str, repo: str, number: int) -> list[Review]:
+        """My substantive submitted reviews, oldest first -- one per round.
+
+        Empty-bodied records are dropped: a standalone inline comment creates
+        its own zero-body review record, so counting raw records overcounts
+        rounds badly. On fahera-mx/studio.alissa.app#210 three real rounds
+        produced six records (round 1 plus three inline-comment artifacts, then
+        rounds 2 and 3), and round 3's reviewer was told it was "round 6 of
+        cap 10".
+
+        Do NOT dedupe by `commit_id` instead -- it looks like the natural
+        grouping key but it UNDERCOUNTS. A round reviews whatever head is
+        current, and consecutive rounds routinely land on the same commit when
+        the implementer triages findings without pushing: on #210 rounds 2 and
+        3 both carry head 805398a and would collapse into one. Body presence
+        tracks "a reviewer wrote a verdict"; commit identity does not.
+        """
+        mine = [
+            r
+            for r in self.reviews(owner, repo, number)
+            if r.author == self.login
+            and r.state in SUBMITTED_STATES
+            and r.is_substantive
+        ]
+        return sorted(mine, key=lambda r: r.submitted_at)
+
+    def comment(self, owner: str, repo: str, number: int, body: str) -> None:
+        run_json(
+            [
+                "gh",
+                "api",
+                f"repos/{owner}/{repo}/issues/{number}/comments",
+                "-f",
+                f"body={body}",
+            ]
+        )
+
+    def issue_comments(self, owner: str, repo: str, number: int) -> list[IssueComment]:
+        data = (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/issues/{number}/comments",
+                "-f",
+                "per_page=100",
+            )
+            or []
+        )
+        return [
+            IssueComment(
+                id=int(c.get("id") or 0),
+                author=(c.get("user") or {}).get("login", ""),
+                body=c.get("body") or "",
+            )
+            for c in data
+        ]
+
+    def update_comment(self, owner: str, repo: str, comment_id: int, body: str) -> None:
+        self._api(
+            "-X",
+            "PATCH",
+            f"repos/{owner}/{repo}/issues/comments/{comment_id}",
+            "-f",
+            f"body={body}",
+        )