stackvitals 0.1.0__py3-none-any.whl

stackvitals/portal/action.py

@@ -0,0 +1,205 @@
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from stackvitals.ci.action import BRANCH, DataBranch, GitError
+from stackvitals.ci.api import ActionsAPI
+from stackvitals.flow.action import FLOW_EVENTS
+from stackvitals.flow.action import make_gql as _gql
+import httpx
+
+from stackvitals.ci import bench as ci_bench
+from stackvitals.flow import peers as flow_peers
+from stackvitals.portal.catalog import build_catalog
+from stackvitals.ci.api import APIError, OutOfBudget
+from stackvitals.portal.catalog import cacheable
+from stackvitals.portal.export import entities_yaml
+from stackvitals.portal.checks import CAP as CHECKS_CAP
+from stackvitals.portal.checks import load_level, plan
+from stackvitals.portal.golden import GoldenError, load_paths
+from stackvitals.portal.rollup import org_rollup
+from stackvitals.portal.checks import send as send_checks
+from stackvitals.portal.campaigns import load_campaigns, progress, reminder_text, reminders_due, update_tracking_issue
+from stackvitals.portal.github import NA, read, read_file
+from stackvitals.portal.history import since
+from stackvitals import shell
+from stackvitals.portal.pages import _cell, publishable, render_catalog, render_catalog_html
+from stackvitals.portal.scorecard import file_rules, rules_or_default, score_catalog
+from stackvitals.core.store import accept, published
+
+def _scorecard_client() -> httpx.Client:
+    return httpx.Client(timeout=20)
+
+
+LABEL = "Portal"
+SETUP = ("Public mode: only the org's public repos are read. To include private repos, give the Action a token from an "
+         "org-owned read-only GitHub App as `portal-token` (see docs/modules.md).")
+
+
+def _history_row(r: dict) -> dict:
+    # One compact line per repo per day: enough for "since when" and campaign progress later.
+    o = r.get("owners") or {}
+    return {"name": r["name"], "archived": r.get("archived"), "language": r.get("language"), "owners": o.get("status"),
+            "why": len(o.get("reasons") or []),
+            "level": (r.get("score") or {}).get("level"),
+            "failed": [x["id"] for x in (r.get("score") or {}).get("results") or [] if x["result"] == "fail"],
+            "modules": r.get("modules"), "rules": r.get("rules"), "checked": r.get("checked")}
+
+
+def portal_step(ws, env: dict, now: datetime, make_api=ActionsAPI) -> dict:
+    """Portal's part of a job: the catalog, a daily history line per repo and the pages into the shared checkout;
+    after the commit, the campaign tracking issues and the summary."""
+    repo, builtin = ws.repo, env.get("STACKVITALS_TOKEN") or env.get("GITHUB_TOKEN")
+    app = (env.get("STACKVITALS_PORTAL_TOKEN") or "").strip()
+    org = (env.get("STACKVITALS_PORTAL_ORG") or "").strip() or repo.split("/")[0]
+    mode = "private" if app else "public"
+    own = make_api(builtin, repo, max_requests=5)
+    here = read(own, f"/repos/{repo}")
+    # The org's own rules live in this repo as portal.toml; without it the default pack applies.
+    text = read_file(own, repo, "portal.toml")
+    rules, exemptions, rule_notes = rules_or_default(None if text is NA else text)
+    try:
+        campaigns = load_campaigns(None if text is NA else text)
+    except ValueError:
+        campaigns = []  # a broken file was already reported by the rules note
+    # Unknown visibility counts as public: the safe side.
+    destination_private = bool(here.get("private")) if here is not NA and isinstance(here, dict) else False
+    folder = ws.path / "portal"
+    folder.mkdir(parents=True, exist_ok=True)
+    try:
+        previous = accept(json.loads((folder / "catalog.json").read_text(encoding="utf-8")))
+    except (OSError, ValueError):
+        previous = None
+    api = make_api(app or builtin, repo, max_requests=4000 if app else 700)
+    # Conditional reads kept between runs: a repo whose rules and owners didn't change costs nothing the next day.
+    try:
+        api.etags = json.loads((folder / "etags.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        api.etags = {}
+    api.cacheable = cacheable
+    catalog = build_catalog(api, org, mode, now, previous=previous, scorecard_client=_scorecard_client(),
+                            gql=_gql(app or builtin), file_rules=file_rules(rules))
+    # Peer levels need the public benchmark files (none before launch: those rules are "not available").
+    bench = {"ci": ci_bench.load(None, ws.work / "bench"), "flow": flow_peers.load(None, ws.work / "bench")}
+    score_catalog(catalog, rules, exemptions, now, bench)
+    # Since when each repo has had its owner status and level, from the days already kept.
+    when = since(folder / "history", catalog["repos"], now.strftime("%Y-%m-%d"))
+    for r in catalog["repos"]:
+        if r.get("score"):
+            r["since"] = when.get(r["name"])
+    kept = publishable(catalog["repos"], destination_private)
+    # The org view, from the facts the repos this page may show publish themselves.
+    catalog["org_view"] = org_rollup(kept)
+    # Campaign progress only ever counts repos this page may show.
+    catalog["campaigns"] = [progress(c, kept, folder / "history", now) for c in campaigns]
+    # The golden paths people may run from the app (what each is, never the App's token).
+    try:
+        golden = load_paths(None if text is NA else text)
+    except (GoldenError, ValueError) as exc:
+        golden, rule_notes = {}, [*rule_notes, f"Golden paths in portal.toml: {exc}"]
+    catalog["golden"] = [{k: g[k] for k in ("id", "title", "kind", "description", "private")} for g in golden.values()]
+    catalog["golden_ready"] = bool(app)
+    (folder / "catalog.json").write_text(json.dumps(published({**catalog, "repos": kept}), indent=1), encoding="utf-8")
+    # Kept answers name repos and hold their rules: never on a public portal repo that reads private repos, and only
+    # for repos still listed.
+    if isinstance(getattr(api, "etags", None), dict) and (destination_private or mode == "public"):
+        live = tuple(f"/repos/{r['name']}/" for r in catalog["repos"])
+        kept_tags = {k: v for k, v in api.etags.items() if k.startswith(live) or k.startswith(f"/orgs/{org}/")}
+        (folder / "etags.json").write_text(json.dumps(kept_tags, separators=(",", ":")), encoding="utf-8")
+    else:
+        (folder / "etags.json").unlink(missing_ok=True)
+    (folder / "README.md").write_text(render_catalog(catalog, destination_private), encoding="utf-8")
+    # Backstage: one location file for the repos without their own catalog-info.yaml.
+    pages = here.get("has_pages") and not destination_private if isinstance(here, dict) else False
+    owner, name = repo.split("/")
+    (folder / "entities.yaml").write_text(entities_yaml(kept, f"https://{owner.lower()}.github.io/{name}/" if pages else None),
+                                          encoding="utf-8")
+    docs = ws.path / "docs"
+    docs.mkdir(parents=True, exist_ok=True)
+    (docs / "portal.html").write_text(render_catalog_html(catalog, destination_private, shell.present(docs) | {"portal.html"}),
+                                      encoding="utf-8")
+    (folder / "history").mkdir(exist_ok=True)
+    (folder / "history" / f"{now:%Y-%m-%d}.json").write_text(
+        json.dumps({"built_at": catalog["built_at"], "repos": [_history_row(r) for r in kept]}, separators=(",", ":")),
+        encoding="utf-8")
+    left_out = len(catalog["repos"]) - len(kept)
+    out = {"mode": mode, "repos": len(kept), "complete": catalog["complete"], "left_out": left_out}
+    # Deadline reminders, once each: remembered before the commit so an overlapping run never sends one twice.
+    sent_file = folder / "reminders.json"
+    try:
+        sent = json.loads(sent_file.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        sent = {}
+    remind = reminders_due(catalog.get("campaigns") or [], sent, now)
+    if remind:
+        for p, days in remind:
+            sent.setdefault(p["id"], []).append(days)
+        sent_file.write_text(json.dumps(sent, indent=1, sort_keys=True), encoding="utf-8")
+
+    # Opt-in required check: only with the org App (it writes to every repo) and a level in portal.toml.
+    level = load_level(None if text is NA else text)
+    checks = plan(catalog, level) if level and app else []
+    # The cap would always stop at the same repo: each run starts where the last one stopped.
+    cursor_file = folder / "checks-cursor.json"
+    try:
+        start = int(json.loads(cursor_file.read_text(encoding="utf-8")).get("next", 0)) % max(len(checks), 1)
+    except (OSError, ValueError, TypeError):
+        start = 0
+    checks = checks[start:] + checks[:start]
+    if checks:
+        # Saved before the commit (sends come after it): the next run starts about where this one's cap will end.
+        cursor_file.write_text(json.dumps({"next": (start + CHECKS_CAP // 3) % len(checks)}), encoding="utf-8")
+
+    def after_commit():
+        issue_notes = []
+        if level and not app:
+            issue_notes.append(f"[checks] level = \"{level}\" needs the org App (with Checks: write) to post checks.")
+        if checks:
+            done = send_checks(make_api(app, repo, max_requests=1000), checks)
+            issue_notes.append(f"Portal checks: {done['posted']} posted for {level}"
+                               + ("; stopped at the cap, the next run carries on" if done["stopped"] else "")
+                               + (f"; refused for {len(done['refused'])} repos (the App needs Checks: write)" if done["refused"] else "")
+                               + ".")
+        for p in catalog.get("campaigns") or []:
+            try:
+                number = update_tracking_issue(make_api(builtin, repo, max_requests=10), repo, p)
+                for q, days in remind:
+                    if q["id"] == p["id"] and number:
+                        make_api(builtin, repo, max_requests=3).send("POST", f"/repos/{repo}/issues/{number}/comments",
+                                                                     {"body": reminder_text(p, days)})
+            except (APIError, OutOfBudget):
+                issue_notes = ["Add `issues: write` to this workflow's permissions to keep one tracking issue per campaign."]
+        summary = env.get("GITHUB_STEP_SUMMARY")
+        if summary:
+            active = [r for r in kept if not r.get("archived") and not r.get("fork")]
+            counts = {s: sum(1 for r in active if (r.get("owners") or {}).get("status") == s) for s in ("valid", "weak", "none")}
+            notes = [f"### StackVitals Portal: {_cell(org)}",
+                     f"{len(kept)} repos; owners {counts['valid']} valid, {counts['weak']} weak, {counts['none']} without CODEOWNERS. "
+                     f"The catalog is in this repo's `{BRANCH}` branch, `portal/README.md`."]
+            if mode == "public":
+                notes.append(SETUP)
+            notes += rule_notes + issue_notes
+            if left_out:
+                notes.append(f"This portal repo is public, so its private repos were left out ({left_out}).")
+            if not catalog["complete"]:
+                notes.append("Some repos keep an earlier check (GitHub's hourly limit); the next run continues with them.")
+            with open(summary, "a", encoding="utf-8") as f:
+                f.write("\n\n".join(notes) + "\n")
+    ws.after_commit(after_commit, LABEL)
+    return out
+
+
+def run_portal_action(env: dict, now: datetime | None = None, make_api=ActionsAPI, workspace=None) -> dict | None:
+    """One Portal run in the org's portal repo: the catalog, a daily history line per repo and the pages, kept in this
+    repo's data branch. A public portal repo never receives private-repo data."""
+    if env.get("GITHUB_EVENT_NAME") not in FLOW_EVENTS:
+        return None
+    from stackvitals.core.workspace import run_job
+    now = now or datetime.now(timezone.utc)
+
+    def step(ws):
+        return portal_step(ws, env, now, make_api)
+    if workspace is not None:
+        return step(workspace)
+    job = run_job(env, [(LABEL, step)], now, message=f"stackvitals: portal {now:%Y-%m-%d %H:%M} UTC", catch=False)
+    return {**job["results"][LABEL], "pushed": job["outcome"] == "pushed"}

stackvitals/portal/batch.py

@@ -0,0 +1,80 @@
+"""The light core: one GraphQL query reads ten repos' files at once (CODEOWNERS, catalog-info.yaml, the rule files, the
+root and docs/ listings, the community files GitHub resolves, the suite's facts on the data branch), instead of a REST
+request per file per repo. The readers in inventory.py and owners.py take what this found and ask REST only for the rest."""
+import json
+
+from mergescout.github.graphql import GraphQLError, RateLimited
+
+BATCH = 10
+# How a repo runs, from its root folder's names alone (no extra request).
+RUNTIMES = (("kubernetes", ("k8s", "kubernetes", "charts", "helm", "chart.yaml", "kustomization.yaml", "skaffold.yaml")),
+            ("container", ("dockerfile", "containerfile", "compose.yaml", "docker-compose.yml", "docker-compose.yaml")),
+            ("terraform", ("terraform", "main.tf", "infra")), ("serverless", ("serverless.yml", "serverless.yaml", "template.yaml")))
+CODEOWNERS_PATHS = (".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS")
+DATA = "stackvitals-data"
+
+
+def _blob(alias: str, expression: str) -> str:
+    return f"{alias}: object(expression: {json.dumps(expression)}) {{ ... on Blob {{ text byteSize }} }}"
+
+
+def _repo_fields(paths: list[str]) -> str:
+    files = [_blob(f"co{i}", f"HEAD:{p}") for i, p in enumerate(CODEOWNERS_PATHS)]
+    files += [_blob(f"f{i}", f"HEAD:{p}") for i, p in enumerate(paths)]
+    files.append(_blob("desc", "HEAD:catalog-info.yaml"))
+    files.append(_blob("app", f"{DATA}:docs/app.json"))
+    trees = " ".join(f'{a}: object(expression: "HEAD:{p}") {{ ... on Tree {{ entries {{ name type }} }} }}'
+                     for a, p in (("root", ""), ("gh", ".github"), ("docs", "docs")))
+    return (" ".join(files) + " " + trees + f' data: ref(qualifiedName: "refs/heads/{DATA}") {{ name }} '
+            "licenseInfo { spdxId } codeOfConduct { url } contributingGuidelines { url }")
+
+
+def query(names: list[str], paths: list[str]) -> str:
+    fields = _repo_fields(paths)
+    parts = [f"r{i}: repository(owner: {json.dumps(n.split('/')[0])}, name: {json.dumps(n.split('/')[1])}) {{ {fields} }}"
+             for i, n in enumerate(names)]
+    return "query { rateLimit { cost remaining resetAt } " + " ".join(parts) + " }"
+
+
+def _text(node) -> str | None:
+    return (node or {}).get("text") if isinstance(node, dict) else None
+
+
+def _names(node) -> list[str]:
+    return [e["name"] for e in (node or {}).get("entries") or [] if isinstance(e, dict) and e.get("name")]
+
+
+def facts(node: dict, owner: str, paths: list[str]) -> dict:
+    """What one repo's answer says, in the shape the readers use."""
+    codeowners = next(((p, _text(node.get(f"co{i}"))) for i, p in enumerate(CODEOWNERS_PATHS) if _text(node.get(f"co{i}")) is not None),
+                      (None, None))
+    root, gh, docs = _names(node.get("root")), _names(node.get("gh")), _names(node.get("docs"))
+    starts = lambda names, word: any(n.lower().startswith(word) for n in names)  # noqa: E731
+    org_default = lambda field: f"/{owner.lower()}/.github/" in (((node.get(field) or {}).get("url")) or "").lower()  # noqa: E731
+    files = {"readme": starts(root, "readme") or starts(gh, "readme") or starts(docs, "readme"),
+             "license": bool((node.get("licenseInfo") or {}).get("spdxId")) or starts(root, "license") or starts(root, "copying"),
+             "contributing": bool(node.get("contributingGuidelines")),
+             "code_of_conduct": bool(node.get("codeOfConduct"))}
+    files["org_defaults"] = [k for k, field in (("contributing", "contributingGuidelines"), ("code_of_conduct", "codeOfConduct"))
+                             if files[k] and org_default(field)]
+    lower = {n.lower() for n in root}
+    runtime = [kind for kind, marks in RUNTIMES if lower & set(marks)]
+    return {"runtime": runtime, "codeowners": codeowners, "descriptor": _text(node.get("desc")), "app": _text(node.get("app")),
+            "data_branch": bool(node.get("data")), "files": files, "docs": docs if node.get("docs") else None,
+            "rule_files": {p: _text(node.get(f"f{i}")) for i, p in enumerate(paths)}}
+
+
+def prefetch(gql, repos: list[dict], paths: list[str]) -> dict[str, dict]:
+    """Each repo's facts by name; repos a batch couldn't read are left out (their readers fall back to REST)."""
+    out = {}
+    for i in range(0, len(repos), BATCH):
+        batch = repos[i:i + BATCH]
+        try:
+            data = gql.query(query([r["name"] for r in batch], paths), {}).data or {}
+        except (GraphQLError, RateLimited):
+            continue
+        for j, r in enumerate(batch):
+            node = data.get(f"r{j}")
+            if isinstance(node, dict):
+                out[r["name"]] = facts(node, r["name"].split("/")[0], paths)
+    return out

stackvitals/portal/campaigns.py

@@ -0,0 +1,104 @@
+"""Campaigns: a set of rules, the repos they target and a date. Progress and the burn-down come from the daily history, and
+one tracking issue in the portal repo is kept up to date (issues in each repo would need write access everywhere)."""
+import fnmatch
+import json
+import tomllib
+from datetime import date, datetime
+from pathlib import Path
+
+from stackvitals.flow.report import _md
+
+MARKER = "<!-- stackvitals:campaign"
+DONE = ("pass", "exempt")
+
+
+def load_campaigns(text: str | None) -> list[dict]:
+    doc = tomllib.loads(text) if text else {}
+    out = []
+    for c in doc.get("campaign") or []:
+        if isinstance(c, dict) and c.get("id") and c.get("rules"):
+            out.append({"id": str(c["id"]), "title": str(c.get("title") or c["id"]), "rules": [str(r) for r in c["rules"]],
+                        "repos": str(c.get("repos") or "*"), "language": c.get("language"), "until": str(c.get("until") or "")})
+    return out
+
+
+def _targeted(c: dict, name: str, language: str | None) -> bool:
+    return fnmatch.fnmatch(name.lower(), c["repos"].lower()) and (not c["language"] or (language or "").lower() == c["language"].lower())
+
+
+def progress(c: dict, repos: list[dict], history: Path, now: datetime) -> dict:
+    """How many targeted repos pass every campaign rule today, who still fails, and the failing count on each kept day."""
+    today = now.strftime("%Y-%m-%d")
+    targets = [r for r in repos if not r.get("archived") and not r.get("fork") and _targeted(c, r["name"], r.get("language"))]
+
+    def passes(r):
+        results = {x["id"]: x["result"] for x in (r.get("score") or {}).get("results") or []}
+        return all(results.get(rule) in DONE for rule in c["rules"])
+    failing = sorted(r["name"] for r in targets if not passes(r))
+    passed = sorted(r["name"] for r in targets if passes(r))
+    burn = []
+    for path in sorted(Path(history).glob("*.json")):
+        if path.stem >= today:
+            continue
+        try:
+            rows = json.loads(path.read_text(encoding="utf-8")).get("repos") or []
+        except (OSError, ValueError):
+            continue
+        burn.append([path.stem, sum(1 for row in rows if _targeted(c, row.get("name") or "", row.get("language"))
+                                    and set(c["rules"]) & set(row.get("failed") or []))])
+    burn.append([today, len(failing)])
+    try:
+        days_left = (date.fromisoformat(c["until"]) - now.date()).days if c["until"] else None
+    except ValueError:
+        days_left = None
+    return {**c, "targets": len(targets), "passing": len(targets) - len(failing), "failing": failing, "passed": passed,
+            "days_left": days_left, "burn_down": burn}
+
+
+REMIND_AT = (7, 1)
+
+
+def reminders_due(campaigns: list[dict], sent: dict, now: datetime) -> list[tuple[dict, int]]:
+    """Campaigns at 7 or 1 days left that still have failing repos and haven't had that reminder (Cortex's rhythm)."""
+    out = []
+    for p in campaigns:
+        days = p.get("days_left")
+        if p.get("failing") and days in REMIND_AT and days not in (sent.get(p["id"]) or []):
+            out.append((p, days))
+    return out
+
+
+def reminder_text(p: dict, days: int) -> str:
+    names = ", ".join(_md(n) for n in p["failing"][:20]) + (f" and {len(p['failing']) - 20} more" if len(p["failing"]) > 20 else "")
+    return (f"Reminder: {days} day{'' if days == 1 else 's'} left for this campaign (until {p['until']}). "
+            f"{len(p['failing'])} repo{'' if len(p['failing']) == 1 else 's'} still fail: {names}.")
+
+
+def issue_body(p: dict) -> str:
+    lines = [f"{MARKER} {p['id']} -->", f"### Campaign: {_md(p['title'])}", "",
+             f"{p['passing']} of {p['targets']} repos pass every rule ({', '.join(map(_md, p['rules']))})"
+             + (f"; {p['days_left']} days left (until {p['until']})." if p.get("days_left") is not None else ".")]
+    if p["failing"] or p.get("passed"):
+        # A checklist ticked again on every run: done repos checked, the rest open.
+        lines += ["", "**Repos:**", *[f"- [ ] {_md(n)}" for n in p["failing"][:100]],
+                  *[f"- [x] {_md(n)}" for n in (p.get("passed") or [])[:50]]]
+        if len(p["failing"]) > 100:
+            lines.append(f"- ... and {len(p['failing']) - 100} more still failing")
+    if len(p["burn_down"]) > 1:
+        lines += ["", "**Failing repos over time:** " + " → ".join(f"{d} {n}" for d, n in p["burn_down"][-12:])]
+    lines += ["", "<sub>Kept up to date by StackVitals Portal on each run; edits to this text are replaced.</sub>"]
+    return "\n".join(lines)
+
+
+def update_tracking_issue(api, repo: str, p: dict) -> int | None:
+    """One issue per campaign in the portal repo, found by its marker and edited in place; closed once every repo passes."""
+    marker = f"{MARKER} {p['id']} -->"
+    open_issues = api._get(f"/repos/{repo}/issues", {"state": "open", "per_page": 100})
+    found = next((i for i in open_issues if not i.get("pull_request") and marker in (i.get("body") or "")), None)
+    body = issue_body(p)
+    if found:
+        api.send("PATCH", f"/repos/{repo}/issues/{found['number']}", {"body": body, **({} if p["failing"] else {"state": "closed"})})
+        return found["number"]
+    if p["failing"]:
+        return api.send("POST", f"/repos/{repo}/issues", {"title": f"Campaign: {p['title']}", "body": body}).get("number")
+    return None

stackvitals/portal/catalog.py

@@ -0,0 +1,104 @@
+"""The org catalog: every repo with its settings, owners with evidence and the suite's module results. Repos checked longest
+ago go first, so a run that hits its request budget (the built-in token allows 1,000 an hour) keeps earlier results for the
+rest and the next run continues."""
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+
+from stackvitals.ci.api import OutOfBudget
+from stackvitals.portal import descriptor
+from stackvitals.portal.batch import prefetch
+from stackvitals.portal.inventory import (branch_protected, branch_rules, custom_properties, descriptor_for, file_facts, list_repos,
+                                          module_facts, push_ci, repo_files, review_stats, scorecard_checks)
+from stackvitals.portal.owners import owner_status
+
+
+WORKERS = 6
+PER_REPO = 15  # REST requests one repo can take, for deciding when to slow down
+
+
+def cacheable(path: str) -> bool:
+    """Small answers that rarely change, read conditionally: an unchanged one costs nothing from the hourly limit."""
+    return any(part in path for part in ("/rules/branches/", "/codeowners/errors", "/teams/", "/protection",
+                                         "/properties/values", "/branches/stackvitals-data"))
+
+
+def _iso(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _owner_checks(d: dict, owners: dict) -> dict:
+    # Each owned entity says whether CODEOWNERS agrees, for the Catalog tab (no rule needed).
+    if d.get("present") and owners.get("status") != "none":
+        for e in d["entities"]:
+            if e["kind"] in descriptor.NEEDS:
+                e["owner_check"] = list(descriptor.owner_check(e.get("owner"), owners.get("owners") or []))
+    return d
+
+
+def build_catalog(api, org: str, mode: str, now: datetime, previous: dict | None = None, scorecard_client=None,
+                  gql=None, file_rules: list[dict] | None = None) -> dict:
+    stamp = _iso(now)
+    old = {r["name"]: r for r in (previous or {}).get("repos") or [] if isinstance(r, dict) and r.get("name")}
+    repos = list_repos(api, org, mode)
+    props = custom_properties(api, org)
+    cache, out = {}, {}
+    order = sorted(repos, key=lambda r: (old.get(r["name"]) or {}).get("checked") or "")
+    # Ten repos' files in one GraphQL query; a repo it couldn't read is asked over REST as before.
+    paths = list(dict.fromkeys(x["path"] for x in file_rules or []))
+    pre = prefetch(gql, [r for r in order if not (r["archived"] or r["fork"])], paths) if gql is not None else {}
+    stop = threading.Event()
+
+    def check(r: dict) -> tuple[str, dict]:
+        kept = {**old[r["name"]], **r} if r["name"] in old else {**r, "checked": None}
+        # Archived repos and forks are listed, not judged: a fork carries its upstream's CODEOWNERS (astral-sh/peps: 783 errors).
+        # The org's .github repo holds shared settings, not a product.
+        if r["archived"] or r["fork"] or r["name"].split("/")[-1].lower() == ".github":
+            return r["name"], r
+        if stop.is_set():
+            return r["name"], kept
+        try:
+            # OpenSSF publishes Scorecard results for public repos only; private repos stay "not available" for those rules.
+            openssf = scorecard_checks(scorecard_client, r["name"], (old.get(r["name"]) or {}).get("openssf"), now) \
+                if scorecard_client is not None and not r["private"] else None
+            mine = pre.get(r["name"])
+            modules = module_facts(api, r["name"], mine)
+            reviews = review_stats(gql, r["name"], now) if gql is not None and not (modules or {}).get("flow") else None
+            rules = branch_rules(api, r["name"], r["default_branch"])
+            owners = owner_status(api, org, r, now, cache, members_visible=mode == "private",
+                                  reviewers=(reviews or {}).get("reviewers"), pre=mine)
+            return r["name"], {**r, "properties": props.get(r["name"]) or {}, "rules": rules,
+                               "protected": branch_protected(api, r["name"], r["default_branch"])
+                               if isinstance(rules, list) and "pull_request" not in rules else None,
+                               "owners": owners, "descriptor": _owner_checks(descriptor_for(api, r, mine), owners),
+                               "files": file_facts(api, r, file_rules or [], mine),
+                               "modules": modules, "docs": repo_files(api, r, mine),
+                               # The docs/ folder's pages, for the catalog's docs index.
+                               "doc_pages": (mine or {}).get("docs"),
+                               # How it runs (kubernetes, container, terraform, serverless), from its root folder.
+                               "runtime": (mine or {}).get("runtime"),
+                               # Where CI Health doesn't run, Portal measures push CI itself (one request).
+                               "ci": None if (modules or {}).get("ci_first_try")
+                               else push_ci(api, r["name"], now, previous=(old.get(r["name"]) or {}).get("ci")),
+                               # Likewise first reviews where Team Flow doesn't run (one GraphQL point, a separate budget).
+                               "reviews": reviews,
+                               "openssf": openssf, "scorecard": (openssf or {}).get("checks"), "checked": stamp}
+        except OutOfBudget:
+            stop.set()
+            return r["name"], kept
+        except Exception as exc:  # one repo's surprise keeps its earlier check and never stops the org's catalog
+            return r["name"], {**kept, "error": type(exc).__name__}
+    # Six repos at a time while the budget is ample (most of a repo's time is waiting on GitHub); one at a time near its
+    # end, so the repos checked longest ago still go first.
+    budget = getattr(api, "max_requests", None)
+    i = 0
+    with ThreadPoolExecutor(max_workers=WORKERS) as pool:
+        while i < len(order):
+            left = None if budget is None else budget - (api.requests - getattr(api, "unchanged", 0))
+            chunk = order[i:i + (1 if left is not None and left < WORKERS * PER_REPO else WORKERS)]
+            for name, record in pool.map(check, chunk):
+                out[name] = record
+            i += len(chunk)
+    complete = not stop.is_set()
+    return {"org": org, "mode": mode, "built_at": stamp, "complete": complete, "requests": getattr(api, "requests", None),
+            "repos": sorted(out.values(), key=lambda r: r["name"].lower())}

stackvitals/portal/checks.py

@@ -0,0 +1,63 @@
+"""Scorecards as a required check (opt-in): with `[checks] level = "silver"` in portal.toml and an org App that may write
+checks, each repo's default branch and open pull requests get a "StackVitals portal" check that passes when the repo
+meets the level, and says which rules keep it below. Branch protection can then require it. Written once a run, after
+the catalog is saved; the result follows the daily catalog, so a fix shows on the next run."""
+import tomllib
+
+from stackvitals.ci.api import APIError, OutOfBudget
+from stackvitals.portal.scorecard import LEVELS
+
+NAME = "StackVitals portal"
+CAP = 300  # check runs a run writes at most; the next run carries on with the rest
+PRS = 20  # open pull requests a repo gets the check on
+
+
+def load_level(text: str | None) -> str | None:
+    try:
+        level = ((tomllib.loads(text or "").get("checks") or {}).get("level") or "").lower()
+    except tomllib.TOMLDecodeError:
+        return None
+    return level if level in LEVELS else None
+
+
+def plan(catalog: dict, level: str) -> list[dict]:
+    """One check per scored repo: success at or above the level, else failure with the rules that keep it below."""
+    need = LEVELS.index(level)
+    out = []
+    for r in catalog.get("repos") or []:
+        score = r.get("score")
+        if r.get("archived") or r.get("fork") or not score:
+            continue
+        got = LEVELS.index(score["level"]) if score.get("level") in LEVELS else -1
+        blocking = [x for x in score.get("results") or [] if x["result"] == "fail" and x["level"] in LEVELS[:need + 1]]
+        ok = got >= need
+        lines = [f"Meets {level}." if ok else f"Below {level} (now {score.get('level') or 'no level'})."]
+        lines += [f"- `{x['id']}` ({x['level']}): {x['evidence']}" for x in blocking]
+        out.append({"repo": r["name"], "branch": r.get("default_branch"), "conclusion": "success" if ok else "failure",
+                    "title": f"{'Meets' if ok else 'Below'} {level}", "summary": "\n".join(lines)})
+    return out
+
+
+def send(api, checks: list[dict], cap: int = CAP) -> dict:
+    """Posts each check on the default branch's head and the open pull requests' heads, up to `cap` writes."""
+    posted, refused, stopped, repos = 0, [], False, 0
+    for c in checks:
+        try:
+            heads = []
+            if c["branch"]:
+                heads.append(api._get(f"/repos/{c['repo']}/commits/{c['branch']}")["sha"])
+            heads += [p["head"]["sha"] for p in api._get(f"/repos/{c['repo']}/pulls", {"state": "open", "per_page": PRS}) or []]
+            for sha in heads:
+                if posted >= cap:
+                    stopped = True
+                    break
+                api.send("POST", f"/repos/{c['repo']}/check-runs",
+                         {"name": NAME, "head_sha": sha, "status": "completed", "conclusion": c["conclusion"],
+                          "output": {"title": c["title"], "summary": c["summary"]}})
+                posted += 1
+        except (APIError, OutOfBudget) as exc:
+            refused.append(f"{c['repo']}: {str(exc)[:120]}")
+        if stopped:
+            break
+        repos += 1
+    return {"posted": posted, "refused": refused, "stopped": stopped, "repos": repos}