alissa-tools-github-revloop 0.19.0__tar.gz → 0.21.0__tar.gz

{alissa_tools_github_revloop-0.19.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.19.0
+Version: 0.21.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.19.0 → alissa_tools_github_revloop-0.21.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -80,6 +80,15 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="OWNER/REPO",
         help="only watch this repo; repeatable. Replaces the config list entirely.",
     )
+    over.add_argument(
+        "--author",
+        dest="authors",
+        action="append",
+        metavar="LOGIN",
+        help="only review PRs opened by this GitHub login; repeatable. "
+        "Replaces the config list entirely. Empty = every author is served "
+        "(a scope filter, not a grant); the self-review skip still applies.",
+    )
     over.add_argument(
         "--operator",
         dest="operators",
@@ -194,6 +203,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
     through. `repos` becomes a tuple so it matches the config-file form."""
     return {
         "repos": tuple(args.repos) if args.repos else None,
+        "authors": tuple(args.authors) if args.authors else None,
         "operators": tuple(args.operators) if args.operators else None,
         "poll_interval": args.poll_interval,
         "round_cap": args.round_cap,

{alissa_tools_github_revloop-0.19.0 → alissa_tools_github_revloop-0.21.0}/src/main/alissa/tools/github/revloop/config.py

@@ -120,6 +120,7 @@ CONFIG_KEYS = (
     "poll_interval",
     "round_cap",
     "repos",
+    "authors",
     "operators",
     "agent_profile",
     "reviewer_login",
@@ -262,6 +263,21 @@ class Config:
     # Empty tuple means "every repo that requests a review from me".
     repos: tuple[str, ...] = ()
 
+    # GitHub logins whose PRs this loop will spend rounds on. A SCOPE FILTER,
+    # not a capability grant -- so, like `repos` and unlike `operators`, empty
+    # (the default) means EVERY author, and an existing deployment with no
+    # `authors` key behaves exactly as it did before the key existed.
+    #
+    # The distinction is worth keeping straight: `operators` empty means NOBODY
+    # because honouring an ack is a power being handed out, and a grant that
+    # defaults to everyone is a hole. Serving a review request is not a power
+    # the daemon hands to the author -- summoning the loop already costs repo
+    # write access (to request the reviewer) plus a place on the `repos`
+    # allowlist. This key only narrows which of those already-authorised PRs are
+    # worth the rounds: skip dependabot/renovate, or a teammate who does not
+    # want agent reviews.
+    authors: tuple[str, ...] = ()
+
     # GitHub logins whose re-entry ack may raise a capped PR's effective cap
     # (loop.parse_reentry_ack). Empty -- the default -- means NO ack is ever
     # honoured: the lever fails closed, because anyone who can comment on a PR
@@ -356,6 +372,23 @@ class Config:
     def watches(self, full_name: str) -> bool:
         return not self.repos or full_name in self.repos
 
+    def serves_author(self, login: str) -> bool:
+        """Whether a PR by this login is in scope for the loop.
+
+        Empty list = every author (the filter pattern, see the field). Otherwise
+        membership case-insensitively, because GitHub logins are: a config
+        saying `Alissa-App` must match the `alissa-app` the API returns, or the
+        allowlist silently serves nobody -- the same failure mode `_string_list`
+        exists to prevent. Mirrors `loop.ReviewWatcher._is_operator`.
+
+        This is not the self-review guard and cannot stand in for it: an author
+        listed here is still refused if it is the reviewer identity, because
+        that check runs first and independently (see `loop.evaluate`).
+        """
+        if not self.authors:
+            return True
+        return login.lower() in {a.lower() for a in self.authors}
+
     @classmethod
     def build(
         cls,
@@ -399,6 +432,9 @@ class Config:
             )
 
         repos = _string_list(raw.get("repos", ()), "repos", "owner/repo entries")
+        authors = _string_list(
+            raw.get("authors", ()), "authors", "GitHub logins"
+        )
         operators = _string_list(
             raw.get("operators", ()), "operators", "GitHub logins"
         )
@@ -529,6 +565,7 @@ class Config:
             poll_interval=interval,
             round_cap=cap,
             repos=repos,
+            authors=authors,
             operators=operators,
             agent_profile=raw.get("agent_profile", "claude"),
             reviewer_login=raw.get("reviewer_login"),
@@ -553,8 +590,8 @@ def _string_list(value: Any, key: str, what: str) -> tuple[str, ...]:
     The guard is the point: JSON makes `"repos": "org/repo"` an easy typo, and
     Python would iterate it into single CHARACTERS -- an allowlist of 30-odd
     one-character names, which `watches()` then matches against nothing and the
-    daemon quietly reviews no PR at all. Both list keys go through here so
-    neither can grow the footgun back.
+    daemon quietly reviews no PR at all. Every list key goes through here so
+    none of them can grow the footgun back.
     """
     if isinstance(value, str):
         raise ValueError(

{alissa_tools_github_revloop-0.19.0 → alissa_tools_github_revloop-0.21.0}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -899,12 +899,28 @@ class GitHub:
         app; see ACTIONS_FALLBACK_NOTE for why that is accepted here and how the
         answer says so.
 
-        COST: this path costs one call for the run listing plus one per kept
-        workflow, where the read it replaces cost one. It is taken only where
-        the alternative is a permanent CHECKS_UNKNOWN, and only on the rollup
-        reads the caller already decided to make -- the gate's existing
-        per-round caching is what bounds how often that is. On this fleet's
-        repos (one or two workflows per commit) it is two or three calls.
+        COST, stated exactly, because it is the sentence an operator would size
+        rate-limit headroom from: this path costs one call for the run listing
+        plus one per KEPT workflow, where the read it replaces cost one.
+
+        Nothing caches that on the production path. `loop._dry_run_rollups` is
+        the only rollup memo and only the dry-run branch reads it, so what
+        bounds how often the cost is paid is the POLL INTERVAL -- both while
+        `_checks_at_spawn` holds a round on `checks_spawn_wait_seconds` and
+        while `_gate_on_checks` holds a finished verdict on
+        `checks_wait_seconds`, each of which re-reads the rollup every pass.
+
+        Nor is the fan-out bounded. CHECK_RUN_PAGE_LIMIT bounds the run
+        LISTING; the number of kept workflows is whatever the sha carries, and
+        each one costs a `jobs` call with `_api`'s 60s timeout, so a
+        many-workflow sha turns one rollup read into a long synchronous stall
+        inside a poll pass that has other PRs to decide. On this fleet's repos
+        (one or two workflows per commit) it is two or three calls; that is a
+        fact about these repos, not a bound this code enforces.
+
+        The trade is still worth taking where it applies: the alternative there
+        is a permanent CHECKS_UNKNOWN, which costs one call and can never
+        approve.
         """
         runs = self._rollup_listing(
             f"repos/{owner}/{repo}/actions/runs",
@@ -919,14 +935,26 @@ class GitHub:
 
     @staticmethod
     def _latest_run_per_workflow(runs: list[dict]) -> list[dict]:
-        """One run per workflow: the most recent.
-
-        A sha carries more than one run of the same workflow whenever it was
-        triggered more than once -- a re-run shares its run id, but a distinct
-        trigger event (a `push` and a `pull_request` on the same commit, a
-        workflow re-dispatched by hand) creates a distinct run. Reading all of
-        them would judge the commit on a superseded attempt: an earlier failed
-        run whose re-trigger passed would hold the head red forever.
+        """One run per workflow AND trigger event: the most recent.
+
+        Two different facts are being separated here, and collapsing them was a
+        fail-open bug.
+
+        SUPERSEDED ATTEMPTS collapse. A sha carries more than one run of the
+        same workflow for the same event whenever it was triggered again -- a
+        re-run shares its run id, a re-dispatch does not. Reading all of them
+        would judge the commit on a superseded attempt: an earlier failed run
+        whose re-trigger passed would hold the head red forever.
+
+        DISTINCT EVENTS DO NOT. A workflow declaring `on: [push, pull_request]`
+        produces a `push` run and a `pull_request` run for the same sha, and
+        GitHub publishes a check run per job for BOTH -- so the read this
+        stands in for reports both. Keying on `workflow_id` alone dropped the
+        lower `run_number` of the pair unread, and when the dropped one was the
+        red one the fallback answered GREEN for a commit whose real rollup is
+        red. That is the fail-open direction this whole component exists to
+        avoid, so the key carries `event` as well. A re-run preserves its run's
+        `event`, so the superseded-attempt collapse above is unaffected.
 
         Recency is `run_number` then `id`, both monotonic per workflow and both
         integers -- deliberately not a timestamp string, which is the field a
@@ -938,7 +966,7 @@ class GitHub:
         for index, run_ in enumerate(runs):
             workflow_id = run_.get("workflow_id")
             key: object = (
-                ("workflow", workflow_id)
+                ("workflow", workflow_id, str(run_.get("event") or ""))
                 if workflow_id is not None
                 else ("unidentified", index)
             )

{alissa_tools_github_revloop-0.19.0 → alissa_tools_github_revloop-0.21.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -407,6 +407,22 @@ CHECKS_FAILING_LINE = "- `{name}` — {conclusion}{url}"
 
 # Prepended when the gate held the approve for the whole wait bound and the
 # rollup still had not settled, so the verdict lands as a COMMENT.
+# Prepended to an APPROVE whose green came from the Actions-API fallback rather
+# than the check-runs rollup. Not a caveat on the review -- the code verdict is
+# unchanged -- but on the EVIDENCE behind the approve: the fallback cannot see a
+# check run posted by a third-party check app, so "green" here means "every
+# Actions-produced context passed", which is the same thing only on an
+# Actions-only repo.
+CHECKS_FALLBACK_LEAD = (
+    "**CI rollup at `{sha}` read through the Actions API.** This deployment's "
+    "credential cannot read check runs (GitHub does not offer the `Checks` "
+    "permission on fine-grained PATs), so the head was confirmed green from its "
+    "workflow runs and jobs instead. That read sees every GitHub-Actions "
+    "context and no third-party check app's, so on an Actions-only repo it is "
+    "the same answer — flagging the path because an approve is the operator's "
+    "merge cue.\n\n"
+)
+
 CHECKS_UNSETTLED_LEAD = (
     "**Recorded as a comment, not an approve — the CI rollup at `{sha}` never "
     "concluded.**\n\n"
@@ -466,10 +482,18 @@ CHECKS_STILL_RUNNING = "Still running at the bound: {names}."
 # which waited on nothing and so cannot describe anything as being "at the
 # bound" (see CHECKS_AT_SPAWN_GATE_OFF).
 CHECKS_GATE_OFF_DETAIL = "Still running when the round was queued: {names}."
+# Deliberately does NOT tell the operator to grant `checks: read`, which is what
+# it said before the Actions fallback existed. GitHub does not offer the `Checks`
+# permission on fine-grained PATs at all, and a rollup that reaches UNKNOWN on
+# such a deployment has ALREADY tried the Actions read and failed -- so that
+# advice pointed at the one action that provably cannot work, at the moment the
+# operator is already blocked. The remaining causes are the ones named here.
 CHECKS_UNREADABLE = (
     "The rollup could not be read: `{why}`. An unreadable rollup is not a green "
-    "one — check that the reviewer credential carries `checks: read` on this "
-    "repo."
+    "one. On a credential that cannot read check runs the loop already fell "
+    "back to the Actions API, so reaching this point means that read failed "
+    "too — check the credential's `Actions: Read`, or whether the listing was "
+    "truncated (more contexts than the page bound)."
 )
 
 # The operator page for a native verdict post that keeps failing. Loud on
@@ -1671,6 +1695,13 @@ class ReviewWatcher:
         if pr.author == self.github.login:
             # GitHub rejects a self review-request, so this should be
             # unreachable -- but a shared bot identity would land here.
+            #
+            # FIRST, and deliberately above the authors allowlist (further
+            # down): the allowlist is a scope filter an operator writes, and no
+            # entry in it may buy back a review GitHub itself forbids. Listing
+            # the reviewer login in `authors` therefore narrows the loop to a PR
+            # it will then refuse -- which is the correct reading of "only serve
+            # this author" for an author that cannot be served.
             return Decision(
                 Action.SKIPPED,
                 f"PR author is the reviewer identity ({pr.author}); "
@@ -1731,6 +1762,36 @@ class ReviewWatcher:
             self._clear_own_review_request(pr, my_reviews, converged)
             return Decision(Action.CONVERGED, converged, completed)
 
+        # THE AUTHORS SCOPE FILTER (issue #93), and its position is the whole
+        # of its contract: it gates STARTING a round and nothing else.
+        #
+        # Client-side, because the discovery search is deliberately untouched --
+        # the author is only in hand once the PR detail is fetched. Below
+        # convergence rather than up beside the self-review skip, because every
+        # branch above finishes a round that was already started: a verdict
+        # envelope ahead of its native review still becomes a review of record
+        # (_close_round_natively), and a converged PR still gets its dangling
+        # review request withdrawn (_clear_own_review_request). An operator who
+        # narrows `authors` mid-round must not strand the round that is already
+        # running, and stopping one step short of its verdict of record is the
+        # studio #298 failure this module refuses everywhere else (PR #94 round
+        # 1). It costs a filtered PR one my_reviews fetch and the review-task
+        # lookup per poll -- the negative cache bounds the corpus search -- and
+        # that is the price of not stranding a round.
+        #
+        # Above THIS line, therefore, and everything the issue's checklist asks
+        # for follows from where it sits: the effective cap and its ack
+        # announcement, the cap-out escalation (the only branch below that would
+        # COMMENT on the PR), `round_ = completed + 1`, the stale-round probe and
+        # the spawn are all downstream. A filtered PR burns no round number,
+        # records no attempt, holds no stale-round slot and never says a word on
+        # the PR -- it gets silence, exactly as an unwatched repo does.
+        if not self.config.serves_author(pr.author):
+            return Decision(
+                Action.SKIPPED,
+                f"PR author {pr.author} is not in the authors allowlist",
+            )
+
         # The effective cap is the configured one plus every re-entry an
         # operator has explicitly acked on THIS PR (issue #42). The sum is a
         # local read, so it costs nothing on the common path; the GitHub scan
@@ -2438,10 +2499,24 @@ class ReviewWatcher:
         rollup = self.github.check_rollup(pr.owner, pr.repo, judged)
 
         if rollup.state == CHECKS_GREEN:
-            log.debug(
+            # `info`, not `debug`: this is the line an operator reads to find
+            # out WHICH read path called the head green, and on the deployment
+            # that needs the answer the fallback is every read.
+            log.info(
                 "%s round %d: CI rollup at %s is %s — approving as usual",
                 pr.slug, round_, judged[:8], rollup.summary,
             )
+            if rollup.via_actions_fallback:
+                # The one state where the marker had nowhere PR-visible to go.
+                # Every other path that surfaces `summary` (the hold activity
+                # comment, the degraded-verdict lead) is reachable only from
+                # PENDING or UNKNOWN, so "approved on green" -- the claim an
+                # operator acts on -- was the single verdict that did not say
+                # it came from the narrower read.
+                return ChecksGate(
+                    lead=CHECKS_FALLBACK_LEAD.format(sha=judged[:8]),
+                    state=CHECKS_GREEN,
+                )
             return ChecksGate()
 
         if rollup.state == CHECKS_RED:

alissa_tools_github_revloop-0.21.0/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.21.0

{alissa_tools_github_revloop-0.19.0 → alissa_tools_github_revloop-0.21.0/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.19.0
+Version: 0.21.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_revloop-0.19.0/src/main/alissa/tools/github/revloop/version

@@ -1 +0,0 @@
-0.19.0