alissa-tools-github-revloop 0.25.0__tar.gz → 0.27.0__tar.gz

{alissa_tools_github_revloop-0.25.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.27.0}/PKG-INFO

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

{alissa_tools_github_revloop-0.25.0 → alissa_tools_github_revloop-0.27.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -101,6 +101,14 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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(
+        "--stability-rounds",
+        type=int,
+        metavar="N",
+        help="PRODUCT-STABILITY GUARD: hold the loop once the shipped-product "
+        "diff has been empty for N consecutive request_changes rounds (0 "
+        "disables the guard entirely)",
+    )
     over.add_argument("--hub-template", metavar="TEMPLATE")
     over.add_argument("--agent-profile", metavar="NAME")
     over.add_argument("--reviewer-login", metavar="LOGIN")
@@ -218,6 +226,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "operators": tuple(args.operators) if args.operators else None,
         "poll_interval": args.poll_interval,
         "round_cap": args.round_cap,
+        "stability_rounds": args.stability_rounds,
         "hub_template": args.hub_template,
         "agent_profile": args.agent_profile,
         "reviewer_login": args.reviewer_login,

{alissa_tools_github_revloop-0.25.0 → alissa_tools_github_revloop-0.27.0}/src/main/alissa/tools/github/revloop/config.py

@@ -21,6 +21,7 @@ daemons over different workspaces on the same machine, each pointed with
 
 from __future__ import annotations
 
+import fnmatch
 import json
 import os
 import re
@@ -127,6 +128,8 @@ CONFIG_KEYS = (
     "hub_template",
     "poll_interval",
     "round_cap",
+    "stability_rounds",
+    "stability_nonshipped_globs",
     "repos",
     "authors",
     "operators",
@@ -276,6 +279,105 @@ DEFAULT_CHECKS_SPAWN_WAIT_SECONDS = 15 * 60
 DEFAULT_REVIEW_TASK_MISS_TTL_POLLS = 10
 
 
+# -- the product-stability guard (issue #105) ---------------------------------
+#
+# How many consecutive `request_changes` rounds must move NOTHING outside
+# `stability_nonshipped_globs` before the loop stops spending rounds on a PR
+# whose shipped product has converged. Measured on the live fleet: of the PRs
+# sampled on 2026-08-28/29, none that was still unapproved at round 5 ever
+# needed a shipped-code change again -- studio #847 ran eleven further rounds
+# (~7 h, ~22 agent sessions) moving only `tests/**`.
+#
+# 3 rather than 1 because ONE empty round is ordinary: a round that only asked
+# for a comment to be reworded is a normal round, and holding on it would turn
+# the guard into a second cap. Three consecutive ones is a pattern.
+#
+# 0 disables the guard, and disables it COMPLETELY: no compare call, no
+# directive block, no hold, every decision bit-identical to the world before
+# this key existed. That is the escape hatch a deployment that dislikes the
+# guard uses, and it is why the gate is skipped whole rather than degraded into
+# a no-op.
+DEFAULT_STABILITY_ROUNDS = 3
+
+# Path globs whose movement is NOT product movement. Deliberately conservative:
+# a file that is not obviously a test, a doc or a generated artifact counts as
+# shipped, because the guard's two failure directions are not symmetric --
+# calling shipped code non-shipped can hold a PR that still needs work, while
+# calling a test file shipped only costs another round.
+DEFAULT_STABILITY_NONSHIPPED_GLOBS = (
+    "tests/**",
+    "test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/*.md",
+    "docs/**",
+    "**/__snapshots__/**",
+    "**/_generated/**",
+)
+
+
+def glob_matches(path: str, pattern: str) -> bool:
+    """Does `path` match `pattern`, with `**` crossing directory separators?
+
+    Neither obvious implementation does what these globs mean:
+
+    * `pathlib.PurePosixPath.match` treats `**` as a single component, so
+      `**/*.test.*` misses `src/a/b/x.test.ts` -- the exact nesting the guard
+      has to recognise, and the miss is silent (the file reads as shipped and
+      the PR simply never stabilises);
+    * bare `fnmatch` goes the other way -- its `*` crosses `/` too, so `docs/*`
+      would swallow `docs/a/b/c` -- and, worse for the defaults here, `**/*.md`
+      then REQUIRES a `/` and does not match a top-level `README.md`.
+
+    So the pattern is matched SEGMENT by segment: `**` matches zero or more
+    whole segments (which is what makes `**/*.md` cover both `README.md` and
+    `docs/a/b.md`), and every other segment is an ordinary `fnmatch` pattern
+    that cannot cross a separator. A trailing `**` matches the whole remainder,
+    including none of it.
+
+    Case-SENSITIVE (`fnmatchcase`): `fnmatch.fnmatch` normalises by platform, so
+    the same config would classify `Docs/x.MD` one way on a developer's macOS
+    checkout and another in the Linux container. Repo paths are case-sensitive
+    on the side that matters -- GitHub's.
+    """
+    return _match_segments(
+        tuple(part for part in str(path).split("/") if part != ""),
+        tuple(str(pattern).split("/")),
+    )
+
+
+def _match_segments(
+    path_parts: "tuple[str, ...]", pat_parts: "tuple[str, ...]"
+) -> bool:
+    """The recursion behind `glob_matches`. Branching is bounded by the pattern:
+    only a `**` branches, the defaults carry at most one, and a pattern is
+    operator-written config rather than repo-controlled text."""
+    if not pat_parts:
+        return not path_parts
+    head, rest = pat_parts[0], pat_parts[1:]
+    if head == "**":
+        if not rest:
+            return True  # the whole remainder, including nothing
+        return any(
+            _match_segments(path_parts[i:], rest) for i in range(len(path_parts) + 1)
+        )
+    if not path_parts:
+        return False
+    if not fnmatch.fnmatchcase(path_parts[0], head):
+        return False
+    return _match_segments(path_parts[1:], rest)
+
+
+def is_nonshipped(path: str, globs: "tuple[str, ...]") -> bool:
+    """Whether a changed path is one the stability guard ignores.
+
+    An EMPTY glob tuple means nothing is non-shipped, so every changed file is
+    product movement and the guard can never hold -- the same fail-toward-rounds
+    direction every other unknown in the guard takes.
+    """
+    return any(glob_matches(path, pattern) for pattern in globs)
+
+
 def default_state_path(workspace_root: Path) -> Path:
     return Path(workspace_root) / ".revloop" / "state.db"
 
@@ -289,6 +391,15 @@ class Config:
     poll_interval: int = 60
     round_cap: int = 10  # CR9 default
 
+    # How many consecutive request_changes rounds with an EMPTY shipped-product
+    # diff make the loop stop spawning plain rounds; see
+    # DEFAULT_STABILITY_ROUNDS. 0 disables the guard entirely.
+    stability_rounds: int = DEFAULT_STABILITY_ROUNDS
+
+    # The path globs that count as non-shipped when the guard measures that
+    # diff; see DEFAULT_STABILITY_NONSHIPPED_GLOBS and `glob_matches`.
+    stability_nonshipped_globs: tuple[str, ...] = DEFAULT_STABILITY_NONSHIPPED_GLOBS
+
     # Empty tuple means "every repo that requests a review from me".
     repos: tuple[str, ...] = ()
 
@@ -524,6 +635,20 @@ class Config:
         if cap < 1:
             raise ValueError(f"round_cap must be >= 1, got {cap}")
 
+        stability = int(raw.get("stability_rounds", cls.stability_rounds))
+        if stability < 0:
+            # 0 is legal and means "off", unlike round_cap's floor of 1: the
+            # guard is an ADDITION to the loop, so switching it off has to be
+            # expressible, and the value that expresses it is the one asking
+            # for zero stable rounds.
+            raise ValueError(f"stability_rounds must be >= 0, got {stability}")
+
+        nonshipped = _string_list(
+            raw.get("stability_nonshipped_globs", cls.stability_nonshipped_globs),
+            "stability_nonshipped_globs",
+            "path globs",
+        )
+
         interval = int(raw.get("poll_interval", 60))
         if interval < MIN_POLL_INTERVAL:
             raise ValueError(
@@ -637,6 +762,8 @@ class Config:
             hub_template=raw.get("hub_template", cls.hub_template),
             poll_interval=interval,
             round_cap=cap,
+            stability_rounds=stability,
+            stability_nonshipped_globs=nonshipped,
             repos=repos,
             authors=authors,
             operators=operators,

{alissa_tools_github_revloop-0.25.0 → alissa_tools_github_revloop-0.27.0}/src/main/alissa/tools/github/revloop/ghclient.py

@@ -42,6 +42,33 @@ SUBMITTED_STATES = {"APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"}
 PER_PAGE = 100
 COMMENT_PAGE_LIMIT = 20
 
+# The compare endpoint's HARD cap on the `files` array, and it is a cap, not a
+# page: `files` is not paginated at all. Measured against api.github.com on
+# python/cpython v3.11.0...v3.12.0 (PR #106 round 1, blocker):
+#
+#   per_page=300 page=1 -> {"commits": 300, "files": 300}
+#   per_page=300 page=2 -> {"commits": 300, "files":   0}
+#   per_page=100 page=1 -> {"commits": 100, "files": 300}
+#   per_page=1   page=1 -> {"commits":   1, "files": 300}
+#
+# So `per_page` sizes the COMMITS array and nothing else, and page 2 carries no
+# files because there is no second page of them. A reader that paged until a
+# short page would take that empty page 2 as "the listing ended" and hand back
+# exactly 300 paths as a complete diff -- and `files` comes back in PATH ORDER,
+# so what survives is the alphabetically first 300, which is where `docs/**` and
+# `**/*.md` live and where `src/**` does not. Truncation therefore does not
+# sample the diff, it systematically keeps the non-shipped files and drops the
+# shipped ones -- inverting the one invariant the stability guard rests on.
+#
+# Hence: ONE request, and a full 300 means "cannot prove absence" (see
+# `compare_files`).
+COMPARE_FILE_PAGE = 300
+
+# `per_page` only sizes the commits array, which no caller here reads, so it is
+# asked for the smallest legal value rather than for a page that matches the
+# file cap. 300 commits per evaluation was payload nobody looked at.
+COMPARE_COMMITS_PER_PAGE = 1
+
 # GitHub's OWN cap on the pull-request commits endpoint: it "lists a maximum of
 # 250 commits" and refers callers with more to the repository commits endpoint.
 # That, not a page count of ours, is where absence stops being provable -- a
@@ -1196,6 +1223,74 @@ class GitHub:
             )
         return out
 
+    def compare_files(
+        self, owner: str, repo: str, base_sha: str, head_sha: str
+    ) -> list[str]:
+        """Every path that differs between two commits, in the order GitHub
+        returns them (path order).
+
+        Read on ONE path: the product-stability guard, which asks whether the
+        diff between the head a round judged N rounds ago and the head now
+        contains anything outside the non-shipped globs. ABSENCE is therefore
+        the load-bearing answer, and this endpoint cannot support it past
+        COMPARE_FILE_PAGE files -- the array is capped, not paged, so a
+        comparison at the cap is indistinguishable from one just under it. At
+        the cap the read is REFUSED (`TruncatedListing`) rather than answered
+        short; the caller turns that into an inert guard and another round.
+
+        ONE request. An earlier version paged until a short page, which on this
+        endpoint always arrived on page 2 with zero files -- see
+        COMPARE_FILE_PAGE for the measurement and for why the truncation is
+        biased rather than random.
+
+        A RENAME contributes BOTH names. GitHub reports it as one entry whose
+        `filename` is the new path and whose `previous_filename` is the old one,
+        and only counting the new one loses exactly the case the guard must not
+        miss: `src/thing.ts` renamed to `tests/thing.test.ts` moved shipped
+        code, and reading only the destination makes it look like a test-only
+        change.
+
+        403 is NOT caught here (`forbidden_is_rate_limit=False` lets it through
+        as a CommandError): whether an unreadable comparison is fatal or merely
+        makes a guard inert is the caller's decision, not this client's -- and
+        this credential is the same PAT that cannot read check-runs, so it is a
+        live case rather than a theoretical one.
+        """
+        payload = (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/compare/{base_sha}...{head_sha}",
+                "-f",
+                f"per_page={COMPARE_COMMITS_PER_PAGE}",
+                forbidden_is_rate_limit=False,
+            )
+            or {}
+        )
+        files = payload.get("files") or []
+        if len(files) >= COMPARE_FILE_PAGE:
+            log.warning(
+                "%s/%s comparison %s...%s reported %d files, the API's "
+                "per-comparison cap — the file list is not complete, so "
+                "'nothing shipped moved' cannot be read from it",
+                owner, repo, base_sha[:8], head_sha[:8], len(files),
+            )
+            raise TruncatedListing(
+                f"{owner}/{repo} comparison {base_sha[:8]}...{head_sha[:8]} "
+                f"reported {len(files)} files, the API's per-comparison cap; "
+                f"absence cannot be proven from it"
+            )
+
+        out: list[str] = []
+        seen: set[str] = set()
+        for entry in files:
+            for key in ("filename", "previous_filename"):
+                name = str(entry.get(key) or "")
+                if name and name not in seen:
+                    seen.add(name)
+                    out.append(name)
+        return out
+
     def update_comment(self, owner: str, repo: str, comment_id: int, body: str) -> None:
         self._api(
             "-X",