stackvitals 0.1.0__py3-none-any.whl

stackvitals/flow/analyze.py

@@ -0,0 +1,418 @@
+import re
+from bisect import bisect_left, bisect_right
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+from stackvitals.core import metrics
+from stackvitals.core.actors import INSIDER_ASSOC, People, kind_of
+from stackvitals.core.stats import median as _median
+from stackvitals.core.stats import percentile as _pct
+from stackvitals.core.time import iso as _iso
+from stackvitals.core.time import parse as _t
+from stackvitals.core.time import secs as _secs
+
+INSIDERS = INSIDER_ASSOC
+FAILING = {"FAILURE", "ERROR"}
+STAGES = ("pickup", "review", "merge", "cycle")
+# Nothing is "slow" before a day (repos that merge right after approval would flag minutes), and a wait
+# beyond 30 days is stale backlog rather than today's work.
+SLOW_FLOOR = 24 * 3600
+STALE = 30 * 24 * 3600
+MIN_BASELINE = 10
+
+
+def is_bot(p: dict) -> bool:
+    # Bots, coding agents and deleted accounts are not people (the crawl's rule).
+    return kind_of(p.get("au"), p.get("at")) != "person"
+
+
+def _human_reviews(p: dict) -> list[list]:
+    # GitHub's stage metrics skip bots, the author and Copilot; so do we.
+    return [e for e in p["ev"] if e[0] == "review" and e[2] and e[2] != p.get("au") and kind_of(e[2], e[5]) == "person"
+            and e[3] != "PENDING"]
+
+
+def _insider(login: str | None, assoc: str | None, people: People | None) -> bool:
+    # With the repo's people known, insiders are found by what they do; without, by GitHub's label alone.
+    return people.is_insider(login) if people is not None else assoc in INSIDER_ASSOC
+
+
+def ready_at(p: dict) -> str | None:
+    """When the PR first asked for review: its creation, or leaving draft if it was opened as a draft."""
+    toggles = [e for e in p["ev"] if e[0] in ("ready", "draft")]
+    if toggles and toggles[0][0] == "ready":
+        return toggles[0][1]
+    if toggles or not p.get("draft"):
+        return p["cr"]
+    return None
+
+
+def stages(p: dict) -> dict:
+    ready, merged = ready_at(p), p.get("mg")
+    reviews = [e for e in _human_reviews(p) if not merged or e[1] <= merged]
+    first = reviews[0][1] if reviews else None
+    final = reviews[-1][1] if reviews else None
+    return {"ready": ready, "reviewed": bool(reviews),
+            "pickup": _secs(ready, first), "review": _secs(first, final) if merged else None,
+            "merge": _secs(final, merged), "cycle": _secs(ready, merged)}
+
+
+def _asks(comment: list) -> bool:
+    # Older records have no flag: their comments count as asking, as before.
+    return comment[4] if len(comment) > 4 else True
+
+
+# Bots whose red marks rarely block a merge: performance and coverage reporters.
+NOISY = re.compile(r"codspeed|codecov|coverage|benchmark|\bperf\b|performance|sonar|deepsource", re.I)
+
+
+def _failing_checks(p: dict, shared: set[str]) -> tuple[list[str], list[str]]:
+    """Failing checks as (required, other); checks failing on many open PRs at once and noisy bots never count."""
+    chk = p.get("chk")
+    if not chk:
+        return (["checks"] if p.get("ci") in FAILING else []), []
+    live = [(name, required) for name, required in chk["failing"] if name not in shared]
+    return ([name for name, required in live if required],
+            [name for name, required in live if not required and not NOISY.search(name or "")])
+
+
+# Status labels maintainers set, matched on lower-case names with separators as spaces ("S-waiting-on-author").
+AUTHOR_LABEL = re.compile(r"waiting (on|for) (the )?(author|contributor|submitter|op|response|feedback|reporter)"
+                          r"|awaiting (author|changes|response|feedback|contributor)|changes requested|pending author"
+                          r"|merge conflicts?|has conflicts?"
+                          r"|needs? (changes|work|tests?|test coverage|rebase|more info|info|author|update|response|revision)")
+CONFLICT_LABEL = re.compile(r"needs? rebase|merge conflicts?|has conflicts?")
+READY_LABEL = re.compile(r"ready (to|for) merge|merge ready|waiting (on|for) (the )?(community )?(reviews?|maintainers?|merge)"
+                         r"|awaiting (review|merge|maintainers?)|needs? review|ready for review")
+# One or two red jobs while a reviewer is asked are often flaky; more than that is the change itself.
+BROAD_FAILURE = 3
+
+
+def _norm(label: str) -> str:
+    return " ".join(re.sub(r"[-_:/]+", " ", label.lower()).split())
+
+
+def _label(p: dict) -> tuple[str, str, str] | None:
+    """The newest status label still on the PR, as (author | ready, name, since). The author's turn runs from the first
+    such label still on; a review wait from the last status-label change (clippy drops "community reviews" to hand over)."""
+    added, changed = {}, ""
+    for when, sign, name in p.get("lbe") or []:
+        if name and _kind(name):
+            changed = max(changed, when)
+            if sign == "+":
+                added[name] = max(added.get(name, ""), when)
+    found = [(added[name], kind, name) for name in p.get("lb") or [] if (kind := _kind(name)) and name in added]
+    if not found:
+        return None
+    when, kind, name = max(found)
+    if kind == "author":
+        return kind, name, min(w for w, k, _ in found if k == "author")
+    return kind, name, max(when, changed)
+
+
+def _kind(label: str) -> str | None:
+    return "author" if AUTHOR_LABEL.search(_norm(label)) else "ready" if READY_LABEL.search(_norm(label)) else None
+
+
+def _work(p: dict) -> tuple[list[str], list[str]]:
+    """The author's new work (own non-merge commits, by authored date) and all their pushes; others' commits don't count."""
+    cmt = p.get("cmt")
+    if not cmt:
+        # Older records know only the last commit, whoever made it.
+        return [t for t in [p.get("la") or p.get("lc")] if t], [t for t in [p.get("lc"), p.get("la")] if t]
+    mine = [c for c in cmt if c[2] in (p.get("au"), None)]
+    return [c[0] for c in mine if not c[3] and c[0]], [c[1] for c in mine if c[1]]
+
+
+def who_acts_next(p: dict, now: datetime, heads: dict[str, int] | None = None, shared: set[str] | None = None,
+                  people: People | None = None) -> dict:
+    """Who holds the ball on an open PR, why, and since when (the event that put it there)."""
+    w = _decide(p, now, heads, shared, people)
+    # A reviewer the repo assigned (rust-clippy's rustbot) is named instead of unnamed maintainers.
+    owners = [a for a in p.get("asg") or [] if a != p.get("au")]
+    return {**w, "actor": "reviewers", "who": owners} if w["actor"] == "maintainers" and owners else w
+
+
+def _decide(p: dict, now: datetime, heads: dict[str, int] | None, shared: set[str] | None,
+            people: People | None = None) -> dict:
+    au = p.get("au")
+    parent = (heads or {}).get(p.get("base"))
+    if parent and parent != p["n"]:
+        # A stacked PR waits for the PR it builds on; that wait is nobody's review delay.
+        return {"actor": "nobody", "who": [], "why": f"stacked on #{parent}: waits for it to merge first",
+                "since": p["cr"], "step": "stacked"}
+    if p.get("draft"):
+        since = max([e[1] for e in p["ev"] if e[0] == "draft"] or [p["cr"]])
+        return {"actor": "nobody", "who": [au], "why": "draft: the author is still working on it", "since": since,
+                "step": "draft"}
+    label = _label(p)
+    if p.get("mgs") == "CONFLICTING":
+        # GitHub keeps no time for a conflict; a "needs rebase" style label set after the last commit dates it better,
+        # unless the author already owed work from an earlier point (ansible: changes requested months before the conflict).
+        since = max(p.get("lc") or p["up"], label[2] if label and label[0] == "author" else "")
+        rest = [x for x in p.get("lb") or [] if not CONFLICT_LABEL.search(_norm(x))]
+        before = _decide({**p, "mgs": None, "lb": rest}, now, heads, shared, people)
+        if before["actor"] == "author":
+            since = min(since, before["since"])
+        return {"actor": "author", "who": [au], "why": "has merge conflicts with the base branch", "since": since, "step": "checks"}
+    if (p.get("chk") or {}).get("awaiting"):
+        return {"actor": "maintainers", "who": [], "why": "CI runs wait for a maintainer to approve them",
+                "since": p.get("lc") or p["up"], "step": "pickup"}
+    code, pushes = _work(p)
+    if label:
+        kind, name, when = label
+        # A maintainer's status label decides until the author pushes after a "waiting on author" one.
+        if kind == "author" and not any(t > when for t in pushes):
+            return {"actor": "author", "who": [au], "why": f'labelled "{name}"', "since": when, "step": "author_changes"}
+        if kind == "ready":
+            return {"actor": "reviewers" if p["rq"] else "maintainers", "who": list(p["rq"]), "why": f'labelled "{name}"',
+                    "since": when, "step": "merge" if "merge" in _norm(name) else "pickup"}
+    required, other = _failing_checks(p, shared or set())
+    # A failing required check is always the author's; others are, unless a reviewer was asked and only one or two fail.
+    if required or (other and (not p["rq"] or len(other) >= BROAD_FAILURE)):
+        names = required or other
+        what = "checks are failing" if names == ["checks"] else f"checks are failing ({', '.join(names[:2])})"
+        return {"actor": "author", "who": [au], "why": f"{what} on the latest commit", "since": p.get("lc") or p["up"],
+                "step": "checks"}
+    # Anyone can press "request changes" on a public repo; only maintainers' reviews decide who holds the ball.
+    reviews = [e for e in _human_reviews(p) if _insider(e[2], e[4], people)]
+    latest = {}
+    for e in reviews:
+        if e[3] != "COMMENTED":
+            latest[e[2]] = e
+    # A formal change request is answered by a reply or new work, judged by when it was written (a rebase keeps that date);
+    # a question or comment by any push or reply. The ball moves at the author's first answer, not a later ping.
+    replies = [c[0] for c in p["cm"] if c[1] == au]
+    activity = sorted(replies + pushes + code)
+    blocking = sorted((e for e in latest.values() if e[3] == "CHANGES_REQUESTED"), key=lambda e: e[1])
+    if blocking:
+        names = [e[2] for e in blocking]
+        answers = sorted(t for t in replies + code if t > blocking[-1][1])
+        if answers:
+            return {"actor": "reviewers", "who": names, "why": f"the author updated it after changes requested by {', '.join(names)}",
+                    "since": answers[0], "step": "rereview"}
+        return {"actor": "author", "who": [au], "why": f"changes requested by {', '.join(names)}", "since": blocking[-1][1],
+                "step": "author_changes"}
+    if p["rq"]:
+        # Each reviewer's latest request counts: a re-request restarts their clock.
+        latest_ask = [max(e[1] for e in p["ev"] if e[0] == "req" and e[2] == who) for who in p["rq"]
+                      if any(e[0] == "req" and e[2] == who for e in p["ev"])]
+        return {"actor": "reviewers", "who": list(p["rq"]), "why": "review requested",
+                "since": min(latest_ask) if latest_ask else ready_at(p) or p["cr"], "step": "rereview" if reviews else "pickup"}
+    approvals = [e for e in latest.values() if e[3] == "APPROVED"]
+    if approvals:
+        last = max(approvals, key=lambda e: e[1])
+        # A maintainer's later comment-only review that raised points reopens it until new code arrives (older records lack the flag).
+        raised = [e for e in reviews if e[3] == "COMMENTED" and len(e) > 6 and e[6] and e[1] > last[1]]
+        if raised:
+            r = raised[-1]
+            later = sorted(t for t in code if t > r[1])
+            if later:
+                return {"actor": "reviewers", "who": [r[2]], "why": f"the author updated it after {r[2]}'s review",
+                        "since": later[0], "step": "rereview"}
+            return {"actor": "author", "who": [au], "why": f"{r[2]} raised points after the approval", "since": r[1],
+                    "step": "author_changes"}
+        if _insider(au, p.get("as"), people):
+            return {"actor": "author", "who": [au], "why": f"approved by {last[2]}; the author (a maintainer) can merge it",
+                    "since": last[1], "step": "merge"}
+        return {"actor": "maintainers", "who": [], "why": f"approved by {last[2]}, waiting to be merged", "since": last[1],
+                "step": "merge"}
+    asked = [c[0] for c in p["cm"] if _insider(c[1], c[2], people) and c[1] != au and _asks(c)] + [e[1] for e in reviews]
+    spoke = [c[0] for c in p["cm"] if _insider(c[1], c[2], people) and c[1] != au] + [e[1] for e in reviews]
+    if asked and max(asked) > (activity[-1] if activity else ""):
+        return {"actor": "author", "who": [au], "why": "a maintainer asked something", "since": max(asked), "step": "author_reply"}
+    after = [t for t in activity if spoke and t > max(spoke)]
+    if after:
+        return {"actor": "maintainers", "who": [], "why": "the author replied", "since": after[0], "step": "maintainer_reply"}
+    if spoke:
+        return {"actor": "maintainers", "who": [], "why": "a maintainer commented but nobody reviewed yet", "since": max(spoke),
+                "step": "pickup"}
+    return {"actor": "maintainers", "who": [], "why": "ready, but nobody was asked to review", "since": ready_at(p) or p["cr"],
+            "step": "pickup"}
+
+
+def _author_responses(p: dict) -> list[float]:
+    # How long authors take to answer a change request: the next commit or comment after it.
+    au, out = p.get("au"), []
+    acts = sorted([c[0] for c in p["cm"] if c[1] == au] + ([p["lc"]] if p.get("lc") else []))
+    for e in _human_reviews(p):
+        if e[3] == "CHANGES_REQUESTED":
+            later = [a for a in acts if a > e[1]]
+            if later:
+                out.append(_secs(e[1], later[0]))
+    return [x for x in out if x is not None]
+
+
+def _baselines(prs: list[dict]) -> dict:
+    st = [stages(p) for p in prs if p.get("mg")]
+    values = {"pickup": [s["pickup"] for s in st if s["pickup"] is not None],
+              "merge": [s["merge"] for s in st if s["merge"] is not None],
+              "author": [x for p in prs for x in _author_responses(p)]}
+    return {**{k: _pct(v, 0.75) for k, v in values.items()}, "n": {k: len(v) for k, v in values.items()}}
+
+
+def _summary(values: list[float]) -> dict:
+    return {"median_s": _median(values), "p90_s": _pct(values, 0.9), "n": len(values)}
+
+
+def _measures(all_stages: list[dict], outsider: list[dict], humans_open: list[dict], now: datetime, window_days: int) -> dict:
+    # The registry's view of the same numbers: id, version, n, range and as-of, for every surface and the benchmarks.
+    def pick(name):
+        return [s[name] for s in all_stages if s[name] is not None]
+    found = [metrics.measure("flow.pickup_time", values=pick("pickup"), as_of=now, window_days=window_days),
+             metrics.measure("flow.cycle_time", values=pick("cycle"), as_of=now, window_days=window_days),
+             metrics.measure("flow.outsider_merge_rate", hits=sum(1 for p in outsider if p.get("mg")), n=len(outsider),
+                             as_of=now, window_days=window_days),
+             metrics.measure("flow.open_prs", n=len(humans_open), as_of=now)]
+    return {m.metric: m.to_dict() for m in found}
+
+
+def _group(prs: list[dict]) -> dict:
+    merged = [p for p in prs if p.get("mg")]
+    unmerged = [p for p in prs if not p.get("mg")]
+    st = [stages(p) for p in merged]
+    out = {"merged": len(merged), "closed_unmerged": len(unmerged),
+           "merge_rate": round(len(merged) / len(prs), 4) if prs else None,
+           "merged_without_review": sum(not s["reviewed"] for s in st)}
+    for name in STAGES:
+        out[name] = _summary([s[name] for s in st if s[name] is not None])
+    return out
+
+
+SHARED_WINDOW = timedelta(days=7)
+SHARED_NEAREST = 6
+
+
+def _broken(name: str, group: list[tuple]) -> bool:
+    # Failing for 3+ different authors and on 80%+ of the PRs that ran it; one person's repeated slip stays theirs.
+    failing = [au for _, failed, au in group if name in failed]
+    return len(set(failing)) >= 3 and len(failing) / max(len(group), 1) >= 0.8
+
+
+def _nearest(runs: list[tuple], times: list[datetime], t: datetime, k: int) -> list[tuple]:
+    # The k runs closest in time to t, from a time-sorted list and its times.
+    i = bisect_left(times, t)
+    lo, hi, out = i - 1, i, []
+    while len(out) < k and (lo >= 0 or hi < len(runs)):
+        if hi < len(runs) and (lo < 0 or runs[hi][0] - t <= t - runs[lo][0]):
+            out.append(runs[hi])
+            hi += 1
+        else:
+            out.append(runs[lo])
+            lo -= 1
+    return out
+
+
+def _shared_breakage(prs: list[dict]) -> dict[int, set[str]]:
+    """Per PR, failing checks that were broken for everyone when its checks ran: judged among PRs that ran the same check,
+    pushed within 7 days of it or, in a quiet repo, the 6 pushed closest to it; never on today's PRs alone."""
+    by_check, mine = defaultdict(list), []
+    for p in prs:
+        chk = p.get("chk")
+        if chk:
+            t, failed = _t(p.get("lc") or p["up"]), {name for name, _ in chk.get("failing", [])}
+            mine.append((p["n"], t, failed))
+            for name in set(chk.get("ran") or failed) | failed:
+                by_check[name].append((t, failed, p.get("au")))
+    for runs in by_check.values():
+        runs.sort(key=lambda r: r[0])
+    # Times per check, built once: big repos have hundreds of open PRs with dozens of jobs each.
+    times = {name: [r[0] for r in runs] for name, runs in by_check.items()}
+    out = {}
+    for n, t, failed in mine:
+        out[n] = set()
+        for name in failed:
+            runs, ts = by_check[name], times[name]
+            week = runs[bisect_left(ts, t - SHARED_WINDOW):bisect_right(ts, t + SHARED_WINDOW)]
+            if _broken(name, week) or _broken(name, _nearest(runs, ts, t, SHARED_NEAREST)):
+                out[n].add(name)
+    return out
+
+
+BASELINE_STEPS = {"pickup": "pickup", "rereview": "pickup", "merge": "merge", "author_changes": "author",
+                  "author_reply": "author", "checks": "author", "maintainer_reply": "pickup"}
+
+
+def analyze(data: dict, now: datetime, window_days: int = 90, people_speed: bool = False, owner: str | None = None,
+            people: People | None = None) -> dict:
+    """Review flow of the last `window_days`, the open-PR queue and review load; people's speed only when asked."""
+    since = _iso(now - timedelta(days=window_days))
+    if people is None:
+        people = People(data["open"] + data["closed"])
+    humans_open = [p for p in data["open"] if not is_bot(p)]
+    closed = [p for p in data["closed"] if (p.get("cl") or "") >= since]
+    humans_closed = [p for p in closed if not is_bot(p)]
+    insider = [p for p in humans_closed if people.is_insider(p.get("au"))]
+    outsider = [p for p in humans_closed if not people.is_insider(p.get("au"))]
+    all_stages = [stages(p) for p in humans_closed if p.get("mg")]
+    baselines = _baselines(humans_closed)
+    # Outsiders' PRs usually wait longer; each PR is compared with its own group when there's enough history.
+    by_group = {"insider": _baselines(insider), "outsider": _baselines(outsider)}
+    # Branches of open PRs in this repo itself, to spot PRs stacked on another one.
+    heads = {p["head"]: p["n"] for p in data["open"] if owner and p.get("ho") == owner and p.get("head")}
+    shared = _shared_breakage(humans_open)
+    queue = []
+    for p in humans_open:
+        w = who_acts_next(p, now, heads, shared.get(p["n"]), people)
+        if w["actor"] == "nobody":
+            continue
+        waited = _secs(w["since"], _iso(now)) or 0.0
+        step = BASELINE_STEPS.get(w["step"], "pickup")
+        group = "insider" if people.is_insider(p.get("au")) else "outsider"
+        base = by_group[group][step] if by_group[group]["n"][step] >= MIN_BASELINE else baselines[step]
+        queue.append({"n": p["n"], "title": p.get("ti"), "author": p.get("au"), "outsider": group == "outsider",
+                      **w, "waiting_s": waited, "usual_s": base, "stale": waited > STALE,
+                      "slow": bool(base is not None and waited > max(base, SLOW_FLOOR))})
+    # Today's work first: overdue PRs, then the rest by wait; stale backlog last.
+    queue.sort(key=lambda q: (q["stale"], not q["slow"], -q["waiting_s"]))
+    load = defaultdict(list)
+    for p in humans_open:
+        if p.get("draft"):
+            continue
+        for who in p["rq"]:
+            asked = [e[1] for e in p["ev"] if e[0] == "req" and e[2] == who]
+            load[who].append(min(asked) if asked else ready_at(p) or p["cr"])
+    monthly = defaultdict(lambda: {"opened": 0, "merged": 0, "pickup": [], "cycle": []})
+    for p in [*humans_open, *[p for p in data["closed"] if not is_bot(p)]]:
+        if p["cr"] >= _iso(now - timedelta(days=365)):
+            monthly[p["cr"][:7]]["opened"] += 1
+        if p.get("mg") and p["mg"] >= _iso(now - timedelta(days=365)):
+            m = monthly[p["mg"][:7]]
+            m["merged"] += 1
+            if (s := stages(p))["pickup"] is not None:
+                m["pickup"].append(s["pickup"])
+            if s["cycle"] is not None:
+                m["cycle"].append(s["cycle"])
+    out = {"generated": _iso(now), "window_days": window_days,
+           "open": len(humans_open), "drafts": sum(1 for p in humans_open if p.get("draft")),
+           "merged": len(all_stages), "closed_unmerged": sum(1 for p in humans_closed if not p.get("mg")),
+           "stages": {name: _summary([s[name] for s in all_stages if s[name] is not None]) for name in STAGES},
+           "merged_without_review": sum(not s["reviewed"] for s in all_stages),
+           "groups": {"insider": _group(insider), "outsider": _group(outsider)},
+           "baselines": {k: v for k, v in baselines.items() if k != "n"}, "queue": queue,
+           "stale": sum(q["stale"] for q in queue),
+           "load": sorted(({"reviewer": who, "open_requests": len(ts), "oldest_since": min(ts)} for who, ts in load.items()),
+                          key=lambda r: (-r["open_requests"], r["oldest_since"])),
+           "monthly": [{"month": k, "opened": v["opened"], "merged": v["merged"], "pickup_median_s": _median(v["pickup"]),
+                        "cycle_median_s": _median(v["cycle"])}
+                       for k, v in sorted(monthly.items())],
+           "bots": {"open": len(data["open"]) - len(humans_open), "closed": len(closed) - len(humans_closed)},
+           "measures": _measures(all_stages, outsider, humans_open, now, window_days)}
+    if people_speed:
+        out["responders"] = _responders([*humans_open, *humans_closed])
+    return out
+
+
+def _responders(prs: list[dict]) -> list[dict]:
+    # Each reviewer's own answer time, from being asked (or the PR being ready) to their first review after it.
+    waits = defaultdict(list)
+    for p in prs:
+        ready = ready_at(p)
+        for who in {e[2] for e in _human_reviews(p)}:
+            asked = [e[1] for e in p["ev"] if e[0] == "req" and e[2] == who]
+            start = min(asked) if asked else ready
+            after = [e[1] for e in _human_reviews(p) if e[2] == who and start and e[1] >= start]
+            if start and after:
+                waits[who].append(_secs(start, after[0]))
+    return sorted(({"reviewer": who, "median_s": _median([w for w in ws if w is not None]), "n": len(ws)}
+                   for who, ws in waits.items()), key=lambda r: -r["n"])

stackvitals/flow/automate.py

@@ -0,0 +1,72 @@
+"""Team automation, on by default and switched under [automation]: one suggested reviewer requested on ready pull requests
+nobody was asked to review, a size label on each, and a "low risk" label on docs-only ones. Planned before the data
+branch's commit (so overlapping runs never ask twice) and sent after it."""
+import re
+from urllib.parse import quote
+
+from stackvitals.flow.analyze import is_bot
+
+# Line counts (added plus deleted) at each size's top; Kubernetes' and gitStream's usual cuts.
+SIZES = (("size/XS", 10), ("size/S", 100), ("size/M", 500), ("size/L", 1000), ("size/XL", None))
+DOCS_LABEL = "low risk: docs only"
+# Markup files anywhere, anything under docs/, and the usual top files by exact name (requirements.txt is not docs).
+DOCS = re.compile(r"(?i)(\.(md|mdx|rst|adoc)$|^docs?/|(^|/)(README|CHANGELOG|CONTRIBUTING|LICENSE|AUTHORS|NOTICE)"
+                  r"(\.(md|rst|txt))?$)")
+MAX_WRITES = 40
+
+
+def size_label(lines: int) -> str:
+    return next(name for name, top in SIZES if top is None or lines < top)
+
+
+def plan(open_prs: list[dict], queue: list[dict], switches: dict, state: dict) -> tuple[list[dict], dict]:
+    """The writes to make (at most MAX_WRITES) and the state to keep: PRs a reviewer was requested on."""
+    acts, asked = [], list(state.get("requested") or [])
+    by_n = {p["n"]: p for p in open_prs}
+    for p in open_prs:
+        if p.get("draft") or is_bot(p):
+            continue
+        labels = set(p.get("lb") or [])
+        if switches.get("size_labels"):
+            want = size_label((p.get("add") or 0) + (p.get("del") or 0))
+            stale = {x for x in labels if x.startswith("size/") and x != want}
+            if want not in labels:
+                acts.append({"kind": "label", "n": p["n"], "body": {"labels": [want]}})
+            acts += [{"kind": "unlabel", "n": p["n"], "label": x} for x in sorted(stale)]
+        if switches.get("docs_label"):
+            # Only when every changed file was read (the collector reads the first 50).
+            paths = p.get("paths") or []
+            docs = bool(paths) and len(paths) == (p.get("files") or len(paths)) and all(DOCS.search(x) for x in paths)
+            if docs and DOCS_LABEL not in labels:
+                acts.append({"kind": "label", "n": p["n"], "body": {"labels": [DOCS_LABEL]}})
+            elif not docs and DOCS_LABEL in labels:
+                acts.append({"kind": "unlabel", "n": p["n"], "label": DOCS_LABEL})
+    if switches.get("review_requests"):
+        for q in queue:
+            p = by_n.get(q["n"])
+            pick = next((s["login"] for s in q.get("suggested") or [] if s.get("login")), None)
+            if p and pick and q["n"] not in asked and not p.get("draft") and not is_bot(p) and pick != p.get("au"):
+                acts.append({"kind": "review", "n": q["n"], "body": {"reviewers": [pick]}})
+                asked.append(q["n"])
+    acts = acts[:MAX_WRITES]
+    sent = {a["n"] for a in acts if a["kind"] == "review"}
+    return acts, {"requested": [n for n in asked if n in sent or n in (state.get("requested") or [])][-500:]}
+
+
+def send(api, acts: list[dict]) -> dict:
+    """Make the planned writes; one refused for lack of permission is counted, the rest still go."""
+    done, refused = {"label": 0, "unlabel": 0, "review": 0, "comment": 0}, []
+    for a in acts:
+        try:
+            if a["kind"] == "label":
+                api.send("POST", f"/repos/{api.repo}/issues/{a['n']}/labels", a["body"])
+            elif a["kind"] == "comment":
+                api.send("POST", f"/repos/{api.repo}/issues/{a['n']}/comments", a["body"])
+            elif a["kind"] == "unlabel":
+                api.send("DELETE", f"/repos/{api.repo}/issues/{a['n']}/labels/{quote(a['label'], safe='')}")
+            else:
+                api.send("POST", f"/repos/{api.repo}/pulls/{a['n']}/requested_reviewers", a["body"])
+            done[a["kind"]] += 1
+        except Exception as exc:  # noqa: BLE001
+            refused.append(f"#{a['n']} {a['kind']}: {exc}")
+    return {**done, "refused": refused[:5]}

stackvitals/flow/build.py

@@ -0,0 +1,46 @@
+from datetime import datetime
+
+from stackvitals.core.actors import People
+from stackvitals.flow.analyze import analyze
+from stackvitals.flow.knowledge import codeowners_for, delivery, expertise, knowledge_map, suggest_reviewers
+from stackvitals.flow.peers import compare, own_metrics
+from stackvitals.flow.preflight import Habits, folder_habits, gaps, preflight
+
+
+def build(data: dict, repo: dict, now: datetime, owner: str | None = None, people_speed: bool = False,
+          window_days: int = 90, asks: dict | None = None, bench: dict | None = None, names: bool = True) -> dict:
+    """Everything Team Flow shows: the queue (with reviewer suggestions where nobody was asked), review stages,
+    the knowledge map and delivery. People's answer times are used and shown only when people_speed is set; the
+    knowledge map names people only when names is set."""
+    prs = data["open"] + data["closed"]
+    # Who is an insider is decided once, by what people do, and shared by every part below.
+    people = People(prs)
+    result = analyze(data, now, window_days=window_days, people_speed=people_speed, owner=owner, people=people)
+    ex = expertise(prs, now, people=people)
+    load = {r["reviewer"]: r["open_requests"] for r in result["load"]}
+    speed = {r["reviewer"]: r["median_s"] for r in result.get("responders", [])} if people_speed else None
+    text = repo.get("codeowners")
+    by_n = {p["n"]: p for p in data["open"]}
+    habits_index = Habits(prs, now)
+    for q in result["queue"]:
+        p = by_n.get(q["n"])
+        if p:
+            # Where this PR differs from what merged PRs in its folders usually include.
+            q["gaps"] = gaps(p, habits_index.norms(p.get("paths") or []))
+        if p and q["actor"] == "maintainers" and q["step"] == "pickup" and not p["rq"]:
+            owners = {path: codeowners_for(path, text) for path in p.get("paths") or []} if text else {}
+            q["suggested"] = suggest_reviewers(p, ex, load, owners, speed)
+    result["knowledge"] = knowledge_map(prs, now)
+    if not names:
+        # A public repo's pages are public: the map names areas, never the person behind them (route work, don't rate people).
+        for a in result["knowledge"].get("areas") or []:
+            a["owner"] = None
+    result["delivery"] = delivery(prs, repo.get("releases") or [], now, window_days)
+    habits = habits_index.norms([])
+    # Maintainers' asks are shown only when they come up often enough to matter.
+    common = [a for a in preflight(prs, asks or {}, [], now)["asks"] if a["share"] >= 0.05 and a["prs"] >= 3]
+    # Per folder too, so the app's planned-PR check narrows to the folders it touches like the CLI does.
+    result["habits"] = {**habits, "asks": common, "folders": folder_habits(prs, asks or {}, now, habits_index)}
+    # Compared with similar public repos, only when a benchmarks file was found.
+    result["peers"] = compare(own_metrics(prs, now, window_days, people=people), bench, repo.get("language"), repo.get("stars"))
+    return result

stackvitals/flow/cli.py

@@ -0,0 +1,93 @@
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mergescout.github.graphql import GitHubGraphQL, GraphQLError
+from stackvitals.ci.cli import home, token
+from stackvitals.flow.action import write_flow_outputs
+from stackvitals.flow.build import build
+from stackvitals.flow import peers
+from stackvitals.flow.collect import collect
+from stackvitals.flow.preflight import collect_asks, gaps, norms, preflight
+from stackvitals.flow import triage as triage_mod
+from stackvitals.flow.report import render_text
+from stackvitals.flow.store import FlowStore
+
+
+def local_gql(tok: str) -> GitHubGraphQL:
+    # On the user's machine a short wait for the limit is fine.
+    return GitHubGraphQL(tok, max_wait=120)
+
+
+def load_model(tok: str | None) -> dict | None:
+    from stackvitals.ci import bench as ci_bench
+    return ci_bench.load(tok, home() / "bench", name=triage_mod.MODEL_FILE, url_env="STACKVITALS_TRIAGE_URL",
+                         validate=triage_mod.valid, default_url=None)
+
+
+def main(argv: list[str] | None = None, now: datetime | None = None, make_gql=local_gql, tok: str | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="stackvitals flow", description="Team Flow: who acts next on pull requests.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    rep = sub.add_parser("report", help="Read a repo's pull requests and show who acts next and how review flows")
+    rep.add_argument("repo", help="owner/name")
+    rep.add_argument("--months", type=int, default=12, help="history to read on the first run")
+    rep.add_argument("--window", type=int, default=90, help="days the flow numbers cover")
+    rep.add_argument("--json", action="store_true")
+    rep.add_argument("--html", help="also write a dashboard into this folder (without people's answer times)")
+    pre = sub.add_parser("preflight", help="What merged PRs here usually include, and what a planned PR is missing")
+    pre.add_argument("repo", help="owner/name")
+    pre.add_argument("--paths", nargs="+", default=[], help="files the PR changes")
+    pre.add_argument("--lines", type=int, default=0, help="lines the PR adds plus removes")
+    pre.add_argument("--months", type=int, default=12)
+    tri = sub.add_parser("triage", help="Private: chance each open outside PR gets merged within 30 days, and why")
+    tri.add_argument("repo", help="owner/name")
+    tri.add_argument("--pr", type=int, default=0, help="only this PR")
+    tri.add_argument("--months", type=int, default=12)
+    args = parser.parse_args(argv)
+    tok = tok or token()
+    if not tok:
+        print("A GitHub token is needed. Set GITHUB_TOKEN, or run `gh auth login`.", file=sys.stderr)
+        return 1
+    now = now or datetime.now(timezone.utc)
+    owner, name = args.repo.split("/", 1)
+    store = FlowStore(home() / "flow" / args.repo.replace("/", "__"))
+    try:
+        gql = make_gql(tok)
+        stats = collect(gql, store, owner, name, now, months=args.months,
+                        log=lambda line: print(line, file=sys.stderr, flush=True))
+        collect_asks(gql, store, owner, name, store.load()["closed"], cap=1000)
+    except GraphQLError as exc:
+        print(f"GitHub refused: {exc}", file=sys.stderr)
+        return 1
+    if args.cmd == "triage":
+        model = load_model(tok)
+        if model is None:
+            print("The triage model could not be read (it is published with the daily data).", file=sys.stderr)
+            return 1
+        data = store.load()
+        if args.pr:
+            data = {"open": [p for p in data["open"] if p["n"] == args.pr], "closed": data["closed"]}
+        print(json.dumps(triage_mod.triage(data, model, now), indent=1))
+        return 0
+    if args.cmd == "preflight":
+        data = store.load()
+        prs = data["open"] + data["closed"]
+        habits = norms(prs, args.paths, now)
+        out = {"repo": args.repo, **habits, "gaps": gaps({"paths": args.paths, "add": args.lines}, habits),
+               "asks": preflight(prs, store.asks(), args.paths, now)["asks"][:5]}
+        print(json.dumps(out, indent=1))
+        return 0
+    # This view is the user's own, so it may include each reviewer's answer time.
+    result = build(store.load(), store.repo(), now, owner=owner, people_speed=True, window_days=args.window,
+                   asks=store.asks(), bench=peers.load(tok, home() / "bench"))
+    if args.html:
+        write_flow_outputs(Path(args.html), result, args.repo)
+    if args.json:
+        print(json.dumps({**result, "collect": stats}, indent=1))
+    else:
+        print(render_text(result, args.repo))
+        if not stats["complete"]:
+            print("\n(Not all pull requests were read yet; run the same command again to continue.)")
+    return 0