alissa-tools-github-revloop 0.12.0__tar.gz

alissa_tools_github_revloop-0.12.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include requirements.txt
+include src/main/alissa/tools/github/revloop/version

alissa_tools_github_revloop-0.12.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: alissa-tools-github-revloop
+Version: 0.12.0
+Summary: ALISSA-TOOLS-GITHUB-REVLOOP
+Home-page: https://alissa.app
+Author: Fahera
+Author-email: support@alissa.app
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# alissa-tools-github-revloop
+
+The `alissa.tools.github.revloop` module: a GitHub watcher that drives the
+`alissa-code-review` adversarial review loop (CR1–CR9) to convergence.
+
+This distribution ships **only** that module. Everything above it —
+`alissa`, `alissa.tools`, `alissa.tools.github` — is a
+[PEP 420](https://peps.python.org/pep-0420/) namespace package with no
+`__init__.py`, so other distributions in other repositories can contribute
+their own packages under the same namespace:
+
+```
+alissa/                                  ← namespace (no __init__.py)
+└── tools/                               ← namespace
+    ├── github/                          ← namespace
+    │   ├── revloop/   __init__.py    ← THIS distribution
+    │   └── issues/       __init__.py    ← could ship from another repo
+    └── slack/                           ← namespace
+        └── notify/       __init__.py    ← could ship from another repo
+```
+
+The rule: a distribution owns a leaf package and declares only that subtree
+(`find_namespace_packages(include=[PACKAGE, f"{PACKAGE}.*"])`). Adding an
+`__init__.py` at any namespace level would claim it for one distribution and
+shadow the others.
+
+## Install
+
+```sh
+pip install -e ./alissa-tools-github-revloop
+```
+
+## Console scripts
+
+| Command | Entry point |
+| --- | --- |
+| `alissa-revloop` | `alissa.tools.github.revloop.__main__:main` |
+
+## Layout
+
+`src/main` holds the package tree, `src/test` mirrors it as `test_*`. The
+distribution version lives in the plain-text `version` file next to the module
+it versions (`src/main/alissa/tools/github/revloop/version`), read by both
+`setup.py` and `version.py`.

alissa_tools_github_revloop-0.12.0/README.md

@@ -0,0 +1,44 @@
+# alissa-tools-github-revloop
+
+The `alissa.tools.github.revloop` module: a GitHub watcher that drives the
+`alissa-code-review` adversarial review loop (CR1–CR9) to convergence.
+
+This distribution ships **only** that module. Everything above it —
+`alissa`, `alissa.tools`, `alissa.tools.github` — is a
+[PEP 420](https://peps.python.org/pep-0420/) namespace package with no
+`__init__.py`, so other distributions in other repositories can contribute
+their own packages under the same namespace:
+
+```
+alissa/                                  ← namespace (no __init__.py)
+└── tools/                               ← namespace
+    ├── github/                          ← namespace
+    │   ├── revloop/   __init__.py    ← THIS distribution
+    │   └── issues/       __init__.py    ← could ship from another repo
+    └── slack/                           ← namespace
+        └── notify/       __init__.py    ← could ship from another repo
+```
+
+The rule: a distribution owns a leaf package and declares only that subtree
+(`find_namespace_packages(include=[PACKAGE, f"{PACKAGE}.*"])`). Adding an
+`__init__.py` at any namespace level would claim it for one distribution and
+shadow the others.
+
+## Install
+
+```sh
+pip install -e ./alissa-tools-github-revloop
+```
+
+## Console scripts
+
+| Command | Entry point |
+| --- | --- |
+| `alissa-revloop` | `alissa.tools.github.revloop.__main__:main` |
+
+## Layout
+
+`src/main` holds the package tree, `src/test` mirrors it as `test_*`. The
+distribution version lives in the plain-text `version` file next to the module
+it versions (`src/main/alissa/tools/github/revloop/version`), read by both
+`setup.py` and `version.py`.

alissa_tools_github_revloop-0.12.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alissa_tools_github_revloop-0.12.0/setup.py

@@ -0,0 +1,58 @@
+import os
+from setuptools import setup, find_namespace_packages
+
+
+CODEBASE_PATH = os.environ.get(
+    "CODEBASE_PATH",
+    default=os.path.join("src", "main"),
+)
+
+# Everything above `revloop` is a PEP 420 namespace package (no __init__.py),
+# so other distributions can ship their own alissa.tools.* / alissa.tools.github.*
+# concrete packages. This distribution declares only its own subtree.
+NAMESPACE = "alissa.tools.github"
+PACKAGE = f"{NAMESPACE}.revloop"
+
+with open("requirements.txt", "r") as file:
+    requirements = [line for line in file.read().splitlines() if line and not line.startswith("#")]
+
+version_filepath = os.path.join(CODEBASE_PATH, *PACKAGE.split("."), "version")
+with open(version_filepath, "r") as file:
+    version = file.read().strip()
+
+
+with open("README.md") as file:
+    readme = file.read()
+
+
+setup(
+    name="alissa-tools-github-revloop",
+    version=version,
+    description="ALISSA-TOOLS-GITHUB-REVLOOP",
+    long_description=readme,
+    long_description_content_type='text/markdown',
+    url="https://alissa.app",
+    author="Fahera",
+    author_email="support@alissa.app",
+    packages=find_namespace_packages(
+        where=CODEBASE_PATH,
+        include=[PACKAGE, f"{PACKAGE}.*"],
+    ),
+    package_dir={
+        "": CODEBASE_PATH
+    },
+    package_data={
+        "": [
+            version_filepath,
+        ]
+    },
+    entry_points={
+        "console_scripts": [
+            "alissa-revloop=alissa.tools.github.revloop.__main__:main",
+            "alissa-pr-review=alissa.tools.github.revloop.prreview:main",
+        ]
+    },
+    install_requires=requirements,
+    include_package_data=True,
+    python_requires=">=3.11",
+)

alissa_tools_github_revloop-0.12.0/src/main/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-0.12.0/src/main/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-0.12.0/src/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()