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

alissa/tools/github/revloop/__init__.py

@@ -0,0 +1,8 @@
+"""revloop — a GitHub watcher that drives the alissa-code-review
+adversarial review loop (CR1–CR9) to convergence."""
+
+from .config import Config
+from .loop import Action, Decision, ReviewWatcher
+
+__all__ = ["Config", "ReviewWatcher", "Decision", "Action"]
+__version__ = "0.1.0"

alissa/tools/github/revloop/__main__.py

@@ -0,0 +1,181 @@
+"""CLI entry point: alissa-revloop (or python -m alissa.tools.github.revloop)"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import re
+import sys
+from pathlib import Path
+
+from .config import (
+    HUB_ADD,
+    HUB_SKIP,
+    ON_MISSING_CREATE,
+    ON_MISSING_SKIP,
+    ON_MISSING_SPAWN,
+    Config,
+    load_config_file,
+    resolve_config_path,
+)
+from .ghclient import IdentityMismatch
+from .loop import ReviewWatcher
+from .proc import CommandError
+
+log = logging.getLogger(__name__)
+
+
+def parse_pr_ref(ref: str) -> tuple[str, str, int]:
+    """Parse `owner/repo#123` (or a full PR URL) into its parts."""
+    match = re.search(r"([\w.-]+)/([\w.-]+?)(?:#|/pull/)(\d+)", ref)
+    if not match:
+        raise ValueError(f"expected OWNER/REPO#N or a PR URL, got {ref!r}")
+    return match.group(1), match.group(2), int(match.group(3))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="alissa-revloop",
+        description="Watch GitHub for review requests and run the adversarial "
+        "review loop (alissa-code-review CR1-CR9).",
+        epilog="Every setting below can also live in the config file; CLI "
+        "arguments win. workspace_root is CLI-only, so one config can drive "
+        "several daemons over different workspaces.",
+    )
+
+    p.add_argument(
+        "--workspace-root",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="the Alissa Code Workspace to watch (default: current directory)",
+    )
+    p.add_argument(
+        "-c",
+        "--config-path",
+        "--config",
+        dest="config_path",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help="config file; without it, ./revloop.config.json then "
+        "<workspace-root>/revloop.config.json, else defaults only",
+    )
+
+    mode = p.add_argument_group("mode")
+    mode.add_argument("--once", action="store_true", help="run a single poll pass and exit")
+    mode.add_argument(
+        "--pr",
+        metavar="OWNER/REPO#N",
+        help="evaluate one PR directly, bypassing the search — use this to tell "
+        "'the search did not find it' apart from 'the decision was no'",
+    )
+    mode.add_argument("-v", "--verbose", action="store_true")
+
+    over = p.add_argument_group("config overrides (win over the config file)")
+    over.add_argument(
+        "--repo",
+        dest="repos",
+        action="append",
+        metavar="OWNER/REPO",
+        help="only watch this repo; repeatable. Replaces the config list entirely.",
+    )
+    over.add_argument("--poll-interval", type=int, metavar="SECONDS")
+    over.add_argument("--round-cap", type=int, metavar="N", help="CR9 round cap")
+    over.add_argument("--hub-template", metavar="TEMPLATE")
+    over.add_argument("--agent-profile", metavar="NAME")
+    over.add_argument("--reviewer-login", metavar="LOGIN")
+    over.add_argument("--state-path", type=Path, metavar="PATH")
+    over.add_argument(
+        "--on-missing-review-task",
+        choices=[ON_MISSING_SPAWN, ON_MISSING_CREATE, ON_MISSING_SKIP],
+    )
+    over.add_argument("--on-missing-hub", choices=[HUB_SKIP, HUB_ADD])
+
+    dry = over.add_mutually_exclusive_group()
+    dry.add_argument(
+        "--dry-run",
+        dest="dry_run",
+        action="store_true",
+        default=None,
+        help="decide and log, but never enqueue a session or comment",
+    )
+    dry.add_argument(
+        "--no-dry-run",
+        dest="dry_run",
+        action="store_false",
+        help="act for real even if the config sets dry_run",
+    )
+    return p
+
+
+def overrides_from(args: argparse.Namespace) -> dict:
+    """CLI values, with None meaning 'not specified' so the config file shows
+    through. `repos` becomes a tuple so it matches the config-file form."""
+    return {
+        "repos": tuple(args.repos) if args.repos else None,
+        "poll_interval": args.poll_interval,
+        "round_cap": args.round_cap,
+        "hub_template": args.hub_template,
+        "agent_profile": args.agent_profile,
+        "reviewer_login": args.reviewer_login,
+        "state_path": args.state_path,
+        "on_missing_review_task": args.on_missing_review_task,
+        "on_missing_hub": args.on_missing_hub,
+        "dry_run": args.dry_run,
+    }
+
+
+def resolve_config(args: argparse.Namespace) -> Config:
+    workspace_root = args.workspace_root or Path.cwd()
+    path = resolve_config_path(args.config_path, workspace_root)
+
+    file_data = load_config_file(path) if path else {}
+    log.info("config: %s", path or "none found — defaults + CLI arguments only")
+
+    return Config.build(workspace_root, file_data, overrides_from(args))
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    try:
+        config = resolve_config(args)
+        log.info("workspace: %s", config.workspace_root)
+
+        watcher = ReviewWatcher(config)
+        for warning in watcher.preflight():
+            log.warning(warning)
+
+        if args.pr:
+            owner, repo, number = parse_pr_ref(args.pr)
+            decision = watcher.evaluate(owner, repo, number)
+            print(f"\n{args.pr} → {decision.action.value}")
+            print(f"  round:  {decision.round}")
+            print(f"  reason: {decision.reason or '—'}")
+        elif args.once:
+            watcher.poll_once()
+        else:
+            watcher.run_forever()
+    except IdentityMismatch as exc:
+        print(f"identity error: {exc}", file=sys.stderr)
+        return 2
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        return 2
+    except CommandError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alissa/tools/github/revloop/alissa.py

@@ -0,0 +1,315 @@
+"""Alissa CLI access: locate the review task (CR2) and enqueue the fresh
+reviewer session (orchestration P1)."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .proc import CommandError, run, run_json
+
+log = logging.getLogger(__name__)
+
+# A review task is "open" while it can still receive a verdict.
+OPEN_STATUSES = {"committed", "in_progress", "pending_validation", "todo"}
+
+# CR6 verdict envelope outcomes.
+VERDICT_APPROVE = "approve"
+VERDICT_REQUEST_CHANGES = "request_changes"
+
+# Envelope titles and bodies both read:
+#   Review verdict: <org>/<repo>#<n> — request_changes (round 3, ...)
+#   # Review verdict: <org>/<repo>#<n> — approve
+# The separator is an em-dash in practice; en-dash and hyphen are accepted too
+# so a hand-written envelope does not silently fail to parse.
+# Kept to a single line on purpose: the verdict word sits on the same line as
+# the "Review verdict:" lead-in, so matching across newlines could only pick up
+# a later round's wording out of order.
+_VERDICT_RE = re.compile(
+    r"Review\s+verdict\s*:[^\n]*?[—–-]\s*(approve|request_changes)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class Task:
+    ref: str  # TASK-<taskNumber>
+    title: str
+    status: str
+
+    @property
+    def is_open(self) -> bool:
+        return self.status in OPEN_STATUSES
+
+
+# The namespace loop.session_name() spawns reviewers into; the reap sweep only
+# ever considers sessions under it.
+REVIEW_SESSION_PREFIX = "review-"
+
+
+@dataclass(frozen=True)
+class ManagedSession:
+    name: str
+    status: str  # the worker's view: "idle", "busy", ...
+    # Epoch seconds of the session's last tmux activity. 0 when the CLI did
+    # not report one -- treated as "long quiet", so a missing field can never
+    # indefinitely immunize a session against the sweep.
+    last_activity: float = 0.0
+
+    @property
+    def is_idle(self) -> bool:
+        return self.status == "idle"
+
+
+def _title_pattern(owner: str, repo: str, number: int) -> re.Pattern[str]:
+    """CR2 title convention: `Review PR <org>/<repo>#<n> (TASK-<origin>)`."""
+    return re.compile(
+        rf"^Review PR\s+{re.escape(owner)}/{re.escape(repo)}#{number}\b",
+        re.IGNORECASE,
+    )
+
+
+class Alissa:
+    def list_tasks(self) -> list[Task]:
+        data = run_json(["alissa", "task", "list", "--json"], timeout=90) or []
+        tasks = []
+        for row in data:
+            # `taskNumber` is the ref the API resolves; `taskSeq` is a display
+            # ordinal and 404s as `TASK-<seq>`.
+            number = row.get("taskNumber")
+            if number is None:
+                continue
+            tasks.append(
+                Task(
+                    ref=f"TASK-{number}",
+                    title=row.get("title", ""),
+                    status=row.get("status", ""),
+                )
+            )
+        return tasks
+
+    def find_review_task(self, owner: str, repo: str, number: int) -> Task | None:
+        """CR2: exactly one review task per PR. Reuse it across rounds (CR7)."""
+        pattern = _title_pattern(owner, repo, number)
+        matches = [t for t in self.list_tasks() if pattern.match(t.title) and t.is_open]
+
+        if not matches:
+            return None
+        if len(matches) > 1:
+            # Several verdicts on one task are fine; several tasks per PR are not.
+            log.warning(
+                "CR2 violation: %d open review tasks for %s/%s#%d (%s) -- using %s",
+                len(matches),
+                owner,
+                repo,
+                number,
+                ", ".join(t.ref for t in matches),
+                matches[0].ref,
+            )
+        return matches[0]
+
+    def latest_verdict(self, task_ref: str) -> str | None:
+        """The newest CR6 verdict envelope on a review task, or None.
+
+        Returns VERDICT_APPROVE / VERDICT_REQUEST_CHANGES. This is the verdict
+        of record: reviewers post comment-mode reviews, so the GitHub review
+        state is always COMMENTED and cannot express approval at all.
+
+        Never raises. The daemon polls forever and this runs inside every pass,
+        so absent, empty or malformed evidence degrades to "no verdict" rather
+        than taking the loop down.
+        """
+        try:
+            data = run_json(["alissa", "task", "get", task_ref, "--json"], timeout=90)
+        except CommandError as exc:
+            log.warning("could not read verdict evidence for %s: %s", task_ref, exc)
+            return None
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("unexpected failure reading verdict evidence for %s", task_ref)
+            return None
+
+        try:
+            return self._newest_verdict(data)
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("could not parse verdict evidence for %s", task_ref)
+            return None
+
+    @staticmethod
+    def _newest_verdict(payload: object) -> str | None:
+        """Pick the newest parseable verdict out of a task's evidence array.
+
+        Every layer is optional by design -- the payload shape is whatever the
+        CLI printed, and a task with no evidence is the normal round-1 case.
+        """
+        if not isinstance(payload, dict):
+            return None
+        evidence = payload.get("evidence")
+        if not isinstance(evidence, list):
+            return None
+
+        found: list[tuple[str, str]] = []
+        for item in evidence:
+            if not isinstance(item, dict):
+                continue
+            title = item.get("title")
+            content = item.get("markdownContent")
+            for blob in (title, content):
+                if not isinstance(blob, str):
+                    continue
+                match = _VERDICT_RE.search(blob)
+                if match:
+                    created = item.get("createdAt")
+                    found.append(
+                        (created if isinstance(created, str) else "", match.group(1).lower())
+                    )
+                    break
+
+        if not found:
+            return None
+        # ISO-8601 timestamps sort lexicographically. Undated evidence sorts
+        # first (empty string), so a dated envelope always wins over one that
+        # lost its timestamp.
+        return max(found, key=lambda pair: pair[0])[1]
+
+    def count_verdicts(self, task_ref: str) -> int:
+        """How many CR6 verdict envelopes are on the review task.
+
+        One envelope per completed round (CR7, append-only), so this is the
+        authoritative round count -- unlike the GitHub review count it cannot be
+        thrown off by an empty-bodied review or two reviews in one cycle. Never
+        raises: absent, empty, or malformed evidence degrades to 0 (round 1)
+        rather than taking the loop down.
+        """
+        try:
+            data = run_json(["alissa", "task", "get", task_ref, "--json"], timeout=90)
+        except CommandError as exc:
+            log.warning("could not read verdict evidence for %s: %s", task_ref, exc)
+            return 0
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("unexpected failure reading verdict evidence for %s", task_ref)
+            return 0
+        try:
+            return self._count_verdicts(data)
+        except Exception:  # pragma: no cover - defence in depth
+            log.exception("could not count verdict evidence for %s", task_ref)
+            return 0
+
+    @staticmethod
+    def _count_verdicts(payload: object) -> int:
+        """Count evidence items carrying a verdict envelope. Mirrors
+        `_newest_verdict`'s tolerant parsing -- one match per item at most."""
+        if not isinstance(payload, dict):
+            return 0
+        evidence = payload.get("evidence")
+        if not isinstance(evidence, list):
+            return 0
+        count = 0
+        for item in evidence:
+            if not isinstance(item, dict):
+                continue
+            for blob in (item.get("title"), item.get("markdownContent")):
+                if isinstance(blob, str) and _VERDICT_RE.search(blob):
+                    count += 1
+                    break
+        return count
+
+    def enqueue_reviewer(
+        self,
+        *,
+        session: str,
+        directive: str,
+        cwd: Path,
+        agent: str,
+        task_ref: str | None,
+        dry_run: bool = False,
+    ) -> None:
+        argv = [
+            "alissa",
+            "tmux",
+            "queue",
+            "add",
+            session,
+            "--agent",
+            agent,
+            "--cwd",
+            str(cwd),
+        ]
+        if task_ref:
+            argv += ["--task", task_ref]
+        argv.append(directive)
+
+        if dry_run:
+            log.info("[dry-run] would enqueue: %s", " ".join(argv[:-1]) + " <directive>")
+            return
+
+        run(argv, timeout=60)
+
+        # Reviewers are one-shot per round (CR3): once the session finishes and is
+        # reaped, it must never be respawned. Make that explicit so a self-kill or
+        # a daemon reap can't trigger a respawn loop. Best-effort — an older CLI
+        # without `queue set` should not fail the enqueue.
+        try:
+            run(["alissa", "tmux", "queue", "set", session, "respawn", "off"],
+                timeout=30, check=False)
+        except CommandError:  # pragma: no cover - defence in depth
+            log.warning("could not set respawn off for %s", session)
+
+    def list_review_sessions(self) -> list[ManagedSession]:
+        """The live `review-*` managed sessions, from `alissa tmux ls`.
+
+        The reap sweep's starting point. Unlike the review-requested search,
+        the live session list cannot lose a finished session, so every reap
+        candidate is reachable from here. `--live` because a session that is
+        already gone (self-killed, or killed by an operator) holds no worker
+        slot and needs no reap. Raises CommandError upward -- the sweep skips
+        this pass and tries again next poll.
+        """
+        data = run_json(["alissa", "tmux", "ls", "--json", "--live"], timeout=60) or []
+        sessions = []
+        for row in data if isinstance(data, list) else []:
+            if not isinstance(row, dict):
+                continue
+            name = row.get("name")
+            if isinstance(name, str) and name.startswith(REVIEW_SESSION_PREFIX):
+                last = row.get("lastActivity")
+                sessions.append(
+                    ManagedSession(
+                        name=name,
+                        status=str(row.get("status") or ""),
+                        last_activity=float(last) if isinstance(last, (int, float)) else 0.0,
+                    )
+                )
+        return sessions
+
+    def kill_session(self, session: str) -> None:
+        """Kill a finished reviewer's managed session to free its worker slot.
+
+        Best-effort and idempotent-friendly: the session may already be gone (the
+        reviewer self-killed), so a non-zero exit is not an error here. Dry-run
+        is the caller's job (the sweep decides and logs before calling).
+        """
+        run(["alissa", "tmux", "kill", session], timeout=30, check=False)
+
+    def add_repo_to_workspace(
+        self, owner: str, repo: str, workspace_root: Path, *, dry_run: bool = False
+    ) -> None:
+        """Hub-ify a repo into the workspace (bare clone + main/ worktree) and
+        record it in alissa-workspace.yaml. Idempotent per the CLI's contract."""
+        argv = ["alissa", "code", "workspace", "add", f"{owner}/{repo}"]
+        if dry_run:
+            log.info("[dry-run] would run: %s (cwd=%s)", " ".join(argv), workspace_root)
+            return
+
+        log.info("hub-ifying %s/%s into %s", owner, repo, workspace_root)
+        # Cloning a repo can be slow; the poll loop tolerates a long pass.
+        run(argv, timeout=600, cwd=workspace_root)
+
+    def worker_running(self) -> bool:
+        """The queue only drains while `alissa worker` reconciles it."""
+        try:
+            out = run(["alissa", "worker", "status"], timeout=30, check=False)
+        except CommandError:
+            return False
+        return "not running" not in out.lower() and "no worker" not in out.lower()