stackvitals 0.1.0__py3-none-any.whl

mergescout/labels.py

@@ -0,0 +1,20 @@
+import re
+
+# Label names that mark an issue as open to newcomers; GitHub matches any of them, ignoring case.
+OPPORTUNITY_LABELS = ("good first issue", "good-first-issue", "help wanted", "help-wanted", "beginner",
+                      "beginner friendly", "easy", "first-timers-only", "starter", "good first contribution")
+
+
+def norm_label(name: str) -> str:
+    # "Good-First-Issue :wave:" and "good_first_issue" both become "good first issue".
+    text = re.sub(r":[a-z0-9_+-]+:", " ", (name or "").lower())
+    return " ".join(re.sub(r"[^a-z0-9]+", " ", text).split())
+
+
+HOT = {norm_label(label) for label in OPPORTUNITY_LABELS}
+# "help wanted" invites anyone; these labels promise a task sized for a first contribution.
+BEGINNER = HOT - {"help wanted"}
+
+
+def has_opportunity(labels: list[str]) -> bool:
+    return any(norm_label(label) in HOT for label in labels or [])

mergescout/mcp_server.py

@@ -0,0 +1,228 @@
+import json
+import os
+import sys
+import threading
+from datetime import datetime
+from pathlib import Path
+
+import httpx
+from mcp.server.mcpserver import MCPServer
+
+from mergescout.github.releases import ReleaseError, Releases
+from mergescout.tool.action_pack import build_action_pack
+from mergescout.tool.live import GitHubLive, LiveError
+from mergescout.tool.queries import Snapshot
+from mergescout.tool.refs import parse_ref
+from mergescout.tool.store import DEFAULT_REPO, SnapshotStore, data_token, home
+from mergescout.tool.tracking import Tracker
+
+TOOL_NAMES = ("find_issues", "action_pack", "repo_health", "repos_needing_help", "check_issue", "similar_issues",
+              "explain", "track", "report_outcome")
+INSTRUCTIONS = ("MergeScout answers from a daily snapshot of GitHub repos: which open issues an outsider can "
+                "realistically get merged, with evidence (merge rates with sample sizes, review times, walls). "
+                "Call check_issue before telling someone an issue is free. Quote the evidence and say "
+                "'not enough evidence' whenever a result does.")
+
+
+class NoSnapshot(RuntimeError):
+    pass
+
+
+class App:
+    def __init__(self, root: Path | None = None, releases=None, live=None, log=None):
+        self.root = root or home()
+        self.log = log or (lambda msg: print(msg, file=sys.stderr))
+        repo = os.environ.get("MERGESCOUT_DATA_REPO", DEFAULT_REPO)
+        self.store = SnapshotStore(self.root, releases or Releases(data_token(), repo))
+        self.live = live or GitHubLive(data_token())
+        self.tracker = Tracker(self.root)
+        self._snap = None
+        # Tools run in worker threads; only one of them may check for and download a snapshot.
+        self._lock = threading.Lock()
+
+    def snapshot(self) -> Snapshot:
+        with self._lock:
+            if self._snap is None:
+                path = self.store.ensure(log=self.log)
+                if path is None:
+                    raise NoSnapshot("No issue snapshot is available yet: it isn't published for outside use. "
+                                     "Maintainers with access to the private data set MERGESCOUT_TOKEN, then run "
+                                     "`mergescout update`.")
+                self._snap = Snapshot(path)
+            return self._snap
+
+
+def plain(exc: Exception) -> str:
+    if isinstance(exc, httpx.HTTPError):
+        return f"Could not reach GitHub (network problem: {exc}). Answers from the snapshot still work."
+    if isinstance(exc, ReleaseError):
+        return (f"Could not read the issue snapshot ({exc}). It isn't published for outside use yet; maintainers "
+                "with access to the private data set MERGESCOUT_TOKEN.")
+    return str(exc)
+
+
+def _safe(fn):
+    # Agents read plain answers better than stack traces.
+    def run(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except (NoSnapshot, LiveError, ValueError, httpx.HTTPError, ReleaseError) as exc:
+            return {"error": plain(exc)}
+    run.__name__, run.__doc__ = fn.__name__, fn.__doc__
+    return run
+
+
+def live_status(app: App, ref) -> dict:
+    status = app.live.issue_status(ref.owner, ref.name, ref.number)
+    if status.get("linked_open_prs") is not None:
+        return status
+    # Without a token GitHub hides linked PRs; keep the open PR the snapshot last saw.
+    try:
+        snap = app.snapshot()
+    except NoSnapshot:
+        return status
+    row = snap.issue(ref.repo, ref.number)
+    if row and row["linked_open_prs"]:
+        status = {**status, "linked_open_prs": row["linked_open_prs"], "available": False,
+                  "reasons": status.get("reasons", []) + [f"open PR (seen in the snapshot of {snap.built_at})"]}
+    return status
+
+
+def verify_live(app: App, out: dict, limit: int) -> dict:
+    # Real queries (2026-10-16): 7 of 60 snapshot results were taken within a day; check the list in one call.
+    refs = [parse_ref(r["issue"]) for r in out["results"]]
+    try:
+        statuses = app.live.issue_statuses([(f.owner, f.name, f.number) for f in refs])
+    except Exception as exc:  # noqa: BLE001 - any odd answer falls back to the snapshot list
+        out["results"] = out["results"][:limit]
+        out["note"] += f" Live check failed ({plain(exc)}); availability is from the snapshot."
+        return out
+    kept, taken, gone = [], 0, 0
+    for r, f in zip(out["results"], refs):
+        s = statuses.get((f.owner, f.name, f.number))
+        if s is None or not s["available"]:
+            taken += s is not None
+            gone += s is None
+            continue
+        r = {**r, "checked_live": True}
+        if s["older_claims"]:
+            r["earlier_claims"] = (f"{len(s['older_claims'])} older offer(s) to work on it, the last on "
+                                   f"{s['older_claims'][-1]['at'][:10]}; ask on the issue before starting")
+        if s.get("note"):
+            r["live_note"] = s["note"]
+        kept.append(r)
+    out["note"] = (f"Checked live on GitHub just now: {taken} of {len(refs)} candidates are taken or not ready and "
+                   f"{gone} no longer exist; they are left out.")
+    out["results"] = kept[:limit]
+    return out
+
+
+def build_server(app: App) -> MCPServer:
+    server = MCPServer("mergescout", instructions=INSTRUCTIONS)
+
+    @server.tool()
+    def find_issues(language: str | None = None, topic: str | None = None, beginner_labels_only: bool = False,
+                    min_score: float = 0.0, allow_walls: bool = True, fresh: bool = False, limit: int = 10,
+                    detail: bool = False) -> dict:
+        """Open issues an outsider can likely get merged, best first, each with its evidence.
+        topic: plain words matched against titles, labels and bodies. allow_walls=False hides repos with a CLA,
+        DCO, issue-first rule or AI ban. fresh=True also lists beginner issues opened after the snapshot."""
+        return _safe(_find)(language, topic, beginner_labels_only, min_score, allow_walls, fresh, limit, detail)
+
+    def _find(language, topic, beginner_labels_only, min_score, allow_walls, fresh, limit, detail):
+        snap = app.snapshot()
+        limit = max(1, min(limit, 50))
+        # With a token, twice the candidates are read so the list stays full after taken ones are dropped.
+        live = bool(getattr(app.live, "token", None))
+        out = snap.find_issues(language, topic, beginner_labels_only, min_score, allow_walls,
+                               min(limit * 2, 50) if live else limit, detail)
+        if live and out["results"]:
+            out = verify_live(app, out, limit)
+        if fresh:
+            since = datetime.fromisoformat(snap.built_at.replace("Z", "+00:00"))
+            try:
+                out["fresh"] = snap.with_repo_stats(app.live.fresh_issues(language, since, limit))[:limit]
+            except (LiveError, httpx.HTTPError) as exc:
+                out["fresh"], out["fresh_note"] = [], f"fresh lane unavailable: {plain(exc)}"
+        return out
+
+    @server.tool()
+    def action_pack(issue: str) -> dict:
+        """Everything needed to start on one issue: live status, what it asks, accepted outsider PRs to copy,
+        the project's rules as a checklist, a size hint and next steps. issue: owner/name#number or a URL."""
+        def run():
+            ref = parse_ref(issue)
+            try:
+                status, failed = live_status(app, ref), None
+            except (LiveError, httpx.HTTPError) as exc:
+                status, failed = None, plain(exc)
+            pack = build_action_pack(app.snapshot(), ref, status)
+            if failed:
+                pack["status"]["note"] = f"live check failed ({failed}); status is from the snapshot of {app.snapshot().built_at}"
+            return pack
+        return _safe(run)()
+
+    @server.tool()
+    def repo_health(repo: str, detail: bool = False) -> dict:
+        """How outsiders fare in one repo: merge rates with sample sizes, review time, walls, how to reach it."""
+        def run():
+            out = app.snapshot().repo_health(parse_ref(repo).repo, detail)
+            return out or {"error": f"{repo} is not in the snapshot (not crawled yet or too inactive)."}
+        return _safe(run)()
+
+    @server.tool()
+    def repos_needing_help(language: str | None = None, limit: int = 10) -> dict:
+        """Repos that merge outsider PRs but have very few active maintainers."""
+        return _safe(lambda: app.snapshot().repos_needing_help(language, limit))()
+
+    @server.tool()
+    def check_issue(issue: str) -> dict:
+        """Live check on GitHub right now: open, assigned, linked PRs, recent claims, maintainer 'please wait'."""
+        def run():
+            return live_status(app, parse_ref(issue))
+        return _safe(run)()
+
+    @server.tool()
+    def similar_issues(issue: str, limit: int = 5) -> dict:
+        """Free issues whose titles share words with this one (keyword match)."""
+        def run():
+            ref = parse_ref(issue)
+            return app.snapshot().similar_issues(ref.repo, ref.number, limit)
+        return _safe(run)()
+
+    @server.tool()
+    def explain(issue: str) -> dict:
+        """The full evidence record behind an issue's score: counts, ranges, windows, exclusions and notes."""
+        def run():
+            ref = parse_ref(issue)
+            return app.snapshot().explain(ref.repo, ref.number) or {"error": f"{ref.key} is not in the snapshot."}
+        return _safe(run)()
+
+    @server.tool()
+    def track(issue: str | None = None, untrack: bool = False) -> dict:
+        """Track an issue (stored on this machine); untrack=True stops tracking it.
+        Without an issue: list tracked issues and what changed since the last look."""
+        def run():
+            if issue and untrack:
+                app.tracker.untrack(parse_ref(issue).key)
+            elif issue:
+                ref = parse_ref(issue)
+                app.tracker.track(ref.key, live_status(app, ref))
+            return {"tracked": sorted(app.tracker.tracked()), "changes": [] if issue else app.tracker.updates(app.live)}
+        return _safe(run)()
+
+    @server.tool()
+    def report_outcome(issue: str, outcome: str, note: str = "") -> dict:
+        """Record what happened (started, pr_opened, merged, closed_unmerged, abandoned, taken_by_someone_else).
+        Kept on this machine only."""
+        return _safe(lambda: app.tracker.report_outcome(parse_ref(issue).key, outcome, note))()
+
+    @server.resource("corpus://stats", mime_type="application/json")
+    def stats() -> str:
+        """Snapshot date and coverage."""
+        try:
+            return json.dumps(app.snapshot().stats())
+        except NoSnapshot as exc:
+            return json.dumps({"error": str(exc)})
+
+    return server

mergescout/measure/__main__.py

@@ -0,0 +1,75 @@
+import argparse
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import orjson
+
+from mergescout.config import load_config
+from mergescout.github.graphql import GitHubGraphQL, GraphQLError
+from mergescout.measure.api_cost import measure_repo
+from mergescout.measure.count_repos import count_repos, listing_requests
+from mergescout.measure.jsonl import append_jsonl, read_jsonl
+from mergescout.measure.report import render_markdown, summarize
+from mergescout.measure.sample import build_sample_queries, collect_sample
+
+
+def run_api_cost(gql, sample: list[dict], results_path: Path, now: datetime, limit: int | None = None) -> int:
+    done = {r["repo"] for r in read_jsonl(results_path)}
+    measured = 0
+    for entry in sample:
+        if entry["repo"] in done:
+            continue
+        if limit is not None and measured >= limit:
+            break
+        try:
+            record = measure_repo(gql, entry["repo"], now)
+        except GraphQLError as exc:
+            # Not recorded, so the next run tries this repo again.
+            print(f"{entry['repo']}: failed ({exc})")
+            continue
+        record["bucket"] = entry.get("bucket")
+        append_jsonl(results_path, record)
+        measured += 1
+        print(f"{entry['repo']}: {record['status']}")
+    return measured
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m mergescout.measure", description="Phase 0 measurements.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("sample", help="Pick about 300 repos across star ranges")
+    api = sub.add_parser("api-cost", help="Measure API points per sampled repo (safe to re-run)")
+    api.add_argument("--limit", type=int, default=None)
+    sub.add_parser("count-repos", help="Count public repos by star range")
+    rep = sub.add_parser("report", help="Print the budget report")
+    rep.add_argument("--daily-points", type=int, default=120_000)
+    args = parser.parse_args(argv)
+
+    cfg = load_config()
+    out = cfg.data_dir / "measure"
+    out.mkdir(parents=True, exist_ok=True)
+    now = datetime.now(timezone.utc)
+    recent = (now - timedelta(days=30)).date()
+
+    if args.cmd == "report":
+        print(render_markdown(summarize(read_jsonl(out / "api_cost.jsonl"), daily_points=args.daily_points)))
+        return 0
+
+    gql = GitHubGraphQL(cfg.require_token())
+    if args.cmd == "sample":
+        sample = collect_sample(gql, build_sample_queries(recent))
+        (out / "sample.json").write_bytes(orjson.dumps(sample, option=orjson.OPT_INDENT_2))
+        print(f"Sampled {len(sample)} repos -> {out / 'sample.json'}")
+    elif args.cmd == "api-cost":
+        sample = orjson.loads((out / "sample.json").read_bytes())
+        run_api_cost(gql, sample, out / "api_cost.jsonl", now, args.limit)
+    elif args.cmd == "count-repos":
+        counts = count_repos(gql, recent)
+        counts["listing_requests"] = listing_requests(counts["rows"])
+        (out / "count_repos.json").write_bytes(orjson.dumps(counts, option=orjson.OPT_INDENT_2))
+        print(orjson.dumps(counts, option=orjson.OPT_INDENT_2).decode())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mergescout/measure/api_cost.py

@@ -0,0 +1,91 @@
+from datetime import datetime, timedelta
+
+from mergescout.github.graphql import NotFound
+from mergescout.timeutil import parse_time
+
+PR_HISTORY_QUERY = """
+query($owner: String!, $name: String!, $cursor: String) {
+  rateLimit { cost remaining resetAt }
+  repository(owner: $owner, name: $name) {
+    pullRequests(first: 100, after: $cursor, orderBy: {field: CREATED_AT, direction: DESC}) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number createdAt mergedAt closedAt state authorAssociation author { login }
+        reviews(first: 1) { nodes { submittedAt authorAssociation } }
+      }
+    }
+  }
+}
+"""
+
+INCREMENTAL_QUERY = """
+query($owner: String!, $name: String!, $cursor: String) {
+  rateLimit { cost remaining resetAt }
+  repository(owner: $owner, name: $name) {
+    pullRequests(first: 100, after: $cursor, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number updatedAt createdAt mergedAt closedAt state authorAssociation author { login }
+        reviews(first: 1) { nodes { submittedAt authorAssociation } }
+      }
+    }
+  }
+}
+"""
+
+OPEN_ISSUES_QUERY = """
+query($owner: String!, $name: String!, $cursor: String) {
+  rateLimit { cost remaining resetAt }
+  repository(owner: $owner, name: $name) {
+    issues(first: 100, after: $cursor, states: OPEN, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number updatedAt
+        assignees(first: 5) { totalCount }
+        labels(first: 10) { nodes { name } }
+        closedByPullRequestsReferences(first: 5, includeClosedPrs: true) { nodes { number state } }
+        comments(last: 5) { nodes { createdAt authorAssociation author { login } body } }
+      }
+    }
+  }
+}
+"""
+
+
+def walk_connection(gql, query: str, owner: str, name: str, connection: str, time_field: str,
+                    since: datetime, max_pages: int) -> dict:
+    cursor = None
+    pages = cost = items = 0
+    capped = False
+    while True:
+        result = gql.query(query, {"owner": owner, "name": name, "cursor": cursor})
+        pages += 1
+        cost += result.cost
+        repo = result.data.get("repository")
+        if repo is None:
+            raise NotFound(f"{owner}/{name} not found")
+        conn = repo[connection]
+        nodes = conn["nodes"]
+        in_window = [n for n in nodes if (parse_time(n.get(time_field)) or since) >= since]
+        items += len(in_window)
+        if len(in_window) < len(nodes) or not conn["pageInfo"]["hasNextPage"]:
+            break
+        if pages >= max_pages:
+            capped = True
+            break
+        cursor = conn["pageInfo"]["endCursor"]
+    return {"pages": pages, "cost": cost, "items": items, "capped": capped}
+
+
+def measure_repo(gql, full_name: str, now: datetime) -> dict:
+    owner, name = full_name.split("/", 1)
+    try:
+        full = walk_connection(gql, PR_HISTORY_QUERY, owner, name, "pullRequests", "createdAt",
+                               now - timedelta(days=365), max_pages=30)
+        incremental = walk_connection(gql, INCREMENTAL_QUERY, owner, name, "pullRequests", "updatedAt",
+                                      now - timedelta(days=1), max_pages=30)
+        issues = walk_connection(gql, OPEN_ISSUES_QUERY, owner, name, "issues", "updatedAt",
+                                 now - timedelta(days=90), max_pages=20)
+    except NotFound:
+        return {"repo": full_name, "status": "not_found"}
+    return {"repo": full_name, "status": "ok", "full": full, "incremental": incremental, "issues": issues}

mergescout/measure/count_repos.py

@@ -0,0 +1,30 @@
+import math
+from datetime import date
+
+COUNT_RANGES = [("50-99", "50..99"), ("100-199", "100..199"), ("200-499", "200..499"),
+                ("500-999", "500..999"), ("1k-5k", "1000..4999"), ("5k+", ">=5000")]
+
+COUNT_QUERY = """
+query($q: String!) {
+  rateLimit { cost remaining resetAt }
+  search(query: $q, type: REPOSITORY, first: 1) { repositoryCount }
+}
+"""
+
+
+def count_repos(gql, pushed_since: date) -> dict:
+    rows = []
+    cost = 0
+    for label, stars in COUNT_RANGES:
+        base = f"stars:{stars} fork:false archived:false"
+        total = gql.query(COUNT_QUERY, {"q": base})
+        active = gql.query(COUNT_QUERY, {"q": f"{base} pushed:>={pushed_since.isoformat()}"})
+        cost += total.cost + active.cost
+        rows.append({"range": label, "total": total.data["search"]["repositoryCount"],
+                     "active": active.data["search"]["repositoryCount"]})
+    return {"rows": rows, "cost": cost}
+
+
+def listing_requests(rows: list[dict]) -> int:
+    # Search pages hold 100 repos, so listing every active repo takes at least this many calls.
+    return sum(math.ceil(row["active"] / 100) for row in rows)

mergescout/measure/jsonl.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+import orjson
+
+
+def read_jsonl(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    return [orjson.loads(line) for line in path.read_bytes().splitlines() if line.strip()]
+
+
+def append_jsonl(path: Path, record: dict) -> None:
+    with path.open("ab") as f:
+        f.write(orjson.dumps(record) + b"\n")

mergescout/measure/report.py

@@ -0,0 +1,56 @@
+def _mean(values: list[float]) -> float:
+    return sum(values) / len(values) if values else 0.0
+
+
+def _percentile(values: list[float], p: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    return ordered[round((len(ordered) - 1) * p)]
+
+
+def summarize(results: list[dict], daily_points: int = 120_000,
+              tier_sizes: tuple[int, ...] = (10_000, 25_000, 50_000, 100_000)) -> dict:
+    ok = [r for r in results if r.get("status") == "ok"]
+    full = [r["full"]["cost"] for r in ok]
+    incr = [r["incremental"]["cost"] for r in ok]
+    issues = [r["issues"]["cost"] for r in ok]
+    # Totals use the mean, not the median, because a few huge repos eat most of the budget.
+    fill_per_repo = _mean(full) + _mean(issues)
+    refresh_per_repo = _mean(incr) + _mean(issues)
+    tiers = [{"tier": n,
+              "first_fill_days": n * fill_per_repo / daily_points,
+              "refresh_cycle_days": n * refresh_per_repo / daily_points} for n in tier_sizes]
+    buckets = {}
+    for bucket in sorted({r.get("bucket") or "?" for r in ok}):
+        rows = [r for r in ok if (r.get("bucket") or "?") == bucket]
+        costs = [r["full"]["cost"] for r in rows]
+        buckets[bucket] = {"repos": len(rows), "full_median": _percentile(costs, 0.5),
+                           "full_p90": _percentile(costs, 0.9),
+                           "issues_median": _percentile([r["issues"]["cost"] for r in rows], 0.5)}
+    return {
+        "daily_points": daily_points,
+        "repos_measured": len(ok),
+        "not_found": sum(1 for r in results if r.get("status") == "not_found"),
+        "capped": sum(1 for r in ok if any(r[k]["capped"] for k in ("full", "incremental", "issues"))),
+        "mean_full": _mean(full), "mean_incremental": _mean(incr), "mean_issues": _mean(issues),
+        "tiers": tiers, "by_bucket": buckets,
+    }
+
+
+def render_markdown(s: dict) -> str:
+    lines = [
+        f"Repos measured: {s['repos_measured']} (not found: {s['not_found']}, hit page cap: {s['capped']})",
+        f"Mean points per repo: full history {s['mean_full']:.1f}, incremental {s['mean_incremental']:.1f}, "
+        f"open issues {s['mean_issues']:.1f}",
+        f"Daily budget assumed: {s['daily_points']} points",
+        "",
+        "| Tier size | First fill (days) | Refresh cycle (days) |",
+        "|---|---|---|",
+    ]
+    lines += [f"| {t['tier']} | {t['first_fill_days']:.1f} | {t['refresh_cycle_days']:.1f} |" for t in s["tiers"]]
+    lines += ["", "| Star bucket | Repos | Full history median | Full history p90 | Issues median |",
+              "|---|---|---|---|---|"]
+    lines += [f"| {b} | {v['repos']} | {v['full_median']} | {v['full_p90']} | {v['issues_median']} |"
+              for b, v in s["by_bucket"].items()]
+    return "\n".join(lines)

mergescout/measure/sample.py

@@ -0,0 +1,37 @@
+from datetime import date
+
+STAR_BUCKETS = [("50-199", "50..199"), ("200-999", "200..999"), ("1k-10k", "1000..9999"), ("10k+", ">=10000")]
+CREATED_SLICES = ["<2016-01-01", "2016-01-01..2018-12-31", "2019-01-01..2021-12-31",
+                  "2022-01-01..2023-12-31", ">=2024-01-01"]
+
+SEARCH_QUERY = """
+query($q: String!, $n: Int!) {
+  rateLimit { cost remaining resetAt }
+  search(query: $q, type: REPOSITORY, first: $n) {
+    repositoryCount
+    nodes { ... on Repository { nameWithOwner stargazerCount } }
+  }
+}
+"""
+
+
+def build_sample_queries(pushed_since: date) -> list[tuple[str, str]]:
+    # Mixing star ranges and creation years gives a spread of repo sizes and ages.
+    return [
+        (label, f"stars:{stars} created:{created} pushed:>={pushed_since.isoformat()} fork:false archived:false")
+        for label, stars in STAR_BUCKETS
+        for created in CREATED_SLICES
+    ]
+
+
+def collect_sample(gql, queries: list[tuple[str, str]], per_query: int = 15) -> list[dict]:
+    seen: set[str] = set()
+    sample = []
+    for label, q in queries:
+        result = gql.query(SEARCH_QUERY, {"q": q, "n": per_query})
+        for node in result.data["search"]["nodes"]:
+            name = node.get("nameWithOwner")
+            if name and name not in seen:
+                seen.add(name)
+                sample.append({"repo": name, "stars": node["stargazerCount"], "bucket": label})
+    return sample

mergescout/owners.py

@@ -0,0 +1,22 @@
+import re
+
+LOGIN = re.compile(r"(?<![\w.])@([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))(?![\w/.-]*\.\w)")
+YAML_KEY = re.compile(r"^(approvers|reviewers|maintainers)\s*:\s*$", re.I)
+YAML_ITEM = re.compile(r"^\s*-\s*([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\s*(#.*)?$")
+
+
+def owner_logins(text: str) -> set[str]:
+    # "@alice" counts, "@org/team" and e-mail addresses do not; Kubernetes OWNERS files list plain names.
+    text = text or ""
+    found = {m.group(1).lower() for m in LOGIN.finditer(text) if text[m.end():m.end() + 1] != "/"}
+    in_list = False
+    for line in text.splitlines():
+        if YAML_KEY.match(line.strip()):
+            in_list = True
+            continue
+        item = YAML_ITEM.match(line) if in_list else None
+        if item:
+            found.add(item.group(1).lower())
+        elif line.strip() and not line.startswith((" ", "\t", "-")):
+            in_list = False
+    return found

mergescout/setup_check.py

@@ -0,0 +1,64 @@
+"""Check the crawler repo's tokens without crawling: python -m mergescout.setup_check"""
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from mergescout.config import load_config
+from mergescout.github.graphql import GitHubGraphQL
+from mergescout.github.identities import Identity, identities_from_env
+from mergescout.github.releases import Releases
+
+PROBE = 'query { rateLimit { cost remaining limit resetAt } repository(owner: "psf", name: "requests") { stargazerCount } }'
+
+
+def check_identity(identity: Identity) -> tuple[bool, str]:
+    try:
+        data = identity.make_gql().query(PROBE).data
+    except Exception as exc:
+        return False, str(exc)
+    rate = data.get("rateLimit") or {}
+    if not (data.get("repository") or {}).get("stargazerCount"):
+        return False, "token works but cannot read public repositories"
+    return True, f"{rate.get('limit')} points/hour, {rate.get('remaining')} left"
+
+
+def check_store(releases, tag: str = "crawl-state") -> tuple[bool, str]:
+    # Proves read and write with one tiny file that is removed straight away.
+    try:
+        if releases.get(tag) is None:
+            return False, f"can reach the repo but release '{tag}' is missing"
+        with tempfile.TemporaryDirectory() as tmp:
+            probe = Path(tmp) / "setup-check.txt"
+            probe.write_text("setup check, safe to delete\n", encoding="utf-8")
+            asset = releases.upload(tag, probe)
+        releases.delete_asset(asset)
+    except Exception as exc:
+        return False, str(exc)
+    return True, "read and write both work"
+
+
+def main() -> int:
+    cfg = load_config()
+    results = []
+    if not cfg.github_token:
+        results.append(("personal token", False, "GITHUB_TOKEN is empty (secret MS_GITHUB_TOKEN)"))
+    else:
+        for identity in identities_from_env(cfg.github_token, max_wait=60, client=GitHubGraphQL):
+            results.append((f"{identity.name} token", *check_identity(identity)))
+        names = {i.name for i in identities_from_env(cfg.github_token, None)}
+        for expected in ("app", "actions"):
+            if expected not in names:
+                results.append((f"{expected} token", False, "not passed to this run"))
+    token, repo = os.environ.get("MS_RELEASE_TOKEN"), os.environ.get("MS_STORE_REPO")
+    if not token or not repo:
+        results.append(("data store", False, "MS_RELEASE_TOKEN or MS_STORE_REPO is empty (secret MS_STORE_TOKEN)"))
+    else:
+        results.append((f"data store ({repo})", *check_store(Releases(token, repo))))
+    for name, ok, detail in results:
+        print(f"{'OK  ' if ok else 'FAIL'} {name}: {detail}", flush=True)
+    return 0 if all(ok for _, ok, _ in results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())