stackvitals 0.1.0__py3-none-any.whl

stackvitals/core/capex.py

@@ -0,0 +1,57 @@
+"""Effort and capitalisation for finance: one row per merged pull request into the default branch (month, link, kind of
+work and how it was decided, its epic or project when Jira or Linear is connected, written by a coding agent or a person)
+as a CSV an auditor can follow back to GitHub, and a monthly summary of author-weeks by kind of work with the agent share.
+Feature work is what teams usually capitalise; the rule stays the team's and its auditor's, these are the facts behind it."""
+import csv
+import io
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+from stackvitals.core.ai_outcomes import mode
+from stackvitals.core.investment import classify
+
+COLUMNS = ("month", "merged_at", "pr", "url", "title", "kind", "decided_by", "epic", "author", "author_kind")
+
+
+def rows(prs: list[dict], repo: str, now: datetime, private: bool, base: str | None = None, months: int = 12,
+         rules: dict | None = None, tracker_types: dict | None = None, epics: dict | None = None) -> list[dict]:
+    """Merged PRs of the last `months` months, oldest first; a public repo's rows carry no titles."""
+    since = (now - timedelta(days=31 * months)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    out = []
+    for p in sorted((p for p in prs if p.get("mg") and p["mg"] >= since and (not base or not p.get("base") or p["base"] == base)),
+                    key=lambda p: p["mg"]):
+        kind, how = classify(p, rules, (tracker_types or {}).get(p["n"]))
+        row = {"month": p["mg"][:7], "merged_at": p["mg"], "pr": p["n"], "url": f"https://github.com/{repo}/pull/{p['n']}",
+               "kind": kind, "decided_by": how, "epic": (epics or {}).get(p["n"]) or "",
+               "author": "agent" if mode(p) == "agent" else "person", "author_kind": mode(p),
+               "_login": (p.get("au") or "").lower()}  # for author-weeks only; never written to the file
+        if private:
+            row["title"] = (p.get("ti") or "")[:200]
+        out.append(row)
+    return out
+
+
+def to_csv(rows: list[dict]) -> str:
+    buf = io.StringIO()
+    w = csv.DictWriter(buf, fieldnames=[c for c in COLUMNS if not rows or c in rows[0]], extrasaction="ignore",
+                       lineterminator="\n")
+    w.writeheader()
+    w.writerows(rows)
+    return buf.getvalue()
+
+
+def summary(rows: list[dict]) -> list[dict]:
+    """Per month: merged PRs, author-weeks by kind of work (one author's PRs of one kind in one ISO week count once),
+    the feature share and how many PRs coding agents wrote."""
+    months = defaultdict(lambda: {"prs": 0, "agent_prs": 0, "weeks": defaultdict(set), "kinds": defaultdict(int)})
+    for r in rows:
+        m = months[r["month"]]
+        m["prs"] += 1
+        m["agent_prs"] += r["author"] == "agent"
+        m["kinds"][r["kind"]] += 1
+        week = datetime.fromisoformat(r["merged_at"].replace("Z", "+00:00")).isocalendar()[:2]
+        m["weeks"][r["kind"]].add((r.get("_login"), week))
+    return [{"month": month, "prs": m["prs"], "agent_prs": m["agent_prs"], "kinds": dict(m["kinds"]),
+             "author_weeks": {k: len(v) for k, v in m["weeks"].items()},
+             "feature_share": round(m["kinds"].get("feature", 0) / m["prs"], 4) if m["prs"] else None}
+            for month, m in sorted(months.items())]

stackvitals/core/change_risk.py

@@ -0,0 +1,181 @@
+"""Change risk before merge, from this repo's own history: which merged pull requests caused trouble (later reverted, or
+shipped in a small deployment that then failed), how often changes to the same folders, of the same size, by someone
+new to those folders, without test changes or by a coding agent did, and a score with its reasons for an open one.
+A backtest on the newest pull requests says how much the score is worth here."""
+import math
+import re
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+from stackvitals.core.ai_outcomes import BATCH_MAX, _band, is_revert, mode, revert_target
+
+MIN_TROUBLED = 5   # fewer troubled pull requests and there is no score, not a guess
+MIN_PRS = 30
+PRIOR = 5          # each factor's rate is pulled toward the repo's base rate as if it had 5 more ordinary PRs
+NESTED = {"src", "lib", "libs", "packages", "apps", "services", "pkg", "internal", "app", "cmd"}
+TESTS = ("test", "spec", "__tests__")
+
+
+def troubled(rows: list, incidents: list[dict]) -> set[int]:
+    """Merged PRs a later revert undid, or that shipped in a small deployment (5 PRs or fewer) that failed."""
+    by_number = {p["n"]: p for p, _ph, _d in rows}
+    out = {n for p, _ph, _d in rows if is_revert(p) and (n := revert_target(p, by_number)) is not None}
+    batch = defaultdict(int)
+    for _p, _ph, d in rows:
+        if d:
+            batch[d["id"]] += 1
+    failed = {i.get("deployment") for i in incidents if i.get("deployment")}
+    out |= {p["n"] for p, _ph, d in rows if d and d["id"] in failed and batch[d["id"]] <= BATCH_MAX}
+    return out
+
+
+FIX = re.compile(r"\b(fix|fixes|fixed|bug|bugfix|hotfix|regression)\b", re.I)
+FOLLOW_UP_DAYS = 14
+COMMON = 0.2  # a file most PRs touch (a lockfile, the changelog) links nothing
+
+
+def _when(text: str) -> datetime:
+    return datetime.fromisoformat(text.replace("Z", "+00:00"))
+
+
+def follow_up_fixes(prs: list[dict], days: int = FOLLOW_UP_DAYS) -> set[int]:
+    """Merged PRs that a fix (by its title or a label) changing the same files followed within `days`: the lightweight
+    form of SZZ, the standard way to find changes that needed fixing. Files most PRs touch are ignored."""
+    merged = sorted((p for p in prs if p.get("mg") and p.get("paths")), key=lambda p: p["mg"])
+    if not merged:
+        return set()
+    touched = defaultdict(int)
+    for p in merged:
+        for path in set(p["paths"]):
+            touched[path] += 1
+    common = {f for f, n in touched.items() if n > COMMON * len(merged)}
+    is_fix = lambda p: bool(FIX.search(p.get("ti") or "") or any(FIX.search(x) for x in p.get("lb") or []))  # noqa: E731
+    out = set()
+    for f in (p for p in merged if is_fix(p)):
+        files, end = set(f["paths"]) - common, _when(f["mg"])
+        if not files:
+            continue
+        for p in merged:
+            if p["n"] != f["n"] and not is_fix(p) and end - timedelta(days=days) <= _when(p["mg"]) < end \
+                    and files & set(p["paths"]):
+                out.add(p["n"])
+    return out
+
+
+def _dirs(p: dict) -> set[str]:
+    out = set()
+    for path in p.get("paths") or []:
+        parts = path.split("/")
+        if len(parts) < 2:
+            out.add("(root)")
+        else:
+            depth = 2 if parts[0] in NESTED and len(parts) > 2 else 1
+            out.add("/".join(parts[:depth]) + "/")
+    return out
+
+
+def _tests(p: dict) -> bool:
+    return any(any(t in path.lower() for t in TESTS) for path in p.get("paths") or [])
+
+
+def _facts(p: dict, seen: dict) -> dict:
+    dirs = _dirs(p)
+    who = (p.get("au") or "").lower()
+    return {"dirs": dirs, "band": _band(p), "new": bool(dirs) and not (dirs & seen.get(who, set())),
+            "tests": _tests(p), "agent": mode(p) == "agent"}
+
+
+def fit(prs: list[dict], bad: set[int]) -> dict | None:
+    """Each factor's smoothed troubled rate, learnt from merged PRs oldest first (familiarity as it was at the time)."""
+    prs = sorted((p for p in prs if p.get("mg") and not is_revert(p)), key=lambda p: p["mg"])
+    if len(prs) < MIN_PRS or sum(1 for p in prs if p["n"] in bad) < MIN_TROUBLED:
+        return None
+    base = sum(1 for p in prs if p["n"] in bad) / len(prs)
+    counts = defaultdict(lambda: [0, 0])  # factor -> [PRs, troubled]
+    seen: dict[str, set] = defaultdict(set)
+    for p in prs:
+        f, hit = _facts(p, seen), p["n"] in bad
+        for key in [f"dir:{d}" for d in f["dirs"]] + [f"band:{f['band']}", f"new:{f['new']}", f"tests:{f['tests']}",
+                                                       f"agent:{f['agent']}"]:
+            counts[key][0] += 1
+            counts[key][1] += hit
+        seen[(p.get("au") or "").lower()] |= f["dirs"]
+    rates = {k: (t + PRIOR * base) / (n + PRIOR) for k, (n, t) in counts.items()}
+    return {"base": base, "rates": rates, "counts": {k: v for k, v in counts.items()}, "seen": seen, "prs": len(prs)}
+
+
+def _odds(p: float) -> float:
+    p = min(max(p, 1e-4), 1 - 1e-4)
+    return p / (1 - p)
+
+
+def score(p: dict, model: dict | None) -> dict | None:
+    """{"risk", "level", "reasons"} for one PR; None without a model."""
+    if not model:
+        return None
+    base, rates, counts = model["base"], model["rates"], model["counts"]
+    f = _facts(p, model["seen"])
+    dir_keys = [f"dir:{d}" for d in f["dirs"] if f"dir:{d}" in rates]
+    # The riskiest folder speaks for the change; other factors are combined as odds against the base rate.
+    keys = ([max(dir_keys, key=lambda k: rates[k])] if dir_keys else []) + \
+        [k for k in (f"band:{f['band']}", f"new:{f['new']}", f"tests:{f['tests']}", f"agent:{f['agent']}") if k in rates]
+    log_odds = math.log(_odds(base)) + sum(math.log(_odds(rates[k]) / _odds(base)) for k in keys)
+    risk = 1 / (1 + math.exp(-log_odds))
+    reasons = []
+    for k in keys:
+        if rates[k] < 1.5 * base:
+            continue
+        n, t = counts[k]
+        kind, value = k.split(":", 1)
+        reasons.append({"dir": f"{value}: {t} of {n} changes here caused trouble",
+                        "band": f"a change of about {(p.get('add') or 0) + (p.get('del') or 0):,} lines ({t} of {n} this size did)",
+                        "new": "the author's first change in these folders",
+                        "tests": "no test files changed" if value == "False" else "test files changed",
+                        "agent": "written by a coding agent"}[kind])
+    level = "high" if risk >= 2 * base and risk >= 0.1 else "medium" if risk >= 1.3 * base else "low"
+    return {"risk": round(risk, 4), "level": level, "base": round(base, 4), "reasons": reasons}
+
+
+def _auc(scored: list[tuple[float, bool]]) -> float | None:
+    pos = [s for s, y in scored if y]
+    neg = [s for s, y in scored if not y]
+    if not pos or not neg:
+        return None
+    wins = sum((a > b) + 0.5 * (a == b) for a in pos for b in neg)
+    return wins / (len(pos) * len(neg))
+
+
+def backtest(prs: list[dict], bad: set[int], share: float = 0.7) -> dict | None:
+    """Learn from the oldest 70% of merged PRs and score the newest 30%: how well the score ranks the troubled ones
+    (AUC, 0.5 = no better than chance) and the trouble rate among the top fifth scored."""
+    merged = sorted((p for p in prs if p.get("mg") and not is_revert(p)), key=lambda p: p["mg"])
+    cut = int(len(merged) * share)
+    train, test = merged[:cut], merged[cut:]
+    model = fit(train, bad)
+    hits = [p for p in test if p["n"] in bad]
+    if not model or len(hits) < 3:
+        return None
+    scored = sorted(((score(p, model)["risk"], p["n"] in bad) for p in test), key=lambda x: -x[0])
+    top = scored[:max(1, len(scored) // 5)]
+    return {"train": len(train), "test": len(test), "test_troubled": len(hits), "auc": round(_auc(scored), 3),
+            "top_fifth_trouble": round(sum(y for _s, y in top) / len(top), 3),
+            "overall_trouble": round(len(hits) / len(test), 3)}
+
+
+MIN_AUC = 0.65  # below this, this repo's own backtest says the score isn't worth showing
+
+
+def assess(prs: list[dict], bad: set[int], open_prs: list[dict], top: int = 50) -> dict:
+    """The backtest first; open PRs scored (riskiest first) only when it shows the score ranks trouble here."""
+    bt = backtest(prs, bad)
+    if not bt:
+        return {"backtest": None, "open": None, "troubled": len(bad),
+                "note": "Not enough history yet: it needs about 30 merged pull requests and a few that needed a fix."}
+    if bt["auc"] < MIN_AUC:
+        return {"backtest": bt, "open": None, "troubled": len(bad),
+                "note": f"Not predictive in this repo: on its newest pull requests it ranked trouble about as well as chance "
+                        f"(AUC {bt['auc']:.2f}), so no score is shown."}
+    model = fit(prs, bad)
+    scored = [{"pr": p.get("n"), **score(p, model)} for p in open_prs]
+    scored.sort(key=lambda s: -s["risk"])
+    return {"backtest": bt, "open": scored[:top], "troubled": len(bad), "note": None}

stackvitals/core/changes.py

@@ -0,0 +1,133 @@
+"""Week against baseline: the latest seven days of a number against the four weeks before them, with n on both sides
+and a p-value, so the digest flags only the changes that survive false-alarm control across everything it checked."""
+import math
+from datetime import datetime, timedelta
+
+from stackvitals.core import stats
+from stackvitals.core.time import iso
+
+WEEK, BASE_WEEKS = timedelta(days=7), 4
+HISTORY_WEEKS = 8  # past weeks that show how much this repo's weeks usually swing
+# The typical swing before a repo's own history is known, worth 4 weeks: review times swing 1.5 to 2 times what
+# independent PRs would (20 public repos; 1.5 chosen on half of them, checked on the other half); shares and counts 1.
+PRIOR_SPREAD, PRIOR_WEEKS = {"share": 1.0, "count": 1.0}, 4
+TIME_SPREAD = 1.5
+# One wild past week (a backlog merged at once) counts as at most a four-sigma swing: the same catches as three sigma
+# on 29 public repos, with fewer false flags (7.6% and 8.8% of shuffled scans on each half against 7.9% and 9.7%).
+Z2_CAP = 16.0
+MIN_EACH = 5  # fewer on either side and a shift says nothing
+Q = 0.1  # the share of flagged changes allowed to be false alarms, across one scan
+
+
+def windows(now: datetime, weeks: int = 1) -> tuple[tuple[str, str], tuple[str, str]]:
+    """(the last `weeks` weeks, the four weeks before them) as ISO bounds, start included and end left out."""
+    cut = now - WEEK * weeks
+    return (iso(cut), iso(now)), (iso(cut - WEEK * BASE_WEEKS), iso(cut))
+
+
+def _row(metric: str, label: str, now, base, n_now: int, n_base: int, p: float, better: int, unit: str,
+         note: str | None = None, **extra) -> dict:
+    direction = None if now is None or base is None else "same" if now == base else "up" if now > base else "down"
+    worse = direction in ("up", "down") and better != 0 and (direction == "up") == (better < 0)
+    return {"metric": metric, "label": label, "now": now, "base": base, "n_now": n_now, "n_base": n_base,
+            "p": round(p, 6), "direction": direction, "better": better, "worse": worse, "unit": unit, "note": note,
+            **extra}
+
+
+def share(metric: str, label: str, k_now: int, n_now: int, k_base: int, n_base: int, better: int) -> dict:
+    """A share this week against the weeks before (Fisher's exact test)."""
+    enough = min(n_now, n_base) >= MIN_EACH
+    p = stats.fisher(k_now, n_now, k_base, n_base) if enough else 1.0
+    value = lambda k, n: round(k / n, 4) if n else None  # noqa: E731
+    return _row(metric, label, value(k_now, n_now), value(k_base, n_base), n_now, n_base, p, better, "share",
+                None if enough else "too few to tell")
+
+
+def times(metric: str, label: str, now_values: list[float], base_values: list[float], better: int, unit: str,
+          span: int = 1) -> dict:
+    """A duration over the last `span` weeks against the four before (medians shown, Mann-Whitney tested)."""
+    a, b = [v for v in now_values if v is not None], [v for v in base_values if v is not None]
+    enough = min(len(a), len(b)) >= MIN_EACH
+    p = stats.mann_whitney(a, b) if enough else 1.0
+    mid = lambda v: None if not v else round(stats.median(v), 2)  # noqa: E731
+    logs = [math.log(max(v, 1 / 60)) for v in b]  # a minute's floor: instant merges would make the log endless
+    log_sd = round(stats.stdev(logs), 4) if len(logs) > 1 else None
+    return _row(metric, label, mid(a), mid(b), len(a), len(b), p, better, unit, None if enough else "too few to tell",
+                log_sd=log_sd, span=span)
+
+
+def count(metric: str, label: str, now_count: int, base_count: int, better: int) -> dict:
+    """A weekly count against the weekly average of the weeks before (binomial on the combined count)."""
+    enough = now_count + base_count >= MIN_EACH
+    p = stats.count_change(now_count, base_count, BASE_WEEKS) if enough else 1.0
+    return _row(metric, label, now_count, round(base_count / BASE_WEEKS, 2), now_count, base_count, p, better, "count",
+                None if enough else "too few to tell")
+
+
+def calibrate(checks_at, now: datetime, weeks: int = HISTORY_WEEKS) -> list[dict]:
+    """This week's checks with each p-value judged against the same check in the repo's past weeks.
+
+    Work arrives in batches (a busy review day, a release week), so events in one week are not independent and a
+    plain test overstates certainty. Each check is also run for each past week against its own four before it; how
+    widely those results swing (their mean squared z, blended with a typical swing worth four weeks) scales this
+    week's z, read on a t-distribution with one degree of freedom per week of evidence (an empirical null).
+    A check over several weeks is judged against past windows that don't overlap it, so an ongoing slowdown doesn't
+    count as the repo's usual swing."""
+    current = checks_at(now)
+    longest = max((c.get("span", 1) for c in current), default=1)
+    past = {j: checks_at(now - WEEK * j) for j in range(1, weeks + longest)}
+    out = []
+    for i, c in enumerate(current):
+        span = c.get("span", 1)
+        z2 = [min(stats.normal_isf(week[i]["p"]) ** 2, Z2_CAP) for week in (past[j] for j in range(span, span + weeks))
+              if i < len(week) and week[i]["note"] is None]
+        if c["note"] is None:
+            prior = PRIOR_SPREAD.get(c["unit"], TIME_SPREAD)
+            spread = max(1.0, (sum(z2) + PRIOR_WEEKS * prior) / (len(z2) + PRIOR_WEEKS))
+            p = stats.t_two_sided(stats.normal_isf(c["p"]) / math.sqrt(spread), len(z2) + PRIOR_WEEKS)
+            c = {**c, "p": round(p, 6), "p_raw": c["p"], "spread": round(spread, 2), "weeks_seen": len(z2),
+                 "df": len(z2) + PRIOR_WEEKS, "scale": _scale(c, spread)}
+        out.append(c)
+    return out
+
+
+def _scale(c: dict, spread: float) -> float | None:
+    # One standard error of the change on its own scale (log time, or share), widened by the repo's usual swing.
+    if c["unit"] == "count" or not c["n_now"] or not c["n_base"]:
+        return None
+    both = math.sqrt(1 / c["n_now"] + 1 / c["n_base"]) * math.sqrt(spread)
+    if c["unit"] == "share":
+        pb = min(max(c["base"] or 0, 0.02), 0.98)
+        return round(math.sqrt(pb * (1 - pb)) * both, 5)
+    if not c.get("log_sd"):
+        return None
+    return round(c["log_sd"] * both * 1.023, 5)  # rank tests on skewed times lose about 2% against the ideal test
+
+
+def detectable(c: dict, run: int, q: float = Q) -> float | None:
+    """The change this check would have caught with about 80% chance in a scan of `run` checks: a factor for times,
+    points of share for shares, None for counts."""
+    if c.get("scale") is None:
+        return None
+    z = stats.t_isf(q / max(run, 1), c["df"]) + 0.8416
+    return round(math.exp(z * c["scale"]) if c["unit"] not in ("share", "count") else z * c["scale"], 4)
+
+
+def flag(found: list[dict], q: float = Q) -> list[dict]:
+    """Every change with `changed` set: True only for those surviving Benjamini-Hochberg over the checks actually run
+    in the scan (one with too few items to tell is not a test, so it doesn't count against the others)."""
+    run = [i for i, c in enumerate(found) if c.get("note") is None]
+    keep = {i for i, k in zip(run, stats.bh([found[i]["p"] for i in run], q)) if k}
+    # A pairing from an earlier pass (a module's own) is decided again here, over this scan's checks.
+    out = [{**{k: v for k, v in c.items() if k != "shown_with"}, "changed": i in keep and c["direction"] in ("up", "down")}
+           for i, c in enumerate(found)]
+    # A slowdown flagged both this week and over 14 days is one finding: the 14-day row is shown with the weekly one.
+    weekly = {c["metric"]: c for c in out if c["changed"]}
+    return [{**c, "shown_with": c["metric"][:-4]} if c["metric"].endswith("_14d") and c["changed"]
+            and weekly.get(c["metric"][:-4], {}).get("direction") == c["direction"] else c for c in out]
+
+
+def annotate(found: list[dict], q: float = Q) -> list[dict]:
+    """A module's checks as its page shows them: flagged within the module, each with the change it could have caught."""
+    run = sum(1 for c in found if c.get("note") is None)
+    return [{**c, "detectable": detectable(c, run, q) if c.get("note") is None else None} for c in flag(found, q)]

stackvitals/core/chat.py

@@ -0,0 +1,143 @@
+"""Chat messages in each chat's own shape: Slack Block Kit with link buttons (and Slack's own markdown), a Teams Adaptive
+Card with open-link actions (Teams Workflows), a Discord embed, or plain JSON for anything else; and which webhook a
+team's message goes to. Buttons only open links: nothing here needs a server to answer clicks."""
+import re
+
+import httpx
+
+BOLD = re.compile(r"\*\*(.+?)\*\*")
+LINK = re.compile(r"\[([^\]]+)\]\((https?://[^)\s]+)\)")
+TEAM_LINE = re.compile(r"^\s*(@?[\w.-]+(?:/[\w.-]+)?)\s*=\s*(https://\S+)\s*$")
+SLACK_SECTION, SLACK_BLOCKS, SLACK_BUTTONS, DISCORD_TEXT = 3000, 50, 5, 4096
+
+
+def message(title: str, lines: list[str], links=(), data: dict | None = None) -> dict:
+    """What every chat gets: a title, Markdown lines (**bold**, `code`, [text](url)), up to five link buttons, and the
+    numbers for plain JSON webhooks."""
+    return {"title": title, "lines": list(lines), "links": list(links), "data": data or {}}
+
+
+def safe(name, size: int = 200) -> str:
+    """A name from the repo (a test, a job, a package) as inert text: one line that can't become a link (no chat pings plain @names)."""
+    out = " ".join(str(name).split())[:size].replace("`", "'")
+    return out.replace("](", "]\u200b(").replace("://", ":\u200b//")
+
+
+def kind(url: str) -> str:
+    if "hooks.slack.com" in url:
+        return "slack"
+    if "discord.com/api/webhooks" in url or "discordapp.com/api/webhooks" in url:
+        return "discord"
+    if "logic.azure.com" in url or "webhook.office.com" in url or "powerplatform.com" in url:
+        return "teams"
+    return "json"
+
+
+def text(msg: dict) -> str:
+    """The message as plain lines (job summaries, fallbacks)."""
+    return "\n".join([msg["title"], *msg["lines"]])
+
+
+def _slack_escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _slack_md(text: str) -> str:
+    text = _slack_escape(text)
+    return LINK.sub(r"<\2|\1>", BOLD.sub(r"*\1*", text))
+
+
+def _chunks(lines: list[str], size: int) -> list[str]:
+    out, cur = [], ""
+    for line in lines:
+        line = line[:size]
+        if cur and len(cur) + 1 + len(line) > size:
+            out.append(cur)
+            cur = line
+        else:
+            cur = f"{cur}\n{line}" if cur else line
+    return out + ([cur] if cur else [])
+
+
+def _slack(msg: dict) -> dict:
+    blocks = [{"type": "header", "text": {"type": "plain_text", "text": msg["title"][:150]}}]
+    sections = _chunks([_slack_md(x) for x in msg["lines"]], SLACK_SECTION)
+    room = SLACK_BLOCKS - 1 - (1 if msg["links"] else 0)
+    blocks += [{"type": "section", "text": {"type": "mrkdwn", "text": s}} for s in sections[:room]]
+    if msg["links"]:
+        blocks.append({"type": "actions", "elements": [
+            {"type": "button", "text": {"type": "plain_text", "text": label[:75]}, "url": url}
+            for label, url in msg["links"][:SLACK_BUTTONS]]})
+    # The fallback is read as Slack markup too (notifications), so it is escaped like the sections.
+    return {"text": _slack_escape(text(msg))[:3000], "blocks": blocks}
+
+
+def _teams(msg: dict) -> dict:
+    card = {"type": "AdaptiveCard", "version": "1.4", "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+            "body": [{"type": "TextBlock", "text": msg["title"], "weight": "Bolder", "size": "Medium", "wrap": True},
+                     *({"type": "TextBlock", "text": line, "wrap": True} for line in msg["lines"])],
+            "actions": [{"type": "Action.OpenUrl", "title": label, "url": url} for label, url in msg["links"][:SLACK_BUTTONS]]}
+    return {"type": "message", "attachments": [{"contentType": "application/vnd.microsoft.card.adaptive", "content": card}]}
+
+
+def _discord(msg: dict) -> dict:
+    links = " · ".join(f"[{label}]({url})" for label, url in msg["links"])
+    body = "\n".join(msg["lines"])
+    room = DISCORD_TEXT - len(links) - 2
+    text = (body if len(body) <= room else body[:room - 1] + "…") + (f"\n\n{links}" if links else "")
+    return {"embeds": [{"title": msg["title"][:256], "description": text[:DISCORD_TEXT],
+                        **({"url": msg["links"][0][1]} if msg["links"] else {})}], "allowed_mentions": {"parse": []}}
+
+
+def payload(url: str, msg: dict) -> dict:
+    shape = kind(url)
+    if shape == "slack":
+        return _slack(msg)
+    if shape == "teams":
+        return _teams(msg)
+    if shape == "discord":
+        return _discord(msg)
+    return {"source": "stackvitals", "title": msg["title"], "text": text(msg),
+            "links": [{"label": label, "url": url} for label, url in msg["links"]], **msg["data"]}
+
+
+def post(url: str, msg: dict, client: httpx.Client | None = None, what: str = "the webhook") -> str | None:
+    """Post a message in the chat's own shape; a failure comes back as text for the job summary, never as an exception."""
+    url = url.strip()  # a secret pasted with a trailing newline
+    try:
+        response = (client or httpx.Client(timeout=30)).post(url, json=payload(url, msg))
+    except (httpx.HTTPError, httpx.InvalidURL) as exc:
+        return f"Could not send {what} ({type(exc).__name__})."
+    if response.status_code >= 300:
+        return f"{what[0].upper()}{what[1:]} answered {response.status_code}."
+    return None
+
+
+def app_url(repo: str, info: dict | None, route: str = "") -> str | None:
+    """The monitor's address on GitHub Pages, when the repo is public and publishes Pages; else None."""
+    if not info or info.get("private") or not info.get("has_pages"):
+        return None
+    owner, name = repo.split("/")
+    base = f"https://{owner.lower()}.github.io/" if name.lower() == f"{owner.lower()}.github.io" else f"https://{owner.lower()}.github.io/{name}/"
+    return base + (f"#/{route}" if route else "")
+
+
+def team_hooks(env: dict) -> dict[str, str]:
+    """`STACKVITALS_TEAM_WEBHOOKS`, one `owner = https://...` per line (owners as CODEOWNERS names them, @org/team)."""
+    out = {}
+    for line in (env.get("STACKVITALS_TEAM_WEBHOOKS") or "").splitlines():
+        found = TEAM_LINE.match(line)
+        if found:
+            out[found.group(1)] = found.group(2)
+    return out
+
+
+def route(owners_by_item: dict[str, list[str]], env: dict) -> dict[str, list[str]]:
+    """Which webhook gets which items: each owning team with its own webhook gets its items, the rest go to the default."""
+    teams, default = team_hooks(env), (env.get("STACKVITALS_WEBHOOK") or "").strip()
+    out = {}
+    for item, owners in owners_by_item.items():
+        hooks = [teams[o] for o in owners or [] if o in teams]
+        for hook in dict.fromkeys(hooks or ([default] if default else [])):
+            out.setdefault(hook, []).append(item)
+    return out