stackvitals 0.1.0__py3-none-any.whl

stackvitals/core/model.py

@@ -0,0 +1,285 @@
+"""The suite's typed entities, with Apache DevLake's domain names and enums (so its SQL runs on our exports) and
+OpenTelemetry's attribute names for CI/CD and VCS columns. Built from the records the modules already store, so nothing
+is collected twice; new code reads these, old code keeps its dicts until it moves over."""
+from dataclasses import dataclass, field
+
+from stackvitals.core.actors import kind_of
+from stackvitals.core.time import secs
+
+PR_STATES = ("OPEN", "MERGED", "CLOSED")
+# DevLake's cicd result and status enums; GitHub's conclusions fold into them.
+CICD_RESULTS = {"success": "SUCCESS", "failure": "FAILURE", "timed_out": "FAILURE", "startup_failure": "FAILURE",
+                "cancelled": "ABORT", "action_required": "MANUAL"}
+# GitHub's own word for each result, for DevLake's original_result column.
+ORIGINAL = {"SUCCESS": "success", "FAILURE": "failure", "ABORT": "cancelled", "MANUAL": "action_required"}
+ISSUE_TYPES = ("REQUIREMENT", "BUG", "INCIDENT")
+INCIDENT_LABELS = ("incident", "outage", "sev1", "sev2", "p0")
+BUG_LABELS = ("bug", "defect", "regression")
+EVENT_KINDS = {"ready": "READY", "draft": "DRAFT", "req": "REVIEW_REQUEST", "unreq": "REVIEW_REQUEST_REMOVED",
+               "review": "REVIEW", "merged": "MERGED", "closed": "CLOSED"}
+
+
+def entity_id(entity: str, repo: str, key, source: str = "github") -> str:
+    # DevLake's id form: plugin:Entity:connection:id, with the repo as the connection.
+    return f"{source}:{entity}:{repo}:{key}"
+
+
+def cicd_result(conclusion: str | None) -> str:
+    return CICD_RESULTS.get(conclusion or "", "OTHER")
+
+
+@dataclass
+class ChangeEvent:
+    kind: str  # READY, DRAFT, REVIEW_REQUEST, REVIEW_REQUEST_REMOVED, COMMENT, REVIEW, MERGED, CLOSED
+    at: str
+    actor: str | None = None
+    actor_kind: str = "unknown"
+    state: str | None = None  # review state: APPROVED, CHANGES_REQUESTED, COMMENTED
+    assoc: str | None = None
+    raised: bool = False  # the review or comment asked the author something
+
+
+@dataclass
+class ChangeRequest:
+    """DevLake's pull_requests entity with its timeline."""
+    id: str
+    repo: str
+    number: int
+    title: str
+    state: str
+    draft: bool
+    author: str | None
+    author_kind: str
+    author_assoc: str | None
+    created_at: str | None
+    ready_at: str | None
+    merged_at: str | None
+    closed_at: str | None
+    updated_at: str | None
+    additions: int | None
+    deletions: int | None
+    changed_files: int | None
+    base_ref: str | None
+    head_ref: str | None
+    head_owner: str | None
+    last_commit_at: str | None
+    paths: list[str] = field(default_factory=list)
+    labels: list[str] = field(default_factory=list)
+    requested: list[str] = field(default_factory=list)
+    events: list[ChangeEvent] = field(default_factory=list)
+    linked_issue: bool = False
+
+    @classmethod
+    def from_flow(cls, rec: dict, repo: str) -> "ChangeRequest":
+        from stackvitals.flow.analyze import ready_at
+        events = []
+        for e in rec.get("ev") or []:
+            kind = EVENT_KINDS.get(e[0])
+            if not kind:
+                continue
+            actor = e[2] if len(e) > 2 else None
+            if e[0] == "review":
+                events.append(ChangeEvent(kind, e[1], actor, kind_of(actor, e[5] if len(e) > 5 else None), e[3],
+                                          e[4] if len(e) > 4 else None, bool(e[6]) if len(e) > 6 else False))
+            else:
+                events.append(ChangeEvent(kind, e[1], actor, kind_of(actor) if actor else "unknown"))
+        for c in rec.get("cm") or []:
+            if c and c[0]:
+                events.append(ChangeEvent("COMMENT", c[0], c[1], kind_of(c[1], c[3] if len(c) > 3 else None), None,
+                                          c[2] if len(c) > 2 else None, bool(c[4]) if len(c) > 4 else False))
+        events.sort(key=lambda e: e.at)
+        return cls(entity_id("PullRequest", repo, rec["n"]), repo, rec["n"], rec.get("ti") or "", rec.get("st") or "OPEN",
+                   bool(rec.get("draft")), rec.get("au"), kind_of(rec.get("au"), rec.get("at")), rec.get("as"), rec.get("cr"),
+                   ready_at(rec), rec.get("mg"), rec.get("cl"), rec.get("up"), rec.get("add"), rec.get("del"), rec.get("files"),
+                   rec.get("base"), rec.get("head"), rec.get("ho"), rec.get("lc"), list(rec.get("paths") or []),
+                   list(rec.get("lb") or []), list(rec.get("rq") or []), events, bool(rec.get("iss")))
+
+    def to_devlake(self) -> dict:
+        # DevLake's pull_requests columns, so its dashboards' SQL runs on an export of ours.
+        return {"id": self.id, "pull_request_key": self.number, "title": self.title, "status": self.state,
+                "author_name": self.author, "author_id": entity_id("Account", self.repo, self.author or "") if self.author else None,
+                "created_date": self.created_at, "merged_date": self.merged_at, "closed_date": self.closed_at,
+                "additions": self.additions, "deletions": self.deletions, "is_draft": self.draft,
+                "base_ref": self.base_ref, "head_ref": self.head_ref,
+                "url": f"https://github.com/{self.repo}/pull/{self.number}"}
+
+
+@dataclass
+class Step:
+    number: int | None
+    name: str | None
+    result: str
+    started_at: str | None
+    finished_at: str | None
+
+
+@dataclass
+class Task:
+    """DevLake's cicd_tasks: one job of a run attempt."""
+    id: str
+    name: str | None
+    result: str
+    created_at: str | None
+    started_at: str | None
+    finished_at: str | None
+    labels: list[str] = field(default_factory=list)
+    steps: list[Step] = field(default_factory=list)
+
+    @property
+    def duration_s(self) -> float | None:
+        return secs(self.started_at, self.finished_at)
+
+
+@dataclass
+class PipelineRun:
+    """DevLake's cicd_pipelines: one attempt of a workflow run."""
+    id: str
+    repo: str
+    run_id: int
+    attempt: int
+    name: str | None
+    path: str | None
+    trigger: str | None
+    branch: str | None
+    sha: str | None
+    tree: str | None
+    change_numbers: list[int]
+    head_owner: str | None
+    result: str
+    created_at: str | None
+    started_at: str | None
+    updated_at: str | None
+    tasks: list[Task] = field(default_factory=list)
+
+    @classmethod
+    def from_ci(cls, run: dict, jobs: list[dict], repo: str) -> "PipelineRun":
+        key = f"{run['id']}:{run.get('att', 1)}"
+        tasks = [Task(entity_id("CicdTask", repo, f"{key}:{j['id']}"), j.get("n"), cicd_result(j.get("c")), j.get("cr"),
+                      j.get("st"), j.get("en"), list(j.get("lb") or []),
+                      [Step(s[0], s[1], cicd_result(s[2]), *(list(s[3:5]) + [None, None])[:2]) for s in j.get("steps") or []])
+                 for j in jobs if j.get("run") == run["id"] and j.get("att", 1) == run.get("att", 1)]
+        return cls(entity_id("CicdPipeline", repo, key), repo, run["id"], run.get("att", 1), run.get("wfn"), run.get("path"),
+                   run.get("ev"), run.get("br"), run.get("sha"), run.get("tree"), list(run.get("pr") or []), run.get("ho"),
+                   cicd_result(run.get("c")), run.get("cr"), run.get("st"), run.get("up"), tasks)
+
+    def to_devlake(self, scope: str) -> dict:
+        """DevLake's cicd_pipelines row, its cicd_tasks rows (this attempt's jobs) and its cicd_pipeline_commits row."""
+        whole = lambda s: None if s is None else int(round(s))  # noqa: E731
+        url = f"https://github.com/{self.repo}/actions/runs/{self.run_id}" + (f"/attempts/{self.attempt}" if self.attempt > 1 else "")
+        pipeline = {"id": self.id, "name": self.name, "result": self.result, "status": "DONE",
+                    "original_status": "completed", "original_result": ORIGINAL.get(self.result, self.result.lower()),
+                    "duration_sec": whole(secs(self.started_at, self.updated_at)),
+                    "queued_duration_sec": whole(secs(self.created_at, self.started_at)), "created_date": self.created_at,
+                    "queued_date": self.created_at, "started_date": self.started_at, "finished_date": self.updated_at,
+                    "environment": None, "type": None, "cicd_scope_id": scope, "display_title": self.name, "url": url}
+        tasks = [{"id": t.id, "name": t.name, "pipeline_id": self.id, "result": t.result, "status": "DONE",
+                  "original_status": "completed", "original_result": ORIGINAL.get(t.result, t.result.lower()), "type": None,
+                  "environment": None, "duration_sec": whole(t.duration_s), "queued_duration_sec": whole(secs(t.created_at, t.started_at)),
+                  "started_date": t.started_at, "finished_date": t.finished_at, "created_date": t.created_at,
+                  "queued_date": t.created_at, "cicd_scope_id": scope} for t in self.tasks]
+        commit = {"pipeline_id": self.id, "commit_sha": self.sha, "branch": self.branch, "repo_id": scope,
+                  "repo_url": f"https://github.com/{self.repo}"}
+        return {"cicd_pipelines": pipeline, "cicd_tasks": tasks, "cicd_pipeline_commits": [commit] if self.sha else []}
+
+    def to_otel(self) -> dict:
+        # OpenTelemetry's CI/CD and VCS attribute names (semantic conventions, release candidate).
+        return {"cicd.pipeline.name": self.name, "cicd.pipeline.run.id": self.run_id, "cicd.pipeline.run.attempt": self.attempt,
+                "cicd.pipeline.result": self.result, "cicd.pipeline.run.state": "finished",
+                "vcs.repository.name": self.repo, "vcs.ref.head.name": self.branch, "vcs.ref.head.revision": self.sha,
+                "vcs.change.id": self.change_numbers[0] if self.change_numbers else None}
+
+
+@dataclass
+class TestResult:
+    """One test's outcome in one run attempt, with CTRF's field names in to_ctrf()."""
+    test_id: str
+    status: str  # PASSED, FAILED, FLAKY, SKIPPED
+    repo: str
+    run_id: int
+    attempt: int
+    artifact: int | None = None
+    suite: str | None = None
+    fingerprint: str | None = None
+    message: str | None = None
+    duration_ms: int | None = None
+
+    @classmethod
+    def from_report(cls, rec: dict, repo: str) -> list["TestResult"]:
+        run, att, art, suite = rec.get("run"), rec.get("att", 1), rec.get("art"), rec.get("name")
+        slow = {tid: ms for tid, ms in rec.get("slow") or []}
+        out = [cls(tid, "FAILED", repo, run, att, art, suite, fp, msg, slow.get(tid)) for tid, fp, msg in rec.get("failed") or []]
+        out += [cls(tid, "FLAKY", repo, run, att, art, suite, None, None, slow.get(tid)) for tid in rec.get("flaky") or []]
+        return out
+
+    def to_ctrf(self) -> dict:
+        status = {"FAILED": "failed", "FLAKY": "passed", "SKIPPED": "skipped"}.get(self.status, "passed")
+        out = {"name": self.test_id, "status": status, "duration": self.duration_ms or 0, "flaky": self.status == "FLAKY",
+               "suite": self.suite}
+        if self.message:
+            out["message"] = self.message
+        return out
+
+
+@dataclass
+class Issue:
+    """DevLake's issues: type REQUIREMENT, BUG or INCIDENT; status TODO or DONE."""
+    id: str
+    repo: str
+    number: int
+    type: str
+    status: str
+    created_at: str | None
+    closed_at: str | None
+    author: str | None
+    author_kind: str
+    labels: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_community(cls, rec: dict, repo: str, incident_labels=INCIDENT_LABELS, bug_labels=BUG_LABELS) -> "Issue":
+        labels = [str(x).lower() for x in rec.get("lb") or []]
+        kind = "INCIDENT" if any(x in labels for x in incident_labels) else "BUG" if any(x in labels for x in bug_labels) \
+            else "REQUIREMENT"
+        return cls(entity_id("Issue", repo, rec["n"]), repo, rec["n"], kind, "DONE" if rec.get("cl") else "TODO", rec.get("cr"),
+                   rec.get("cl"), rec.get("au"), kind_of(rec.get("au"), rec.get("at")), labels)
+
+
+@dataclass
+class Release:
+    id: str
+    repo: str
+    tag: str
+    published_at: str | None
+    sha: str | None = None
+
+
+@dataclass
+class Deployment:
+    """DevLake's cicd_deployment_commits: a successful production deployment of one commit."""
+    id: str
+    repo: str
+    sha: str | None
+    finished_at: str | None
+    source: str  # workflow, api, release
+    environment: str = "PRODUCTION"
+    result: str = "SUCCESS"
+    name: str | None = None
+
+    @classmethod
+    def new(cls, repo: str, key: str, sha: str | None, finished_at: str | None, source: str, name: str | None = None) -> "Deployment":
+        return cls(entity_id("CicdDeployment", repo, key), repo, sha, finished_at, source, name=name)
+
+
+@dataclass
+class Incident:
+    """An incident (issue labelled incident, a revert or a hotfix PR) linked to the deployment before it, or to none."""
+    id: str
+    repo: str
+    opened_at: str | None
+    resolved_at: str | None
+    source: str  # issue, revert, hotfix
+    deployment_id: str | None = None
+
+    @classmethod
+    def new(cls, repo: str, key: str, opened_at: str | None, resolved_at: str | None, source: str,
+            deployment_id: str | None = None) -> "Incident":
+        return cls(entity_id("Incident", repo, key), repo, opened_at, resolved_at, source, deployment_id)

stackvitals/core/projectcli.py

@@ -0,0 +1,66 @@
+"""`stackvitals project NAME owner/a owner/b ...`: one project's DORA across several repos, as an Apache DevLake project
+counts it (its own SQL on the repos' tables pooled), next to each repo's own; no DevLake, MySQL or Grafana running."""
+import argparse
+import json
+import sys
+import tempfile
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+from mergescout.github.graphql import GraphQLError
+from stackvitals.ci import cli as ci_cli
+from stackvitals.ci.api import APIError, OutOfBudget
+from stackvitals.core import export, services
+
+PANELS = ("deployment_frequency", "lead_time", "change_failure_rate", "recovery")
+
+
+def project_dora(name: str, tables_by_repo: dict, start: datetime, end: datetime, report: str = "2023") -> dict:
+    """{"project": DevLake's four panels on the pooled tables, "repos": {repo: its own four}}."""
+    def four(tables: dict, project: str) -> dict:
+        with tempfile.TemporaryDirectory() as tmp:
+            export.write(tables, tmp)
+            got = export.panels(tmp, start, end, report, project)
+        return {k: got.get(k) for k in PANELS}
+    return {"project": four(export.pool(tables_by_repo, name), name),
+            "repos": {repo: four(t, repo) for repo, t in tables_by_repo.items()}}
+
+
+def main(argv: list[str] | None = None, tok: str | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="stackvitals project", description="DORA for one project across several repos.")
+    ap.add_argument("name", help="the project's name")
+    ap.add_argument("repos", nargs="+", help="owner/name of each repo in it")
+    ap.add_argument("--days", type=int, default=90)
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    tok = tok or ci_cli.token()
+    if not tok:
+        print("A GitHub token is needed. Set GITHUB_TOKEN, or run `gh auth login`.", file=sys.stderr)
+        return 1
+    now = datetime.now(timezone.utc)
+    days = max(1, min(a.days, 90))
+    tables, report = {}, "2023"
+    for repo in a.repos:
+        try:
+            flow, info, ci, issues, cfg = services.delivery_inputs(repo, days, tok, ci_cli.home(), now=now,
+                                                                   log=lambda line: print(line, file=sys.stderr, flush=True))
+        except (APIError, OutOfBudget, GraphQLError, httpx.HTTPError) as exc:
+            print(f"Could not read {repo}: {exc}", file=sys.stderr)
+            return 1
+        report = cfg["delivery"]["dora_report"]
+        tables[repo] = export.devlake_tables(repo, flow, info, ci, issues, cfg)
+    try:
+        out = project_dora(a.name, tables, now - timedelta(days=days), now, report)
+    except ImportError:
+        print("This needs DuckDB: pip install 'stackvitals[sql]'.", file=sys.stderr)
+        return 1
+    if a.json:
+        print(json.dumps({"name": a.name, "days": days, **out}, indent=1, default=str))
+        return 0
+    print(f"{a.name}: {len(a.repos)} repos, last {days} days, DORA as Apache DevLake counts a project:")
+    for k in PANELS:
+        print(f"  {k.replace('_', ' '):24} {out['project'][k]}")
+    for repo, p in out["repos"].items():
+        print(f"  {repo}: " + "; ".join(f"{k.replace('_', ' ')} {p[k]}" for k in PANELS))
+    return 0

stackvitals/core/propose.py

@@ -0,0 +1,86 @@
+"""Agents propose, people submit: the same prefilled request issue the app opens, for a settings change and/or a
+`/stackvitals` command, checked first with the Action's own parsers so a bad value never reaches GitHub. Nothing is sent:
+a person opens the link and presses Submit, and the workflow applies it if they have the access."""
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from datetime import date, datetime, timezone
+from urllib.parse import quote
+
+from stackvitals.core import decisions as dec
+from stackvitals.core.tomledit import EditError, apply
+
+URL_MAX = 7500
+
+
+class ProposalError(ValueError):
+    pass
+
+
+def body(changes: list[dict], settings: dict, note: str = "") -> str:
+    """The issue text, the same as the app's write.js builds."""
+    block = json.dumps({"version": 1, "changes": changes, "settings": settings}, separators=(",", ":"))
+    return (f"{note + chr(10) + chr(10) if note else ''}Sent from the StackVitals app. The StackVitals workflow applies this when "
+            f"someone with access opens it, answers here and closes it.\n\n```stackvitals\n{block}\n```\n")
+
+
+def proposal(repo: str, settings: dict | None = None, command: str | None = None, note: str = "", today: date | None = None) -> dict:
+    """{url, title, note}: a link to a prefilled request issue; ProposalError when the change can't be applied."""
+    today = today or datetime.now(timezone.utc).date()
+    settings = settings or {}
+    try:
+        decided = dec.parse_command(command or "", today) if command else []
+    except dec.CommandError as exc:
+        raise ProposalError(str(exc)) from None
+    if command and not decided:
+        raise ProposalError("A command starts with /stackvitals, for example: /stackvitals mute test:<id> for 7d because <reason>.")
+    if not decided and not settings:
+        raise ProposalError("Nothing to propose: give settings to change and/or a /stackvitals command.")
+    if settings:
+        try:
+            apply("", settings)  # every key must exist and every value be one the parser accepts
+        except EditError as exc:
+            raise ProposalError(str(exc)) from None
+    changes = [asdict(d) for d in decided]
+    what = ", ".join([*(f"{d.verb} {d.kind} {d.id}" for d in decided), *settings])
+    title = f"StackVitals: {what}"[:120]
+    url = f"https://github.com/{repo}/issues/new?title={quote(title)}&body={quote(body(changes, settings, note))}"
+    if len(url) > URL_MAX:
+        raise ProposalError("This change is too long for one link; split it into smaller ones.")
+    need = "write" if settings else "triage or write"
+    return {"url": url, "title": title,
+            "note": f"Open the link and press Submit; the StackVitals workflow applies it when someone with {need} access opened it."}
+
+
+def _value(text: str):
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text  # a plain word, like a regex or a day name
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="stackvitals propose",
+                                     description="Print a link that proposes a settings change or a decision; a person submits it.")
+    parser.add_argument("repo", help="owner/name")
+    parser.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+                        help="a setting, e.g. alerts.pickup_p75_hours=6 or automation.issues=true (JSON values)")
+    parser.add_argument("--decide", help='a command, e.g. "/stackvitals mute test:<id> for 7d because <reason>"')
+    parser.add_argument("--note", default="", help="a line of context for the person who submits it")
+    args = parser.parse_args(argv)
+    settings = {}
+    for item in args.set:
+        key, sep, value = item.partition("=")
+        if not sep:
+            print(f"--set needs KEY=VALUE, not {item!r}", file=sys.stderr)
+            return 2
+        settings[key.strip()] = _value(value.strip())
+    try:
+        out = proposal(args.repo, settings, args.decide, args.note)
+    except ProposalError as exc:
+        print(f"Not proposed: {exc}", file=sys.stderr)
+        return 1
+    print(out["note"])
+    print(out["url"])
+    return 0

stackvitals/core/pulse.py

@@ -0,0 +1,85 @@
+"""A weekly developer pulse in the digest issue (SPACE's satisfaction and DX Core 4's experience, the GitHub-native way):
+three questions posted as comments that people answer with a reaction, counted the next week. StackVitals keeps and
+shows only the counts; GitHub itself shows who reacted to anyone who can see the issue. On a public repo only the
+team's own people (insiders) are counted."""
+
+QUESTIONS = (("flow", "Could you get your work done this week without waiting on others?"),
+             ("friction", "Did CI and reviews stay out of your way this week?"),
+             ("satisfaction", "Are you happy with how the team shipped this week?"))
+ANSWERS = {"+1": "yes", "-1": "no", "confused": "mixed"}
+NAMES = {"flow": "Flow", "friction": "Low friction", "satisfaction": "Satisfaction"}
+
+
+def _marker(week: str, key: str) -> str:
+    return f"<!-- stackvitals:pulse {week} {key} -->"
+
+
+def ask(api, issue: int, week: str) -> None:
+    for key, question in QUESTIONS:
+        api.send("POST", f"/repos/{api.repo}/issues/{issue}/comments",
+                 {"body": f"**Pulse:** {question}\n\nReact 👍 yes, 👎 no, 😕 mixed. StackVitals reads only the counts (reactions themselves are visible on GitHub).\n{_marker(week, key)}"})
+
+
+def tally(api, issue: int, week: str, since: str | None = None, keep=None) -> dict:
+    """Reaction counts on that week's three questions (`keep(login)` picks whose count); a question not found counts
+    nothing. Up to 300 reactions a question."""
+    comments = api._get(f"/repos/{api.repo}/issues/{issue}/comments", {"per_page": 100, **({"since": since} if since else {})})
+    out = {key: {"yes": 0, "no": 0, "mixed": 0} for key, _q in QUESTIONS}
+    for c in comments or []:
+        key = next((k for k, _q in QUESTIONS if _marker(week, k) in (c.get("body") or "")), None)
+        if not key:
+            continue
+        for page in (1, 2, 3):
+            got = api._get(f"/repos/{api.repo}/issues/comments/{c['id']}/reactions", {"per_page": 100, "page": page}) or []
+            for r in got:
+                if r.get("content") in ANSWERS and (keep is None or keep((r.get("user") or {}).get("login"))):
+                    out[key][ANSWERS[r["content"]]] += 1
+            if len(got) < 100:
+                break
+    return out
+
+
+def section(counts: dict) -> str | None:
+    """The digest's pulse lines, or None when nobody answered."""
+    if not any(sum(v.values()) for v in counts.values()):
+        return None
+    parts = [f"{NAMES[k]} {v['yes']} yes, {v['no']} no" + (f", {v['mixed']} mixed" if v["mixed"] else "")
+             for k, v in counts.items() if sum(v.values())]
+    return "**Team pulse last week** (reactions, counts only): " + "; ".join(parts) + "."
+
+
+KEEP_WEEKS = 52
+MIN_ANSWERS = 5  # fewer answers to a question in a week and no share is shown: too few to read, too easy to trace
+# The number each question sits beside in the app: waiting on others / CI and reviews in the way / how the team shipped.
+BESIDE = {"flow": "pickup", "friction": "first_try", "satisfaction": "deployments"}
+
+
+def record(root, week: str, counts: dict) -> None:
+    """Keep one week's counts (and nothing about who answered) in docs/pulse.json, a year at most."""
+    import json
+    from pathlib import Path
+
+    from stackvitals.core.store import published, write_if_changed
+    path = Path(root) / "docs" / "pulse.json"
+    try:
+        weeks = json.loads(path.read_text(encoding="utf-8")).get("weeks") or []
+    except (OSError, ValueError):
+        weeks = []
+    clean = {k: {a: int((counts.get(k) or {}).get(a) or 0) for a in ("yes", "no", "mixed")} for k, _q in QUESTIONS}
+    weeks = [w for w in weeks if w.get("week") != week] + [{"week": week, **clean}]
+    weeks = sorted(weeks, key=lambda w: w["week"])[-KEEP_WEEKS:]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_if_changed(path, published({"weeks": weeks, "beside": BESIDE, "min_answers": MIN_ANSWERS}))
+
+
+def trend(weeks: list[dict]) -> dict:
+    """{question: [{"week", "answers", "yes_share"}]}; the share is None for a week with fewer than 5 answers."""
+    out = {}
+    for key, _q in QUESTIONS:
+        rows = []
+        for w in weeks:
+            c = w.get(key) or {}
+            n = sum(int(c.get(a) or 0) for a in ("yes", "no", "mixed"))
+            rows.append({"week": w["week"], "answers": n, "yes_share": round(c.get("yes", 0) / n, 4) if n >= MIN_ANSWERS else None})
+        out[key] = rows
+    return out