stackvitals 0.1.0__py3-none-any.whl

stackvitals/community/cli.py

@@ -0,0 +1,79 @@
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mergescout.github.graphql import GraphQLError
+from stackvitals.ci.api import ActionsAPI, APIError, OutOfBudget
+from stackvitals.ci.cli import home, token
+from stackvitals.community.action import load_benchmarks, write_community_outputs
+from stackvitals.community.build import build
+from stackvitals.community.collect import _read, collect_issues, collect_stars, collect_traffic
+from stackvitals.community.report import render_text
+from stackvitals.flow.cli import local_gql
+from stackvitals.flow.collect import collect
+from stackvitals.flow.store import FlowStore
+
+
+def local_community(repo: str, tok: str, now: datetime, months: int = 12, make_gql=local_gql, make_api=ActionsAPI,
+                    root: Path | None = None, log=None) -> tuple[dict, dict]:
+    """Read a repo's PRs (shared with Team Flow's local copy), issues, star history and, if this token may, traffic."""
+    owner, name = repo.split("/", 1)
+    root = Path(root or home())
+    prs = FlowStore(root / "flow" / repo.replace("/", "__"))
+    folder = root / "community" / repo.replace("/", "__")
+    issues = FlowStore(folder, "issues")
+    gql = make_gql(tok)
+    got_prs = collect(gql, prs, owner, name, now, months=months, log=log)
+    got = collect_issues(gql, issues, owner, name, now, months=months)
+    notes = []
+    try:
+        collect_stars(make_api(tok, repo, max_requests=110), folder, now)
+    except (APIError, OutOfBudget) as exc:
+        notes.append(f"Star history wasn't read ({exc}).")
+    try:
+        # Only a token with Administration read on this repo (yours, if you own it) may read traffic.
+        collect_traffic(make_api(tok, repo, max_requests=10), folder, now)
+    except (APIError, OutOfBudget):
+        pass
+    bench, star_bench = load_benchmarks(root / "bench", tok)
+    result = build(prs.load(), issues.load(), _read(folder / "stars.json"), _read(folder / "traffic.json"), prs.repo(), now,
+                   bench=bench, star_bench=star_bench)
+    return result, {"complete": got_prs["complete"] and got["complete"], "issues_refused": bool(got.get("refused")),
+                    "notes": notes}
+
+
+def main(argv: list[str] | None = None, now: datetime | None = None, make_gql=local_gql, make_api=ActionsAPI,
+         tok: str | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="stackvitals community",
+                                     description="Community: where newcomers drop out and how fast they get a first answer.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    rep = sub.add_parser("report", help="Read a repo's PRs, issues and stars and show its newcomer funnel and first answers")
+    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("--json", action="store_true")
+    rep.add_argument("--html", help="also write the page and badges into this folder")
+    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)
+    try:
+        result, stats = local_community(args.repo, tok, now, months=args.months, make_gql=make_gql, make_api=make_api,
+                                        log=lambda line: print(line, file=sys.stderr, flush=True))
+    except GraphQLError as exc:
+        print(f"GitHub refused: {exc}", file=sys.stderr)
+        return 1
+    if args.html:
+        write_community_outputs(Path(args.html), result, args.repo)
+    if args.json:
+        print(json.dumps({**result, "collect": stats}, indent=1))
+        return 0
+    print(render_text(result, args.repo))
+    for note in stats["notes"]:
+        print(f"\n({note})")
+    if not stats["complete"]:
+        print("\n(Not all pull requests and issues were read yet; run the same command again to continue.)")
+    return 0

stackvitals/community/collect.py

@@ -0,0 +1,240 @@
+"""What Community adds to Team Flow's PR history: issues with their first replies, the weekly star history and, when the
+user set up a token that may read it, traffic (GitHub deletes it after 14 days)."""
+import json
+from collections import defaultdict
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from mergescout.github.graphql import GraphQLError, RateLimited
+from stackvitals.flow.store import FlowStore
+
+ISSUES_QUERY = """
+query($owner:String!,$name:String!,$cursor:String,$n:Int!,$since:DateTime) {
+  rateLimit { cost remaining resetAt }
+  repository(owner:$owner,name:$name) {
+    issues(first:$n, after:$cursor, orderBy:{field:UPDATED_AT, direction:DESC}, filterBy:{since:$since}) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number state createdAt updatedAt closedAt author { __typename login } authorAssociation
+        labels(first:10) { nodes { name } }
+        comments(first:10) { totalCount nodes { createdAt author { __typename login } authorAssociation } }
+        closer: timelineItems(last:1, itemTypes:[CLOSED_EVENT]) { nodes { ... on ClosedEvent { createdAt actor { login } } } }
+        triage: timelineItems(first:5, itemTypes:[LABELED_EVENT, ASSIGNED_EVENT, MARKED_AS_DUPLICATE_EVENT]) {
+          nodes { ... on LabeledEvent { createdAt actor { __typename login } } ... on AssignedEvent { createdAt actor { __typename login } }
+                  ... on MarkedAsDuplicateEvent { createdAt actor { __typename login } } } }
+      }
+    }
+  }
+}"""
+SCHEMA = 3  # 3: who triaged each issue (labels, assignments, duplicates)
+OVERLAP = timedelta(hours=1)
+# Discussions: questions answered there instead of in issues (no `since` filter, so pages stop at the last read).
+DISCUSSIONS_QUERY = """
+query($owner:String!,$name:String!,$cursor:String,$n:Int!) {
+  rateLimit { cost remaining resetAt }
+  repository(owner:$owner,name:$name) {
+    discussions(first:$n, after:$cursor, orderBy:{field:UPDATED_AT, direction:DESC}) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number createdAt updatedAt closed closedAt answerChosenAt author { __typename login } authorAssociation
+        category { name isAnswerable }
+        comments(first:10) { totalCount nodes { createdAt author { __typename login } authorAssociation } }
+      }
+    }
+  }
+}"""
+
+
+def issue_record(node: dict, now: datetime) -> dict:
+    """One issue as a compact record: who opened it and when the first replies came (their text is never read)."""
+    author = node.get("author") or {}
+    talk = [[c.get("createdAt"), (c.get("author") or {}).get("login"), c.get("authorAssociation"),
+             (c.get("author") or {}).get("__typename")]
+            for c in (node.get("comments") or {}).get("nodes") or [] if c and c.get("createdAt")]
+    return {"t": "issue", "n": node["number"], "st": node.get("state"), "cr": node.get("createdAt"),
+            "up": node.get("updatedAt"), "cl": node.get("closedAt"), "au": author.get("login"), "at": author.get("__typename"),
+            "as": node.get("authorAssociation"), "cm": sorted(talk, key=lambda c: c[0]),
+            "cmn": (node.get("comments") or {}).get("totalCount"),
+            # Who closed it: an author closing their own issue is not an answer.
+            "clb": (((((node.get("closer") or {}).get("nodes") or [None])[-1]) or {}).get("actor") or {}).get("login"),
+            # Who labelled, assigned or marked it a duplicate: on GitHub only people with triage rights can, on others' issues.
+            "tr": sorted({((e.get("actor") or {}).get("login"), e.get("createdAt")) for e in ((node.get("triage") or {}).get("nodes") or [])
+                          if e and e.get("createdAt") and (e.get("actor") or {}).get("__typename") == "User"
+                          and (e.get("actor") or {}).get("login") not in (None, author.get("login"))}),
+            # Labels say which issues are incidents (Delivery's change failure rate).
+            "lb": [x["name"] for x in (node.get("labels") or {}).get("nodes") or [] if x and x.get("name")],
+            "f": now.strftime("%Y-%m-%dT%H:%M:%SZ")}
+
+
+def discussion_record(node: dict, now: datetime) -> dict:
+    """A discussion kept like an issue (the same answer rule reads both), with its category and when an answer was chosen."""
+    rec = issue_record({**node, "state": "CLOSED" if node.get("closed") else "OPEN"}, now)
+    cat = node.get("category") or {}
+    return {**rec, "t": "discussion", "cat": cat.get("name"), "qa": bool(cat.get("isAnswerable")), "ans": node.get("answerChosenAt")}
+
+
+def collect_discussions(gql, store: FlowStore, owner: str, name: str, now: datetime, months: int = 12, page: int = 50,
+                        max_pages: int = 40) -> dict:
+    """Discussions updated since the last run (or the last `months`), newest first, stopping at what was already read."""
+    state = store.state()
+    floor = (datetime.fromisoformat(state["synced_up_to"].replace("Z", "+00:00")) - OVERLAP if state.get("synced_up_to")
+             else now - timedelta(days=30 * months)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    opened, closed = store.open(), defaultdict(list)
+    cursor, newest, count, cost, complete, pages = None, None, 0, 0, True, 0
+    while pages < max_pages:
+        try:
+            result = gql.query(DISCUSSIONS_QUERY, {"owner": owner, "name": name, "cursor": cursor, "n": page})
+        except RateLimited:
+            complete = False
+            break
+        except GraphQLError as exc:
+            # Discussions off, or the token can't read them: nothing to keep, and the run goes on.
+            return {"discussions": 0, "points": cost, "complete": False, "refused": "not accessible" in str(exc).lower()}
+        pages += 1
+        cost += result.cost
+        block = (result.data.get("repository") or {}).get("discussions") or {"nodes": [], "pageInfo": {}}
+        stop = False
+        for node in block["nodes"]:
+            if not node:
+                continue
+            if node["updatedAt"] < floor:
+                stop = True
+                break
+            newest = newest or node["updatedAt"]
+            rec = discussion_record(node, now)
+            count += 1
+            if rec["st"] == "OPEN":
+                opened[rec["n"]] = rec
+            else:
+                opened.pop(rec["n"], None)
+                closed[(rec["cl"] or rec["up"])[:10]].append(rec)
+        if stop or not (block.get("pageInfo") or {}).get("hasNextPage"):
+            break
+        cursor = block["pageInfo"]["endCursor"]
+    else:
+        complete = False
+    for day, recs in closed.items():
+        store.put(recs, day)
+    store.save_open(opened)
+    if complete:
+        state["synced_up_to"] = max(filter(None, [newest, state.get("synced_up_to")]), default=None)
+    store.save_state(state)
+    return {"discussions": count, "points": cost, "complete": complete}
+
+
+def collect_issues(gql, store: FlowStore, owner: str, name: str, now: datetime, months: int = 12, page: int = 50,
+                   max_pages: int = 200) -> dict:
+    """Issues updated since the last run (or the last `months` on the first), about 1 point per 50 issues."""
+    state = store.state()
+    synced = state.get("synced_up_to") if state.get("schema", 0) >= SCHEMA else None
+    floor = (datetime.fromisoformat(synced.replace("Z", "+00:00")) - OVERLAP if synced
+             else now - timedelta(days=30 * months)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    opened, closed = store.open(), defaultdict(list)
+    cursor, newest, count, cost, complete, pages = None, None, 0, 0, True, 0
+    while pages < max_pages:
+        try:
+            result = gql.query(ISSUES_QUERY, {"owner": owner, "name": name, "cursor": cursor, "n": page, "since": floor})
+        except RateLimited:
+            complete = False
+            break
+        except GraphQLError as exc:
+            text = str(exc).lower()
+            # The workflow lacks `issues: read`: said in the summary, and the rest of the run goes on.
+            if "not accessible" in text:
+                return {"issues": 0, "points": cost, "complete": False, "refused": True}
+            # Issues turned off in this repo: nothing to read.
+            if "disabled" in text:
+                break
+            raise
+        pages += 1
+        cost += result.cost
+        block = (result.data.get("repository") or {}).get("issues") or {"nodes": [], "pageInfo": {}}
+        stop = False
+        for node in block["nodes"]:
+            if not node:
+                continue
+            # The filter keeps older issues out; this guards against GitHub returning one anyway.
+            if node["updatedAt"] < floor:
+                stop = True
+                break
+            newest = newest or node["updatedAt"]
+            rec = issue_record(node, now)
+            count += 1
+            if rec["st"] == "OPEN":
+                opened[rec["n"]] = rec
+            else:
+                opened.pop(rec["n"], None)
+                closed[(rec["cl"] or rec["up"])[:10]].append(rec)
+        if stop or not (block.get("pageInfo") or {}).get("hasNextPage"):
+            break
+        cursor = block["pageInfo"]["endCursor"]
+    else:
+        complete = False
+    for day, recs in closed.items():
+        store.put(recs, day)
+    store.save_open(opened)
+    if complete:
+        state["synced_up_to"] = max(filter(None, [newest, synced]), default=None)
+        state["schema"] = SCHEMA
+    state["last_collect"] = now.strftime("%Y-%m-%dT%H:%M:%SZ")
+    store.save_state(state)
+    store.compress(now.date().isoformat())
+    return {"issues": count, "points": cost, "complete": complete}
+
+
+def _read(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _write(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, sort_keys=True, separators=(",", ":")), encoding="utf-8", newline="\n")
+
+
+def collect_stars(api, folder: Path, now: datetime, max_pages: int = 100) -> dict:
+    """GitHub's weekly star counts (no stargazer names): all of it the first time, then the newest 30 weeks once a day."""
+    path = Path(folder) / "stars.json"
+    old = _read(path)
+    weeks = {str(k): v for k, v in (old.get("weeks") or {}).items()}
+    if (old.get("fetched") or "")[:10] == now.strftime("%Y-%m-%d"):
+        return {"requests": 0, "weeks": len(weeks)}
+    requests = 0
+    for page in range(1, (1 if weeks else max_pages) + 1):
+        rows = api._get(f"/repos/{api.repo}/stargazers/history", {"per_page": 30, "page": page})
+        requests += 1
+        if not isinstance(rows, list) or not rows:
+            break
+        for r in rows:
+            if isinstance(r, dict) and isinstance(r.get("week"), int):
+                weeks[str(r["week"])] = int(r.get("total") or 0)
+        if len(rows) < 30:
+            break
+    _write(path, {"weeks": weeks, "fetched": now.strftime("%Y-%m-%dT%H:%M:%SZ")})
+    return {"requests": requests, "weeks": len(weeks)}
+
+
+def collect_traffic(api, folder: Path, now: datetime, keep_days: int = 400) -> dict:
+    """Views and clones per day kept past GitHub's 14 days; the top referrers and paths as a dated snapshot.
+    Needs a token with Administration read (the user's own GitHub App), which the built-in token can't have."""
+    path = Path(folder) / "traffic.json"
+    out = {k: dict(_read(path).get(k) or {}) for k in ("views", "clones", "referrers", "paths")}
+    for key in ("views", "clones"):
+        body = api._get(f"/repos/{api.repo}/traffic/{key}", {"per": "day"})
+        for x in body.get(key) or []:
+            if isinstance(x, dict) and x.get("timestamp"):
+                # The newest answer wins: today's count grows during the day.
+                out[key][x["timestamp"][:10]] = [int(x.get("count") or 0), int(x.get("uniques") or 0)]
+    day = now.strftime("%Y-%m-%d")
+    refs = api._get(f"/repos/{api.repo}/traffic/popular/referrers")
+    out["referrers"][day] = [[r.get("referrer"), r.get("count"), r.get("uniques")] for r in refs or [] if isinstance(r, dict)][:10]
+    # Page titles are text anyone can set; only the paths are kept.
+    paths = api._get(f"/repos/{api.repo}/traffic/popular/paths")
+    out["paths"][day] = [[p.get("path"), p.get("count"), p.get("uniques")] for p in paths or [] if isinstance(p, dict)][:10]
+    oldest = (now - timedelta(days=keep_days)).strftime("%Y-%m-%d")
+    for key in ("referrers", "paths"):
+        out[key] = {d: v for d, v in out[key].items() if d >= oldest}
+    _write(path, out)
+    return {"requests": 4, "days": len(out["views"])}

stackvitals/community/context.py

@@ -0,0 +1,54 @@
+"""What a repo states about itself, read once a week and shown beside its numbers: a governance file, funding links, a
+security policy, a code of conduct, Discussions, how many maintainers it lists, and any response time its contributing
+guide promises (so a slow first answer is read against the project's own word). File text is read, never kept."""
+import re
+
+from mergescout.github.graphql import GraphQLError, RateLimited
+
+PATHS = {"gov": ("GOVERNANCE.md", ".github/GOVERNANCE.md", "docs/GOVERNANCE.md"),
+         "c": ("CONTRIBUTING.md", ".github/CONTRIBUTING.md", "docs/CONTRIBUTING.md"),
+         "m": ("MAINTAINERS", "MAINTAINERS.md"), "o": (".github/CODEOWNERS", "CODEOWNERS")}
+UNITS = {"hour": 1, "day": 24, "week": 168}
+# "respond ... within 3 business days", "triage issues within 48 hours": a promise about people answering.
+PROMISE = re.compile(r"(?i)\b(respond|reply|replies|response|triage|review|get back|acknowledge|answer)\w*\b[^.\n]{0,80}?"
+                     r"\b((?:within|in)\s+(\d+)\s*(?:business\s+|working\s+)?(hour|day|week)s?)")
+
+
+def stated_response(text: str | None) -> dict | None:
+    m = PROMISE.search(text or "")
+    if not m:
+        return None
+    return {"hours": int(m.group(3)) * UNITS[m.group(4).lower()], "said": " ".join(m.group(2).lower().split())}
+
+
+def query() -> str:
+    files = " ".join(f'{k}{i}: object(expression: "HEAD:{p}") {{ ... on Blob {{ byteSize text }} }}'
+                     for k, paths in PATHS.items() for i, p in enumerate(paths, 1))
+    return ("query($owner: String!, $name: String!) { rateLimit { cost remaining resetAt } repository(owner: $owner, name: $name) { isSecurityPolicyEnabled "
+            "hasDiscussionsEnabled codeOfConduct { name } fundingLinks { platform url } " + files + " } }")
+
+
+def _first(repo: dict, k: str) -> dict | None:
+    return next((repo.get(f"{k}{i}") for i in range(1, len(PATHS[k]) + 1) if repo.get(f"{k}{i}")), None)
+
+
+def context_record(repo: dict) -> dict:
+    """The facts, from one GraphQL answer: what is stated, never the files' text."""
+    contributing = (_first(repo, "c") or {}).get("text")
+    listed = [x for x in ((_first(repo, "m") or {}).get("text") or "").splitlines() if x.strip() and not x.lstrip().startswith("#")]
+    owners = {o for line in ((_first(repo, "o") or {}).get("text") or "").splitlines() if not line.lstrip().startswith("#")
+              for o in line.split()[1:] if o.startswith("@")}
+    return {"governance": bool(_first(repo, "gov")), "security_policy": bool(repo.get("isSecurityPolicyEnabled")),
+            "code_of_conduct": (repo.get("codeOfConduct") or {}).get("name"),
+            "funding": [f["platform"] for f in repo.get("fundingLinks") or [] if f and f.get("platform")],
+            "discussions": bool(repo.get("hasDiscussionsEnabled")), "contributing": bool(contributing),
+            "response_policy": stated_response(contributing),
+            "maintainers_listed": len(listed) or None, "code_owners": len(owners) or None}
+
+
+def read_context(gql, owner: str, name: str) -> dict | None:
+    try:
+        repo = (gql.query(query(), {"owner": owner, "name": name}).data or {}).get("repository")
+    except (GraphQLError, RateLimited):
+        return None
+    return context_record(repo) if repo else None

stackvitals/community/report.py

@@ -0,0 +1,250 @@
+import html
+
+from stackvitals import shell
+from stackvitals.flow.report import _md
+
+TRAFFIC_HELP = ("Traffic is off: GitHub keeps views and clones for 14 days only, and the built-in token can't read them. "
+                "To keep them, give the Action a token from your own GitHub App (see docs/modules.md).")
+
+
+
+def _when(stamp: str) -> str:
+    # ISO time as people read it; older files already hold "YYYY-MM-DD HH:MM UTC".
+    return stamp if stamp.endswith("UTC") else stamp[:16].replace("T", " ") + " UTC"
+
+def _h(hours) -> str:
+    if hours is None:
+        return "-"
+    if hours < 1:
+        return "under 1 h"
+    return f"{round(hours)} h" if hours < 48 else f"{hours / 24:.1f} d"
+
+
+def _days(n: int) -> str:
+    return f"{n} day" if n == 1 else f"{n} days"
+
+
+def _pct(x, digits: int = 0) -> str:
+    return "-" if x is None else f"{x:.{digits}%}"
+
+
+def _value(f: dict) -> str:
+    return _h(f["you"]) if f["kind"] == "hours" else _pct(f["you"])
+
+
+def _typical(f: dict) -> str:
+    return _h(f["typical"]) if f["kind"] == "hours" else _pct(f["typical"])
+
+
+def _sections(r: dict) -> list[tuple[str, list[str]]]:
+    """Titled groups of plain-text lines, shared by the terminal, the job summary and the page (the waiting list apart)."""
+    out = []
+    s = r.get("score")
+    if s:
+        lines = [f"Community score {s['score']}/100: on average better than {s['score']}% of {s['group']} "
+                 f"({s['repos']} repos) on {len(s['facts'])} facts."]
+        lines += [f"{f['name']}: {_value(f)} (typical {_typical(f)}), better than about {f['better_than']}%." for f in s["facts"]]
+        if s["left_out"]:
+            lines.append("Not scored yet (too little data here): " + ", ".join(k.replace("_", " ") for k in s["left_out"]) + ".")
+        out.append(("Score", lines))
+    elif not r.get("has_bench"):
+        out.append(("Score", ["No score yet: the public benchmarks aren't available to this run yet."]))
+    else:
+        out.append(("Score", ["No score yet: it needs two of these facts, and there is too little history here: 10+ outside PRs "
+                              "in 90 days, 10+ newcomers two weeks old, 10+ newcomers four months old."]))
+    f = r["funnel"]
+    out.append(("Newcomers, last 12 months", [
+        f"{f['newcomers']} first-time contributors (a first PR or issue here).",
+        (f"Of the {f['judged']} whose first contribution was 90+ days ago, {f['returned']} came back within 90 days "
+         f"({_pct(f['return_rate'])})." if f["judged"] else "None is old enough yet to tell whether they came back."),
+        f"Regulars (active in 3 of the last 4 quarters): {f['regulars']}. Maintainers active: {f['maintainers']}."]))
+    a = r["answers"]
+    lines = []
+    for key, label in (("prs", "Outside PRs"), ("issues", "Outside issues")):
+        x = a[key]
+        if not x["items"] and x.get("earlier"):
+            lines.append(f"No {label.lower()} in the last {a['days']} days ({x['earlier']} in the 9 months before).")
+        elif x["items"] and x["median_hours"] is None:
+            lines.append(f"{label}: {x['items']}, none answered yet.")
+        elif x["items"]:
+            km = x.get("km")
+            if km and km.get("waiting") and not km.get("too_few"):
+                # The median of answered items alone hides the ones still waiting: say both.
+                honest = (f"over {_h(km['at_least'])} (more than half have no answer yet)" if km["median"] is None
+                          else f"{_h(km['median'])} (likely {_h(km['low'])} "
+                               + (f"to {_h(km['high'])})" if km["high"] is not None else "or more)"))
+                lines.append(f"{label}: {x['items']}, answered {_pct(x['answered'])}, first answer after "
+                             f"{_h(x['median_hours'])} among those answered, within a day {_pct(x['within_1d'])}; counting "
+                             f"the {km['waiting']} still waiting, {honest}.")
+            else:
+                lines.append(f"{label}: {x['items']}, answered {_pct(x['answered'])}, first answer after {_h(x['median_hours'])} "
+                             f"(median), within a day {_pct(x['within_1d'])}.")
+    if a.get("left_out"):
+        n = a["left_out"]["accounts"]
+        lines.append(f"Left out: {a['left_out']['items']} items from {n} account{'' if n == 1 else 's'} that opened 20 or more "
+                     "in one day (likely automated).")
+    for key, label in (("newcomers", "Newcomers (their first contribution here)"), ("regulars", "Regulars")):
+        x = (r.get("tenure") or {}).get(key)
+        if x and x["n"]:
+            lines.append(f"{label}: {x['n']}, " + (f"first answer after {_h(x['median_h'])} (median), within a day "
+                                                   f"{_pct(x['answered_1d_share'])}." if x["median_h"] is not None
+                                                   else "too few to say (10 needed)."))
+    n = (a.get("issues") or {}).get("responders")
+    if lines and n:
+        lines.append(f"Issues count a reply from a maintainer or one of {n} regular responder{'' if n == 1 else 's'} (people who "
+                     "answered 10 or more others' issues or first-reviewed 2 or more others' PRs in the last year); PRs count "
+                     "a maintainer's.")
+    out.append((f"First answers by the project, last {a['days']} days", lines or ["No outside PRs or issues in this window."]))
+    d = r.get("dependency")
+    if d:
+        lines = [f"{d['merged']} merged pull requests by {d['people']} people in the last {d['days']} days; the most active "
+                 f"person made {_pct(d['top_share'])} of them. Bus factor {d['bus_factor']}: the fewest people behind half of "
+                 "the merged work."]
+        bus, top = (d.get("peers") or {}).get("bus_factor"), (d.get("peers") or {}).get("top_share")
+        if bus:
+            lines.append(f"{bus['group'][0].upper()}{bus['group'][1:]} ({bus['repos']}): bus factor typically {bus['typical']} "
+                         f"(middle half {bus['low']} to {bus['high']})"
+                         + (f"; the most active person's share typically {_pct(top['typical'])}." if top else "."))
+    else:
+        lines = ["Fewer than 20 merged pull requests by people in the last 180 days: not enough to say who carries the work."]
+    o = r.get("orgs")
+    if o:
+        top = ", ".join(f"{x['org']} {_pct(x['share'])}" for x in o["orgs"][:3])
+        lines.append((f"Elephant factor {o['factor']}: the fewest organisations behind half the work with a known one"
+                      if o["factor"] else "No elephant factor: most of the work is by people with no known organisation")
+                     + f"; {_pct(o['unknown_share'])} has none known" + (f"; {top}." if top else "."))
+    said = (r.get("context") or {}).get("response_policy")
+    if said:
+        lines.append(f"The contributing guide promises an answer {said['said']}.")
+    stated = (r.get("context") or {}).get("stated") or {}
+    if stated.get("capacity"):
+        lines.append(f"In the project's own words, who maintains it: {stated['capacity']}")
+    if stated.get("norms"):
+        lines.append(f"In the project's own words, how it works: {stated['norms']}")
+    out.append(("Who carries the work", lines))
+    lever = r.get("lever")
+    if lever:
+        rows = "; ".join(f"{b['bucket']} {_pct(b['returned'], 1)}" for b in lever["by_answer"])
+        lines = [f"Across {lever['newcomers']:,} newcomers in {lever['repos']} public repos, the share who came back with new work "
+                 f"within 90 days, by how long their first PR waited for an answer: {rows}."]
+        if lever["by_outcome"]:
+            lines.append("By outcome: " + "; ".join(f"{b['outcome']} {_pct(b['returned'], 1)}" for b in lever["by_outcome"])
+                         + ". Newcomers left without an answer came back least often; this is an association across repos, "
+                           "not proof that answering brings a given newcomer back.")
+        out.append(("Newcomers who came back, by first answer (public repos)", lines))
+    st = r.get("stars")
+    if st and st.get("gained_12w") is not None:
+        # Percentages of a few stars mislead; the benchmarks start at 100 stars too.
+        big = (st.get("stars") or 0) >= 100
+        line = f"+{st['gained_12w']:,} stars in the last 12 complete weeks" + (f" ({_pct(st['growth_12w'], 1)} growth)" if big else "")
+        if st.get("peers"):
+            line += f", {st['peers']['place']} of {st['peers']['group']} ({st['peers']['repos']} repos)"
+        out.append(("Stars", [line + "."]))
+    t = r.get("traffic")
+    if t:
+        lines = [f"Last {t['days']} days: {t['views_total']:,} views ({t['visitors_total']:,} unique visitors, summed per day) "
+                 f"and {t['clones_total']:,} clones; kept since {t['since']}."]
+        if t["referrers"]:
+            lines.append("Top referrers (" + str(t["referrers_day"]) + "): "
+                         + ", ".join(f"{x[0]} {x[1]}" for x in t["referrers"][:5]) + ".")
+        out.append(("Traffic", lines))
+    else:
+        out.append(("Traffic", [TRAFFIC_HELP]))
+    return out
+
+
+def _waiting_lines(r: dict, repo: str = "") -> list[str]:
+    def link(w):
+        return f" https://github.com/{repo}/{'pull' if w['kind'] == 'pr' else 'issues'}/{int(w['n'])}" if repo else ""
+    rows = [f"{'PR' if w['kind'] == 'pr' else 'Issue'} #{w['n']}: waiting {_days(w['days'])}{link(w)}" for w in r["waiting"][:20]]
+    if r["waiting_total"] > len(rows):
+        rows.append(f"... and {r['waiting_total'] - len(rows)} more")
+    return rows or ["Nobody's first contribution is waiting for an answer."]
+
+
+def render_text(r: dict, repo: str) -> str:
+    out = [f"{repo}: community, updated {_when(r['generated'])}", ""]
+    sections = _sections(r)
+    for title, lines in sections[:1] + [("Newcomers waiting for a first answer", _waiting_lines(r, repo))] + sections[1:]:
+        out += [title + ":", *[f"  {line}" for line in lines], ""]
+    return "\n".join(out).rstrip()
+
+
+def render_markdown(r: dict, repo: str) -> str:
+    out = [f"### StackVitals Community: {_md(repo)}", ""]
+    sections = _sections(r)
+    for title, lines in sections[:1] + [("Newcomers waiting for a first answer", _waiting_lines(r))] + sections[1:]:
+        out += [f"**{_md(title)}**", *[f"- {_md(line)}" for line in lines], ""]
+    return "\n".join(out).rstrip()
+
+
+def _some(*series) -> bool:
+    # A chart of only gaps and zeros says nothing; the text sections already say so.
+    return any(v for values in series for v in values)
+
+
+def _trends(r: dict) -> str:
+    figs, qs = [], r.get("quarters") or []
+    labels = [q["quarter"] for q in qs]
+    hours = [None if q["median_hours"] is None else round(q["median_hours"], 1) for q in qs]
+    if _some(hours):
+        figs.append(shell.chart("First answers per quarter", "Quarter", labels,
+                                [("Median hours to the project's first answer", hours)], y="hours", fmt=lambda v: f"{v:g} h",
+                                kind="bar"))
+    new, items = [q["newcomers"] for q in qs], [q["items"] for q in qs]
+    if _some(new, items):
+        figs.append(shell.chart("New contributors per quarter", "Quarter", labels,
+                                [("First-time contributors", new), ("Outside PRs and issues", items)], y="count", kind="bar"))
+    weeks = (r.get("stars") or {}).get("weeks") or []
+    if len(weeks) >= 2 and _some([w[1] for w in weeks]):
+        figs.append(shell.chart("Stars per week", "Week", [w[0] for w in weeks], [("Stars", [w[1] for w in weeks])], y="stars"))
+    if not figs:
+        return ""
+    return ("<h2>Trends</h2><p class=mut>Calendar quarters, this one so far. A quarter before the history can tell newcomers "
+            "apart shows no newcomer count.</p>" + shell.charts(figs))
+
+
+def render_html(r: dict, repo: str, pages=()) -> str:
+    e = html.escape
+    kind = {"pr": "pull", "issue": "issues"}
+    body = []
+    sections = _sections(r)
+    for title, lines in sections[:1]:
+        body.append(f"<h2>{e(title)}</h2><ul>" + "".join(f"<li>{e(x)}</li>" for x in lines) + "</ul>")
+    body.append("<h2>Newcomers waiting for a first answer</h2>")
+    if r["waiting"]:
+        body.append("<div class=tbl><table class=find><tr><th>Item</th><th>Waiting</th></tr>" + "".join(
+            f"<tr><td><a href='https://github.com/{e(repo)}/{kind.get(w['kind'], 'issues')}/{int(w['n'])}'>"
+            f"{'PR' if w['kind'] == 'pr' else 'Issue'} #{int(w['n'])}</a></td><td>{_days(int(w['days']))}</td></tr>"
+            for w in r["waiting"]) + "</table></div>")
+        if r["waiting_total"] > len(r["waiting"]):
+            body.append(f"<p class=mut>... and {r['waiting_total'] - len(r['waiting'])} more.</p>")
+    else:
+        body.append("<p>Nobody's first contribution is waiting for an answer.</p>")
+    body.append(_trends(r))
+    for title, lines in sections[1:]:
+        body.append(f"<h2>{e(title)}</h2><ul>" + "".join(f"<li>{e(x)}</li>" for x in lines) + "</ul>")
+    body.append("<footer class=mut>Outside contributors are people who are not owners, members, collaborators or bots. "
+                "Nobody is ranked and nobody is listed as having left. History is kept in this repo's "
+                "<code>stackvitals-data</code> branch. Made by StackVitals.</footer>")
+    return shell.page("Community", repo, "community.html", f"Updated {e(_when(r['generated']))}", "".join(body), pages)
+
+
+def badges(r: dict) -> dict[str, dict]:
+    """Two shields.io endpoint badges: measured facts, and the score (users pick one or both)."""
+    f, s = r.get("facts") or {}, r.get("score")
+    parts = []
+    if f.get("first_answer_hours") is not None:
+        parts.append(f"first answer {_h(f['first_answer_hours'])}")
+    if f.get("newcomer_return_rate") is not None:
+        parts.append(f"newcomers back {_pct(f['newcomer_return_rate'])}")
+    elif f.get("newcomer_answered_share") is not None:
+        parts.append(f"newcomers answered {_pct(f['newcomer_answered_share'])}")
+    facts = {"schemaVersion": 1, "label": "community", "message": " · ".join(parts) or "not enough data yet",
+             "color": "blue" if parts else "lightgrey"}
+    if s:
+        color = "brightgreen" if s["score"] >= 67 else "yellow" if s["score"] >= 40 else "orange"
+        scored = {"schemaVersion": 1, "label": "community score", "message": f"{s['score']}/100", "color": color}
+    else:
+        scored = {"schemaVersion": 1, "label": "community score", "message": "not enough data yet", "color": "lightgrey"}
+    return {"community-badge.json": facts, "community-score.json": scored}