diffbutler 0.5.3__tar.gz → 0.6.1__tar.gz

{diffbutler-0.5.3 → diffbutler-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffbutler
-Version: 0.5.3
+Version: 0.6.1
 Summary: A terminal dashboard for human-directed AI code reviews.
 Keywords: code-review,github,terminal,ai
 License-Expression: MIT
@@ -34,7 +34,7 @@ Keep track of what each pull request needs next: AI review, your review, or auth
 changes. Start an AI review, discuss its findings in the agent's own session, and
 finish your review in the browser.
 
-![DiffButler dashboard showing pull requests and the next review action](diffbutler.png)
+![DiffButler dashboard showing pull requests and the next review action](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/diffbutler.png)
 
 ## Install
 
@@ -91,22 +91,25 @@ From the GitHub repository you want to review, launch:
 diffbutler
 ```
 
-First-run setup detects the local repository, looks up your GitHub username using
-the selected token, asks for your preferred agent, and saves your choices. If username detection
-is unavailable, setup asks for it. Choose the recommended token access for public repositories;
-private repositories require it. Setup asks for the token's environment variable name
-and validates access. It never saves the token.
+First-run setup detects the local repository and asks whether to monitor just that
+repository or all repositories belonging to the same owner. It looks up your GitHub
+username using the selected token, asks for your preferred agent, and saves your choices.
+If username detection is unavailable, setup asks for it. Choose the recommended token
+access for public repositories; private repositories require it. Setup asks for the
+token's environment variable name and validates access. It never saves the token.
 New configs silently enable both Codex and Claude when found in `PATH`; setup asks
 only which detected agent should be the default. Missing agents get commented-out
 entries you can enable after installation.
 Later launches reuse your configuration.
+Repository filters accept exact names such as `heikkitoivonen/diffbutler` or
+`heikkitoivonen/*` for all accessible repositories owned by that account.
 
 The dashboard shows active reviews, including followed PRs whose GitHub review
 requests have disappeared after you posted feedback. Waiting-for-author reviews
 stay visible across refreshes and restarts. If an approved PR receives new commits,
 it reappears as `done+` at the end of the queue without starting another AI review.
-Authenticated polling slows when API quota is scarce and speeds back up when it
-recovers, accounting for refresh cost and time until the quota resets.
+Polling spreads API quota evenly until it resets, leaving 10% in reserve: it slows
+when quota is scarce or refreshes are costly and speeds back up when quota recovers.
 
 Select a PR with the arrow keys, then work through the review:
 
@@ -125,20 +128,24 @@ Select a PR with the arrow keys, then work through the review:
    starts a new run with the current reviewer and replaces the current review details.
    Ask questions and explicitly tell the agent which comments to post, if any.
 3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
-   Press `w` if you are waiting for author changes, or `o` to review in your browser.
+   Press `o` to open the PR in your browser at any time; it does not change the state.
+   Press `w` if you are waiting for author changes, or `a` once you are ready to approve.
 4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
    also detects your approval, closure, or merge and cleans up owned session resources
    while retaining review history.
 
 `Space` performs the selected PR's next action: start a review, discuss findings,
-or open the browser. An AI review never counts as your approval. Background analysis
+or open the browser. For `check` and `author`, it resumes the saved agent conversation,
+just like `c`. An AI review never counts as your approval. Background analysis
 uses the agent's [native permission controls](docs/native-reviews.md#native-permissions-and-authentication)
 and read-only review instructions; source sent to the agent may go to its model provider.
 
 - `/`: Filter the queue.
-- `a`: Toggle monitoring all open PRs in configured repositories.
+- `A`: Toggle monitoring all open PRs in configured repositories.
 - `b`: Browse accessible PRs and follow one.
-- `R`: Refresh from GitHub.
+- `R`: Find and add a PR by link or number, then review it; choose a repository if
+  the number is ambiguous. Explicitly selected PRs bypass queue visibility filters.
+- `Ctrl+R`: Refresh from GitHub.
 - `k`: Stop the selected PR's review and reset its local tracking and owned resources.
   It disappears until a forge refresh rediscovers it; review history is retained.
 - `h`: View completed review history.
@@ -149,10 +156,34 @@ See the [dashboard guide](docs/dashboard.md) for all actions and
 [configuration guide](docs/configuration.md) for settings.
 
 Your own PRs are hidden from the review queue by default, including direct and team
-requests. Set `include_own_prs = true` in `[ui]` to review them, such as PRs an agent
-created using your account. PRs assigned to you are also hidden by default, even when
+requests. Use `R` to select one explicitly, or set `include_own_prs = true` in `[ui]`
+to show them all, such as PRs an agent created using your account.
+PRs assigned to you are also hidden by default, even when
 you are requested directly or through a team. Set `include_assigned_prs = true` in
-`[ui]` to include them.
+`[ui]` to include them, or select one with `R`.
+
+### How PRs move through the board
+
+Solid arrows are actions you take; dashed arrows happen automatically.
+
+How a PR arrives:
+
+![Flow diagram: review requests and all-PR monitoring reach the board through polling, browsing adds followed PRs, and your own or assigned PRs are hidden unless enabled; R adds a PR directly and starts a review. New PRs start as pending unless already approved, closed, or merged.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-arrival.svg)
+
+How its status changes:
+
+![State diagram: r queues a review, the worker runs it, and the result is approve or check; w, a, and m move a PR between author, approve, and done; Ctrl+C or a failed agent returns it to pending; GitHub commits, your submitted reviews, and closes or merges move it automatically; new commits after approval show done+.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-status.svg)
+
+`r`, `a`, `w`, and `m` work from any open status, not only along the arrows shown,
+though `r` refuses while a review is already queued or running. New commits on a
+`done+` PR keep it `done+` rather than returning it to `pending`.
+
+How it leaves:
+
+![Flow diagram: m, your approval, or a close or merge moves a PR to done and history; k removes it until a refresh finds it still requested or monitored; becoming an assignee hides it unless include_assigned_prs is set or it was selected with R.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-exit.svg)
+
+A PR stays on the board when its review request is withdrawn; press `k` to remove it.
+A PR you only followed stays away after `k` until you follow it again.
 
 ## Reset
 

{diffbutler-0.5.3 → diffbutler-0.6.1}/README.md

@@ -6,7 +6,7 @@ Keep track of what each pull request needs next: AI review, your review, or auth
 changes. Start an AI review, discuss its findings in the agent's own session, and
 finish your review in the browser.
 
-![DiffButler dashboard showing pull requests and the next review action](diffbutler.png)
+![DiffButler dashboard showing pull requests and the next review action](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/diffbutler.png)
 
 ## Install
 
@@ -63,22 +63,25 @@ From the GitHub repository you want to review, launch:
 diffbutler
 ```
 
-First-run setup detects the local repository, looks up your GitHub username using
-the selected token, asks for your preferred agent, and saves your choices. If username detection
-is unavailable, setup asks for it. Choose the recommended token access for public repositories;
-private repositories require it. Setup asks for the token's environment variable name
-and validates access. It never saves the token.
+First-run setup detects the local repository and asks whether to monitor just that
+repository or all repositories belonging to the same owner. It looks up your GitHub
+username using the selected token, asks for your preferred agent, and saves your choices.
+If username detection is unavailable, setup asks for it. Choose the recommended token
+access for public repositories; private repositories require it. Setup asks for the
+token's environment variable name and validates access. It never saves the token.
 New configs silently enable both Codex and Claude when found in `PATH`; setup asks
 only which detected agent should be the default. Missing agents get commented-out
 entries you can enable after installation.
 Later launches reuse your configuration.
+Repository filters accept exact names such as `heikkitoivonen/diffbutler` or
+`heikkitoivonen/*` for all accessible repositories owned by that account.
 
 The dashboard shows active reviews, including followed PRs whose GitHub review
 requests have disappeared after you posted feedback. Waiting-for-author reviews
 stay visible across refreshes and restarts. If an approved PR receives new commits,
 it reappears as `done+` at the end of the queue without starting another AI review.
-Authenticated polling slows when API quota is scarce and speeds back up when it
-recovers, accounting for refresh cost and time until the quota resets.
+Polling spreads API quota evenly until it resets, leaving 10% in reserve: it slows
+when quota is scarce or refreshes are costly and speeds back up when quota recovers.
 
 Select a PR with the arrow keys, then work through the review:
 
@@ -97,20 +100,24 @@ Select a PR with the arrow keys, then work through the review:
    starts a new run with the current reviewer and replaces the current review details.
    Ask questions and explicitly tell the agent which comments to post, if any.
 3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
-   Press `w` if you are waiting for author changes, or `o` to review in your browser.
+   Press `o` to open the PR in your browser at any time; it does not change the state.
+   Press `w` if you are waiting for author changes, or `a` once you are ready to approve.
 4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
    also detects your approval, closure, or merge and cleans up owned session resources
    while retaining review history.
 
 `Space` performs the selected PR's next action: start a review, discuss findings,
-or open the browser. An AI review never counts as your approval. Background analysis
+or open the browser. For `check` and `author`, it resumes the saved agent conversation,
+just like `c`. An AI review never counts as your approval. Background analysis
 uses the agent's [native permission controls](docs/native-reviews.md#native-permissions-and-authentication)
 and read-only review instructions; source sent to the agent may go to its model provider.
 
 - `/`: Filter the queue.
-- `a`: Toggle monitoring all open PRs in configured repositories.
+- `A`: Toggle monitoring all open PRs in configured repositories.
 - `b`: Browse accessible PRs and follow one.
-- `R`: Refresh from GitHub.
+- `R`: Find and add a PR by link or number, then review it; choose a repository if
+  the number is ambiguous. Explicitly selected PRs bypass queue visibility filters.
+- `Ctrl+R`: Refresh from GitHub.
 - `k`: Stop the selected PR's review and reset its local tracking and owned resources.
   It disappears until a forge refresh rediscovers it; review history is retained.
 - `h`: View completed review history.
@@ -121,10 +128,34 @@ See the [dashboard guide](docs/dashboard.md) for all actions and
 [configuration guide](docs/configuration.md) for settings.
 
 Your own PRs are hidden from the review queue by default, including direct and team
-requests. Set `include_own_prs = true` in `[ui]` to review them, such as PRs an agent
-created using your account. PRs assigned to you are also hidden by default, even when
+requests. Use `R` to select one explicitly, or set `include_own_prs = true` in `[ui]`
+to show them all, such as PRs an agent created using your account.
+PRs assigned to you are also hidden by default, even when
 you are requested directly or through a team. Set `include_assigned_prs = true` in
-`[ui]` to include them.
+`[ui]` to include them, or select one with `R`.
+
+### How PRs move through the board
+
+Solid arrows are actions you take; dashed arrows happen automatically.
+
+How a PR arrives:
+
+![Flow diagram: review requests and all-PR monitoring reach the board through polling, browsing adds followed PRs, and your own or assigned PRs are hidden unless enabled; R adds a PR directly and starts a review. New PRs start as pending unless already approved, closed, or merged.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-arrival.svg)
+
+How its status changes:
+
+![State diagram: r queues a review, the worker runs it, and the result is approve or check; w, a, and m move a PR between author, approve, and done; Ctrl+C or a failed agent returns it to pending; GitHub commits, your submitted reviews, and closes or merges move it automatically; new commits after approval show done+.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-status.svg)
+
+`r`, `a`, `w`, and `m` work from any open status, not only along the arrows shown,
+though `r` refuses while a review is already queued or running. New commits on a
+`done+` PR keep it `done+` rather than returning it to `pending`.
+
+How it leaves:
+
+![Flow diagram: m, your approval, or a close or merge moves a PR to done and history; k removes it until a refresh finds it still requested or monitored; becoming an assignee hides it unless include_assigned_prs is set or it was selected with R.](https://raw.githubusercontent.com/heikkitoivonen/diffbutler/main/docs/diagrams/pr-exit.svg)
+
+A PR stays on the board when its review request is withdrawn; press `k` to remove it.
+A PR you only followed stays away after `k` until you follow it again.
 
 ## Reset
 

{diffbutler-0.5.3 → diffbutler-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "diffbutler"
-version = "0.5.3"
+version = "0.6.1"
 description = "A terminal dashboard for human-directed AI code reviews."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -39,7 +39,7 @@ dependencies = [
 diffbutler = "diffbutler.ui.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.12.13,<0.13.0"]
+requires = ["uv_build>=0.12.13,<0.14.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -56,7 +56,7 @@ dev = [
 ]
 
 [tool.uv]
-required-version = ">=0.12.13,<0.13"
+required-version = ">=0.12.13"
 exclude-newer = "2 days"
 
 [tool.ruff]

{diffbutler-0.5.3 → diffbutler-0.6.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "diffbutler"
-version = "0.5.3"
+version = "0.6.1"
 description = "A terminal dashboard for human-directed AI code reviews."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -34,7 +34,7 @@ dependencies = [
 diffbutler = "diffbutler.ui.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.12.13,<0.13.0"]
+requires = ["uv_build>=0.12.13,<0.14.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -51,7 +51,7 @@ dev = [
 ]
 
 [tool.uv]
-required-version = ">=0.12.13,<0.13"
+required-version = ">=0.12.13"
 # Give new dependency releases time to settle before routine upgrades.
 exclude-newer = "2 days"
 

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/config/default.toml

@@ -5,7 +5,7 @@ reviewers = []
 
 [general]
 # Minimum: 60 seconds with authenticated accounts, 600 with any public account.
-# poll_interval_s = 600 # Override the minimum; low authenticated quota slows polling.
+# poll_interval_s = 600 # Override the minimum; low quota slows polling.
 max_concurrent_reviews = 2
 # Omit workspace_root to follow $XDG_DATA_HOME/diffbutler/reviews
 # (default ~/.local/share/diffbutler/reviews).
@@ -37,7 +37,7 @@ checkout = "worktree" # Native reviews currently use pinned source snapshots.
 include_own_prs = false # Set true to review PRs authored by your account.
 include_assigned_prs = false # Set true to review PRs assigned to your account.
 columns = ["number", "title", "author", "state"]
-sort_by = "attention"
+sort_by = "state"
 sort_desc = true
 preview_pane = true
 default_filter = "active"
@@ -69,6 +69,7 @@ open_in_browser = ["o", "ctrl+o"]
 # token_env = "GITHUB_TOKEN" # Omit for public access (None); login is then required.
 # include_team_requests = true
 # repositories = [] # Empty means review requests from all accessible repositories.
+# Use ["owner/repo"] for one repository or ["owner/*"] for all of an owner's repositories.
 # login = "your-login"
 
 # Remove the top-level reviewers = [] before adding reviewers:

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/config/settings.py

@@ -125,7 +125,7 @@ class UI(Section):
             "state",
         ]
     )
-    sort_by: str = "attention"
+    sort_by: str = "state"
     sort_desc: bool = True
     preview_pane: bool = True
     default_filter: Literal[

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/config/setup.py

@@ -15,7 +15,7 @@ from diffbutler.config.settings import NATIVE_PRESETS, ConfigError, Forge, Revie
 def save_setup(
     path: Path | None,
     forge: Forge | None,
-    repository_path: Path | None,
+    local_repository: tuple[str, Path] | None,
     reviewers: Sequence[Reviewer] = (),
     default_reviewer: str | None = None,
 ) -> Path:
@@ -40,7 +40,8 @@ def save_setup(
             if "review" not in document:
                 document["review"] = tomlkit.table()
             document["review"]["default_reviewer"] = default_reviewer
-        if repository_path is not None and forge is not None:
+        if local_repository is not None and forge is not None:
+            repository, repository_path = local_repository
             repos = document.get("repos")
             if repos is None:
                 repos = tomlkit.table()
@@ -48,7 +49,6 @@ def save_setup(
             if not isinstance(repos, MutableMapping):
                 raise ConfigError("Use a [repos] table to save local repository paths")
             repos = cast(MutableMapping[str, Any], repos)
-            repository = forge.repositories[0]
             if repository not in repos:
                 repos[repository] = {"path": str(repository_path)}
             else:

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/core/application.py

@@ -1,14 +1,16 @@
 """Configured shared-core entry points with owned database/forge lifetimes."""
 
 import asyncio
+import re
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Literal
 
 from diffbutler.config.settings import Settings, load_settings
+from diffbutler.core.pr_lookup import ReviewTarget, numbered_prs, open_pr
 from diffbutler.core.sync import DiffButler, PullRequestRow, SyncReport, list_queue
-from diffbutler.domain.forge import PRPage, PRQuery
+from diffbutler.domain.forge import Account, PRPage, PRQuery, PRRef
 from diffbutler.forges.base import ForgeError
 from diffbutler.forges.registry import open_forge
 from diffbutler.store.dashboard import SQLiteDashboardStore
@@ -88,6 +90,63 @@ async def browse_configured(
         return await service.browse_prs(query, cursor)
 
 
+async def review_targets_configured(
+    path: Path | None, value: str, *, deadline: float | None = None
+) -> tuple[ReviewTarget, ...]:
+    """Resolve without following PRs or requesting any AI work.
+
+    deadline is the event-loop time by which number lookups must finish.
+    """
+    value = value.strip()
+    numeric = re.fullmatch(r"#?([1-9][0-9]*)", value)
+    if not numeric and not value.startswith("https://"):
+        raise ForgeError("Enter a PR link or a positive PR number")
+    found: dict[tuple[Account, PRRef], ReviewTarget] = {}
+    async with local_store(path) as (store, settings):
+        if not settings.forges:
+            raise ForgeError("No forge configured")
+        if numeric and not any(config.repositories for config in settings.forges):
+            raise ForgeError("No monitored repositories configured; enter a PR link instead")
+        matched_url = False
+        for index, config in enumerate(settings.forges, 1):
+            if numeric and not config.repositories:
+                continue
+            async with remote_service(store, settings, index) as service:
+                if numeric:
+                    prs = await numbered_prs(
+                        service.forge, config.repositories, int(numeric[1]), deadline=deadline
+                    )
+                else:
+                    try:
+                        ref = service.forge.ref(value)
+                    except ForgeError:
+                        continue
+                    matched_url = True
+                    pr = await open_pr(service.forge, ref)
+                    prs = (pr,) if pr else ()
+                account = await service.forge.whoami()
+                if config.login and account.login.casefold() != config.login.casefold():
+                    raise ForgeError("Authenticated identity does not match configured account")
+                for pr in prs:
+                    found.setdefault((account, pr.ref), ReviewTarget(index, account, pr))
+        if not numeric and not matched_url:
+            raise ForgeError("Enter a valid PR link on a configured forge")
+    return tuple(found.values())
+
+
+async def follow_review_target_configured(
+    path: Path | None, target: ReviewTarget
+) -> PullRequestRow:
+    """Revalidate the chosen account and open state before tracking a review target."""
+    async with (
+        local_store(path) as (store, settings),
+        remote_service(store, settings, target.forge_index) as service,
+    ):
+        if await service.forge.whoami() != target.account:
+            raise ForgeError("Configured account changed; look up the PR again")
+        return await service.follow_pr(target.pull_request.ref, for_review=True)
+
+
 async def local_queue(
     path: Path | None,
     view: Literal["active", "requested", "following"],

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/core/dashboard.py

@@ -54,7 +54,7 @@ class DashboardRow(BaseModel):
 
 
 class SortSpec(BaseModel):
-    column: str = "attention"
+    column: str = "state"
     descending: bool = True
 
 
@@ -176,15 +176,23 @@ async def dashboard_rows(
         for row in rows:
             if row.tracked.state == "DONE":
                 continue
-            if view == "triage" and row.tracked.state != "FINDINGS_TRIAGE":
+            if (
+                not row.tracked.explicit_review
+                and view == "triage"
+                and row.tracked.state != "FINDINGS_TRIAGE"
+            ):
                 continue
-            if view == "posted" and row.tracked.state != "PENDING_AUTHOR_CHANGES":
+            if (
+                not row.tracked.explicit_review
+                and view == "posted"
+                and row.tracked.state != "PENDING_AUTHOR_CHANGES"
+            ):
                 continue
             pr = row.tracked.pull_request
             searchable = (
                 f"{pr.ref.namespace}/{pr.ref.repository}#{pr.ref.number} {pr.title} {pr.author}"
             )
-            if text.lower() not in searchable.lower():
+            if not row.tracked.explicit_review and text.lower() not in searchable.lower():
                 continue
             run = await store.latest_run(row.tracked.task_id) if row.tracked.task_id else None
             analysis = await reviews.get_result(run.id) if run else None
@@ -266,6 +274,12 @@ async def state_configured(
         return row.tracked.pull_request.url
 
 
+async def url_configured(path: Path | None, value: str, login: str | None) -> str:
+    """Resolve a tracked PR's URL without changing its state."""
+    async with local_store(path) as (queue, _):
+        return (await resolve_local(queue, value, login)).tracked.pull_request.url
+
+
 async def refresh_configured(path: Path | None, value: str, login: str | None) -> PullRequestRow:
     """Refresh one PR, preserving a durable pending indication on any failure."""
     async with local_store(path) as (queue, settings):

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/core/managed.py

@@ -296,6 +296,9 @@ class ManagedReviews:
             findings_threshold=self.settings.review.findings_threshold,
         )
         try:
+            # Record explicit intent before maintenance can wait on another PR's I/O.
+            # Cancellation while waiting must also cancel this durable queued run.
+            await self.cleanup()
             while True:
                 preferences = await SQLiteDashboardStore(self.store.database).preferences()
                 result = await worker.execute_requested(
@@ -313,6 +316,12 @@ class ManagedReviews:
         except asyncio.CancelledError:
             await self.reviews.cancel_review(run.id)
             raise
+        except Exception:
+            # A maintenance failure before claiming must not leave an orphaned
+            # queued attempt after its supervisor has reported failure.
+            if (await self.reviews.get_run(run.id)).status == "queued":
+                await self.reviews.cancel_review(run.id)
+            raise
 
     async def findings(self, row: PullRequestRow) -> ReviewResult | None:
         if row.tracked.task_id is None:
@@ -363,7 +372,7 @@ async def review_configured(
             load_settings, path, repo=f"{ref.namespace}/{ref.repository}"
         )
         managed = ManagedReviews(queue.database, settings, await owned_directories(settings))
-        await managed.cleanup()
+        await managed.recovery.recover_rebooted()
         return await managed.review(row, reviewer, progress)
 
 
@@ -414,7 +423,7 @@ async def handoff_configured(
     async with local_store(path) as (queue, settings):
         row = await resolve_local(queue, value, login)
         managed = ManagedReviews(queue.database, settings, await owned_directories(settings))
-        await managed.cleanup()
+        await managed.recovery.recover_rebooted()
         launch = await managed.prepare_handoff(row)
         exited = True
         try:

{diffbutler-0.5.3 → diffbutler-0.6.1}/src/diffbutler/core/polling.py

@@ -78,17 +78,15 @@ class Poller:
                     if previous != (budget.interval, budget.wait_for_reset):
                         logging.getLogger(__name__).info(
                             "Polling adjusted host=%s login=%s resource=%s interval_s=%.1f "
-                            "remaining=%d limit=%d reset_in_s=%.1f cost=%.1f "
-                            "external_calls_per_s=%.3f wait_for_reset=%s",
+                            "remaining=%d limit=%d reset_in_s=%.1f cost=%.1f wait_for_reset=%s",
                             sample.host,
-                            sample.login,
+                            sample.login or "(anonymous)",
                             sample.quota.resource,
                             budget.interval,
                             sample.quota.remaining,
                             sample.quota.limit,
                             sample.quota.reset_at.timestamp() - self.now(),
                             budget.cost,
-                            budget.external_rate,
                             budget.wait_for_reset,
                         )
                 self.changed.set()

diffbutler-0.6.1/src/diffbutler/core/pr_lookup.py

@@ -0,0 +1,83 @@
+"""Read-only resolution of explicit review targets across repository scopes."""
+
+import asyncio
+import math
+from dataclasses import dataclass
+
+from diffbutler.domain.forge import Account, PRRef, PullRequest, repository_matches
+from diffbutler.forges.base import ForgeError, ReadForge
+
+
+@dataclass(frozen=True)
+class ReviewTarget:
+    forge_index: int
+    account: Account
+    pull_request: PullRequest
+
+
+async def open_pr(forge: ReadForge, ref: PRRef, *, listed: bool = False) -> PullRequest | None:
+    """Open PR at ref, or None when it is missing or, for listed repositories, unreadable."""
+    try:
+        pr = await forge.get_pull_request(ref)
+    except ForgeError as exc:
+        # A listed repository can deny PR reads (disabled, blocked, or metadata-only
+        # access); rate limits carry retry_after and still fail the lookup.
+        if exc.status == 404 or (listed and exc.status in {403, 451} and exc.retry_after is None):
+            return None
+        raise
+    if pr.ref != ref:
+        raise ForgeError("Forge returned a different PR identity")
+    return pr if pr.state == "open" else None
+
+
+# Reads kept in reserve after a scan: the account check, then following the chosen
+# PR (account checks, the PR, and its first activity pages) on a fresh client.
+FOLLOW_UP_READS = 10
+
+
+def check_budget(forge: ReadForge, number: int, reads: int, deadline: float | None) -> None:
+    """Fail before reads that would reach low-quota pacing or outlast the deadline."""
+    budget = forge.read_budget()
+    if budget.requests is not None and reads + FOLLOW_UP_READS > budget.requests:
+        raise ForgeError(
+            f"Checking PR #{number} in {reads} more repositories needs more requests "
+            f"than the forge's rate limit can spare ({budget.requests}); "
+            "enter the full PR link or retry after the limit resets"
+        )
+    if deadline is not None:
+        needed = (reads + FOLLOW_UP_READS) * budget.seconds_per_request
+        if needed > deadline - asyncio.get_running_loop().time():
+            raise ForgeError(
+                f"Checking PR #{number} in {reads} more repositories and following it "
+                f"would take about {math.ceil(needed)} seconds, longer than the lookup "
+                "allows; enter the full PR link"
+            )
+
+
+async def numbered_prs(
+    forge: ReadForge, repositories: list[str], number: int, *, deadline: float | None = None
+) -> tuple[PullRequest, ...]:
+    """Resolve exact numbers directly after expanding owner repository scopes.
+
+    deadline is an event-loop time. When owner scopes were listed, each read first
+    checks that the remaining reads fit the forge's spare quota and the deadline.
+    """
+    refs: dict[PRRef, bool] = {}
+    for repository in dict.fromkeys(repositories):
+        if not repository.endswith("/*"):
+            refs[forge.ref(f"{repository}#{number}")] = False
+            continue
+        for name in await forge.list_repositories(repository.removesuffix("/*")):
+            ref = forge.ref(f"{name}#{number}")
+            if ref.forge != forge.id or not repository_matches(repository, ref):
+                raise ForgeError("Forge returned a repository outside the requested owner")
+            refs.setdefault(ref, True)
+    budgeted = any(refs.values())
+    found: list[PullRequest] = []
+    for index, (ref, listed) in enumerate(refs.items()):
+        if budgeted:
+            # Rechecking before every read also covers retries that used extra quota.
+            check_budget(forge, number, len(refs) - index, deadline)
+        if pr := await open_pr(forge, ref, listed=listed):
+            found.append(pr)
+    return tuple(found)