stackvitals 0.1.0__py3-none-any.whl

stackvitals/core/stats.py

@@ -0,0 +1,222 @@
+"""The suite's only statistics helpers: every module computes medians, percentiles and ranges the same way."""
+import math
+
+# One implementation each, shared with the crawler that builds the benchmarks.
+from mergescout.bench.matched import mh_risk_difference  # noqa: F401
+from mergescout.bench.prior import beta_fit  # noqa: F401
+
+
+def median(values: list[float]) -> float | None:
+    if not values:
+        return None
+    s, n = sorted(values), len(values)
+    return s[n // 2] if n % 2 else (s[n // 2 - 1] + s[n // 2]) / 2
+
+
+def stdev(values: list[float]) -> float | None:
+    """The sample standard deviation, or None under two values."""
+    if len(values) < 2:
+        return None
+    m = sum(values) / len(values)
+    return math.sqrt(sum((v - m) ** 2 for v in values) / (len(values) - 1))
+
+
+def percentile(values: list[float], q: float) -> float | None:
+    # Nearest rank: the value at ceil(q * n), never interpolated, so small samples show real values.
+    if not values:
+        return None
+    s = sorted(values)
+    return s[min(len(s) - 1, max(0, math.ceil(q * len(s)) - 1))]
+
+
+def wilson(k: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    """A 95% range for a share of k in n; no trials means anything from 0 to 1, and k above n clamps instead of crashing."""
+    if n <= 0:
+        return 0.0, 1.0
+    p = min(k, n) / n
+    d = 1 + z * z / n
+    c = (p + z * z / (2 * n)) / d
+    h = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / d
+    return max(0.0, c - h), min(1.0, c + h)
+
+
+MIN_RANGE = 6
+
+
+def quantile_range(values: list[float], q: float, z: float = 1.96) -> tuple[float, float] | None:
+    """A 95% range for a quantile from the values themselves (binomial order statistics), None under 6 values."""
+    n = len(values)
+    if n < MIN_RANGE:
+        return None
+    s = sorted(values)
+    half = z * math.sqrt(n * q * (1 - q))
+    lo = max(0, math.floor(n * q - half))
+    hi = min(n - 1, math.ceil(n * q + half))
+    return s[lo], s[hi]
+
+
+def median_range(values: list[float], z: float = 1.96) -> tuple[float, float] | None:
+    return quantile_range(values, 0.5, z)
+
+
+def _betacf(a: float, b: float, x: float) -> float:
+    # Lentz's continued fraction for the incomplete beta (Numerical Recipes, 6.4).
+    tiny = 1e-300
+    fix = lambda v: v if abs(v) > tiny else tiny  # noqa: E731
+    c, d = 1.0, 1 / fix(1 - (a + b) * x / (a + 1))
+    h = d
+    for m in range(1, 400):
+        for aa in (m * (b - m) * x / ((a - 1 + 2 * m) * (a + 2 * m)),
+                   -(a + m) * (a + b + m) * x / ((a + 2 * m) * (a + 1 + 2 * m))):
+            d = 1 / fix(1 + aa * d)
+            c = fix(1 + aa / c)
+            h *= d * c
+        if abs(d * c - 1) < 3e-14:
+            break
+    return h
+
+
+def betainc(a: float, b: float, x: float) -> float:
+    """The regularized incomplete beta I_x(a, b): the chance a Beta(a, b) value is at most x."""
+    if x <= 0:
+        return 0.0
+    if x >= 1:
+        return 1.0
+    front = math.exp(math.lgamma(a + b) - math.lgamma(a) - math.lgamma(b) + a * math.log(x) + b * math.log1p(-x))
+    if x < (a + 1) / (a + b + 2):
+        return front * _betacf(a, b, x) / a
+    return 1 - front * _betacf(b, a, 1 - x) / b
+
+
+def beta_ppf(q: float, a: float, b: float) -> float:
+    """The value a Beta(a, b) stays under with chance q (bisection on betainc)."""
+    lo, hi = 0.0, 1.0
+    for _ in range(60):
+        mid = (lo + hi) / 2
+        lo, hi = (mid, hi) if betainc(a, b, mid) < q else (lo, mid)
+    return (lo + hi) / 2
+
+
+def shrink(k: int, n: int, prior: tuple[float, float]) -> dict:
+    """A share of k in n pulled toward its peers' Beta prior: the posterior mean and its 95% range."""
+    a, b = prior[0] + min(k, n), prior[1] + max(0, n - k)
+    return {"value": round(a / (a + b), 4), "low": round(beta_ppf(0.025, a, b), 4), "high": round(beta_ppf(0.975, a, b), 4),
+            "n": n}
+
+
+def t_two_sided(t: float, df: float) -> float:
+    """Two-sided p-value of a Student t statistic with df degrees of freedom."""
+    return min(1.0, betainc(df / 2, 0.5, df / (df + t * t))) if t else 1.0
+
+
+def t_isf(p: float, df: float) -> float:
+    """The |t| whose two-sided p-value with df degrees of freedom is p (bisection on t_two_sided)."""
+    if p >= 1:
+        return 0.0
+    lo, hi = 0.0, 1e4
+    for _ in range(200):
+        mid = (lo + hi) / 2
+        lo, hi = (mid, hi) if t_two_sided(mid, df) > p else (lo, mid)
+    return (lo + hi) / 2
+
+
+def normal_isf(p: float) -> float:
+    """The |z| whose two-sided normal p-value is p (bisection on erfc)."""
+    if p >= 1:
+        return 0.0
+    p = max(p, 1e-300)
+    lo, hi = 0.0, 40.0
+    for _ in range(100):
+        mid = (lo + hi) / 2
+        lo, hi = (mid, hi) if math.erfc(mid / math.sqrt(2)) > p else (lo, mid)
+    return (lo + hi) / 2
+
+
+def _log_comb(n: int, k: int) -> float:
+    return math.lgamma(n + 1) - math.lgamma(k + 1) - math.lgamma(n - k + 1)
+
+
+def fisher(k1: int, n1: int, k2: int, n2: int) -> float:
+    """Two-sided p-value that k1 of n1 and k2 of n2 come from the same share (Fisher's exact test)."""
+    if n1 <= 0 or n2 <= 0:
+        return 1.0
+    hits, total = k1 + k2, n1 + n2
+    lo, hi = max(0, hits - n2), min(hits, n1)
+    log_p = lambda x: _log_comb(n1, x) + _log_comb(n2, hits - x) - _log_comb(total, hits)  # noqa: E731
+    seen = log_p(k1)
+    return min(1.0, sum(math.exp(log_p(x)) for x in range(lo, hi + 1) if log_p(x) <= seen + 1e-7))
+
+
+def mann_whitney(x: list[float], y: list[float]) -> float:
+    """Two-sided p-value that two samples come from the same distribution (normal approximation, ties averaged)."""
+    n1, n2 = len(x), len(y)
+    if not n1 or not n2:
+        return 1.0
+    both = sorted([(v, 0) for v in x] + [(v, 1) for v in y])
+    ranks, ties, i = [0.0] * len(both), 0.0, 0
+    while i < len(both):
+        j = i
+        while j + 1 < len(both) and both[j + 1][0] == both[i][0]:
+            j += 1
+        for t in range(i, j + 1):
+            ranks[t] = (i + j) / 2 + 1
+        ties += (j - i + 1) ** 3 - (j - i + 1)
+        i = j + 1
+    n = n1 + n2
+    u = sum(r for r, (_v, side) in zip(ranks, both) if side == 0) - n1 * (n1 + 1) / 2
+    var = n1 * n2 / 12 * ((n + 1) - ties / (n * (n - 1))) if n > 1 else 0
+    if var <= 0:
+        return 1.0
+    z = max(0.0, abs(u - n1 * n2 / 2) - 0.5) / math.sqrt(var)
+    return min(1.0, math.erfc(z / math.sqrt(2)))
+
+
+def count_change(now: int, before: int, weeks: int) -> float:
+    """Two-sided p-value that this week's count fits the `weeks` weeks before it (binomial on the combined count)."""
+    total = now + before
+    if total <= 0 or weeks <= 0:
+        return 1.0
+    p0 = 1 / (weeks + 1)
+    log_pmf = lambda x: _log_comb(total, x) + x * math.log(p0) + (total - x) * math.log1p(-p0)  # noqa: E731
+    seen = log_pmf(now)
+    return min(1.0, sum(math.exp(log_pmf(x)) for x in range(total + 1) if log_pmf(x) <= seen + 1e-7))
+
+
+KM_MIN = 10
+
+
+def km_median(durations: list[float], answered: list[bool], z: float = 1.96) -> dict:
+    """Median time to an answer with items still waiting kept in (Kaplan-Meier): the median and its 95% range
+    (Brookmeyer-Crowley on Greenwood's variance), or no median and `at_least` when more than half are still waiting."""
+    n, done = len(durations), sum(1 for a in answered if a)
+    out = {"median": None, "low": None, "high": None, "at_least": None, "answered": done, "waiting": n - done}
+    if n < KM_MIN:
+        out["too_few"] = bool(n)
+        return out
+    s, greenwood, curve = 1.0, 0.0, []
+    for t in sorted({d for d, a in zip(durations, answered) if a}):
+        at_risk = sum(1 for d in durations if d >= t)
+        events = sum(1 for d, a in zip(durations, answered) if a and d == t)
+        s *= 1 - events / at_risk
+        if at_risk > events:
+            greenwood += events / (at_risk * (at_risk - events))
+        curve.append((t, s, s * s * greenwood))
+    out["median"] = next((t for t, sv, _v in curve if sv <= 0.5), None)
+    if out["median"] is None:
+        out["at_least"] = max(durations)
+        return out
+    near = [t for t, sv, var in curve if abs(sv - 0.5) <= z * math.sqrt(var)]
+    out["low"], out["high"] = (min(near), max(near)) if near else (out["median"], out["median"])
+    # The curve never clearly drops below a half: the range's upper end is beyond what was seen ("or more").
+    if curve and abs(curve[-1][1] - 0.5) <= z * math.sqrt(curve[-1][2]):
+        out["high"] = None
+    return out
+
+
+def bh(pvalues: list[float], q: float = 0.1) -> list[bool]:
+    """Which p-values survive Benjamini-Hochberg at false-discovery rate q, across everything scanned together."""
+    m = len(pvalues)
+    order = sorted(range(m), key=lambda i: pvalues[i])
+    cut = max((rank for rank, i in enumerate(order, 1) if pvalues[i] <= rank * q / m), default=0)
+    keep = set(order[:cut])
+    return [i in keep for i in range(m)]

stackvitals/core/store.py

@@ -0,0 +1,125 @@
+"""The data branch as a whole: every module's day files, with one retention rule per stream, one size cap that drops the
+oldest days first, a schema number on every published file, and the counter that decides when the git history is
+squashed. The branch is the source of truth; summaries and any database are derived from it."""
+import json
+import os
+import re
+from datetime import date, timedelta
+from pathlib import Path
+
+SCHEMA = 1
+META = "stackvitals.json"
+# Stream folder -> days kept (user decision 2026-10-20: 400 for PRs, issues and Portal history, 180 for CI runs). A
+# connector day file holds the newest copy of what changed that day, so dropping it only loses records idle since.
+STREAMS = {"ci/days": 180, "ci/transitions": 400, "flow/closed": 400, "community/issues/closed": 400, "portal/history": 400,
+           **{f"connectors/{name}/{part}": 400 for name in ("jira", "linear", "pagerduty", "incident_io") for part in ("days", "raw")},
+           "connectors/copilot/days": 730, "connectors/ai_spend/days": 730}
+DEFAULT_CAP_MB = 250
+SQUASH_EVERY = 1000
+DAY_FILE = re.compile(r"^(\d{4}-\d{2}-\d{2})\.(ndjson|ndjson\.gz|json)$")
+
+
+class HistoryStore:
+    def __init__(self, root: Path):
+        self.root = Path(root)
+
+    def meta(self) -> dict:
+        try:
+            return json.loads((self.root / META).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+
+    def save_meta(self, meta: dict) -> None:
+        path = self.root / META
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps({"schema": SCHEMA, **meta}, indent=1, sort_keys=True), encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+
+    def bump_commits(self) -> int:
+        # Counted here because a shallow clone cannot see the branch's history.
+        meta = self.meta()
+        n = int(meta.get("commits") or 0) + 1
+        self.save_meta({**meta, "commits": n})
+        return n
+
+    def day_files(self) -> list[tuple[str, str, Path]]:
+        out = []
+        for stream in STREAMS:
+            folder = self.root / stream
+            if not folder.is_dir():
+                continue
+            for path in sorted(folder.iterdir()):
+                m = DAY_FILE.match(path.name)
+                if m:
+                    out.append((stream, m[1], path))
+        return out
+
+    def retention(self, today: str, days: dict[str, int] | None = None) -> dict[str, int]:
+        """Remove day files older than each stream's retention; returns how many went, per stream."""
+        keep = {**STREAMS, **(days or {})}
+        removed = {}
+        for stream, day, path in self.day_files():
+            oldest = (date.fromisoformat(today) - timedelta(days=keep[stream])).isoformat()
+            if day < oldest:
+                path.unlink()
+                removed[stream] = removed.get(stream, 0) + 1
+        return removed
+
+    def size(self) -> int:
+        # Only the history counts, never the pages: dropping a page would not free history.
+        return sum(path.stat().st_size for _, _, path in self.day_files())
+
+    def cap(self, today: str, max_bytes: int = DEFAULT_CAP_MB * 1024 * 1024) -> list[str]:
+        """Drop the oldest day files, whatever their stream, until the history fits; today's files always stay."""
+        dropped = []
+        files = sorted(self.day_files(), key=lambda x: (x[1], x[0]))
+        total = sum(path.stat().st_size for _, _, path in files)
+        for stream, day, path in files:
+            if total <= max_bytes or day >= today:
+                continue
+            total -= path.stat().st_size
+            path.unlink()
+            dropped.append(f"{stream}/{path.name}")
+        return dropped
+
+
+def published(result: dict) -> dict:
+    # Every file another tool reads says which schema it follows.
+    return {"schema": SCHEMA, **result}
+
+
+def accept(data) -> dict | None:
+    """A published file this version understands, or None: a newer schema is never half-read."""
+    if not isinstance(data, dict):
+        return None
+    version = data.get("schema", SCHEMA)
+    return data if isinstance(version, int) and version <= SCHEMA else None
+
+
+# Fields that move with the clock alone: when a page differs only in these, it is not rewritten (no commit churn).
+CLOCK_FIELDS = ("generated", "as_of", "hours", "since")
+
+
+def _steady(value, top: bool = True):
+    if isinstance(value, dict):
+        # "since" is the window's start at the top level, but a real date inside the records.
+        return {k: _steady(v, False) for k, v in value.items() if k not in CLOCK_FIELDS or (k == "since" and not top)}
+    if isinstance(value, list):
+        return [_steady(v, False) for v in value]
+    return value
+
+
+def write_if_changed(path, data: dict, also=None, compact: bool = False) -> bool:
+    """Write a published JSON file (and `also`'s files) unless the one there differs only in the clock fields."""
+    import json
+    try:
+        old = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        old = None
+    new = json.loads(json.dumps(data))
+    if old is not None and _steady(old) == _steady(new):
+        return False
+    path.write_text(json.dumps(data, separators=(",", ":")) if compact else json.dumps(data, indent=1), encoding="utf-8")
+    if also:
+        also()
+    return True

stackvitals/core/summary.py

@@ -0,0 +1,104 @@
+"""Tier 1 storage: small JSON-lines summaries in the data branch (`summary/`), one row per PR, job or test, that DuckDB
+reads locally and DuckDB-WASM reads in the browser straight from GitHub, with no server and no extra install in the
+Action (Parquet needs pyarrow, which would cost every CI-triggered run several seconds)."""
+import json
+from datetime import datetime
+from pathlib import Path
+
+from stackvitals.core.actors import People
+from stackvitals.core.model import ChangeRequest
+from stackvitals.core.store import SCHEMA
+from stackvitals.core.time import iso
+
+FOLDER = "summary"
+# Fixed column types, so tables from several repos combine even when one repo's column is all empty (DuckDB would read
+# an all-null column as JSON). A new summary field needs its type here (a test checks).
+_RATE = {"flake_rate": "DOUBLE", "rate_low": "DOUBLE", "rate_high": "DOUBLE"}
+TYPES = {
+    "prs": {"number": "BIGINT", "status": "VARCHAR", "draft": "BOOLEAN", "author": "VARCHAR", "author_kind": "VARCHAR",
+            "role": "VARCHAR", "created_at": "TIMESTAMP", "ready_at": "TIMESTAMP", "merged_at": "TIMESTAMP",
+            "closed_at": "TIMESTAMP", "additions": "BIGINT", "deletions": "BIGINT", "changed_files": "BIGINT",
+            "base_ref": "VARCHAR", "head_ref": "VARCHAR", "reviews": "BIGINT", "first_review_at": "TIMESTAMP",
+            "pickup_s": "DOUBLE", "cycle_s": "DOUBLE", "labels": "VARCHAR[]", "linked_issue": "BOOLEAN"},
+    "ci_jobs": {"workflow": "VARCHAR", "job": "VARCHAR", "state": "VARCHAR", "runs": "BIGINT", "failures": "BIGINT",
+                "flake_events": "BIGINT", **_RATE, "median_s": "DOUBLE", "p95_s": "DOUBLE", "last_flake": "TIMESTAMP",
+                "retry_minutes": "DOUBLE", "prs_affected": "BIGINT", "top_step": "VARCHAR", "window_days": "BIGINT"},
+    "tests": {"test_id": "VARCHAR", "suite": "VARCHAR", "workflow": "VARCHAR", "state": "VARCHAR", "runs": "BIGINT",
+              "failures": "BIGINT", "flake_events": "BIGINT", **_RATE, "last_flake": "TIMESTAMP", "message": "VARCHAR",
+              "prs_affected": "BIGINT", "window_days": "BIGINT"},
+}
+
+
+def table_types(stem: str) -> dict | None:
+    """The column types of a summary file (ours, or DevLake's for devlake_*), or None for a file we don't know."""
+    if stem.startswith("devlake_"):
+        from stackvitals.core.export import COLUMNS
+        return COLUMNS.get(stem[len("devlake_"):])
+    return TYPES.get(stem)
+
+
+def _write(root: Path, name: str, rows: list[dict], now: datetime) -> str:
+    folder = root / FOLDER
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / name
+    text = "".join(json.dumps(r, separators=(",", ":"), ensure_ascii=False) + "\n" for r in rows)
+    try:
+        if path.read_text(encoding="utf-8") == text:
+            return f"{FOLDER}/{name}"  # same rows: no rewrite and no new time stamp, so a quiet run commits nothing
+    except OSError:
+        pass
+    path.write_text(text, encoding="utf-8", newline="\n")
+    manifest_path = folder / "manifest.json"
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        manifest = {}
+    files = dict(manifest.get("files") or {})
+    files[name] = {"rows": len(rows), "generated": iso(now)}
+    manifest_path.write_text(json.dumps({"schema": SCHEMA, "generated": iso(now), "files": files}, indent=1), encoding="utf-8",
+                             newline="\n")
+    return f"{FOLDER}/{name}"
+
+
+def pr_rows(data: dict, now: datetime, repo: str = "") -> list[dict]:
+    from stackvitals.flow.analyze import _human_reviews, stages
+    prs = (data.get("open") or []) + (data.get("closed") or [])
+    people = People(prs)
+    rows = []
+    for p in prs:
+        cr = ChangeRequest.from_flow(p, repo)
+        st = stages(p)
+        reviews = _human_reviews(p)
+        rows.append({"number": cr.number, "status": cr.state, "draft": cr.draft, "author": cr.author, "author_kind": cr.author_kind,
+                     "role": people.role(cr.author), "created_at": cr.created_at, "ready_at": cr.ready_at, "merged_at": cr.merged_at,
+                     "closed_at": cr.closed_at, "additions": cr.additions, "deletions": cr.deletions, "changed_files": cr.changed_files,
+                     "base_ref": cr.base_ref, "head_ref": cr.head_ref, "reviews": len(reviews),
+                     "first_review_at": reviews[0][1] if reviews else None, "pickup_s": st["pickup"], "cycle_s": st["cycle"],
+                     "labels": cr.labels, "linked_issue": cr.linked_issue})
+    return rows
+
+
+def write_pr_summary(root: Path, data: dict, now: datetime, repo: str = "") -> list[str]:
+    return [_write(root, "prs.jsonl", pr_rows(data, now, repo), now)]
+
+
+def write_ci_summary(root: Path, result: dict, now: datetime) -> list[str]:
+    window = result.get("window_days")
+    jobs = [{"workflow": j.get("workflow"), "job": j.get("job"), "state": j.get("state"), "runs": j.get("runs"),
+             "failures": j.get("failures"), "flake_events": j.get("flake_events"), "flake_rate": j.get("flake_rate"),
+             "rate_low": j.get("rate_low"), "rate_high": j.get("rate_high"), "median_s": j.get("median_s"), "p95_s": j.get("p95_s"),
+             "last_flake": j.get("last_flake"), "retry_minutes": j.get("retry_minutes"),
+             "prs_affected": len(j.get("prs_affected") or []), "top_step": j.get("top_step"), "window_days": window}
+            for j in result.get("jobs") or []]
+    tests = [{"test_id": t.get("id"), "suite": t.get("suite"), "workflow": t.get("workflow"), "state": t.get("state"),
+              "runs": t.get("runs"), "failures": t.get("failures"), "flake_events": t.get("flake_events"),
+              "flake_rate": t.get("flake_rate"), "rate_low": t.get("rate_low"), "rate_high": t.get("rate_high"),
+              "last_flake": t.get("last_flake"), "message": t.get("message"), "prs_affected": len(t.get("prs_affected") or []),
+              "window_days": window}
+             for t in result.get("tests") or []]
+    return [_write(root, "ci_jobs.jsonl", jobs, now), _write(root, "tests.jsonl", tests, now)]
+
+
+def write_devlake_summary(root: Path, tables: dict[str, list[dict]], now: datetime) -> list[str]:
+    """DevLake's domain tables beside the other summaries (`devlake_<table>.jsonl`), for DevLake's own SQL anywhere."""
+    return [_write(root, f"devlake_{name}.jsonl", rows, now) for name, rows in tables.items()]

stackvitals/core/time.py

@@ -0,0 +1,29 @@
+"""GitHub timestamps ("2026-10-20T12:00:00Z") in and out, and spans that are never negative."""
+from datetime import datetime, timedelta
+
+FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def parse(text: str | None) -> datetime | None:
+    return datetime.fromisoformat(text.replace("Z", "+00:00")) if text else None
+
+
+def iso(dt: datetime) -> str:
+    return dt.strftime(FORMAT)
+
+
+def secs(start: str | None, end: str | None) -> float | None:
+    # Times out of order (clock skew, imported history) give None, never a negative wait.
+    a, b = parse(start), parse(end)
+    return (b - a).total_seconds() if a and b and b >= a else None
+
+
+def hours(start: str | None, end: str | None) -> float | None:
+    s = secs(start, end)
+    return None if s is None else s / 3600
+
+
+def week_of(t: datetime | str) -> str:
+    # Weeks start on Monday.
+    t = parse(t) if isinstance(t, str) else t
+    return (t - timedelta(days=t.weekday())).strftime("%Y-%m-%d")

stackvitals/core/tomledit.py

@@ -0,0 +1,149 @@
+"""Small, checked edits of `.github/stackvitals.toml` for settings changed in the app: a key's line is replaced where it
+is (comments and layout stay), a missing key or table is added, None removes a key so its default applies. The result is
+parsed again and must hold exactly the asked values; anything else (a layout this can't edit, a value the parser
+refuses) raises EditError, so a file is never rewritten blindly."""
+import json
+import re
+import tomllib
+from datetime import date
+
+from stackvitals.core import config, schema
+
+MAPS = ("dates", "map", "teams")
+_HEADER = re.compile(r"^\s*\[\[?\s*([^\[\]]+?)\s*\]\]?\s*(#.*)?$")
+
+
+class EditError(ValueError):
+    pass
+
+
+def _render(value, kind: str) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return repr(value)
+    if isinstance(value, str):
+        if kind == "dates":
+            return date.fromisoformat(value).isoformat()
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, list):
+        return "[" + ", ".join(_render(x, "list") for x in value) + "]"
+    raise EditError(f"{value!r} can't be written as a setting.")
+
+
+def _depth(line: str) -> int:
+    # Brackets opened minus closed on a line, ignoring quoted strings and comments.
+    bare = re.sub(r'"(?:[^"\\]|\\.)*"|\'[^\']*\'', "", line).split("#", 1)[0]
+    return bare.count("[") - bare.count("]")
+
+
+def _tables(lines: list[str]) -> list[tuple[str, int, int]]:
+    """(name, header line, end line) for each table, skipping lines inside multi-line values."""
+    heads, depth = [], 0
+    for i, line in enumerate(lines):
+        m = _HEADER.match(line) if depth == 0 else None
+        if m:
+            heads.append((m[1].replace(" ", ""), i))
+            continue
+        if depth or re.match(r"^\s*[\w\"'.-]+\s*=", line):
+            depth = max(depth + _depth(line), 0)
+    return [(name, start, heads[k + 1][1] if k + 1 < len(heads) else len(lines)) for k, (name, start) in enumerate(heads)]
+
+
+def _comment(line: str) -> str:
+    # The line's trailing comment (outside quoted strings), kept when its value is replaced.
+    bare = re.sub(r'"(?:[^"\\]|\\.)*"|\'[^\']*\'', lambda m: " " * len(m[0]), line)
+    at = bare.find("#")
+    return line[at:].rstrip() if at >= 0 else ""
+
+
+def _key_span(lines: list[str], start: int, end: int, leaf: str) -> tuple[int, int] | None:
+    pattern = re.compile(rf"^\s*(?:{re.escape(leaf)}|\"{re.escape(leaf)}\"|'{re.escape(leaf)}')\s*=")
+    for i in range(start, end):
+        if pattern.match(lines[i]):
+            j, depth = i, _depth(lines[i])
+            while depth > 0 and j + 1 < end:
+                j += 1
+                depth += _depth(lines[j])
+            return i, j + 1
+    return None
+
+
+def _set(lines: list[str], table: str, body: list[str] | None, leaf: str | None) -> list[str]:
+    """Put `body` (the new lines) for `leaf` in `table` (leaf None: the whole table's body); body None removes it."""
+    found = next(((s, e) for name, s, e in _tables(lines) if name == table), None)
+    if found is None:
+        if body is None:
+            return lines
+        gap = [""] if lines and lines[-1].strip() else []
+        return lines + gap + [f"[{table}]", *body]
+    start, end = found
+    if leaf is None:
+        tail = end
+        while tail > start + 1 and not lines[tail - 1].strip():
+            tail -= 1
+        return lines[:start + 1] + (body or []) + lines[tail:end] + lines[end:]
+    span = _key_span(lines, start + 1, end, leaf)
+    if span:
+        note = _comment(lines[span[0]]) if body and len(body) == 1 and span[1] - span[0] == 1 else ""
+        return lines[:span[0]] + ([f"{body[0]}  {note}"] if note else body or []) + lines[span[1]:]
+    if body is None:
+        return lines
+    last = end
+    while last > start + 1 and not lines[last - 1].strip():
+        last -= 1
+    return lines[:last] + body + lines[last:]
+
+
+def _expected(setting: schema.Setting, value):
+    if value is None:
+        return schema.default(setting.key)
+    if setting.kind == "int":
+        return int(value)
+    if setting.kind in ("number", "share", "hours"):
+        return float(value)
+    return value
+
+
+def _get(cfg: dict, key: str):
+    node = cfg
+    for part in key.split("."):
+        node = node[part]
+    return node
+
+
+def apply(text: str | None, changes: dict) -> str:
+    lines = (text or "").replace("\r\n", "\n").split("\n")
+    if lines and lines[-1] == "":
+        lines = lines[:-1]
+    for key, value in changes.items():
+        setting = schema.BY_KEY.get(key)
+        if setting is None:
+            raise EditError(f"{key} is not a setting StackVitals knows.")
+        try:
+            if setting.kind in MAPS:
+                if value is not None and not isinstance(value, dict):
+                    raise EditError(f"{key} takes a table of entries.")
+                body = None if value is None else [f"{json.dumps(str(k), ensure_ascii=False)} = {_render(v, setting.kind)}"
+                                                   for k, v in value.items()]
+                lines = _set(lines, key, body, None)
+            else:
+                table, leaf = key.rsplit(".", 1)
+                lines = _set(lines, table, None if value is None else [f"{leaf} = {_render(value, setting.kind)}"], leaf)
+        except ValueError as exc:
+            raise EditError(f"{key}: {exc}") from None
+    out = "\n".join(lines).strip("\n") + "\n"
+    try:
+        tomllib.loads(out)
+    except tomllib.TOMLDecodeError as exc:
+        raise EditError(f"this file's layout can't be edited automatically ({exc}); change it by hand.") from None
+    cfg, notes = config.parse(out)
+    for key, value in changes.items():
+        try:
+            want = _expected(schema.BY_KEY[key], value)
+        except (TypeError, ValueError):
+            raise EditError(f"{key} can't be set to {value!r}: it needs a {schema.BY_KEY[key].kind}.") from None
+        if _get(cfg, key) != want:
+            why = next((n for n in notes if key.rsplit(".", 1)[-1] in n), "the file's layout kept the old value")
+            raise EditError(f"{key} can't be set to {value!r}: {why}")
+    return out