stackvitals 0.1.0__py3-none-any.whl

mergescout/snapshot/schema.py

@@ -0,0 +1,34 @@
+# The file every user downloads; bump the major version only for changes old tools cannot read.
+SCHEMA_VERSION = "1.1"
+SCHEMA_MAJOR = 1
+
+DDL = """
+CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+CREATE TABLE repos (
+  repo_id INTEGER PRIMARY KEY, name TEXT NOT NULL, stars INTEGER, language TEXT COLLATE NOCASE, pushed_at TEXT,
+  archived INTEGER, license TEXT, has_discussions INTEGER, open_issues INTEGER, open_prs INTEGER, insiders INTEGER,
+  outsider_prs INTEGER, merged INTEGER, closed INTEGER, merge_rate REAL, merge_low REAL, merge_high REAL,
+  merge_enough INTEGER, newcomer_merged INTEGER, newcomer_decided INTEGER, newcomer_rate REAL, newcomer_low REAL,
+  newcomer_high REAL, newcomer_enough INTEGER, reviewed INTEGER, median_review_hours REAL, review_enough INTEGER,
+  window_days INTEGER, window_complete INTEGER, ai_prs INTEGER, bot_prs INTEGER, insider_prs INTEGER,
+  blocking_walls INTEGER NOT NULL, walls_json TEXT NOT NULL, labels_json TEXT NOT NULL, notes TEXT NOT NULL,
+  contributing INTEGER,
+  fetched_at TEXT);
+CREATE UNIQUE INDEX repos_name ON repos (name COLLATE NOCASE);
+CREATE TABLE issues (
+  repo_id INTEGER NOT NULL, number INTEGER NOT NULL, title TEXT, body TEXT, labels TEXT NOT NULL,
+  language TEXT COLLATE NOCASE, created_at TEXT, updated_at TEXT, available INTEGER NOT NULL,
+  opportunity INTEGER NOT NULL, blocked_by TEXT, assignees INTEGER, linked_open_prs INTEGER, dead_ends INTEGER,
+  claimers INTEGER, last_claim_at TEXT, interest_30d INTEGER, score REAL NOT NULL, rank_score REAL NOT NULL,
+  p_avail REAL, p_merge REAL, p_reply REAL, p_fixed REAL, p_quality REAL, mult REAL, fetched_at TEXT,
+  beginner INTEGER NOT NULL DEFAULT 0, kind TEXT,
+  UNIQUE (repo_id, number));
+CREATE INDEX issues_rank ON issues (available, language, rank_score DESC);
+CREATE INDEX issues_rank_all ON issues (available, rank_score DESC);
+CREATE TABLE outsider_prs (repo_id INTEGER NOT NULL, number INTEGER NOT NULL, merged_at TEXT, lines INTEGER,
+  files INTEGER, days_to_merge REAL);
+CREATE INDEX outsider_prs_repo ON outsider_prs (repo_id);
+-- detail=column: single-word search only, about half the index size.
+CREATE VIRTUAL TABLE issues_fts USING fts5(title, labels, body, content='issues', content_rowid='rowid',
+  tokenize='porter unicode61', detail=column);
+"""

mergescout/snapshot/score.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Weights:
+    # Architecture §6 until calibrated odds exist; every number here is config, not a law.
+    availability: float = 0.30
+    outsider_merge: float = 0.30
+    reply: float = 0.15
+    fixed_before: float = 0.10
+    issue_quality: float = 0.15
+    prior_merge: float = 0.2
+    prior_reply: float = 0.3
+    prior_fixed: float = 0.3
+    reply_half_hours: float = 48.0
+    dead_end: float = 0.8
+    dead_end_floor: float = 0.5
+    crowded_interest: int = 3
+    crowded: float = 0.7
+    blocking_wall: float = 0.85
+    freshness_half_days: float = 30.0
+    discussion: float = 0.3
+    untriaged: float = 0.6
+    old_days: int = 365
+    old: float = 0.75
+    very_old_days: int = 730
+    very_old: float = 0.5
+
+
+WEIGHTS = Weights()

mergescout/store/__main__.py

@@ -0,0 +1,46 @@
+import argparse
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mergescout.config import load_config
+from mergescout.github.releases import Releases
+from mergescout.store.sync import pull, push
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m mergescout.store",
+                                     description="Keep crawl data and state in this repo's GitHub releases.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    ps = sub.add_parser("push", help="Upload new crawl batches and a state backup, then clear uploaded batches")
+    ps.add_argument("--with-discover", action="store_true", help="Also back up the sweep results")
+    sub.add_parser("pull", help="Restore state from the releases when the local copy is missing")
+    put = sub.add_parser("put", help="Upload one file to a release tag")
+    put.add_argument("path")
+    put.add_argument("--tag", required=True)
+    # MS_STORE_REPO lets a crawler repo keep its data in another (private) repo; otherwise the running repo.
+    parser.add_argument("--repo", default=os.environ.get("MS_STORE_REPO") or os.environ.get("GITHUB_REPOSITORY"),
+                        help="owner/name of the repo whose releases hold the data")
+    args = parser.parse_args(argv)
+
+    token = os.environ.get("MS_RELEASE_TOKEN")
+    if not token or not args.repo:
+        print("Set MS_RELEASE_TOKEN (a token that can write releases) and GITHUB_REPOSITORY or --repo.",
+              file=sys.stderr)
+        return 1
+    cfg = load_config()
+    releases = Releases(token, args.repo)
+    log = lambda msg: print(msg, flush=True)  # noqa: E731
+    if args.cmd == "push":
+        push(cfg.data_dir, releases, datetime.now(timezone.utc), with_discover=args.with_discover, log=log)
+    elif args.cmd == "put":
+        releases.upload(args.tag, Path(args.path))
+        log(f"uploaded {Path(args.path).name} to {args.tag}")
+    else:
+        pull(cfg.data_dir, releases, log=log)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mergescout/store/sync.py

@@ -0,0 +1,148 @@
+import gzip
+import os
+import re
+import shutil
+import sqlite3
+import tarfile
+from datetime import datetime
+from pathlib import Path
+
+STATE_TAG = "crawl-state"
+
+
+def data_tag(now: datetime) -> str:
+    # One data release per ISO week: hourly runs stay well under GitHub's 1,000 files per release.
+    return f"crawl-{now:%G-W%V}"
+RUN_FILE = re.compile(r"^run=(?P<run>.+)-(?P<seq>\d{3})\.parquet$")
+
+
+def pending_runs(data_dir: Path) -> dict[str, list[Path]]:
+    runs: dict[str, list[Path]] = {}
+    for p in sorted((data_dir / "crawl").glob("*/run=*.parquet")):
+        m = RUN_FILE.match(p.name)
+        if m:
+            runs.setdefault(m["run"], []).append(p)
+    return runs
+
+
+def _tar(paths: list[Path], base: Path, out: Path) -> Path:
+    with tarfile.open(out, "w") as tar:
+        for p in paths:
+            tar.add(p, arcname=p.relative_to(base).as_posix())
+    return out
+
+
+def safe_extract(archive: Path, dest: Path) -> None:
+    # Only plain files and folders that land inside dest; anything else means a broken or hostile archive.
+    root = dest.resolve()
+    with tarfile.open(archive) as tar:
+        members = tar.getmembers()
+        for m in members:
+            target = (dest / m.name).resolve()
+            if not (m.isfile() or m.isdir()) or (target != root and root not in target.parents):
+                raise ValueError(f"refusing archive entry {m.name!r}")
+        dest.mkdir(parents=True, exist_ok=True)
+        for m in members:
+            target = dest / m.name
+            if m.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with tar.extractfile(m) as src, target.open("wb") as out:
+                shutil.copyfileobj(src, out)
+
+
+def _repo_count(state_file: Path) -> int:
+    db = sqlite3.connect(state_file)
+    try:
+        return db.execute("SELECT count(*) FROM repos").fetchone()[0]
+    except sqlite3.Error:
+        return 0
+    finally:
+        db.close()
+
+
+def push(data_dir: Path, releases, now: datetime, with_discover: bool = False, log=print) -> dict:
+    # Upload first, delete after: a failed upload leaves the files for the next run to retry.
+    outbox = data_dir / "outbox"
+    outbox.mkdir(parents=True, exist_ok=True)
+    out = {"runs": 0, "state": False, "discover": False}
+    for run, files in pending_runs(data_dir).items():
+        bundle = _tar(files, data_dir, outbox / f"crawl-{run}.tar")
+        releases.upload(data_tag(now), bundle)
+        for p in files:
+            p.unlink()
+        bundle.unlink()
+        out["runs"] += 1
+    state_file = data_dir / "crawl.sqlite"
+    if state_file.exists() and _repo_count(state_file) == 0:
+        # An empty queue means the state was not restored; never let it replace the good backup.
+        log("not backing up an empty crawl state")
+    elif state_file.exists():
+        snap, packed = outbox / "crawl.sqlite", outbox / "crawl.sqlite.gz"
+        src, dst = sqlite3.connect(state_file), sqlite3.connect(snap)
+        with dst:
+            src.backup(dst)
+        src.close()
+        dst.close()
+        with snap.open("rb") as f, gzip.open(packed, "wb") as g:
+            shutil.copyfileobj(f, g)
+        releases.upload(STATE_TAG, packed)
+        snap.unlink()
+        packed.unlink()
+        out["state"] = True
+    discover = data_dir / "discover"
+    if with_discover and discover.exists():
+        files = [p for p in sorted(discover.rglob("*")) if p.is_file()]
+        bundle = _tar(files, data_dir, outbox / "discover.tar")
+        releases.upload(STATE_TAG, bundle)
+        bundle.unlink()
+        out["discover"] = True
+    log(f"pushed: {out}")
+    return out
+
+
+def pull(data_dir: Path, releases, log=print) -> dict:
+    # Only used when the Actions cache is gone; local files always win.
+    outbox = data_dir / "outbox"
+    out = {"state": False, "discover": False}
+    state_file = data_dir / "crawl.sqlite"
+    if not state_file.exists():
+        packed = outbox / "crawl.sqlite.gz"
+        if releases.download(STATE_TAG, "crawl.sqlite.gz", packed):
+            part = state_file.with_name(state_file.name + ".part")
+            with gzip.open(packed, "rb") as g, part.open("wb") as f:
+                shutil.copyfileobj(g, f)
+            os.replace(part, state_file)
+            packed.unlink()
+            out["state"] = True
+    if not (data_dir / "discover").exists():
+        bundle = outbox / "discover.tar"
+        if releases.download(STATE_TAG, "discover.tar", bundle):
+            safe_extract(bundle, data_dir)
+            bundle.unlink()
+            out["discover"] = True
+    log(f"pulled: {out}")
+    return out
+
+
+def fetch_bronze(releases, data_dir: Path, log=print) -> int:
+    # Each crawl bundle (weekly and older monthly data releases) is downloaded and unpacked once.
+    bronze, got = data_dir / "bronze", 0
+    for release in releases.list_releases():
+        if not release["tag_name"].startswith("crawl-") or release["tag_name"] == STATE_TAG:
+            continue
+        for asset in releases.assets(release):
+            name = asset["name"]
+            marker = bronze / "done" / name
+            if not (name.startswith("crawl-") and name.endswith(".tar")) or marker.exists():
+                continue
+            tar = bronze / "tars" / name
+            releases.download_asset(asset, tar)
+            safe_extract(tar, bronze)
+            tar.unlink()
+            marker.parent.mkdir(parents=True, exist_ok=True)
+            marker.touch()
+            got += 1
+    log(f"bronze: {got} new bundles")
+    return got

mergescout/timeutil.py

@@ -0,0 +1,11 @@
+from datetime import datetime
+
+
+def parse_time(value: str | None) -> datetime | None:
+    # GitHub times look like 2026-10-01T15:00:01Z
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None

mergescout/tool/action_pack.py

@@ -0,0 +1,62 @@
+import json
+import statistics
+
+from mergescout.labels import norm_label
+from mergescout.tool.queries import rate_text, review_text
+from mergescout.tool.refs import Ref
+
+CHECKLIST = {
+    "cla": "Sign the project's CLA before opening the PR",
+    "dco": "Sign off every commit (git commit -s)",
+    "issue_first": "Comment on the issue and wait for a maintainer's OK before coding",
+    "ai_ban": "This project does not accept AI-written contributions; write it yourself",
+    "ai_policy": "Follow the project's AI rules and say in the PR how you used AI",
+    "no_outside_prs": "The project says it does not accept outside PRs right now",
+    "issues_disabled": "Issues are turned off; ask in the project's discussion channel first",
+}
+
+
+def build_action_pack(snap, ref: Ref, status: dict | None = None) -> dict:
+    issue, repo = snap.issue(ref.repo, ref.number), snap.repo(ref.repo)
+    if issue is None or repo is None:
+        raise ValueError(f"{ref.key} is not in today's snapshot; use check_issue for a live look.")
+    walls = json.loads(repo["walls_json"])
+    labels = {lb["label"]: lb for lb in json.loads(repo["labels_json"])}
+    examples = snap.examples(repo["repo_id"])
+    names = [norm_label(x) for x in json.loads(issue["labels"])]
+    fix = next((labels[lb] for lb in names if lb in labels and labels[lb].get("enough")), None)
+    if fix and fix.get("median_fix_lines") is not None:
+        level = f"typical fix for this label here: {fix['median_fix_lines']:.0f} lines in {fix['median_fix_files']:.0f} files"
+    elif examples:
+        level = f"recent accepted outsider PRs: median {statistics.median(e['lines'] or 0 for e in examples):.0f} lines"
+    else:
+        level = "not enough evidence to size this yet"
+    status = status or {"available": bool(issue["available"]),
+                        "reasons": [b for b in (issue["blocked_by"] or "").split(", ") if b], "source": "snapshot",
+                        "note": f"from the snapshot of {snap.built_at}; call check_issue for the live state"}
+    steps = []
+    if not status.get("available", True):
+        steps.append(f"Stop: this issue is not free right now ({', '.join(status.get('reasons') or [])}). "
+                     "Pick another one or ask the person working on it.")
+    if any(w["wall"] == "issue_first" for w in walls):
+        steps.append("Post the draft comment and wait for a maintainer's reply before writing code.")
+    steps += ["Reproduce the problem locally and write down the exact steps.",
+              "Plan a test that fails before your change and passes after it.",
+              "Before opening the PR, explain the change in your own words in the description (no copy-paste).",
+              "Keep the PR small and link the issue with 'Fixes #%d'." % ref.number]
+    if any(w["wall"] in ("ai_policy", "ai_ban") for w in walls):
+        steps.append("Check the project's AI rules (see the checklist) before using an AI assistant.")
+    return {"issue": {"ref": ref.key, "url": f"https://github.com/{repo['name']}/issues/{ref.number}",
+                      "title": issue["title"], "labels": json.loads(issue["labels"]), "asks": issue["body"]},
+            "status": status,
+            "repo": {"outsider_merge": rate_text(repo), "review": review_text(repo),
+                     "how_prs_die": f"{repo['closed'] or 0} of {(repo['merged'] or 0) + (repo['closed'] or 0)} decided "
+                                    f"outsider PRs were closed without merging (last {repo['window_days']} days)",
+                     "contributing": bool(repo["contributing"]), "discussions": bool(repo["has_discussions"])},
+            "accepted_examples": [{"url": f"https://github.com/{repo['name']}/pull/{e['number']}", "lines": e["lines"],
+                                   "files": e["files"], "days_to_merge": e["days_to_merge"]} for e in examples],
+            "policy_checklist": [f"{CHECKLIST[w['wall']]} (project text: \"{w['evidence']}\")" for w in walls
+                                 if w["wall"] in CHECKLIST],
+            "level": level, "next_steps": steps,
+            "draft_comment": ("Hi! I'd like to work on this. My plan: <one or two lines on the approach>. "
+                              "Does that sound right, and could it be assigned to me?")}

mergescout/tool/live.py

@@ -0,0 +1,201 @@
+import math
+import re
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+from mergescout.labels import has_opportunity, norm_label
+from mergescout.signals.rules import (BOT_NAME_PATTERN, CLAIM_PATTERN, HUMAN_BOT_NAMES, KNOWN_BOTS, RULES,
+                                      TRIAGE_LABEL_PATTERN, UNKNOWN_LOGINS, WAIT_LABEL_PATTERN, WAIT_PATTERN)
+
+API = "https://api.github.com"
+INSIDER = {"OWNER", "MEMBER", "COLLABORATOR"}
+FIELDS = """
+fragment S on Issue {
+  title state stateReason updatedAt
+  assignees(first: 5) { totalCount }
+  labels(first: 20) { nodes { name } }
+  closedByPullRequestsReferences(first: 5, includeClosedPrs: false) { nodes { number state } }
+  timelineItems(last: 30, itemTypes: [CROSS_REFERENCED_EVENT]) { nodes { ... on CrossReferencedEvent {
+    source { __typename ... on PullRequest { number state author { __typename login } repository { nameWithOwner } } } } } }
+  comments(last: 10) { nodes { createdAt authorAssociation author { __typename login } bodyText } }
+}"""
+STATUS_QUERY = """
+query($owner: String!, $name: String!, $number: Int!) {
+  rateLimit { cost remaining resetAt }
+  repository(owner: $owner, name: $name) { issue(number: $number) { ...S } }
+}""" + FIELDS
+# "Could you try the build from draft PR #1106?" points at work in progress the issue does not link.
+PR_MENTION = re.compile(r"(?:\bpr\s*#|\bpull request\s*#|/pull/)(\d+)", re.I)
+BATCH = 25
+
+
+class LiveError(RuntimeError):
+    pass
+
+
+def _time(text: str | None) -> datetime | None:
+    return datetime.fromisoformat(text.replace("Z", "+00:00")) if text else None
+
+
+def _bot(login: str, typ: str | None) -> bool:
+    return (typ == "Bot" or login in KNOWN_BOTS or login in UNKNOWN_LOGINS or login.endswith("[bot]")
+            or bool(re.search(BOT_NAME_PATTERN, login) and not re.search(HUMAN_BOT_NAMES, login)))
+
+
+def classify_comments(comments: list[dict], now: datetime) -> tuple[list, list, list]:
+    # Claims older than the claim window do not block, but a user should still see them before starting.
+    claims, waits, older = [], [], []
+    for c in comments:
+        login = (c.get("login") or "").lower()
+        if not login or _bot(login, c.get("type")):
+            continue
+        text, at = (c.get("body") or "").lower(), _time(c.get("created_at"))
+        item = {"by": c.get("login"), "at": c.get("created_at"), "text": (c.get("body") or "")[:160]}
+        if c.get("association") in INSIDER:
+            if re.search(WAIT_PATTERN, text):
+                waits.append(item)
+        elif re.search(CLAIM_PATTERN, text):
+            (claims if at and now - at <= timedelta(days=RULES.claim_days) else older).append(item)
+    return claims, waits, older
+
+
+def _graphql_errors(body: dict) -> list[dict]:
+    errors = body.get("errors") or []
+    if any(e.get("type") == "RATE_LIMITED" or "rate limit" in (e.get("message") or "").lower() for e in errors):
+        raise LiveError("GitHub's rate limit is reached for this token; try again in a few minutes.")
+    return errors
+
+
+def _from_graphql(issue: dict, repo: str) -> tuple[dict, list[dict]]:
+    comments = [{"login": (c.get("author") or {}).get("login"), "type": (c.get("author") or {}).get("__typename"),
+                 "association": c.get("authorAssociation"), "body": c.get("bodyText"), "created_at": c.get("createdAt")}
+                for c in (issue.get("comments") or {}).get("nodes") or [] if c]
+    linked = [p["number"] for p in issue["closedByPullRequestsReferences"]["nodes"] if p and p["state"] == "OPEN"]
+    # Real data (2026-10-16): open PRs often say "related to #N" without the closing keyword GitHub links.
+    mentions = []
+    for ev in (issue.get("timelineItems") or {}).get("nodes") or []:
+        src = (ev or {}).get("source") or {}
+        author = src.get("author") or {}
+        if (src.get("__typename") == "PullRequest" and src.get("state") == "OPEN"
+                and (src.get("repository") or {}).get("nameWithOwner", "").lower() == repo.lower()
+                and src.get("number") not in linked and src.get("number") not in mentions
+                and not _bot((author.get("login") or "").lower(), author.get("__typename"))):
+            mentions.append(src["number"])
+    return ({"state": issue["state"], "title": issue["title"], "assignees": issue["assignees"]["totalCount"],
+             "linked_open_prs": len(linked), "open_prs_mentioning": mentions,
+             "labels": [lb["name"] for lb in issue["labels"]["nodes"] if lb], "updated_at": issue["updatedAt"],
+             "source": "github graphql"}, comments)
+
+
+def _finish(status: dict, comments: list[dict], now: datetime) -> dict:
+    claims, waits, older = classify_comments(comments, now)
+    not_ready = [lb for lb in status["labels"] if re.search(WAIT_LABEL_PATTERN, norm_label(lb))]
+    untriaged = [lb for lb in status["labels"] if re.search(TRIAGE_LABEL_PATTERN, norm_label(lb))]
+    invited = has_opportunity(status["labels"])
+    mentioning = status.get("open_prs_mentioning") or []
+    reasons = [r for r, hit in (("closed", status["state"] != "OPEN"), ("assigned", status["assignees"] > 0),
+                                ("open PR", bool(status["linked_open_prs"])),
+                                (f"open PR mentions it ({', '.join(f'#{n}' for n in mentioning)})", bool(mentioning)),
+                                ("claimed recently", bool(claims)), ("maintainer asked to wait", bool(waits)),
+                                (f"label says not ready ({', '.join(not_ready)})", bool(not_ready)),
+                                (f"label says not settled yet ({', '.join(untriaged)})", bool(untriaged) and not invited))
+               if hit]
+    mentioned = list(dict.fromkeys(int(n) for c in comments for n in PR_MENTION.findall(c.get("body") or "")))
+    notes = [status["note"]] if status.get("note") else []
+    if mentioned and not reasons:
+        notes.append(f"comments mention PR {', '.join(f'#{n}' for n in mentioned)}; check it is not already fixing this")
+    if untriaged and invited and not reasons:
+        notes.append(f"also labelled '{untriaged[0]}': a maintainer may not have confirmed it yet; ask before starting")
+    out = {**status, "claims": claims, "waits": waits, "older_claims": older, "mentioned_prs": mentioned,
+           "available": not reasons, "reasons": reasons, "checked_at": now.strftime("%Y-%m-%dT%H:%M:%SZ")}
+    if notes:
+        out["note"] = "; ".join(notes)
+    return out
+
+
+class GitHubLive:
+    def __init__(self, token: str | None = None, client: httpx.Client | None = None):
+        self.token = (token or "").strip() or None
+        # Renamed repos and moved issues answer with redirects.
+        self.client = client or httpx.Client(timeout=30, follow_redirects=True)
+        self.headers = {"Accept": "application/vnd.github+json", "User-Agent": "mergescout"}
+        if self.token:
+            self.headers["Authorization"] = f"Bearer {self.token}"
+
+    def _get(self, path: str, params=None) -> httpx.Response:
+        resp = self.client.get(f"{API}{path}", headers=self.headers, params=params)
+        if resp.status_code == 404:
+            raise LiveError("GitHub says this issue or repo does not exist (or is private).")
+        if resp.status_code in (401, 403, 429):
+            raise LiveError(f"GitHub refused the live check (HTTP {resp.status_code}); set MERGESCOUT_TOKEN for more calls.")
+        resp.raise_for_status()
+        return resp
+
+    def _post(self, query: str, variables: dict) -> dict:
+        resp = self.client.post(f"{API}/graphql", headers=self.headers, json={"query": query, "variables": variables})
+        if resp.status_code == 401:
+            raise LiveError("GitHub rejected the token (401).")
+        if resp.status_code >= 400:
+            raise LiveError(f"GitHub could not answer the live check (HTTP {resp.status_code}).")
+        return resp.json()
+
+    def issue_status(self, owner: str, name: str, number: int) -> dict:
+        now = datetime.now(timezone.utc)
+        if self.token:
+            body = self._post(STATUS_QUERY, {"owner": owner, "name": name, "number": number})
+            errors = _graphql_errors(body)
+            issue = ((body.get("data") or {}).get("repository") or {}).get("issue")
+            if issue is None:
+                if errors and not all(e.get("type") == "NOT_FOUND" for e in errors):
+                    raise LiveError("GitHub could not answer: " + "; ".join(e.get("message", "?") for e in errors))
+                raise LiveError("GitHub says this issue does not exist (or is a pull request).")
+            status, comments = _from_graphql(issue, f"{owner}/{name}")
+        else:
+            base = self._get(f"/repos/{owner}/{name}/issues/{number}").json()
+            if "pull_request" in base:
+                raise LiveError("That number is a pull request, not an issue.")
+            last = max(1, math.ceil((base.get("comments") or 0) / 100))
+            raw = self._get(f"/repos/{owner}/{name}/issues/{number}/comments", {"per_page": 100, "page": last}).json()
+            comments = [{"login": (c.get("user") or {}).get("login"), "type": (c.get("user") or {}).get("type"),
+                         "association": c.get("author_association"), "body": c.get("body"), "created_at": c.get("created_at")}
+                        for c in raw[-10:]]
+            status = {"state": base["state"].upper(), "title": base["title"], "assignees": len(base.get("assignees") or []),
+                      "linked_open_prs": None, "labels": [lb["name"] for lb in base.get("labels") or []],
+                      "updated_at": base.get("updated_at"), "source": "github rest",
+                      "note": "linked PRs unknown without a token (set MERGESCOUT_TOKEN to check them)"}
+        return _finish(status, comments, now)
+
+    def issue_statuses(self, keys: list[tuple[str, str, int]]) -> dict[tuple[str, str, int], dict | None]:
+        # One GraphQL call per 25 issues, so a whole result list is checked for about one rate-limit point.
+        if not self.token:
+            raise LiveError("checking many issues at once needs MERGESCOUT_TOKEN")
+        now, out = datetime.now(timezone.utc), {}
+        for start in range(0, len(keys), BATCH):
+            chunk = keys[start:start + BATCH]
+            args = ", ".join(f"$o{n}: String!, $n{n}: String!, $k{n}: Int!" for n in range(len(chunk)))
+            parts = " ".join(f"i{n}: repository(owner: $o{n}, name: $n{n}) {{ issue(number: $k{n}) {{ ...S }} }}"
+                             for n in range(len(chunk)))
+            variables = {}
+            for n, (owner, name, number) in enumerate(chunk):
+                variables.update({f"o{n}": owner, f"n{n}": name, f"k{n}": number})
+            body = self._post(f"query({args}) {{ rateLimit {{ cost remaining }} {parts} }}" + FIELDS, variables)
+            _graphql_errors(body)
+            data = body.get("data") or {}
+            if not data:
+                raise LiveError("GitHub could not answer the live check.")
+            for n, key in enumerate(chunk):
+                issue = (data.get(f"i{n}") or {}).get("issue")
+                out[key] = _finish(*_from_graphql(issue, f"{key[0]}/{key[1]}"), now) if issue else None
+        return out
+
+    def fresh_issues(self, language: str | None, since: datetime, limit: int = 20) -> list[dict]:
+        # Issues opened after the snapshot was built: one search call.
+        q = f'is:issue is:open no:assignee label:"good first issue","help wanted" created:>={since:%Y-%m-%dT%H:%M:%SZ}'
+        if language:
+            q += f' language:"{language}"' if " " in language else f" language:{language}"
+        items = self._get("/search/issues", {"q": q, "sort": "created", "order": "desc",
+                                             "per_page": max(1, min(limit * 3, 100))}).json().get("items") or []
+        return [{"repo": it["repository_url"].split("/repos/", 1)[1], "number": it["number"], "title": it["title"],
+                 "labels": [lb["name"] for lb in it.get("labels") or []], "created_at": it["created_at"],
+                 "url": it["html_url"], "fresh": True} for it in items]