flurdy/agent-skills / skills/pr-status
pr-status
VerifiedShow enriched status of your open PRs — CI checks, approvals, unresolved review threads, and linked Jira discussion, with transition-driven suggested next actions.
scripts/gh-pr-review-requests.py
View on GitHub#!/usr/bin/env python3
"""Collect and reduce a bounded, read-only GitHub review-request queue.
The returned state is intended for session/watch-local retention. This command never
writes state, marks notifications, submits reviews, or changes GitHub review requests.
"""
from __future__ import annotations
import argparse
import copy
import json
import os
import re
import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path
from time import monotonic
from typing import Any
SCHEMA_VERSION = 2
DEFAULT_TIMEOUT_SECONDS = 60.0
DEFAULT_MAX_OUTPUT_BYTES = 4_000_000
TRIAGE_FIELDS = (
"title", "createdAt", "additions", "deletions", "changedFiles",
"jiraKeys", "otherReviewers", "ci",
)
JIRA_KEY = re.compile(r"(?<![A-Z0-9])[A-Z][A-Z0-9]+-\d+\b")
DASHBOARD_FIELDS = (
"updatedAt", "checksState", "ciHeadSha", "mergeState",
"reviewDecision", "otherReviews",
)
STATUS_FIELDS = ("checksState", "mergeState", "reviewDecision", "otherReviews", "priorReview")
@dataclass(frozen=True)
class QueueLimits:
page_size: int = 50
max_candidates: int = 100
max_state_entries: int = 200
max_history: int = 200
max_prs_per_query: int = 20
def normalized(self) -> QueueLimits:
return QueueLimits(
page_size=max(1, min(100, self.page_size)),
max_candidates=max(1, self.max_candidates),
max_state_entries=max(1, self.max_state_entries),
max_history=max(1, self.max_history),
max_prs_per_query=max(1, min(50, self.max_prs_per_query)),
)
def as_dict(self) -> dict[str, int]:
return {
"pageSize": self.page_size,
"maxCandidates": self.max_candidates,
"maxStateEntries": self.max_state_entries,
"maxHistoryPerPullRequest": self.max_history,
"maxPullRequestsPerQuery": self.max_prs_per_query,
}
class CollectionError(RuntimeError):
pass
def empty_state(viewer_login: str) -> dict[str, Any]:
return {
"schemaVersion": SCHEMA_VERSION,
"viewerLogin": viewer_login,
"sequence": 0,
"entries": [],
}
def entry_key(repository: str, number: int) -> str:
return f"{repository}#{number}"
def work_key(node_id: str, request_event_id: str, head_sha: str) -> str:
return f"{node_id}|{request_event_id}|{head_sha}"
def validate_state(state: dict[str, Any], viewer_login: str) -> None:
if state.get("schemaVersion") != SCHEMA_VERSION:
raise ValueError("unsupported review-request state schema")
if str(state.get("viewerLogin", "")).casefold() != viewer_login.casefold():
raise ValueError("review-request state belongs to a different GitHub user")
if not isinstance(state.get("entries"), list):
raise ValueError("review-request state entries must be a list")
def latest(items: list[dict[str, Any]], timestamp: str) -> dict[str, Any] | None:
usable = [item for item in items if isinstance(item.get(timestamp), str)]
if not usable:
return None
return max(usable, key=lambda item: (item[timestamp], str(item.get("id", ""))))
def matching_request_events(
snapshot: dict[str, Any], source: str, viewer_login: str, reviewers: set[str]
) -> list[dict[str, Any]]:
matches = []
for event in snapshot.get("requestEvents", []):
if not isinstance(event, dict) or event.get("sourceKind") != source:
continue
reviewer = str(event.get("reviewer", ""))
if source == "direct" and reviewer.casefold() != viewer_login.casefold():
continue
if source == "team" and reviewer not in reviewers:
continue
matches.append(event)
return matches
def current_request_source(
snapshot: dict[str, Any], viewer_login: str
) -> tuple[str | None, set[str], set[str]]:
direct = set()
teams = set()
for request in snapshot.get("currentRequests", []):
if not isinstance(request, dict):
continue
kind = request.get("sourceKind")
reviewer = str(request.get("reviewer", ""))
if kind == "direct" and reviewer.casefold() == viewer_login.casefold():
direct.add(reviewer)
elif kind == "team" and reviewer:
teams.add(reviewer)
if direct:
return "direct", direct, teams
if teams:
return "team", teams, teams
return None, set(), set()
def current_team_events(
snapshot: dict[str, Any], reviewers: set[str]
) -> dict[str, dict[str, Any]]:
events = {}
for reviewer in reviewers:
event = latest(
[
item
for item in snapshot.get("requestEvents", [])
if isinstance(item, dict)
and item.get("sourceKind") == "team"
and item.get("reviewer") == reviewer
],
"createdAt",
)
if event:
events[reviewer] = {
"id": event.get("id"),
"createdAt": event.get("createdAt"),
"requester": event.get("requester"),
}
return events
def new_team_events(
current: dict[str, dict[str, Any]], previous: dict[str, Any] | None
) -> list[tuple[str, dict[str, Any]]]:
previous_events = previous.get("teamRequestEvents", {}) if previous else {}
force_current = previous is None or not previous.get("currentRequested")
changed = []
for reviewer, event in sorted(current.items()):
prior = previous_events.get(reviewer)
event_is_newer = prior and (
event.get("id") != prior.get("id")
and str(event.get("createdAt") or "")
> str(prior.get("createdAt") or "")
)
if force_current or prior is None or event_is_newer:
changed.append((reviewer, event))
return changed
def latest_viewer_review(snapshot: dict[str, Any]) -> dict[str, Any] | None:
return latest(
[
review
for review in snapshot.get("viewerReviews", [])
if isinstance(review, dict) and review.get("submittedAt")
],
"submittedAt",
)
def item_from_entry(
entry: dict[str, Any],
transition: str,
*,
actionable: bool,
explicit_rerequest: bool,
) -> dict[str, Any]:
request_event = None
if entry.get("requestEventId"):
request_event = {
"id": entry["requestEventId"],
"createdAt": entry.get("requestEventAt"),
"requester": entry.get("requester"),
}
return {
"key": entry["key"],
"repository": entry["repository"],
"number": entry["number"],
"nodeId": entry.get("nodeId"),
"url": entry.get("url"),
"author": entry.get("author"),
"state": entry.get("state"),
"isDraft": entry.get("isDraft"),
"headSha": entry.get("headSha"),
"requestSource": entry.get("requestSource"),
"requestReviewers": entry.get("requestReviewers", []),
"teamRequests": entry.get("teamRequests", []),
"requestEvent": request_event,
"requestHistoryCount": entry.get("requestHistoryCount", 0),
"reRequestCount": entry.get("reRequestCount", 0),
"explicitReRequest": explicit_rerequest
or bool(entry.get("explicitReRequest", False)),
"priorReview": entry.get("priorReview"),
**{field: entry.get(field) for field in DASHBOARD_FIELDS},
"workKey": entry.get("workKey"),
"transition": transition,
"actionable": actionable,
**{field: entry.get(field) for field in TRIAGE_FIELDS},
}
def team_transition_item(
entry: dict[str, Any], reviewer: str, event: dict[str, Any]
) -> dict[str, Any]:
team_entry = copy.deepcopy(entry)
team_entry.update(
{
"requestSource": "team",
"requestReviewers": [reviewer],
"requestEventId": event.get("id"),
"requestEventAt": event.get("createdAt"),
"requester": event.get("requester"),
"workKey": None,
}
)
return item_from_entry(
team_entry,
"team_requested",
actionable=False,
explicit_rerequest=False,
)
def terminal_transition(snapshot: dict[str, Any]) -> str | None:
if snapshot.get("merged") is True or snapshot.get("state") == "MERGED":
return "merged"
if snapshot.get("state") == "CLOSED":
return "closed"
return None
def ended_request_transition(
previous: dict[str, Any], review: dict[str, Any] | None
) -> str:
previous_review = previous.get("priorReview") or {}
review_is_new = review and review.get("id") != previous_review.get("id")
if (
previous.get("requestSource") == "direct"
and review_is_new
and previous.get("requestEventAt")
and review.get("submittedAt", "") > previous["requestEventAt"]
):
return "review_submitted"
return "request_removed"
def prune_entries(
entries: list[dict[str, Any]], limit: int, protected_keys: set[str]
) -> tuple[list[dict[str, Any]], set[str]]:
if len(entries) <= limit:
return entries, set()
candidates = sorted(
(entry for entry in entries if entry["key"] not in protected_keys),
key=lambda entry: (
0 if not entry.get("tracking", False) else 1,
int(entry.get("observation", 0)),
entry["key"],
),
)
remove_count = len(entries) - limit
if len(candidates) < remove_count:
raise ValueError("active review-request state exceeds its bounded capacity")
removed_keys = {entry["key"] for entry in candidates[:remove_count]}
return [entry for entry in entries if entry["key"] not in removed_keys], removed_keys
def reduce_queue(
previous_state: dict[str, Any],
snapshots: list[dict[str, Any]],
*,
viewer_login: str,
mode: str = "normal",
failed_repositories: set[str] | None = None,
state_limit: int = 200,
) -> dict[str, Any]:
if mode not in {"normal", "reset", "recheck"}:
raise ValueError(f"unsupported queue mode: {mode}")
validate_state(previous_state, viewer_login)
if len(previous_state["entries"]) > max(1, state_limit):
raise ValueError("review-request state exceeds its bounded capacity")
state = empty_state(viewer_login) if mode == "reset" else copy.deepcopy(previous_state)
previous_entries = {entry["key"]: entry for entry in state["entries"]}
next_entries = copy.deepcopy(previous_entries)
failed = failed_repositories or set()
transitions = []
queue = []
errors = []
sequence = int(state.get("sequence", 0))
observed_entries = {}
for snapshot in sorted(
snapshots, key=lambda item: (item["repository"].casefold(), item["number"])
):
repository = snapshot["repository"]
if repository in failed:
continue
key = entry_key(repository, int(snapshot["number"]))
previous = previous_entries.get(key)
terminal = terminal_transition(snapshot)
if snapshot.get("historyComplete") is not True:
errors.append(
{
"source": "history",
"repository": repository,
"number": snapshot["number"],
"kind": "truncated",
"message": "review-request history was incomplete",
}
)
if terminal is None:
if previous and snapshot.get("isDraft") and snapshot.get("nodeId") == previous.get("nodeId"):
observed = next_entries[key]
observed["isDraft"] = True
observed.pop("triagedWorkKey", None)
if not previous.get("isDraft"):
transitions.append(item_from_entry(
observed, "draft", actionable=False, explicit_rerequest=False
))
continue
sequence += 1
source, reviewers, team_reviewers = current_request_source(
snapshot, viewer_login
)
if terminal:
source, reviewers, team_reviewers = None, set(), set()
team_events = current_team_events(snapshot, team_reviewers)
missing_team_events = team_reviewers - set(team_events)
if missing_team_events:
errors.append(
{
"source": "history",
"repository": repository,
"number": snapshot["number"],
"kind": "missing",
"message": "one or more team requests had no bounded request event",
}
)
request_events = (
matching_request_events(snapshot, source, viewer_login, reviewers)
if source
else []
)
request_event = latest(request_events, "createdAt")
missing_identity = source is not None and (
not snapshot.get("nodeId")
or not snapshot.get("headSha")
or request_event is None
or not request_event.get("id")
)
if source and (request_event is None or missing_identity):
errors.append(
{
"source": "history",
"repository": repository,
"number": snapshot["number"],
"kind": "missing",
"message": "current review request had no complete bounded identity",
}
)
continue
viewer_request_events = matching_request_events(
snapshot, "direct", viewer_login, {viewer_login}
)
review = latest_viewer_review(snapshot)
event_id = request_event.get("id") if request_event else None
event_at = request_event.get("createdAt") if request_event else None
current_work_key = (
work_key(str(snapshot["nodeId"]), str(event_id), str(snapshot["headSha"]))
if source == "direct" and event_id
else None
)
retained_source = source or (previous.get("requestSource") if previous else None)
retained_event_id = event_id or (
previous.get("requestEventId") if previous else None
)
retained_event_at = event_at or (
previous.get("requestEventAt") if previous else None
)
retained_work_key = (
current_work_key
if source is not None
else previous.get("workKey")
if previous
else None
)
entry = {
"key": key,
"repository": repository,
"number": int(snapshot["number"]),
"nodeId": snapshot.get("nodeId"),
"url": snapshot.get("url"),
"author": snapshot.get("author"),
"state": snapshot.get("state"),
"isDraft": bool(snapshot.get("isDraft")),
"headSha": snapshot.get("headSha"),
"requestSource": retained_source,
"requestReviewers": sorted(reviewers)
if source
else previous.get("requestReviewers", [])
if previous
else [],
"teamRequests": sorted(team_reviewers)
if source
else previous.get("teamRequests", [])
if previous
else [],
"teamRequestEvents": team_events
if source
else previous.get("teamRequestEvents", {})
if previous
else {},
"requestEventId": retained_event_id,
"requestEventAt": retained_event_at,
"requester": request_event.get("requester")
if request_event
else previous.get("requester")
if previous
else None,
"requestHistoryCount": max(
len(viewer_request_events),
int(previous.get("requestHistoryCount", 0)) if previous else 0,
),
"reRequestCount": max(
max(0, len(viewer_request_events) - 1),
int(previous.get("reRequestCount", 0)) if previous else 0,
),
"explicitReRequest": len(viewer_request_events) > 1
if source == "direct"
else bool(previous.get("explicitReRequest", False))
if previous
else False,
"priorReview": review or (previous.get("priorReview") if previous else None),
**{field: snapshot.get(field) for field in DASHBOARD_FIELDS},
"workKey": retained_work_key,
"currentRequested": source is not None,
"tracking": source is not None and terminal is None,
"observation": sequence,
**{field: snapshot.get(field) for field in TRIAGE_FIELDS},
}
if previous and previous.get("triagedWorkKey") and not entry["isDraft"]:
entry["triagedWorkKey"] = previous["triagedWorkKey"]
transition = None
transition_entry = entry
extra_transitions = [
team_transition_item(entry, reviewer, event)
for reviewer, event in new_team_events(team_events, previous)
]
explicit_rerequest = False
if terminal:
if previous is None or previous.get("tracking", False):
transition = terminal
entry["tracking"] = False
entry["currentRequested"] = False
elif source is None:
if previous and previous.get("currentRequested"):
transition = ended_request_transition(previous, review)
entry["tracking"] = False
elif source == "team":
if (
previous
and previous.get("requestSource") == "direct"
and previous.get("currentRequested")
):
transition = ended_request_transition(previous, review)
transition_entry = copy.deepcopy(previous)
transition_entry.update(
{
"state": entry["state"],
"isDraft": entry["isDraft"],
"headSha": entry["headSha"],
"teamRequests": entry["teamRequests"],
"teamRequestEvents": entry["teamRequestEvents"],
"priorReview": review or previous.get("priorReview"),
"currentRequested": False,
"tracking": False,
**{field: snapshot.get(field) for field in TRIAGE_FIELDS},
}
)
else:
history_rerequest = len(viewer_request_events) > 1
if mode == "recheck":
transition = "recheck"
elif previous is None:
transition = "re_requested" if history_rerequest else "newly_requested"
explicit_rerequest = history_rerequest
elif previous.get("requestSource") != "direct":
transition = "re_requested" if history_rerequest else "newly_requested"
explicit_rerequest = history_rerequest
entry["explicitReRequest"] = history_rerequest
elif previous.get("requestEventId") != event_id:
transition = "re_requested"
explicit_rerequest = True
entry["explicitReRequest"] = True
elif previous.get("isDraft") and not entry["isDraft"]:
transition = "ready"
elif not previous.get("isDraft") and entry["isDraft"]:
transition = "draft"
elif previous.get("headSha") != entry["headSha"]:
transition = "head_changed"
actionable = (
source == "direct"
and entry["state"] == "OPEN"
and terminal is None
and not entry["isDraft"]
and (mode == "recheck" or entry.get("triagedWorkKey") != current_work_key)
)
changed_fields = [
field for field in STATUS_FIELDS
if previous is not None and previous.get(field) != entry.get(field)
]
if transition is None and source is not None and changed_fields:
transition = "status_changed"
if transition:
item = item_from_entry(
transition_entry,
transition,
actionable=actionable if transition_entry is entry else False,
explicit_rerequest=explicit_rerequest,
)
item["changedFields"] = changed_fields
transitions.append(item)
transitions.extend(extra_transitions)
if actionable:
queue.append(
item_from_entry(
entry,
transition or "pending",
actionable=True,
explicit_rerequest=explicit_rerequest,
)
)
next_entries[key] = {field: value for field, value in entry.items() if field not in TRIAGE_FIELDS}
observed_entries[key] = entry
protected_keys = {
key
for key in previous_entries
if next_entries.get(key, {}).get("tracking", False)
}
entries, pruned_keys = prune_entries(
list(next_entries.values()), max(1, state_limit), protected_keys
)
if pruned_keys:
dropped_active_keys = {
key for key in pruned_keys if next_entries[key].get("tracking", False)
}
transitions = [
item for item in transitions if item["key"] not in dropped_active_keys
]
queue = [item for item in queue if item["key"] not in dropped_active_keys]
if dropped_active_keys:
errors.append(
{
"source": "state",
"kind": "state-capacity",
"message": "new review requests exceeded bounded session-state capacity",
}
)
result_state = {
"schemaVersion": SCHEMA_VERSION,
"viewerLogin": viewer_login,
"sequence": sequence,
"entries": sorted(entries, key=lambda entry: entry["key"].casefold()),
}
return {
"schemaVersion": SCHEMA_VERSION,
"status": "partial" if errors or failed else "complete",
"mode": mode,
"queue": queue,
"requests": dashboard_requests(entries, observed_entries),
"transitions": transitions,
"errors": errors,
"failedRepositories": sorted(failed),
"state": result_state,
}
def dashboard_requests(
entries: list[dict[str, Any]], observed_entries: dict[str, dict[str, Any]]
) -> list[dict[str, Any]]:
requests = []
for retained in entries:
entry = observed_entries.get(retained["key"], retained)
if not entry.get("currentRequested") or not entry.get("tracking"):
continue
available = entry["key"] in observed_entries
item = item_from_entry(
entry, "current", actionable=(
available and entry.get("requestSource") == "direct"
and not entry.get("isDraft") and entry.get("state") == "OPEN"
), explicit_rerequest=False,
)
item["available"] = available
requests.append(item)
return sorted(requests, key=lambda item: (
(item.get("requestEvent") or {}).get("createdAt") or "~",
item["repository"].casefold(), item["number"],
))
def mark_triaged(state: dict[str, Any], displayed_work_keys: list[str]) -> dict[str, Any]:
validate_state(state, str(state.get("viewerLogin", "")))
updated = copy.deepcopy(state)
entries = {entry.get("workKey"): entry for entry in updated["entries"]}
for key in displayed_work_keys:
entry = entries.get(key)
if entry is None:
raise ValueError("work key is not present in review-request state")
if (
entry.get("requestSource") != "direct"
or not entry.get("currentRequested")
or not entry.get("tracking")
or entry.get("state") != "OPEN"
or entry.get("isDraft")
):
raise ValueError("work key is not a current open non-draft direct request")
entry["triagedWorkKey"] = key
return updated
class GhClient:
def __init__(
self,
*,
timeout: float = DEFAULT_TIMEOUT_SECONDS,
max_output_bytes: int = DEFAULT_MAX_OUTPUT_BYTES,
) -> None:
self.deadline = monotonic() + max(0.1, timeout)
self.max_output_bytes = max(1_000, max_output_bytes)
self._viewer_login: str | None = None
def _run(self, arguments: list[str]) -> Any:
remaining = self.deadline - monotonic()
if remaining <= 0:
raise CollectionError("GitHub collection deadline exceeded")
environment = os.environ.copy()
environment.update({"GH_PAGER": "cat", "PAGER": "cat", "NO_COLOR": "1"})
try:
completed = subprocess.run(
["gh", "api", *arguments],
check=False,
capture_output=True,
text=True,
timeout=remaining,
env=environment,
)
except subprocess.TimeoutExpired as error:
raise CollectionError("GitHub collection deadline exceeded") from error
output_bytes = len(completed.stdout.encode()) + len(completed.stderr.encode())
if output_bytes > self.max_output_bytes:
raise CollectionError("GitHub response exceeded the output limit")
if completed.returncode != 0:
message = completed.stderr.strip() or completed.stdout.strip() or "gh api failed"
raise CollectionError(message[:500])
try:
return json.loads(completed.stdout)
except json.JSONDecodeError as error:
raise CollectionError(f"gh api returned invalid JSON: {error}") from error
def viewer_login(self) -> str:
response = self._run(["user"])
login = response.get("login") if isinstance(response, dict) else None
if not isinstance(login, str) or not login:
raise CollectionError("GitHub viewer login was unavailable")
self._viewer_login = login
return login
def search_page(
self, viewer: str, repository: str, after: str | None, first: int
) -> dict[str, Any]:
query = """
query($searchQuery: String!, $first: Int!, $after: String) {
search(type: ISSUE, query: $searchQuery, first: $first, after: $after) {
nodes {
... on PullRequest {
number
repository { nameWithOwner }
}
}
pageInfo { hasNextPage endCursor }
}
}
"""
arguments = [
"graphql",
"-f",
f"query={query}",
"-f",
f"searchQuery=review-requested:{viewer} repo:{repository} is:pr is:open archived:false",
"-F",
f"first={first}",
]
if after:
arguments.extend(["-f", f"after={after}"])
response = self._run(arguments)
if isinstance(response, dict) and response.get("errors"):
raise CollectionError(graphql_error_message(response["errors"]))
try:
connection = response["data"]["search"]
except (KeyError, TypeError) as error:
raise CollectionError("GitHub search response was incomplete") from error
nodes = []
for node in connection.get("nodes") or []:
try:
nodes.append(
{
"repository": node["repository"]["nameWithOwner"],
"number": int(node["number"]),
}
)
except (KeyError, TypeError, ValueError) as error:
raise CollectionError("GitHub search returned an invalid pull request") from error
return {"nodes": nodes, "pageInfo": connection.get("pageInfo") or {}}
def fetch_repository(
self,
repository: str,
numbers: list[int],
*,
page_size: int,
max_history: int,
max_prs_per_query: int,
) -> list[dict[str, Any]]:
owner, repo = split_repository(repository)
snapshots = []
connection_page_size = min(page_size, max_history)
for start in range(0, len(numbers), max_prs_per_query):
batch = numbers[start : start + max_prs_per_query]
response = self._fetch_initial_batch(
owner, repo, batch, connection_page_size
)
for index, number in enumerate(batch):
pull_request = response.get(f"pr{index}")
if not isinstance(pull_request, dict):
raise CollectionError(f"{repository}#{number} was unavailable")
complete = True
for connection_name in ("reviewRequests", "timelineItems"):
connection = pull_request.get(connection_name)
if not isinstance(connection, dict):
raise CollectionError(
f"{repository}#{number} {connection_name} was unavailable"
)
nodes, connection_complete = self._complete_connection(
owner,
repo,
number,
connection_name,
connection,
connection_page_size,
max_history,
)
pull_request[connection_name] = {"nodes": nodes}
complete = complete and connection_complete
if self._viewer_login is None:
raise CollectionError("GitHub viewer login was not resolved")
snapshots.append(
normalize_pull_request(
repository,
pull_request,
complete,
self._viewer_login,
)
)
return snapshots
def _fetch_initial_batch(
self, owner: str, repo: str, numbers: list[int], page_size: int
) -> dict[str, Any]:
aliases = []
for index, number in enumerate(numbers):
aliases.append(
f"pr{index}: pullRequest(number: {number}) {{ {PULL_REQUEST_FIELDS} }}"
)
query = f"""
query($owner: String!, $repo: String!, $pageSize: Int!) {{
repository(owner: $owner, name: $repo) {{
{''.join(aliases)}
}}
}}
"""
response = self._run(
[
"graphql",
"-f",
f"query={query}",
"-f",
f"owner={owner}",
"-f",
f"repo={repo}",
"-F",
f"pageSize={page_size}",
]
)
if isinstance(response, dict) and response.get("errors"):
raise CollectionError(graphql_error_message(response["errors"]))
try:
repository = response["data"]["repository"]
except (KeyError, TypeError) as error:
raise CollectionError(f"{owner}/{repo} response was incomplete") from error
if not isinstance(repository, dict):
raise CollectionError(f"{owner}/{repo} was unavailable")
return repository
def _complete_connection(
self,
owner: str,
repo: str,
number: int,
connection_name: str,
initial: dict[str, Any],
page_size: int,
maximum: int,
) -> tuple[list[dict[str, Any]], bool]:
nodes = [node for node in initial.get("nodes") or [] if isinstance(node, dict)]
initial_overflow = len(nodes) > maximum
page_info = initial.get("pageInfo") or {}
while page_info.get("hasNextPage") and len(nodes) < maximum:
cursor = page_info.get("endCursor")
if not isinstance(cursor, str) or not cursor:
return nodes[:maximum], False
page = self._fetch_connection_page(
owner,
repo,
number,
connection_name,
cursor,
min(page_size, maximum - len(nodes)),
)
nodes.extend(
node for node in page.get("nodes") or [] if isinstance(node, dict)
)
page_info = page.get("pageInfo") or {}
return (
nodes[:maximum],
not initial_overflow and not bool(page_info.get("hasNextPage")),
)
def _fetch_connection_page(
self,
owner: str,
repo: str,
number: int,
connection_name: str,
after: str,
page_size: int,
) -> dict[str, Any]:
fields = CONNECTION_FIELDS[connection_name]
query = f"""
query($owner: String!, $repo: String!, $number: Int!, $pageSize: Int!, $after: String!) {{
repository(owner: $owner, name: $repo) {{
pullRequest(number: $number) {{
{connection_name}(first: $pageSize, after: $after){fields}
}}
}}
}}
"""
response = self._run(
[
"graphql",
"-f",
f"query={query}",
"-f",
f"owner={owner}",
"-f",
f"repo={repo}",
"-F",
f"number={number}",
"-F",
f"pageSize={page_size}",
"-f",
f"after={after}",
]
)
if isinstance(response, dict) and response.get("errors"):
raise CollectionError(graphql_error_message(response["errors"]))
try:
connection = response["data"]["repository"]["pullRequest"][connection_name]
except (KeyError, TypeError) as error:
raise CollectionError(
f"{owner}/{repo}#{number} {connection_name} page was incomplete"
) from error
if not isinstance(connection, dict):
raise CollectionError(
f"{owner}/{repo}#{number} {connection_name} page was invalid"
)
return connection
REVIEWER_FIELDS = """
{
__typename
... on User { id login }
... on Bot { id login }
... on Mannequin { id login }
... on Team { id name slug organization { login } }
... on EnterpriseTeam { id }
}
"""
REVIEW_REQUEST_FIELDS = f"""
{{
nodes {{ id requestedReviewer {REVIEWER_FIELDS} }}
pageInfo {{ hasNextPage endCursor }}
}}
"""
TIMELINE_FIELDS = f"""
{{
nodes {{
__typename
... on ReviewRequestedEvent {{
id createdAt actor {{ login }} requestedReviewer {REVIEWER_FIELDS}
}}
... on PullRequestReview {{
id submittedAt state author {{ login }} commit {{ oid }}
}}
}}
pageInfo {{ hasNextPage endCursor }}
}}
"""
CONNECTION_FIELDS = {
"reviewRequests": REVIEW_REQUEST_FIELDS,
"timelineItems": TIMELINE_FIELDS,
}
PULL_REQUEST_FIELDS = f"""
id
number
url
state
isDraft
merged
title
createdAt
additions
deletions
changedFiles
headRefName
headRefOid
updatedAt
mergeStateStatus
reviewDecision
commits(last: 1) {{ nodes {{ commit {{ oid statusCheckRollup {{ state }} }} }} }}
author {{ login }}
reviewRequests(first: $pageSize) {REVIEW_REQUEST_FIELDS}
timelineItems(
first: $pageSize
itemTypes: [
REVIEW_REQUESTED_EVENT
PULL_REQUEST_REVIEW
]
) {TIMELINE_FIELDS}
"""
def graphql_error_message(errors: Any) -> str:
if not isinstance(errors, list):
return "GitHub GraphQL request failed"
return "; ".join(
str(error.get("message", "GraphQL error"))
if isinstance(error, dict)
else str(error)
for error in errors
)[:500]
def split_repository(repository: str) -> tuple[str, str]:
parts = repository.split("/", 1)
if len(parts) != 2 or not all(parts):
raise CollectionError(f"invalid repository identity: {repository}")
return parts[0], parts[1]
def reviewer_identity(reviewer: Any) -> tuple[str, str] | None:
if not isinstance(reviewer, dict):
return None
typename = reviewer.get("__typename")
if typename == "User":
login = reviewer.get("login")
return ("direct", str(login)) if login else None
if typename == "Team":
organization = reviewer.get("organization") or {}
owner = organization.get("login")
slug = reviewer.get("slug") or reviewer.get("name")
if slug:
return "team", f"{owner}/{slug}" if owner else str(slug)
if typename == "EnterpriseTeam":
identifier = reviewer.get("id")
if identifier:
return "team", f"enterprise-team:{identifier}"
login = reviewer.get("login")
if login:
return "other", str(login)
return None
def exact_head_ci(pull_request: dict[str, Any]) -> dict[str, Any]:
unknown = {"headSha": None, "state": "UNKNOWN"}
commits = pull_request.get("commits")
nodes = commits.get("nodes") if isinstance(commits, dict) else None
if not isinstance(nodes, list) or len(nodes) != 1 or not isinstance(nodes[0], dict):
return unknown
commit = nodes[0].get("commit")
head = pull_request.get("headRefOid")
if not isinstance(commit, dict) or not head or commit.get("oid") != head:
return unknown
rollup = commit.get("statusCheckRollup")
state = rollup.get("state") if isinstance(rollup, dict) else None
if not isinstance(state, str) or state not in {"EXPECTED", "PENDING", "SUCCESS", "ERROR", "FAILURE"}:
return unknown
return {"headSha": head, "state": state}
def nonnegative_count(value: Any) -> int | None:
return value if type(value) is int and value >= 0 else None
def normalize_pull_request(
repository: str,
pull_request: dict[str, Any],
history_complete: bool,
viewer_login: str,
) -> dict[str, Any]:
current_requests = []
for request in pull_request.get("reviewRequests", {}).get("nodes", []):
identity = reviewer_identity(request.get("requestedReviewer"))
if identity:
current_requests.append(
{"sourceKind": identity[0], "reviewer": identity[1]}
)
request_events = []
viewer_reviews = []
other_reviews = []
timeline_nodes = pull_request.get("timelineItems", {}).get("nodes", [])
for event in timeline_nodes:
typename = event.get("__typename")
if typename == "ReviewRequestedEvent":
identity = reviewer_identity(event.get("requestedReviewer"))
if not identity:
continue
request_events.append(
{
"id": event.get("id"),
"createdAt": event.get("createdAt"),
"sourceKind": identity[0],
"reviewer": identity[1],
"requester": (event.get("actor") or {}).get("login"),
}
)
elif typename == "PullRequestReview" and event.get("submittedAt"):
author = (event.get("author") or {}).get("login")
if not isinstance(author, str):
continue
destination = (
viewer_reviews if author.casefold() == viewer_login.casefold()
else other_reviews
)
destination.append(
{
"id": event.get("id"),
"author": author,
"submittedAt": event.get("submittedAt"),
"state": event.get("state"),
"headSha": (event.get("commit") or {}).get("oid"),
}
)
ci = exact_head_ci(pull_request)
return {
"updatedAt": pull_request.get("updatedAt"),
"checksState": ci["state"] if ci["state"] != "UNKNOWN" else None,
"ciHeadSha": ci["headSha"],
"mergeState": pull_request.get("mergeStateStatus"),
"reviewDecision": pull_request.get("reviewDecision"),
"otherReviews": other_reviews if history_complete else None,
"repository": repository,
"number": int(pull_request["number"]),
"nodeId": pull_request.get("id"),
"url": pull_request.get("url"),
"author": (pull_request.get("author") or {}).get("login"),
"state": pull_request.get("state"),
"isDraft": bool(pull_request.get("isDraft")),
"merged": bool(pull_request.get("merged")),
"headSha": pull_request.get("headRefOid"),
"title": pull_request.get("title"),
"createdAt": pull_request.get("createdAt"),
"additions": nonnegative_count(pull_request.get("additions")),
"deletions": nonnegative_count(pull_request.get("deletions")),
"changedFiles": nonnegative_count(pull_request.get("changedFiles")),
"jiraKeys": list(dict.fromkeys(JIRA_KEY.findall(
f"{pull_request.get('title') or ''} {pull_request.get('headRefName') or ''}"
))),
"otherReviewers": [request for request in current_requests
if request["sourceKind"] != "direct"
or request["reviewer"].casefold() != viewer_login.casefold()],
"ci": ci,
"currentRequests": current_requests,
"requestEvents": request_events,
"viewerReviews": viewer_reviews,
"historyComplete": history_complete,
}
def tracked_targets(state: dict[str, Any]) -> dict[str, set[int]]:
targets: dict[str, set[int]] = {}
for entry in state.get("entries", []):
if entry.get("tracking"):
targets.setdefault(entry["repository"], set()).add(int(entry["number"]))
return targets
def state_for_scope(
state: dict[str, Any] | None, repositories: list[str]
) -> dict[str, Any] | None:
if state is None or not isinstance(state.get("entries"), list):
return state
scope = {repository.casefold() for repository in repositories}
scoped = copy.deepcopy(state)
scoped["entries"] = [
entry
for entry in state["entries"]
if isinstance(entry, dict)
and str(entry.get("repository", "")).casefold() in scope
]
return scoped
def collect_queue(
client: Any,
*,
repositories: set[str],
previous_state: dict[str, Any] | None = None,
mode: str = "normal",
limits: QueueLimits | None = None,
) -> dict[str, Any]:
limits = (limits or QueueLimits()).normalized()
scope = sorted(
{repository for repository in repositories if repository},
key=str.casefold,
)
if not scope:
return {
"schemaVersion": SCHEMA_VERSION,
"status": "failed",
"mode": mode,
"viewerLogin": None,
"queue": [],
"transitions": [],
"errors": [
{
"source": "scope",
"kind": "unavailable",
"message": "no current or registered workspace GitHub repositories were resolved",
}
],
"failedRepositories": [],
"limits": limits.as_dict(),
"scope": {"kind": "current-workspace", "repositories": []},
"state": previous_state or empty_state(""),
}
scoped_previous = state_for_scope(previous_state, scope)
try:
viewer_login = client.viewer_login()
except (CollectionError, RuntimeError) as error:
state = scoped_previous or empty_state("")
return {
"schemaVersion": SCHEMA_VERSION,
"status": "failed",
"mode": mode,
"viewerLogin": None,
"queue": [],
"transitions": [],
"errors": [
{"source": "viewer", "kind": "unavailable", "message": str(error)}
],
"failedRepositories": [],
"limits": limits.as_dict(),
"scope": {"kind": "current-workspace", "repositories": scope},
"state": state,
}
prior = scoped_previous or empty_state(viewer_login)
try:
validate_state(prior, viewer_login)
if len(prior["entries"]) > limits.max_state_entries:
raise ValueError("review-request state exceeds its bounded capacity")
except ValueError as error:
return {
"schemaVersion": SCHEMA_VERSION,
"status": "failed",
"mode": mode,
"viewerLogin": viewer_login,
"queue": [],
"transitions": [],
"errors": [
{"source": "state", "kind": "invalid", "message": str(error)}
],
"failedRepositories": [],
"limits": limits.as_dict(),
"scope": {"kind": "current-workspace", "repositories": scope},
"state": prior,
}
collection_state = empty_state(viewer_login) if mode == "reset" else prior
targets = tracked_targets(collection_state)
errors = []
candidate_count = 0
search_failed = False
search_truncated = False
for repository_index, scoped_repository in enumerate(scope):
after = None
page_info: dict[str, Any] = {}
while candidate_count < limits.max_candidates:
first = min(limits.page_size, limits.max_candidates - candidate_count)
try:
page = client.search_page(
viewer_login, scoped_repository, after, first
)
except (CollectionError, RuntimeError) as error:
errors.append(
{
"source": "search",
"repository": scoped_repository,
"kind": "unavailable",
"message": str(error),
}
)
search_failed = True
break
nodes = page.get("nodes")
page_info = page.get("pageInfo")
if not isinstance(nodes, list) or not isinstance(page_info, dict):
errors.append(
{
"source": "search",
"repository": scoped_repository,
"kind": "invalid",
"message": "GitHub search page was malformed",
}
)
search_failed = True
break
for node in nodes:
try:
repository = str(node["repository"])
number = int(node["number"])
if repository.casefold() != scoped_repository.casefold():
raise ValueError("search result was outside repository scope")
except (KeyError, TypeError, ValueError) as error:
errors.append(
{
"source": "search",
"repository": scoped_repository,
"kind": "invalid",
"message": str(error) or "GitHub search item was malformed",
}
)
search_failed = True
continue
targets.setdefault(repository, set()).add(number)
candidate_count += len(nodes)
if not page_info.get("hasNextPage"):
break
after = page_info.get("endCursor")
if not isinstance(after, str) or not after:
errors.append(
{
"source": "search",
"repository": scoped_repository,
"kind": "invalid",
"message": "GitHub search pagination cursor was unavailable",
}
)
search_failed = True
break
if candidate_count >= limits.max_candidates:
search_truncated = (
bool(page_info.get("hasNextPage"))
or repository_index < len(scope) - 1
)
break
if search_truncated:
errors.append(
{
"source": "search",
"kind": "truncated",
"message": f"candidate search exceeded {limits.max_candidates} pull requests",
}
)
snapshots = []
failed_repositories = set()
for repository in sorted(targets, key=str.casefold):
numbers = sorted(targets[repository])
try:
fetched = client.fetch_repository(
repository,
numbers,
page_size=limits.page_size,
max_history=limits.max_history,
max_prs_per_query=limits.max_prs_per_query,
)
found = {int(item["number"]) for item in fetched}
if found != set(numbers):
raise CollectionError("one or more requested pull requests were unavailable")
snapshots.extend(fetched)
except (CollectionError, RuntimeError) as error:
failed_repositories.add(repository)
errors.append(
{
"source": "pull-requests",
"repository": repository,
"kind": "unavailable",
"message": str(error),
}
)
reduced = reduce_queue(
prior,
snapshots,
viewer_login=viewer_login,
mode=mode,
failed_repositories=failed_repositories,
state_limit=limits.max_state_entries,
)
reduced["viewerLogin"] = viewer_login
reduced["limits"] = limits.as_dict()
reduced["errors"] = errors + reduced["errors"]
reduced["failedRepositories"] = sorted(failed_repositories)
reduced["scope"] = {"kind": "current-workspace", "repositories": scope}
if reduced["errors"]:
reduced["status"] = (
"failed"
if search_failed and not snapshots and not collection_state.get("entries")
else "partial"
)
return reduced
def resolve_repository_scope(timeout: float) -> set[str]:
helper = Path(__file__).with_name("gh-pr-checkout.py")
environment = os.environ.copy()
environment.update({"GIT_PAGER": "cat", "PAGER": "cat", "NO_COLOR": "1"})
try:
completed = subprocess.run(
[str(helper), "--scope", "--timeout", str(timeout)],
check=False,
capture_output=True,
text=True,
timeout=max(0.1, timeout) + 1.0,
env=environment,
)
except subprocess.TimeoutExpired as error:
raise CollectionError("repository scope discovery deadline exceeded") from error
if len(completed.stdout.encode()) + len(completed.stderr.encode()) > 1_000_000:
raise CollectionError("repository scope discovery exceeded the output limit")
try:
result = json.loads(completed.stdout)
except json.JSONDecodeError as error:
raise CollectionError("repository scope discovery returned invalid JSON") from error
repositories = result.get("repositories")
if (
completed.returncode != 0
or result.get("status") != "verified"
or not isinstance(repositories, list)
or not repositories
):
errors = result.get("errors") or []
detail = errors[0].get("message") if errors and isinstance(errors[0], dict) else None
raise CollectionError(detail or "repository scope was unavailable")
scope = set()
for repository in repositories:
if not isinstance(repository, str):
raise CollectionError("repository scope contained an invalid repository")
split_repository(repository)
scope.add(repository)
return scope
def parse_state(arguments: argparse.Namespace) -> dict[str, Any] | None:
if arguments.state_json and arguments.state_stdin:
raise ValueError("choose either --state-json or --state-stdin")
raw = sys.stdin.read() if arguments.state_stdin else arguments.state_json
if raw is None:
return None
try:
state = json.loads(raw)
except json.JSONDecodeError as error:
raise ValueError(f"state was not valid JSON: {error}") from error
if not isinstance(state, dict):
raise ValueError("state must be a JSON object")
return state
def parse_args(argv: list[str]) -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--state-json")
parser.add_argument("--state-stdin", action="store_true")
modes = parser.add_mutually_exclusive_group()
modes.add_argument("--reset", action="store_true")
modes.add_argument("--recheck", action="store_true")
modes.add_argument("--mark-triaged", metavar="WORK_KEY", action="append",
help="acknowledge displayed work in returned state only; repeat for a batch")
parser.add_argument("--page-size", type=int, default=50)
parser.add_argument("--max-candidates", type=int, default=100)
parser.add_argument("--max-state-entries", type=int, default=200)
parser.add_argument("--max-history", type=int, default=200)
parser.add_argument("--max-prs-per-query", type=int, default=20)
parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT_SECONDS)
parser.add_argument("--max-output-bytes", type=int, default=DEFAULT_MAX_OUTPUT_BYTES)
parser.add_argument("--pretty", action="store_true")
return parser.parse_args(argv)
def main(argv: list[str]) -> int:
arguments = parse_args(argv)
state = None
mode = "reset" if arguments.reset else "recheck" if arguments.recheck else "normal"
limits = QueueLimits(
page_size=arguments.page_size,
max_candidates=arguments.max_candidates,
max_state_entries=arguments.max_state_entries,
max_history=arguments.max_history,
max_prs_per_query=arguments.max_prs_per_query,
).normalized()
try:
state = parse_state(arguments)
if arguments.mark_triaged:
if state is None:
raise ValueError("--mark-triaged requires session state")
result = {
"schemaVersion": SCHEMA_VERSION,
"status": "complete",
"mode": "mark-triaged",
"state": mark_triaged(state, arguments.mark_triaged),
}
else:
deadline = monotonic() + max(0.1, arguments.timeout)
repositories = resolve_repository_scope(
min(15.0, max(0.1, deadline - monotonic()))
)
remaining = deadline - monotonic()
if remaining <= 0:
raise CollectionError("GitHub collection deadline exceeded")
result = collect_queue(
GhClient(
timeout=remaining,
max_output_bytes=arguments.max_output_bytes,
),
repositories=repositories,
previous_state=state,
mode=mode,
limits=limits,
)
except CollectionError as error:
retained = state or empty_state("")
result = {
"schemaVersion": SCHEMA_VERSION,
"status": "failed",
"mode": mode,
"viewerLogin": retained.get("viewerLogin"),
"queue": [],
"transitions": [],
"scope": {"kind": "current-workspace", "repositories": []},
"errors": [
{"source": "scope", "kind": "unavailable", "message": str(error)}
],
"failedRepositories": [],
"limits": limits.as_dict(),
"state": retained,
}
except ValueError as error:
result = {
"schemaVersion": SCHEMA_VERSION,
"status": "failed",
"mode": "invalid",
"scope": {"kind": "current-workspace", "repositories": []},
"errors": [
{"source": "arguments", "kind": "invalid", "message": str(error)}
],
}
json.dump(result, sys.stdout, indent=2 if arguments.pretty else None, sort_keys=True)
sys.stdout.write("\n")
return 1 if result["status"] == "failed" else 0
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |