Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Add a mage task that attributes ratchet changes (#84109)

Chris Truter7702d04e9b7e
diff --git a/CLAUDE.md b/CLAUDE.md
index b2c43db07f7..eebe10b2e6d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -156,6 +156,13 @@ files. Use `--seed :discouraged-var/clojure.core/println` to seed one symbol's b
To learn which symbol an ignore covers, `./bin/mage kondo-ratchets` runs `clojure -M:kondo` over the files
carrying one, so it needs the Clojure CLI as well as Babashka.
+`./bin/mage kondo-ratchets-history` reports which commits shrank, grew and introduced budgets, from the history of the
+ratchet files. It takes `--days N` (7 by default), `--all`, or a commit to start after, and `--html FILE` writes a page
+of every week and month. A shrink is credited to the commits that removed the suppressions, not to the automation that
+lowered the number. It warns about any raise larger than the suppressions its commit added. Settle one with `--pardon`,
+`--confirm` or `--recount`, each taking a commit or PR number and a `--why`; the verdicts are kept in
+`mage/resources/kondo-ratchets-verdicts.edn`.
+
## Tool Preferences
If `clojure-mcp` tools are available, prefer them over shell-based alternatives for Clojure development.
diff --git a/bb.edn b/bb.edn
index 86e77f7d975..fd6757cdb16 100644
--- a/bb.edn
+++ b/bb.edn
@@ -367,6 +367,27 @@
:requires [[dev.kondo-ratchet] [mage.kondo-ratchet]]
:task (task! (dev.kondo-ratchet/fix! (assoc (:options parsed) :attribute mage.kondo-ratchet/attribute-occurrences!)))}
+ kondo-ratchets-history
+ {:doc "Report which commits and pull requests shrank, grew and introduced ratchet budgets."
+ :examples [["./bin/mage kondo-ratchets-history" "Summarize the last 7 days"]
+ ["./bin/mage kondo-ratchets-history --days 30" "Summarize the last 30 days"]
+ ["./bin/mage kondo-ratchets-history --all" "Summarize every change since the first ratchet"]
+ ["./bin/mage kondo-ratchets-history --html ratchets.html" "Write a page with every week, every month and all time"]
+ ["./bin/mage kondo-ratchets-history 57e0ad66ea5" "Summarize every change after that commit"]
+ ["./bin/mage kondo-ratchets-history --pardon 78082 --why \"the stricter hook flagged requires that already existed\"" "Count the budget raises in PR 78082 against nobody"]
+ ["./bin/mage kondo-ratchets-history --confirm 8d5db3195d" "Keep counting that commit's raises as growth"]
+ ["./bin/mage kondo-ratchets-history --recount 79531 --why \"the same ignores, named per linter\"" "Count none of a commit's changes: it only changed how suppressions are counted"]]
+ :options [["-d" "--days DAYS" "Days to look back (default 7)" :parse-fn parse-long]
+ ["-a" "--all" "Look back to the first ratchet"]
+ ["-o" "--html FILE" "Write a single-file HTML page covering every week, every month and all time"]
+ [nil "--pardon COMMIT" "Count a commit's budget raises against nobody; takes a commit or PR number"]
+ [nil "--confirm COMMIT" "Keep a questioned commit's raises as growth"]
+ [nil "--recount COMMIT" "Count none of a commit's changes: it only changed how suppressions are counted"]
+ ["-w" "--why REASON" "The reason for a verdict; a pardon or a recount needs one"]]
+ :arg-schema [:or [:tuple] [:tuple [:string {:name "commit" :description "Summarize the changes after this commit; not with --days or --all"}]]]
+ :requires [[mage.kondo-ratchets-history]]
+ :task (task! (mage.kondo-ratchets-history/history parsed))}
+
kondo-redundant-ignores
{:doc "Report inline kondo ignores that are no longer necessary (slow: full kondo run)."
:examples [["./bin/mage kondo-redundant-ignores" "Scan the backend tree for removable ignores"]
diff --git a/dev/src/dev/kondo_ratchet.clj b/dev/src/dev/kondo_ratchet.clj
index 4de5c90739c..f035e134f63 100644
--- a/dev/src/dev/kondo_ratchet.clj
+++ b/dev/src/dev/kondo_ratchet.clj
@@ -427,10 +427,12 @@
(known-linter-hint))
{:unknown (vec unknown)}))))
-(def ^:private source-roots
+(def source-roots
+ "Directories, relative to the repo root, whose source files [[scan]] reads."
["src" "test" "enterprise" "modules/drivers" "dev" "bin" "mage"])
-(def ^:private source-extensions
+(def source-extensions
+ "File extensions [[scan]] reads."
[".clj" ".cljc" ".cljs"])
;; Concatenated so the scan does not count this definition as an ignore.
@@ -573,14 +575,13 @@
:when (not-any? #(<= (:start %) offset (dec (:end %))) matches)]
(offset->line masked offset)))
-(defn ignore-matches
- "Inline ignore matches in `content`, in file order:
- `{:start _, :end _, :line _, :linters [...], :justified? _}` with character offsets and a 1-based line.
+(defn- ignore-forms
+ "Inline ignore forms in `masked` ([[mask-strings-and-comments]]), in file order: `{:start _, :end _, :linters [...]}`
+ with character offsets.
The ignore must be the first key of its map. Any other spelling is rejected rather than guessed at,
- so a suppression cannot silently bypass the ratchet. Matches inside strings and comments are excluded."
- [content]
- (let [masked (mask-strings-and-comments content)
- matches (vec (concat (matches-with-offsets vector-form-re masked false)
+ so a suppression cannot silently bypass the ratchet."
+ [masked]
+ (let [matches (vec (concat (matches-with-offsets vector-form-re masked false)
(matches-with-offsets bare-form-re masked true)))
unsupported (vec (unsupported-ignore-lines masked matches))]
(when (seq unsupported)
@@ -589,11 +590,26 @@
(if (= 1 (count unsupported)) "" "s")
(str/join ", " unsupported))
{:lines unsupported})))
- (->> matches
- (sort-by :start)
- (map #(assoc %
- :line (offset->line masked (:start %))
- :justified? (has-justification-comment? content masked (:start %) (:end %)))))))
+ (sort-by :start matches)))
+
+(defn ignored-linters
+ "Linter keywords suppressed by the inline ignore forms in `content`, one per form that names it.
+ The bare vector-less form counts as `:all`. Forms inside strings and comments are excluded.
+ Throws on an ignore that is not the first key of its map, as [[ignore-matches]] does."
+ [content]
+ (mapcat :linters (ignore-forms (mask-strings-and-comments content))))
+
+(defn ignore-matches
+ "Inline ignore matches in `content`, in file order:
+ `{:start _, :end _, :line _, :linters [...], :justified? _}` with character offsets and a 1-based line.
+ The ignore must be the first key of its map. Any other spelling is rejected rather than guessed at,
+ so a suppression cannot silently bypass the ratchet. Matches inside strings and comments are excluded."
+ [content]
+ (let [masked (mask-strings-and-comments content)]
+ (map #(assoc %
+ :line (offset->line masked (:start %))
+ :justified? (has-justification-comment? content masked (:start %) (:end %)))
+ (ignore-forms masked))))
(defn line-linters
"Linter keywords suppressed by inline ignore forms on `line`.
diff --git a/mage/resources/kondo-ratchets-history.html b/mage/resources/kondo-ratchets-history.html
new file mode 100644
index 00000000000..11cb8be3742
--- /dev/null
+++ b/mage/resources/kondo-ratchets-history.html
@@ -0,0 +1,476 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ratchet history</title>
+<style>
+ :root {
+ --bg: #fbfbfa; --panel: #ffffff; --line: #e4e4e0; --text: #1f2328; --muted: #6b7280;
+ --good: #1a7f37; --bad: #c62828; --accent: #4c5fd5; --pick: #eef0fd; --warn: #9a6700;
+ --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+ }
+ @media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #15171a; --panel: #1c1f23; --line: #2e3238; --text: #e6e8eb; --muted: #9aa3ad;
+ --good: #4ac26b; --bad: #ff7b72; --accent: #9aa8ff; --pick: #262b45; --warn: #d4a72c;
+ }
+ }
+ * { box-sizing: border-box; }
+ body { margin: 0; background: var(--bg); color: var(--text);
+ font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; }
+ .layout { display: grid; grid-template-columns: 230px minmax(0, 1fr); min-height: 100vh; }
+ nav { border-right: 1px solid var(--line); padding: 20px 12px; position: sticky; top: 0; height: 100vh;
+ overflow-y: auto; display: flex; flex-direction: column; }
+ /* the footer link is about the numbers, not a period, so it sits apart at the bottom */
+ nav .foot { margin: auto -12px -20px; padding: 10px 12px 14px; position: sticky; bottom: -20px;
+ background: var(--bg); border-top: 1px solid var(--line); }
+ nav .foot a { color: var(--muted); font-size: 13px; }
+ nav .foot a.on { color: var(--accent); }
+ nav h1 { font-size: 15px; margin: 0 8px 4px; }
+ nav .asof { color: var(--muted); font-size: 12px; margin: 0 8px 16px; }
+ nav h2 { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted);
+ margin: 18px 8px 4px; }
+ nav a { display: flex; justify-content: space-between; gap: 8px; padding: 4px 8px; border-radius: 6px;
+ color: var(--text); text-decoration: none; white-space: nowrap; }
+ nav a:hover { background: var(--pick); }
+ nav a.on { background: var(--pick); color: var(--accent); font-weight: 600; }
+ nav a.empty { color: var(--muted); }
+ nav a .n { font-family: var(--mono); font-size: 12px; }
+ main { padding: 28px 32px 64px; max-width: 1080px; }
+ main > header h2 { font-size: 24px; margin: 0; }
+ main > header p { color: var(--muted); margin: 2px 0 0; }
+ .question { color: var(--muted); margin: 0 0 20px; }
+ .tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 12px; margin: 20px 0 8px; }
+ .tile { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; }
+ .tile .k { color: var(--muted); font-size: 12px; }
+ .tile .v { font: 600 24px/1.2 var(--mono); }
+ section { margin-top: 30px; }
+ section h3 { font-size: 15px; margin: 0 0 2px; }
+ section .hint { color: var(--muted); font-size: 12px; margin: 0 0 8px; }
+ .grid2 { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 16px; }
+ .card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; }
+ .card h4 { margin: 0 0 8px; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); }
+ .scroll { overflow-x: auto; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; }
+ table { border-collapse: collapse; width: 100%; }
+ th, td { padding: 5px 12px; text-align: right; white-space: nowrap; }
+ th:first-child, td:first-child { text-align: left; }
+ thead th { font-size: 12px; font-weight: 600; color: var(--muted); border-bottom: 1px solid var(--line); }
+ tbody tr + tr td { border-top: 1px solid var(--line); }
+ tfoot td { border-top: 2px solid var(--line); font-weight: 600; }
+ .num { font-family: var(--mono); }
+ .name { font-family: var(--mono); font-size: 13px; }
+ .good { color: var(--good); } .bad { color: var(--bad); } .zero { color: var(--muted); }
+ .commit { margin: 0 0 4px; }
+ .commit a { color: var(--accent); text-decoration: none; font-family: var(--mono); font-size: 13px; }
+ .commit a:hover { text-decoration: underline; }
+ .commit .subject { color: var(--muted); }
+ .items { margin: 0 0 12px; padding: 0; list-style: none; }
+ .items li { display: grid; grid-template-columns: 56px 1fr; gap: 10px; }
+ .items li .num { text-align: right; }
+ .warn { border-left: 3px solid var(--warn); }
+ .verdict { margin-bottom: 12px; }
+ .why { margin: 4px 0; }
+ /* chart roles: grown and shrunk carry the status hues, read by position and legend as well as color */
+ :root { --grown: #d03b3b; --shrunk: #0ca30c; --net: #2a78d6; --level: #2a78d6; --grid: #e1e0d9; --axis: #c3c2b7; }
+ @media (prefers-color-scheme: dark) { :root { --grid: #2c2c2a; --axis: #45453f; } }
+ .chart-card { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px 8px;
+ position: relative; }
+ .chart-card h4 { margin: 0; font-size: 14px; display: flex; justify-content: space-between; align-items: baseline; }
+ .chart-card h4 .now { font-family: var(--mono); }
+ .chart-card .sub { color: var(--muted); font-size: 12px; margin: 0 0 6px; }
+ .legend { display: flex; flex-wrap: wrap; gap: 4px 16px; font-size: 12px; margin: 0 0 4px; }
+ .legend span.key { display: inline-block; width: 14px; height: 0; border-top: 2px solid; vertical-align: middle;
+ margin-right: 6px; }
+ .legend b { font-family: var(--mono); font-weight: 600; }
+ svg.chart { width: 100%; height: auto; display: block; overflow: visible; }
+ svg.chart text { fill: var(--muted); font-size: 11px; font-family: inherit; }
+ svg.chart .grid { stroke: var(--grid); stroke-width: 1; }
+ svg.chart .zero { stroke: var(--axis); stroke-width: 1; }
+ svg.chart .line { fill: none; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+ svg.chart .cross { stroke: var(--axis); stroke-width: 1; visibility: hidden; }
+ svg.chart .dot { stroke: var(--panel); stroke-width: 2; visibility: hidden; }
+ .tip { position: absolute; pointer-events: none; background: var(--panel); border: 1px solid var(--line);
+ border-radius: 8px; padding: 8px 10px; font-size: 12px; box-shadow: 0 4px 14px rgba(0, 0, 0, .12);
+ max-width: 300px; visibility: hidden; z-index: 2; }
+ .tip .when { color: var(--muted); }
+ .tip .what { margin: 2px 0 4px; }
+ .tip .row { display: flex; justify-content: space-between; gap: 16px; }
+ .tip .row b { font-family: var(--mono); }
+ .tip .step { color: var(--muted); margin-top: 6px; }
+ .callout { border-left: 3px solid var(--accent); background: var(--pick); border-radius: 6px; padding: 8px 14px;
+ margin: 0 0 12px; font-size: 13px; }
+ .callout p { margin: 0; }
+ .callout ul { margin: 4px 0 0; padding-left: 18px; }
+ .reconcile { margin: 12px 0 0; background: var(--panel); border: 1px solid var(--line);
+ border-radius: 10px; padding: 12px 16px; }
+ .reconcile h4 { margin: 0 0 6px; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); }
+ .reconcile .cols { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 12px 40px; }
+ .reconcile .col > div { display: flex; justify-content: space-between; gap: 16px; padding: 2px 0; }
+ .reconcile .nobody { border-left: 1px solid var(--line); padding-left: 20px; }
+ .reconcile .end { border-top: 1px solid var(--line); margin-top: 6px; padding-top: 6px; font-weight: 600; }
+ .callout .term { font-weight: 500; color: var(--accent); }
+ main a, main a:visited { color: var(--accent); text-decoration: none; }
+ main a:hover { text-decoration: underline; }
+ td a { font-family: var(--mono); font-size: 13px; }
+ details.data { margin-top: 10px; }
+ details.people { margin-top: 30px; border-top: 1px solid var(--line); padding-top: 14px; }
+ details.people > summary { cursor: pointer; font-weight: 600; font-size: 15px; }
+ details.people > .hint { margin: 6px 0 0; }
+ details.data summary { cursor: pointer; color: var(--muted); font-size: 12px; }
+ .none { color: var(--muted); padding: 40px 0; }
+ @media (max-width: 800px) {
+ .layout { grid-template-columns: 1fr; }
+ nav { position: static; height: auto; border-right: 0; border-bottom: 1px solid var(--line); max-height: 40vh; }
+ main { padding: 20px 16px 48px; }
+ }
+</style>
+</head>
+<body>
+<div class="layout">
+ <nav id="nav"></nav>
+ <main id="main"></main>
+</div>
+<script type="application/json" id="data">__DATA__</script>
+<script>
+const data = JSON.parse(document.getElementById("data").textContent);
+const byId = Object.fromEntries(data.periods.map(p => [p.id, p]));
+
+const esc = s => String(s ?? "").replace(/[&<>"]/g, c => ({"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;"}[c]));
+const signed = n => (n > 0 ? "+" + n : String(n));
+// shrunk is good, grown is bad; a net is judged by its sign, and a net of zero keeps the text color
+const tone = (n, kind) => n === 0 ? (kind === "net" ? "" : "zero") : (n < 0 ? "good" : "bad");
+const num = (n, kind) => `<td class="num ${tone(n, kind)}">${signed(n)}</td>`;
+
+// A commit by its sha, PR and subject. Authors are left to the closed block at the end; see people.
+function commit(c) {
+ const sha = `<a href="${esc(data.repo)}/commit/${esc(c.sha)}">${esc(c.sha.slice(0, 10))}</a>`;
+ const pr = c.pr ? ` <a href="${esc(data.repo)}/pull/${c.pr}">#${c.pr}</a>` : "";
+ return `<p class="commit">${sha}${pr} <span class="subject">${esc(c.subject)}</span></p>`;
+}
+
+function table(head, rows, foot) {
+ return `<div class="scroll"><table><thead><tr>${head.map(h => `<th>${esc(h)}</th>`).join("")}</tr></thead>` +
+ `<tbody>${rows.join("")}</tbody>${foot ? `<tfoot>${foot}</tfoot>` : ""}</table></div>`;
+}
+
+function section(title, hint, body) {
+ return body ? `<section><h3>${esc(title)}</h3>${hint ? `<p class="hint">${esc(hint)}</p>` : ""}${body}</section>` : "";
+}
+
+// The first data.shown of `items`, then `more` of the rest, if there are any.
+function capped(items, more) {
+ return items.length > data.shown ? [...items.slice(0, data.shown), more(items.slice(data.shown))] : items;
+}
+
+const sumOf = (items, k) => items.reduce((a, i) => a + i[k], 0);
+
+function biggest(title, b) {
+ if (!b) return "";
+ const items = capped(b.measures, rest => ({measure: `${rest.length} more budgets`, delta: sumOf(rest, "delta"), more: true}))
+ .map(m => `<li><span class="num ${tone(m.delta)}">${signed(m.delta)}</span><span class="${m.more ? "" : "name"}">${esc(m.measure)}</span></li>`);
+ return `<div class="card"><h4>${esc(title)}</h4>${commit(b.commit)}` +
+ `<p><span class="num ${tone(b.net)}"><b>${signed(b.net)}</b></span> net, across ${b.measures.length} budget${b.measures.length === 1 ? "" : "s"}</p>` +
+ `<ul class="items">${items.join("")}</ul></div>`;
+}
+
+function ranking(rows, keep, order, cols) {
+ // the row for what no commit explains has no author
+ const who = r => r.author ?? "(unattributed)";
+ const picked = rows.filter(keep).sort((a, b) => order(a) - order(b) || who(a).localeCompare(who(b)));
+ if (!picked.length) return "";
+ return table(["", ...cols.map(c => c[0])],
+ picked.map(r => `<tr><td>${esc(who(r))}</td>${cols.map(c => c[2](r[c[1]])).join("")}</tr>`));
+}
+
+// The rankings of authors, last on the page and closed until the reader opens them.
+function people(title, body) {
+ if (!body) return "";
+ return `<details class="people"><summary>${esc(title)}</summary>` +
+ `<p class="hint">Here for interest and fun. None of this says anything about anyone's actual virtue or blame.</p>` +
+ `${body}</details>`;
+}
+
+// Side-by-side sections, or nothing when every one of them is empty.
+function grid2(body) {
+ return body ? `<div class="grid2">${body}</div>` : "";
+}
+
+function groups(list, item, cls) {
+ if (!list.length) return "";
+ return `<div class="card ${cls || ""}">` +
+ list.map(g => commit(g.commit) + `<ul class="items">${g.items.map(item).join("")}</ul>`).join("") + "</div>";
+}
+
+// ---- charts: step lines over time, one point per commit that changed a budget ----
+
+const W = 520, H = 220, M = {l: 44, r: 12, t: 10, b: 22};
+const drawn = {};
+const day = t => new Date(t).toLocaleDateString("en-GB", {day: "numeric", month: "short", timeZone: "UTC"});
+
+function ticks(lo, hi, n) {
+ const span = (hi - lo) || 1, mag = Math.pow(10, Math.floor(Math.log10(span / n)));
+ const step = Math.max(1, [1, 2, 5, 10].map(m => m * mag).find(s => span / s <= n + 1));
+ const out = [];
+ for (let v = Math.floor(lo / step) * step; v < hi + step * 0.999; v += step) out.push(Math.round(v));
+ return out;
+}
+
+// The points of a period: its commits, each with running totals from the period's start.
+function points(p) {
+ const inside = data.series.filter(s => (!p.from || s.date.slice(0, 10) >= p.from) && (!p.to || s.date.slice(0, 10) < p.to));
+ let shrunk = 0, grown = 0;
+ return inside.map(s => {
+ shrunk += s.shrunk; grown += s.grown;
+ return {...s, t: Date.parse(s.date), cumShrunk: shrunk, cumGrown: grown, cumNet: shrunk + grown};
+ });
+}
+
+// How many commits in a period changed a counted budget, credited or not, as the charts show them.
+const changed = p => points(p).filter(pt => pt["changed?"]).length;
+
+// The parts of a change to the total budget that count for nobody, as the series points name them.
+const uncredited = [
+ ["introduced", "new linters and measures"],
+ ["seeded", "new ratchets over existing debt"],
+ ["unlimited", "moved into or out of :unlimited"],
+ ["excused", "pardoned, recounted or spare"],
+];
+
+// How the credited change and the parts that count for nobody add up to the change in the total budget.
+function reconcile(pts, before) {
+ const start = before ? before.level : 0, end = pts[pts.length - 1].level;
+ const sum = k => pts.reduce((a, pt) => a + pt[k], 0);
+ const parts = uncredited.map(([k, name]) => [name, sum(k)]).filter(([, n]) => n !== 0);
+ const row = (cls, label, value) => `<div class="${cls}"><span>${esc(label)}</span><span class="num">${value}</span></div>`;
+ // the left column adds up on its own; the right one breaks down its "counted for nobody" line
+ const steps = row("", "Total budget at the start", start) +
+ row("", "Relevant changes, the net on the left", signed(sum("shrunk") + sum("grown"))) +
+ (parts.length ? row("", "Counted for nobody", signed(parts.reduce((a, [, n]) => a + n, 0))) : "") +
+ row("end", "Total budget at the end", end);
+ const nobody = parts.length
+ ? `<div class="col nobody"><h4>Counted for nobody</h4>` +
+ parts.map(([name, n]) => row("", name[0].toUpperCase() + name.slice(1), signed(n))).join("") + `</div>`
+ : "";
+ return `<div class="reconcile"><div class="cols">` +
+ `<div class="col"><h4>How the total budget changed</h4>${steps}</div>${nobody}</div></div>`;
+}
+
+// The rows a total-budget tooltip adds for the commit's own step.
+function stepParts(pt) {
+ return [["relevant", pt.shrunk + pt.grown], ...uncredited.map(([k, name]) => [name, pt[k]])]
+ .filter(([, n]) => n !== 0);
+}
+
+// One chart: `series` are {key, name, color, area}; `start` holds each series' value before the first point.
+// `detail`, if given, maps a point to extra [name, change] rows for its tooltip.
+function chart(id, title, sub, pts, span, series, start, zero, detail) {
+ // a series with no value before its first point has no start, and its line begins at that point
+ const values = pts.flatMap(pt => series.map(s => pt[s.key]))
+ .concat(series.map(s => start[s.key]).filter(v => v != null), zero ? [0] : []);
+ const ys = ticks(Math.min(...values), Math.max(...values), 4);
+ const lo = ys[0], hi = ys[ys.length - 1];
+ const x = t => M.l + (t - span[0]) / ((span[1] - span[0]) || 1) * (W - M.l - M.r);
+ const y = v => M.t + (hi - v) / ((hi - lo) || 1) * (H - M.t - M.b);
+ // a budget holds its value until the next commit, so the line steps
+ const step = s => (start[s.key] == null ? `M${x(pts[0].t)},${y(pts[0][s.key])}` : `M${x(span[0])},${y(start[s.key])}`) +
+ pts.map(pt => `H${x(pt.t)}V${y(pt[s.key])}`).join("") + `H${x(span[1])}`;
+ const grid = ys.map(v => `<line class="${zero && v === 0 ? "zero" : "grid"}" x1="${M.l}" x2="${W - M.r}" y1="${y(v)}" y2="${y(v)}"/>` +
+ `<text x="${M.l - 8}" y="${y(v) + 4}" text-anchor="end">${zero ? signed(v) : v}</text>`).join("");
+ const dates = [0, 1, 2, 3].map(i => span[0] + (span[1] - span[0]) * i / 3).map((t, i) =>
+ `<text x="${x(t)}" y="${H - 4}" text-anchor="${i === 0 ? "start" : i === 3 ? "end" : "middle"}">${day(t)}</text>`).join("");
+ const areas = series.filter(s => s.area).map(s =>
+ `<path d="${step(s)}V${y(0)}H${x(span[0])}Z" fill="var(${s.color})" opacity="0.1"/>`).join("");
+ const lines = series.map(s => `<path class="line" d="${step(s)}" stroke="var(${s.color})"/>`).join("");
+ const dots = series.map(s => `<circle class="dot" data-key="${s.key}" r="4.5" fill="var(${s.color})"/>`).join("");
+ const last = pts[pts.length - 1];
+ const legend = series.length > 1 ? `<p class="legend">${series.map(s =>
+ `<span><span class="key" style="border-color: var(${s.color})"></span>${esc(s.name)} <b>${signed(last[s.key])}</b></span>`).join("")}</p>` : "";
+ drawn[id] = {pts, series, x, y, zero, detail};
+ return `<div class="chart-card"><h4><span>${esc(title)}</span>${series.length === 1 ? `<span class="now">${last[series[0].key]}</span>` : ""}</h4><p class="sub">${esc(sub)}</p>${legend}` +
+ `<svg class="chart" id="${id}" viewBox="0 0 ${W} ${H}" role="img" aria-label="${esc(title)}">${grid}${dates}${areas}${lines}` +
+ `<line class="cross" y1="${M.t}" y2="${H - M.b}"/>${dots}</svg><div class="tip"></div></div>`;
+}
+
+function trends(p) {
+ const pts = points(p);
+ if (!pts.length) return "";
+ const before = data.series[data.series.findIndex(s => s.sha === pts[0].sha) - 1];
+ // one step draws no line, but its parts still need adding up
+ if (pts.length < 2) return section("Trends", "One commit changed a budget in this period.", reconcile(pts, before));
+ const end = Math.min(p.to ? Date.parse(p.to) : Infinity, Date.parse(data.generated) + 864e5);
+ const span = [p.from ? Date.parse(p.from) : pts[0].t, Math.max(end, pts[pts.length - 1].t)];
+ const rows = pts.map(pt => `<tr><td>${esc(pt.date.slice(0, 10))} ${commitLink(pt)}</td>${num(pt.shrunk)}${num(pt.grown)}` +
+ `<td class="num">${signed(uncredited.reduce((a, [k]) => a + pt[k], 0))}</td>` +
+ `${num(pt.cumNet, "net")}<td class="num">${pt.level}</td></tr>`);
+ return section("Trends", "Each step is a commit that changed a budget. Hover a chart for the commit behind a step.",
+ `<div class="callout"><p>The two charts measure different things, so they can move apart:</p><ul>` +
+ `<li><span class="term">Relevant changes</span> tracks fixes and regressions: suppressions removed or added, plus raises not yet settled.</li>` +
+ `<li><span class="term">Total budget</span> also moves when what we measure changes, such as a new ratchet over existing debt.</li>` +
+ `<li><span class="term">The breakdown under the charts</span> shows how the two add up.</li></ul></div>` +
+ `<div class="grid2">` +
+ chart("c-change", "Relevant changes", "Running totals from the start of the period. Up is worse.",
+ pts, span,
+ [{key: "cumGrown", name: "Grown", color: "--grown", area: true},
+ {key: "cumNet", name: "Net", color: "--net"},
+ {key: "cumShrunk", name: "Shrunk", color: "--shrunk", area: true}],
+ {cumGrown: 0, cumNet: 0, cumShrunk: 0}, true) +
+ chart("c-level", "Total budget", "All budgets summed. Hover a step to see its parts.",
+ pts, span, [{key: "level", name: "Total budget", color: "--level"}],
+ {level: before ? before.level : null}, false, stepParts) +
+ `</div>${reconcile(pts, before)}<details class="data"><summary>Data table</summary>` +
+ table(["commit", "shrunk", "grown", "other", "net so far", "total budget"], rows) + `</details>`);
+}
+
+function commitLink(c) {
+ return `<a href="${esc(data.repo)}/commit/${esc(c.sha)}">${esc(c.sha.slice(0, 10))}</a>`;
+}
+
+// Crosshair and tooltip: the pointer picks the latest commit at or before its x.
+function wire() {
+ for (const [id, {pts, series, x, y, zero, detail}] of Object.entries(drawn)) {
+ const svg = document.getElementById(id);
+ if (!svg) continue;
+ const tip = svg.parentNode.querySelector(".tip"), cross = svg.querySelector(".cross");
+ const hide = () => { tip.style.visibility = cross.style.visibility = "hidden"; svg.querySelectorAll(".dot").forEach(d => d.style.visibility = "hidden"); };
+ svg.addEventListener("pointerleave", hide);
+ svg.addEventListener("pointermove", e => {
+ const box = svg.getBoundingClientRect(), px = (e.clientX - box.left) / box.width * W;
+ const at = pts.filter(pt => x(pt.t) <= px).pop() || pts[0];
+ cross.setAttribute("x1", x(at.t)); cross.setAttribute("x2", x(at.t)); cross.style.visibility = "visible";
+ svg.querySelectorAll(".dot").forEach(d => {
+ d.setAttribute("cx", x(at.t)); d.setAttribute("cy", y(at[d.dataset.key])); d.style.visibility = "visible";
+ });
+ // commit subjects are untrusted text
+ tip.textContent = "";
+ const add = (cls, text) => { const el = document.createElement("div"); el.className = cls; el.textContent = text; tip.appendChild(el); return el; };
+ add("when", at.date.slice(0, 10));
+ add("what", at.subject);
+ const row = (label, text) => {
+ const el = add("row", ""), name = document.createElement("span"), value = document.createElement("b");
+ name.textContent = label; value.textContent = text;
+ el.append(name, value);
+ };
+ for (const s of series) row(s.name, zero ? signed(at[s.key]) : at[s.key]);
+ const parts = detail ? detail(at) : [];
+ if (parts.length) {
+ add("step", "This commit");
+ for (const [label, n] of parts) row(label, signed(n));
+ }
+ const left = e.clientX - box.left + 28;
+ tip.style.left = (left + 300 > box.width ? Math.max(0, left - 340) : left) + "px";
+ // an SVG element has no offsetTop, so place the tip from the boxes
+ tip.style.top = (box.top - svg.parentNode.getBoundingClientRect().top + 8) + "px";
+ tip.style.visibility = "visible";
+ });
+ }
+}
+
+function render(p) {
+ const r = p.report;
+ const n = changed(p);
+ const head = `<header><h2>${esc(p.label)}</h2><p>${n} commit${n === 1 ? "" : "s"} changed a ratchet budget</p></header>`;
+ if (!r.commits) {
+ // a period can move the total with no credited change, such as the automation taking back a pardoned raise
+ return head + (n
+ ? `<p class="question">No relevant change in this period, but the budgets changed.</p>` + trends(p)
+ : `<p class="none">No ratchet budget changed in this period.</p>`);
+ }
+ const t = r.total;
+ const linters = r.introduced.reduce((a, g) => a + g.items.length, 0);
+ const tile = (k, v, cls) => `<div class="tile"><div class="k">${k}</div><div class="v ${cls}">${v}</div></div>`;
+ const good = n => `<td class="num good">${n}</td>`;
+ return head +
+ `<div class="tiles">${tile("Shrunk", signed(t.shrunk), tone(t.shrunk))}${tile("Grown", signed(t.grown), tone(t.grown))}` +
+ `${tile("Net", signed(t.net), tone(t.net, "net"))}${tile("Introduced", linters, linters ? "good" : "zero")}</div>` +
+ trends(p) +
+ section("Total deltas by budget",
+ r.approximate.length ? `Credit for ${r.approximate.join(", ")} is approximate: those are budgeted per symbol and counted here per ignore.` : "",
+ table(["", "shrunk", "grown", "net"],
+ r.totals.map(x => `<tr><td class="name">${esc(x.measure)}</td>${num(x.shrunk)}${num(x.grown)}${num(x.net, "net")}</tr>`),
+ `<tr><td>total</td>${num(t.shrunk)}${num(t.grown)}${num(t.net, "net")}</tr>`)) +
+ section("Biggest commits", "The commits responsible for the most change, whoever lowered or raised the number.",
+ (r.best || r.worst) ? `<div class="grid2">${biggest("Biggest improvement", r.best)}${biggest("Biggest regression", r.worst)}</div>` : "") +
+ section("New linters and measures", "A linter, a newly discouraged symbol or a measure of the module ratchet that got its first budget in the commit that added it.",
+ groups(r.introduced, i => `<li><span class="num good">${esc(i.budget)}</span><span class="name good">${esc(i.measure)}</span></li>`)) +
+ section("New ratchets over existing debt", "First budgets for linters and measures that already existed, from a commit that added a whole ratchet. They count for nobody.",
+ groups(r.seeded.map(g => ({...g, items: capped(g.items, rest => ({measure: `${rest.length} more budgets`, budget: sumOf(rest, "size"), more: true}))})),
+ i => `<li><span class="num zero">${esc(i.budget)}</span><span class="${i.more ? "" : "name"}">${esc(i.measure)}</span></li>`)) +
+ section("Spare budget that was taken back", "A budget raised by more than its commit added, and lowered again by a later commit. Neither the raise nor the lowering counts for anybody.",
+ groups(r.slack, i => `<li><span class="num zero">${signed(i.size)}</span><span class="name">${esc(i.measure)}</span></li>`)) +
+ section("Moved into or out of :unlimited", "",
+ groups(r.unlimited, i => `<li><span></span><span><span class="name">${esc(i.measure)}</span> ${esc(i.old)} → ${esc(i.new)}</span></li>`)) +
+ section("Shrinks no commit accounts for", "The automation lowered these budgets, but no commit removed that many suppressions.",
+ groups(r.unaccounted, i => `<li><span class="num ${tone(i.delta)}">${signed(i.delta)}</span><span class="name">${esc(i.measure)}</span></li>`, "warn")) +
+ section("Raises with no verdict", "The budget rose by more than the suppressions the commit added. Pardon or confirm each with ./bin/mage kondo-ratchets-history --pardon or --confirm.",
+ groups(r.suspects.map(g => ({...g, items: capped(g.items, rest => ({measure: `${rest.length} more budgets`, delta: sumOf(rest, "delta"), added: sumOf(rest, "added"), more: true}))})),
+ i => `<li><span class="num bad">${signed(i.delta)}</span><span><span class="${i.more ? "" : "name"}">${esc(i.measure)}</span>, with ${i.added} suppressions added</span></li>`, "warn")) +
+ people("Authors",
+ section("Net by author", "From most shrunk to most grown. A shrink is credited to whoever removed the suppressions.",
+ ranking(r.board, x => x.shrunk || x.grown, x => x.net,
+ [["shrunk", "shrunk", n => num(n)], ["grown", "grown", n => num(n)], ["net", "net", n => num(n, "net")]])) +
+ grid2(
+ section("Most shrunk", "", ranking(r.board, x => x.shrunk < 0, x => x.shrunk, [["shrunk", "shrunk", n => num(n)]])) +
+ section("Most grown", "", ranking(r.board, x => x.grown > 0, x => -x.grown, [["grown", "grown", n => num(n)]]))) +
+ section("Most introduced", "Ranked by the budgets the new linters and measures started with: more debt put under a ratchet is better.",
+ ranking(r.board, x => x.linters > 0, x => -x.ignores, [["budget", "ignores", good], ["new", "linters", good]])));
+}
+
+function nav(current) {
+ // a period with only uncredited changes is not empty, and its credited net is zero
+ const link = (p, label) => `<a href="#${p.id}" class="${p.id === current ? "on" : ""} ${changed(p) ? "" : "empty"}">` +
+ `<span>${esc(label || p.label)}</span><span class="n ${changed(p) ? tone(p.report.total.net, "net") : "zero"}">` +
+ `${changed(p) ? signed(p.report.total.net) : "·"}</span></a>`;
+ const of = kind => data.periods.filter(p => p.kind === kind);
+ const weeks = of("week"), months = of("month");
+ return `<h1>Ratchet history</h1><p class="asof">as of ${esc(data.generated)}</p>` +
+ (weeks[0] ? link(weeks[0], "This week") : "") +
+ (months[1] ? link(months[1], "Last month") : "") +
+ link(byId.all) +
+ `<h2>Weeks</h2>${weeks.map(p => link(p)).join("")}` +
+ `<h2>Months</h2>${months.map(p => link(p)).join("")}` +
+ `<div class="foot">${`<a href="#verdicts" class="${current === "verdicts" ? "on" : ""}"><span>Pardons and exclusions</span><span class="n zero">${data.verdicts.length + data.excluded.length}</span></a>`}</div>`;
+}
+
+// What the numbers leave out, and why: pardoned raises, confirmed ones, and linters that are not counted.
+function verdicts() {
+ const sum = v => v.raises.reduce((a, r) => a + r.delta, 0);
+ const card = v => {
+ const items = capped(v.raises, rest => ({measure: `${rest.length} more budgets`, delta: sumOf(rest, "delta"), more: true}))
+ .map(r => `<li><span class="num zero">${signed(r.delta)}</span><span class="${r.more ? "" : "name"}">${esc(r.measure)}</span></li>`);
+ const kind = {pardon: "Pardon", recount: "Recount", confirm: "Confirmed"}[v.verdict] || v.verdict;
+ const recorded = `<p class="hint">${esc(kind)}${v.by || v.on ? ", recorded" : ""}${v.by ? " by " + esc(v.by) : ""}${v.on ? " on " + esc(v.on) : ""}</p>`;
+ return `<div class="card verdict">${commit(v.commit)}<p class="why">${esc(v.why || "No reason recorded.")}</p>${recorded}` +
+ `<p class="hint">${signed(sum(v))} across ${v.raises.length} budget${v.raises.length === 1 ? "" : "s"}</p><ul class="items">${items.join("")}</ul></div>`;
+ };
+ const of = kind => data.verdicts.filter(v => (kind === "pardon" ? v.verdict !== "confirm" : v.verdict === kind)).sort((a, b) => Date.parse(b.commit.date) - Date.parse(a.commit.date));
+ const total = of("pardon").reduce((a, v) => a + sum(v), 0);
+ const pardoned = of("pardon"), confirmed = of("confirm");
+ return `<header><h2>Pardons and exclusions</h2><p>What the numbers on the other pages leave out, and why</p></header>` +
+ section("Linters left out", "Budgets of these linters are not counted anywhere.",
+ data.excluded.length ? `<div class="card">${data.excluded.map(x => `<p><span class="name">${esc(x.linter)}</span><br><span class="why">${esc(x.why)}</span></p>`).join("")}</div>` : "") +
+ section("Pardoned", `These budget changes count for and against nobody, ${signed(total)} in all: each says nothing about the commit that made it. A later shrink that only takes one back is left out too.`,
+ pardoned.map(card).join("")) +
+ section("Confirmed raises", "These raises outran the suppressions their commit added, were looked at, and still count as growth.",
+ confirmed.map(card).join(""));
+}
+
+function show() {
+ const fallback = (data.periods.find(p => p.kind === "week") || byId.all).id;
+ const hash = location.hash.slice(1);
+ const id = (Object.hasOwn(byId, hash) || hash === "verdicts") ? hash : fallback;
+ for (const key of Object.keys(drawn)) delete drawn[key];
+ document.getElementById("nav").innerHTML = nav(id);
+ document.getElementById("main").innerHTML =
+ `<p class="question">Who shrank, grew and introduced kondo ratchet budgets in ${esc(data.repo.replace("https://github.com/", ""))}, per week and month?</p>` +
+ (id === "verdicts" ? verdicts() : render(byId[id]));
+ wire();
+ document.title = "Ratchet history: " + (id === "verdicts" ? "Pardons and exclusions" : byId[id].label);
+ window.scrollTo(0, 0);
+}
+
+window.addEventListener("hashchange", show);
+show();
+</script>
+</body>
+</html>
diff --git a/mage/resources/kondo-ratchets-verdicts.edn b/mage/resources/kondo-ratchets-verdicts.edn
new file mode 100644
index 00000000000..f9123469cef
--- /dev/null
+++ b/mage/resources/kondo-ratchets-verdicts.edn
@@ -0,0 +1,32 @@
+;; Verdicts on the budget raises `./bin/mage kondo-ratchets-history` questions: a raise beyond the
+;; suppressions its commit added. A :pardon counts the commit's raises against nobody; a :confirm keeps them.
+;; A :recount marks a commit that only changed how suppressions are counted: none of its changes count.
+;; Written by `./bin/mage kondo-ratchets-history --pardon`, `--confirm` and `--recount`.
+[{:sha "e24150083f0b0ceed609329fa1bb985714cee5c2"
+ :pr 78082
+ :subject "Report dynamic requires which linter cannot verify (#78082)"
+ :verdict :pardon
+ :why "The modules hook started reporting dynamic requires it cannot check. The 13 ignores mark requires that already existed."
+ :by "Chris Truter"
+ :on "2026-10-10"}
+ {:sha "dd1cb0f0ba7344ba9a8ef7b42f9ffad7112dafb2"
+ :pr 77820
+ :subject "Require justifications for linter ignores (#77820)"
+ :verdict :recount
+ :why "Two ignores in the Mongo driver had their key where the scanner did not read it. Moving the key first made the scanner count 4 suppressions that already existed."
+ :by "Chris Truter"
+ :on "2026-10-10"}
+ {:sha "e4471f76d3dbf85ef14322e01570e0a3dc793866"
+ :pr 83383
+ :subject "Split kondo ratchet budgets into separate prod and test files (#83383)"
+ :verdict :pardon
+ :why "Splitting the ratchet file needed one new dynamic var, with its ignore, to hold the test file's path. The other unit was spare, and the automation took it back the same day (#83450)."
+ :by "Chris Truter"
+ :on "2026-10-10"}
+ {:sha "ec3b24fadd18ad7458943e9b13b067f375b97d7a"
+ :pr 79531
+ :subject "Make every kondo ignore name the linters it suppresses (#79531)"
+ :verdict :recount
+ :why "Every bare ignore now names its linters, so one that covered two warnings counts under both. The `:all` budget went away, and the named budgets absorbed it."
+ :by "Chris Truter"
+ :on "2026-10-10"}]
diff --git a/mage/src/mage/kondo_ratchets_history.clj b/mage/src/mage/kondo_ratchets_history.clj
new file mode 100644
index 00000000000..c292f681633
--- /dev/null
+++ b/mage/src/mage/kondo_ratchets_history.clj
@@ -0,0 +1,1456 @@
+(ns mage.kondo-ratchets-history
+ "Attribute each change to a ratchet budget to the commits, pull requests and authors behind it.
+
+ A budget changes in one of these ways:
+
+ - shrink: the budget fell.
+ The credit belongs to the earlier commits that removed the suppressions, not to the commit that lowered the
+ number, which is usually the post-merge automation.
+ - grow: the budget of a linter that already existed rose, or it got its first budget in a ratchet that
+ already existed.
+ - introduce: a linter, or a measure of the module ratchet, got its first budget in the commit that added it.
+ - slack: the budget rose by more than the suppressions the commit added, and a later commit lowered it again.
+ Budget that nothing used counts for nobody, and neither does taking it back.
+ - seed: a linter that already existed got its first budget because the commit added a whole ratchet: a new
+ ratchet file, or a new kind of budget in one. Existing debt came under a budget, so it counts for nobody.
+ - limit or unlimit: the budget moved out of or into `:unlimited`.
+
+ A measure is one budgeted count, `[side kind name]`: `[:prod :ignore :deprecated-var]`,
+ `[:test :ignore :deprecated-var]`, `[:prod :config :deprecated-var]` or `[:modules :module :ns-prefixes]`.
+ The per-symbol budgets of a discouragement linter add up to one measure.
+ A commit's diff shows how many `:discouraged-var` ignores it removed, but not which symbols they covered.
+ The budget counts each symbol an ignore covers and this history counts each ignore, so the credit for those
+ linters is approximate.
+
+ To explain a shrink, walk back from the commit that lowered the budget.
+ Every commit on the way contributes its change in the actual count less its own change to the budget.
+ The walk ends when the contributions add up to the shrink, or at the previous commit that only lowered budgets.
+ That commit is the post-merge automation, which leaves no slack behind it.
+ Whatever is left belongs to the commit that lowered the budget, which may have changed what the budget counts.
+ When that commit is the automation itself, the rest is reported as unaccounted.
+
+ A verdict in [[verdicts-file]] changes how a commit counts; see [[verdict!]].
+
+ Only the first-parent history of `HEAD` is read.
+ The analysis of each commit that changed a ratchet file is cached under its sha in [[cache-dir]]."
+ (:require
+ [babashka.fs :as fs]
+ [babashka.json :as json]
+ [babashka.process :as p]
+ [clojure.edn :as edn]
+ [clojure.string :as str]
+ [dev.kondo-ratchet :as ratchet]
+ [mage.color :as c]
+ [mage.shell :as shell]
+ [mage.util :as u])
+ (:import
+ (java.time Instant LocalDate OffsetDateTime)
+ (java.time.format DateTimeFormatter)
+ (java.time.temporal ChronoUnit)
+ (java.util Locale)))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private ratchet-files
+ {:prod ratchet/*ratchets-file*
+ :test ratchet/*test-ratchets-file*
+ :modules ratchet/*module-ratchets-file*})
+
+(def ^:private ratchet-paths (set (vals ratchet-files)))
+
+(def ^:private kondo-config-file ".clj-kondo/config.edn")
+
+(def ^:private module-config-file ".clj-kondo/config/modules/config.edn")
+
+(def ^:private verdicts-file
+ "Verdicts on commits, relative to the repo root. [[verdict!]] writes it."
+ "mage/resources/kondo-ratchets-verdicts.edn")
+
+;; A record holds what this namespace and the scanner made of a commit, so the cache is named for the content
+;; of both: a change to either starts a new one.
+(def ^:private cache-dir
+ (let [sources (for [path ["dev/src/dev/kondo_ratchet.clj" "mage/src/mage/kondo_ratchets_history.clj"]]
+ (slurp (fs/file u/project-root-directory path)))]
+ (fs/path (fs/home) ".cache" "mage" "kondo-ratchets-history"
+ (format "%08x" (bit-and 0xffffffff (hash (str/join sources)))))))
+
+;;; ------------------------------------------------- Budgets --------------------------------------------------
+
+(defn- add-budgets [a b]
+ (if (or (= :unlimited a) (= :unlimited b))
+ :unlimited
+ (+ a b)))
+
+(defn- kondo-measures [side policies]
+ (apply merge-with add-budgets
+ (update-keys (:ignore-counts policies {}) #(vector side :ignore %))
+ (update-keys (:config-counts policies {}) #(vector side :config %))
+ (for [linter ratchet/discouragement-linters
+ :let [budgets (get policies (ratchet/discouraged-count-field linter))]
+ :when (seq budgets)]
+ {[side :ignore linter] (reduce + (vals budgets))})))
+
+(defn measures
+ "Budget per measure for `files`, the parsed ratchet files keyed by `:prod`, `:test` and `:modules`."
+ [{:keys [prod test modules]}]
+ (merge (kondo-measures :prod prod)
+ (kondo-measures :test test)
+ (update-keys (or modules {}) #(vector :modules :module %))))
+
+(defn symbol-budgets
+ "Budget per discouraged symbol for `files`, keyed by `[side linter symbol-key]`."
+ [files]
+ (into {}
+ (for [side [:prod :test]
+ linter ratchet/discouragement-linters
+ [sym n] (get-in files [side (ratchet/discouraged-count-field linter)])]
+ [[side linter sym] n])))
+
+(defn- merge-sides
+ "Fold the `:test` entries of `by-measure` into `:prod`: the view from before test code had its own budgets."
+ [by-measure]
+ (reduce-kv (fn [acc k v]
+ (update acc (assoc k 0 (if (= :test (first k)) :prod (first k))) (fnil add-budgets 0) v))
+ {}
+ by-measure))
+
+(defn- ratchets
+ "The `[side kind]` of every ratchet that exists in `files`, whether or not it holds a budget yet."
+ [files]
+ (set (concat
+ (for [side [:prod :test]
+ :let [policies (get files side)]
+ :when policies
+ kind (cond-> []
+ (some #(contains? policies %)
+ (cons :ignore-counts (map ratchet/discouraged-count-field ratchet/discouragement-linters)))
+ (conj :ignore)
+
+ (contains? policies :config-counts)
+ (conj :config))]
+ [side kind])
+ (when (:modules files)
+ [[:modules :module]]))))
+
+(defn- readable
+ "The parsed ratchet `files` on one side of a commit, with each that is `::unreadable` taken to be what
+ it is in `others`, the other side, or absent when it is unreadable there too."
+ [files others]
+ (into {}
+ (for [[k file] files]
+ [k (if (= ::unreadable file)
+ (let [other (get others k)]
+ (when (not= ::unreadable other) other))
+ file)])))
+
+(defn budget-view
+ "The budgets on each side of a commit, from the parsed ratchet files `before` and `after` it.
+ The commit that adds or removes the test file is viewed with both sides merged.
+ Moving a budget from one file to the other is then not a change.
+ A file that is `::unreadable` on one side is taken to be unchanged: nothing can be read across it.
+ Under `:ratcheted` are the `[side kind]` of the ratchets that existed before the commit."
+ [before after]
+ (let [[before after] [(readable before after) (readable after before)]
+ merged? (not= (some? (:test before)) (some? (:test after)))
+ view (if merged? merge-sides identity)
+ side (fn [[side kind]] [(if (and merged? (= :test side)) :prod side) kind])]
+ {:merged? merged?
+ :ratcheted (into #{} (map side) (ratchets before))
+ :before (view (measures before))
+ :after (view (measures after))
+ :symbols-before (view (symbol-budgets before))
+ :symbols-after (view (symbol-budgets after))}))
+
+(defn- seeded-budgets
+ "The budget `changes` gave each measure for symbols it newly discouraged."
+ [changes]
+ (reduce (fn [acc {:keys [key measure new]}]
+ (cond-> acc key (update measure (fnil + 0) new)))
+ {}
+ changes))
+
+(defn budget-changes
+ "Classify what a commit did to each budget in `view` ([[budget-view]]).
+ Returns maps of `:measure`, `:kind`, `:old` and `:new`, with a `:delta` for a `:shrink` or `:grow`.
+ The kinds are those the namespace docstring lists.
+ A change to a measure that has per-symbol budgets is marked `:per-symbol?`.
+ A newly discouraged symbol is its own `:introduce`, with the symbol as `:key`.
+ Given a measure, `new-measure?` says whether the commit also added what it counts: its linter, or the module
+ measure.
+ Given a linter and a symbol, `new-symbol?` says the same of the symbol."
+ [{:keys [ratcheted before after symbols-before symbols-after]} {:keys [new-measure? new-symbol?]}]
+ (let [symbolic (into #{}
+ (map (fn [[side linter _]] [side :ignore linter]))
+ (concat (keys symbols-before) (keys symbols-after)))
+ symbols (for [[[side linter sym :as k] n] (sort-by (comp str key) symbols-after)
+ :when (and (not (contains? symbols-before k))
+ (new-symbol? linter sym))]
+ {:measure [side :ignore linter]
+ :kind :introduce
+ :key sym
+ :new n})
+ seeded (seeded-budgets symbols)]
+ (concat
+ symbols
+ (for [measure (sort-by str (set (concat (keys before) (keys after))))
+ :let [seed (get seeded measure 0)
+ budget (get after measure)
+ ;; the budget of a newly discouraged symbol is an introduction, not growth of its linter
+ old (if (pos? seed) (get before measure 0) (get before measure))
+ new (cond-> budget (and (pos? seed) (number? budget)) (- seed))
+ ;; budgeted per symbol, so counting its ignores only approximates it
+ change (cond-> {:measure measure, :old old, :new new}
+ (symbolic measure) (assoc :per-symbol? true))]
+ :when (not= old new)]
+ (cond
+ (and (nil? old) (new-measure? measure))
+ (assoc change :kind :introduce)
+
+ ;; no ratchet of this kind on this side before: the commit added the ratchet itself
+ (and (nil? old) (not (ratcheted (subvec measure 0 2))))
+ (assoc change :kind :seed)
+
+ (= :unlimited old)
+ (assoc change :kind :limit)
+
+ (= :unlimited new)
+ (assoc change :kind :unlimit)
+
+ :else
+ (let [delta (- (or new 0) (or old 0))]
+ (assoc change :kind (if (neg? delta) :shrink :grow) :delta delta)))))))
+
+(defn- subtract
+ "The difference of `new` less `old`, per key, without the zeros."
+ [new old]
+ (into {} (remove (comp zero? val)) (merge-with + new (update-vals old -))))
+
+(defn- budget-delta
+ "How far a commit moved each numeric budget, from its `view`. A budget it added or removed counts from zero.
+ A move into or out of `:unlimited` is no number."
+ [{:keys [before after]}]
+ (into {}
+ (for [measure (set (concat (keys before) (keys after)))
+ :let [old (get before measure 0)
+ new (get after measure 0)]
+ :when (and (number? old) (number? new) (not= old new))]
+ [measure (- new old)])))
+
+;;; ------------------------------------------------ Attribution -----------------------------------------------
+
+(defn attribute
+ "Explain `shrunk`, a map from measure to its (negative) budget change, by `contributions`.
+ Those are `[commit deltas]` pairs, newest first, where `deltas` maps a measure to what that commit added to
+ its slack-free count.
+ Returns `:causes`, a map from measure to the commits (each with its `:delta`) that explain it, and `:open`,
+ the part of each shrink that no commit explains.
+ A measure stops collecting causes once it is fully explained."
+ [shrunk contributions]
+ (reduce (fn [acc [commit deltas]]
+ (if (empty? (:open acc))
+ (reduced acc)
+ (reduce-kv (fn [acc measure delta]
+ (if-let [open (get-in acc [:open measure])]
+ (-> acc
+ (update-in [:causes measure] (fnil conj []) (assoc commit :delta delta))
+ (update :open (if (= open delta)
+ #(dissoc % measure)
+ #(assoc % measure (- open delta)))))
+ acc))
+ acc
+ deltas)))
+ {:open shrunk, :causes {}}
+ contributions))
+
+;;; ---------------------------------------------------- Git ---------------------------------------------------
+
+(defn- shell-options
+ "Options for a command run in `repo`: quiet, in its directory, and in its environment when it has one."
+ [{:keys [dir env]}]
+ (cond-> {:quiet? true, :dir dir}
+ env (assoc :env env)))
+
+(defn- git [repo & args]
+ (apply shell/sh (shell-options repo) "git" args))
+
+(defn- git-result
+ "The `:exit` code and `:out` lines of git run in `repo` with the vector `args`, without throwing when it fails."
+ [repo args]
+ (apply shell/sh* (shell-options repo) "git" args))
+
+(defn- git-ok? [repo & args]
+ (zero? (:exit (git-result repo args))))
+
+(defn repo
+ "What a run works on and the state it keeps: the git repository in `:dir`, the `:head` commit it was on when
+ the run began, the `:cache-dir` for its records, the `:verdicts-file`, the blob tallies so far and the last
+ window loaded.
+ By default `dir` is this repository, `cache` its cache, and `verdicts` the verdicts file in `dir`.
+ Any `env` adds variables to the environment of every git call."
+ [{:keys [dir cache verdicts env]}]
+ (let [dir (or dir u/project-root-directory)
+ repo {:dir dir
+ :env (when env (merge (into {} (System/getenv)) env))
+ :cache-dir (or cache cache-dir)
+ :verdicts-file (or verdicts (fs/file dir verdicts-file))
+ :tallied (atom {})
+ :window (atom nil)}]
+ ;; resolved once, so that a commit landing during a long run cannot split it across two histories
+ (assoc repo :head (first (git repo "rev-parse" "HEAD")))))
+
+(defn- file-at [repo rev path]
+ (let [{:keys [exit out]} (git-result repo ["show" (str rev ":" path)])]
+ (when (zero? exit)
+ (str/join "\n" out))))
+
+(defn- read-ratchet
+ "The ratchet file `path` at `rev`, parsed from its `text`.
+ Warns and returns `::unreadable` when it does not parse, so that one broken commit does not stop the run and
+ is not mistaken for the file being absent."
+ [rev path text]
+ (try
+ (edn/read-string text)
+ (catch Exception e
+ (binding [*out* *err*]
+ (println (format "WARNING: %s at %s does not parse, so changes to it there are skipped: %s"
+ path rev (ex-message e))))
+ ::unreadable)))
+
+(def ^:private budgets-at
+ (memoize (fn [repo rev]
+ (update-vals ratchet-files #(some->> (file-at repo rev %) (read-ratchet rev %))))))
+
+;; %aN and %aE follow the repo's .mailmap, when it has one
+(def ^:private log-format "--format=%x01%H%x1f%aN%x1f%aE%x1f%cI%x1f%s")
+
+(defn- pr-number [subject]
+ (some-> (re-find #"\(#(\d+)\)\s*$" (or subject "")) second parse-long))
+
+(defn parse-log
+ "Commits from the lines of `git log --raw` output in [[log-format]], each with the `:files` it changed."
+ [lines]
+ (reduce (fn [commits line]
+ (cond
+ (str/starts-with? line "\u0001")
+ (let [[sha author email date subject] (str/split (subs line 1) #"\u001f" 5)]
+ (conj commits {:sha sha
+ :author author
+ :email email
+ :date date
+ :subject subject
+ :pr (pr-number subject)
+ :files []}))
+
+ (str/starts-with? line ":")
+ (let [[stat path] (str/split line #"\t" 2)
+ [_ _ old new] (str/split stat #" ")]
+ (update-in commits [(dec (count commits)) :files] conj {:path path, :old old, :new new}))
+
+ :else
+ commits))
+ []
+ lines))
+
+(defn- log [repo & args]
+ (parse-log (apply git repo "log" "--first-parent" "--topo-order" "--diff-merges=first-parent" "--no-renames"
+ "--raw" "--no-abbrev" log-format args)))
+
+(defn- ratchet-commits
+ "Shas of the commits that changed a ratchet file, newest first.
+ The `args` select the commits, as for `git log`."
+ [repo & args]
+ (vec (apply git repo (concat ["log" "--first-parent" "--format=%H"] args ["--"] ratchet-paths))))
+
+(def ^:private symbol-delimiter "[^A-Za-z0-9*+!?<>=._/-]")
+
+(def ^:private linter-sources
+ "Where a linter or a discouraged symbol is defined: the kondo config and hooks, without the ratchet files."
+ (cons ".clj-kondo" (map #(str ":(exclude)" %) ratchet-paths)))
+
+(def ^:private module-measure-sources
+ "Where the module ratchet's measures are defined."
+ ["dev/src/dev/kondo_ratchet.clj"])
+
+(defn- mentioned?
+ "Does a tracked file under the pathspecs `sources` name one of `names` at `rev`?"
+ [repo rev sources names]
+ (let [quoted (map #(str/replace % #"[.*+?|()\[\]{}^$\\]" "\\\\$0") names)]
+ (apply git-ok? repo "grep" "-q" "-E"
+ "-e" (str "(^|" symbol-delimiter ")(" (str/join "|" quoted) ")(" symbol-delimiter "|$)")
+ rev "--" sources)))
+
+(defn- added-in?
+ "Did commit `sha` add the first mention of one of `names` under the pathspecs `sources`?"
+ [repo sha sources names]
+ (and (not (mentioned? repo (str sha "^") sources names))
+ (mentioned? repo sha sources names)))
+
+(defn- symbol-names
+ "The symbols a discouraged-symbol ratchet key may stand for; see [[ratchet/discouraged-count-key]]."
+ [sym-key]
+ (let [s (subs (str sym-key) 1)]
+ (if (str/starts-with? s "ee.")
+ [(str "metabase-enterprise." (subs s 3))]
+ [s (str "metabase." s)])))
+
+(defn- last-readable
+ "The ratchet files as they were before commit `sha`, with each that does not parse there taken from the
+ nearest earlier commit where it does."
+ [repo sha]
+ (let [broken? (fn [files] (some #{::unreadable} (vals files)))
+ before (budgets-at repo (str sha "^"))]
+ (if-not (broken? before)
+ before
+ (reduce (fn [files earlier]
+ (if (broken? files)
+ (merge-with (fn [file older] (if (= ::unreadable file) older file))
+ files
+ (budgets-at repo earlier))
+ (reduced files)))
+ before
+ (ratchet-commits repo (str sha "^"))))))
+
+(def ^:private commit-view
+ (memoize (fn [repo sha]
+ ;; Measured from the last readable version, so that the commit that repairs a broken ratchet file
+ ;; carries whatever changed across the gap. The commit that broke it shows no change.
+ (budget-view (last-readable repo sha) (budgets-at repo sha)))))
+
+(def ^:private commit-changes
+ (memoize (fn [repo sha]
+ ;; TODO (Chris 2026-10-10) -- also report linters that landed with no budget at all, because nothing
+ ;; needed an ignore. No ratchet file changes for those, so this history never sees them.
+ (let [view (commit-view repo sha)
+ changes (budget-changes view
+ {:new-measure? (fn [[_ kind measured]]
+ (added-in? repo sha
+ (if (= :module kind)
+ module-measure-sources
+ linter-sources)
+ [(str measured)]))
+ :new-symbol? (fn [_linter sym]
+ (added-in? repo sha linter-sources
+ (symbol-names sym)))})
+ ;; A change to a ratchet file that was broken before this commit spans every commit since
+ ;; its last readable version, while the suppressions counted for it are this commit's own.
+ broken (into #{}
+ (keep (fn [[side file]] (when (= ::unreadable file) side)))
+ (budgets-at repo (str sha "^")))
+ ;; a view with test budgets folded into prod reports the test file's changes as prod's
+ broken (cond-> broken (and (:merged? view) (broken :test)) (conj :prod))]
+ (mapv (fn [{[side] :measure, :as change}]
+ (cond-> change (broken side) (assoc :bridged? true)))
+ changes)))))
+
+(defn tightening?
+ "Did a commit only lower budgets, as the post-merge automation does?
+ It takes the `paths` of the files the commit changed and the `kinds` of its budget changes."
+ [paths kinds]
+ ;; a commit that also raises or adds a budget, as a seeding one does, may leave slack behind
+ (boolean (and (seq paths)
+ (every? ratchet-paths paths)
+ (every? #{:shrink :limit} kinds)
+ (some #{:shrink} kinds))))
+
+(def ^:private tighten?
+ "Is commit `sha` one that [[tightening?]] holds for? Such a commit leaves no slack."
+ ;; memoized: the search for a shrink's boundary asks this of every older commit, each time with a git call
+ (memoize (fn [repo sha]
+ ;; without a merge diff mode a merge commit lists no paths at all
+ (tightening? (git repo "diff-tree" "--no-commit-id" "--name-only" "-r" "--diff-merges=first-parent" sha)
+ (map :kind (commit-changes repo sha))))))
+
+(defn- blobs
+ "A map from each of the git blobs `shas` to `f` of its sha and content."
+ [repo f shas]
+ (if (empty? shas)
+ {}
+ (let [options (merge (select-keys (shell-options repo) [:dir :env]) {:in (str/join "\n" shas), :out :bytes})
+ ^bytes out (:out (p/shell options "git" "cat-file" "--batch"))]
+ (loop [pos 0, acc {}]
+ (if (>= pos (alength out))
+ acc
+ (let [eol (long (loop [i pos] (if (= 10 (aget out i)) i (recur (inc i)))))
+ [sha _ n] (str/split (String. out (int pos) (int (- eol pos)) "UTF-8") #" ")]
+ ;; a missing object has a header and no content
+ (if-let [size (some-> n parse-long)]
+ (recur (+ eol size 2) (assoc acc sha (f sha (String. out (int (inc eol)) (int size) "UTF-8"))))
+ (recur (inc eol) acc))))))))
+
+(def ^:private no-blob (apply str (repeat 40 "0")))
+
+(defn- source-file? [path]
+ (and (some #(str/starts-with? path (str % "/")) ratchet/source-roots)
+ (some #(str/ends-with? path %) ratchet/source-extensions)))
+
+(defn counts
+ "What `content`, the file at `path`, adds to each measure's actual count.
+ Sides are those of the file's path."
+ [path content]
+ (cond
+ (= path kondo-config-file)
+ (update-keys (ratchet/config-suppressions (edn/read-string content)) #(vector :prod :config %))
+
+ (= path module-config-file)
+ (update-keys (ratchet/module-escape-hatches (:metabase/modules (edn/read-string content)))
+ #(vector :modules :module %))
+
+ (and (source-file? path) (str/includes? content "clj-kondo/ignore"))
+ (let [side (if (ratchet/test-occurrence? {:file path}) :test :prod)]
+ (update-keys (frequencies (ratchet/ignored-linters content))
+ #(vector side :ignore %)))
+
+ :else
+ {}))
+
+(defn- tallies
+ "What each blob in `files`, the files some commits changed, adds to each measure's actual count.
+ Returns a map from blob sha to path to [[counts]], or to `::unreadable` when the blob does not parse at that
+ path. Only the counts are kept, since a window can change far more source than fits in memory.
+ They are kept for the run in `repo`, so that windows that share a blob scan it once."
+ [repo files]
+ (let [paths (reduce (fn [acc {:keys [path old new]}]
+ (-> acc
+ (update old (fnil conj #{}) path)
+ (update new (fnil conj #{}) path)))
+ {}
+ files)
+ seen @(:tallied repo)
+ pending (for [[sha at] (dissoc paths no-blob)
+ :when (not-every? (get seen sha {}) at)]
+ sha)
+ tally (fn [sha content]
+ (into {}
+ (for [path (paths sha)]
+ [path (try
+ (counts path content)
+ (catch Exception _
+ ::unreadable))])))]
+ (swap! (:tallied repo)
+ #(merge-with merge % (into {} (mapcat (partial blobs repo tally)) (partition-all 500 pending))))))
+
+(defn actual-delta
+ "How far `commit` moved each measure's actual count, from the [[tallies]] of its files.
+ A file that cannot be read on both sides counts nothing."
+ [tallies commit]
+ (apply merge-with + {}
+ (for [{:keys [path old new]} (:files commit)
+ :let [before (get-in tallies [old path] {})
+ after (get-in tallies [new path] {})]
+ :when (not-any? #{::unreadable} [before after])]
+ (subtract after before))))
+
+(defn- load-window
+ "The commits after `boundary` up to `sha`, newest first, that could have moved an actual count or a budget.
+ Returns them as `:commits`, with `:actual`, a function from one of them to how far it moved each actual count."
+ [repo boundary sha]
+ (let [counted? (some-fn source-file? ratchet-paths #{kondo-config-file module-config-file})
+ commits (mapv (fn [commit] (update commit :files #(filterv (comp counted? :path) %)))
+ (apply log repo (str boundary ".." sha) "--"
+ (concat ratchet/source-roots [kondo-config-file module-config-file] ratchet-paths)))
+ by-blob (tallies repo (mapcat :files commits))]
+ {:boundary boundary
+ :commits commits
+ :actual (memoize #(actual-delta by-blob %))}))
+
+(defn- window
+ "[[load-window]], reusing the last one loaded in this run when it has the same `boundary` and reaches `sha`.
+ Commits are analysed newest first, so the shrinks that share a boundary share the first window loaded for it."
+ [repo boundary sha]
+ (let [from-sha (fn [commits] (drop-while #(not= sha (:sha %)) commits))
+ cached @(:window repo)]
+ (if (and (= boundary (:boundary cached)) (seq (from-sha (:commits cached))))
+ (update cached :commits (comp vec from-sha))
+ (reset! (:window repo) (load-window repo boundary sha)))))
+
+(defn- merged-view?
+ "Is the commit `sha`, which changed a ratchet file, viewed with test budgets folded into prod?
+ That holds for a commit from before test code had its own ratchet file, and for the one that split it out."
+ [repo sha]
+ (or (:merged? (commit-view repo sha))
+ (nil? (:test (budgets-at repo sha)))))
+
+(defn- with-added
+ "The budget `changes` of commit `sha`, with the suppressions it `:added` on each `:grow`."
+ [repo sha changes]
+ (if (not-any? #(= :grow (:kind %)) changes)
+ changes
+ (let [{:keys [commits actual]} (load-window repo (str sha "^") sha)
+ added (subtract (cond-> (actual (first commits)) (merged-view? repo sha) merge-sides)
+ (seeded-budgets changes))]
+ (mapv (fn [{:keys [kind measure], :as change}]
+ (cond-> change (= :grow kind) (assoc :added (get added measure 0))))
+ changes))))
+
+(defn- budgeted-from-count
+ "The measures that commit `sha` gave a first budget taken to match their count, leaving no slack: the seeds,
+ the new linters and measures, and the linters it newly discouraged a symbol under.
+ A first budget in a ratchet that already existed is growth, and can leave slack."
+ [repo sha]
+ ;; For a newly discouraged symbol this sets aside the commit's whole effect on its linter: the diff does not
+ ;; say which ignores cover the new symbol, so its budget cannot be told from slack.
+ (distinct (for [{:keys [kind measure]} (commit-changes repo sha)
+ :when (#{:seed :introduce} kind)]
+ measure)))
+
+(defn- contributions
+ "The `[commit deltas]` pairs [[attribute]] takes, for the shrink in commit `sha` and the commits back to
+ `boundary`."
+ [repo boundary sha changes]
+ (let [{:keys [commits actual]} (window repo boundary sha)
+ ratchet? (fn [commit] (some ratchet-paths (map :path (:files commit))))
+ ;; The newest commit in the window with the merged view, if any. Every commit from it back has that view
+ ;; too, and asking only the commits that changed a ratchet file keeps this to a few git calls.
+ split (first (keep-indexed (fn [i commit]
+ (when (and (ratchet? commit) (merged-view? repo (:sha commit)))
+ i))
+ commits))
+ seeded (seeded-budgets changes)]
+ (map-indexed (fn [i commit]
+ (let [actual (cond-> (actual commit) (and split (>= i split)) merge-sides)]
+ [(dissoc commit :files)
+ (cond
+ (= sha (:sha commit)) (subtract actual seeded)
+ (ratchet? commit) (apply dissoc
+ (subtract actual (budget-delta (commit-view repo (:sha commit))))
+ (budgeted-from-count repo (:sha commit)))
+ :else actual)]))
+ commits)))
+
+(defn- analyse
+ "The record for `sha`, a commit that changed a ratchet file.
+ The `history` is every such commit, newest first."
+ [repo history sha]
+ (let [changes (commit-changes repo sha)
+ shrunk (into {} (for [{:keys [kind measure delta]} changes :when (= kind :shrink)] [measure delta]))
+ older (rest (drop-while #(not= sha %) history))
+ boundary (or (first (filter #(tighten? repo %) older)) (last older))
+ {:keys [open causes]} (when (and boundary (seq shrunk))
+ (attribute shrunk (contributions repo boundary sha changes)))]
+ (cond-> (-> (first (parse-log (git repo "log" "-1" log-format sha)))
+ (dissoc :files)
+ (assoc :changes (with-added repo sha changes)))
+ (seq causes) (assoc :causes causes)
+ (seq open) (assoc :unaccounted open)
+ (tighten? repo sha) (assoc :tighten? true))))
+
+;;; --------------------------------------------------- Cache --------------------------------------------------
+
+(defn- cached [repo sha]
+ (let [file (fs/file (:cache-dir repo) (str sha ".edn"))]
+ (when (fs/exists? file)
+ (edn/read-string (slurp file)))))
+
+(defn- record!
+ "The record for `sha`, from the cache when it is there."
+ [repo history sha]
+ (or (cached repo sha)
+ (let [record (analyse repo history sha)]
+ (fs/create-dirs (:cache-dir repo))
+ (spit (fs/file (:cache-dir repo) (str sha ".edn")) (pr-str record))
+ record)))
+
+(defn records
+ "The record of every commit that changed a ratchet file in the history of `HEAD`, newest first.
+ Analyses and caches the ones that are not cached yet.
+ The optional callbacks report that work: `:starting` takes how many commits need analysing, and is not called
+ when none do, and `:analysed` takes each of their records."
+ ([repo]
+ (records repo {}))
+ ([repo {:keys [starting analysed]}]
+ (let [all (ratchet-commits repo (:head repo))
+ pending (set (remove #(cached repo %) all))]
+ (when (and starting (seq pending))
+ (starting (count pending)))
+ (mapv (fn [sha]
+ (let [record (record! repo all sha)]
+ (when (and analysed (pending sha))
+ (analysed record))
+ record))
+ all))))
+
+;;; -------------------------------------------------- Verdicts ------------------------------------------------
+
+(def ^:private uncounted-linters
+ "Linters whose suppressions say nothing about the code, each with the reason. Their budgets are left out."
+ {:metabase/prefer-with-dynamic-fn-redefs "Ignoring it works around a bug in the linter itself."})
+
+(def ^:private verdicts-header
+ [";; Verdicts on the budget raises `./bin/mage kondo-ratchets-history` questions: a raise beyond the"
+ ";; suppressions its commit added. A :pardon counts the commit's raises against nobody; a :confirm keeps them."
+ ";; A :recount marks a commit that only changed how suppressions are counted: none of its changes count."
+ ";; Written by `./bin/mage kondo-ratchets-history --pardon`, `--confirm` and `--recount`."])
+
+(defn- read-verdicts [repo]
+ (let [file (:verdicts-file repo)]
+ (if (fs/exists? file)
+ (edn/read-string (slurp file))
+ [])))
+
+(defn render-verdicts
+ "The text of [[verdicts-file]] holding `verdicts`: a vector of maps, one key per line."
+ [verdicts]
+ (let [entry (fn [verdict]
+ (str "{"
+ (str/join "\n "
+ (for [k [:sha :pr :subject :verdict :why :by :on]
+ :when (some? (get verdict k))]
+ (format "%-8s %s" k (pr-str (get verdict k)))))
+ "}"))]
+ (str (str/join "\n" verdicts-header)
+ "\n["
+ (str/join "\n " (map entry verdicts))
+ "]\n")))
+
+(defn- covered-kinds
+ "The kinds of change that a verdict of `kind` is about."
+ [kind]
+ (if (= :recount kind)
+ #{:grow :shrink}
+ #{:grow}))
+
+(defn- unused-budget
+ "How much of a raise, a `:grow` change, went beyond the suppressions its commit added, or nil when none did.
+ A commit that removed suppressions while raising a budget added none.
+ A measure budgeted per symbol is counted per ignore, which is only approximate, so its raises are never
+ held to the count. Neither is a `:bridged?` raise, made by the commit that repaired a broken ratchet file:
+ the suppressions behind it may have come in while the file was broken."
+ [{:keys [kind measure delta added per-symbol? bridged?]}]
+ (when (and (= :grow kind)
+ added
+ (< added delta)
+ (not per-symbol?)
+ (not bridged?)
+ (not (uncounted-linters (peek measure))))
+ (- delta (max 0 added))))
+
+(defn suspects
+ "The commits in `records` not in `judged` that raised a budget beyond the suppressions they added.
+ Each keeps only those raises as its `:changes`."
+ [judged records]
+ (for [record records
+ :when (not (judged (:sha record)))
+ :let [raises (filter unused-budget (:changes record))]
+ :when (seq raises)]
+ (assoc record :changes raises)))
+
+(defn- split-causes
+ "The `causes` of the shrinks in commit `sha`, per measure, split in two.
+ For each measure, `:returned` is how much of them only takes back another commit's raise: the whole cause
+ when that commit is one `recount?` holds for, or else up to what is `left` of its pardoned raise, a map from
+ commit to measure.
+ Next to it, `:kept` holds the causes with what remains of each.
+ Returns `[left split]`, with what was taken back removed from `left`."
+ [left recount? sha causes]
+ (reduce-kv
+ (fn [[left split] measure entries]
+ (let [[left returned kept]
+ (reduce (fn [[left returned kept] {cause :sha, :keys [delta], :as entry}]
+ (let [allowance (get-in left [cause measure])
+ back (cond
+ (= sha cause) 0
+ (recount? cause) delta
+ (nil? allowance) 0
+ ;; what the commit removed beyond its own raise is a real improvement
+ :else (min 0 (max delta (- allowance))))
+ remains (- delta back)]
+ [(cond-> left (and allowance (neg? back)) (update-in [cause measure] + back))
+ (+ returned back)
+ (cond-> kept (not (zero? remains)) (conj (assoc entry :delta remains)))]))
+ [left 0 []]
+ entries)]
+ [left (assoc split measure {:returned returned, :kept kept})]))
+ [left {}]
+ causes))
+
+(defn- spare-budget
+ "Per commit and measure, how far a raise in `records` outran the suppressions its commit added: budget that
+ nothing used. Commits in `judged` have a verdict already and are left out."
+ [judged records]
+ (into {}
+ (for [{:keys [sha changes]} records
+ :when (not (judged sha))
+ :let [spare (into {}
+ (for [{:keys [measure], :as change} changes
+ :let [unused (unused-budget change)]
+ :when unused]
+ [measure unused]))]
+ :when (seq spare)]
+ [sha spare])))
+
+(defn pardon
+ "The `records`, the whole history newest first, with the verdicts applied.
+ A raise in `pardons`, a map from commit to measure to the size of the raise, turns from `:grow` into `:pardon`.
+ A shrink loses the part that only takes a pardoned raise back, and the credit for it.
+ A raise is taken back once: the oldest shrinks after it use it up.
+ A commit in `recounts` only changed how suppressions are counted, so its own shrinks go too, and so does any
+ credit it has for a later shrink.
+ Any `spare` budget, as [[spare-budget]] gives it, is taken back in the same way without a verdict.
+ The part of a raise a later shrink took back is its `:slack`; a raise that was all slack becomes a `:slack`."
+ [{:keys [pardons recounts spare]} records]
+ (let [recount? (or recounts #{})
+ settle-change (fn [split sha {:keys [kind measure delta], :as change}]
+ (case kind
+ :grow (cond-> change (get-in pardons [sha measure]) (assoc :kind :pardon))
+ :shrink (let [delta (- delta (get-in split [measure :returned] 0))]
+ (when-not (or (recount? sha) (zero? delta))
+ (assoc change :delta delta :kind (if (neg? delta) :shrink :grow))))
+ change))
+ [left settled]
+ (reduce (fn [[left settled] {:keys [sha causes], :as record}]
+ (let [[left split] (split-causes left recount? sha causes)]
+ ;; consing onto a list puts the records back newest first
+ [left (cons (cond-> (update record :changes #(keep (partial settle-change split sha) %))
+ causes (assoc :causes (update-vals split :kept)))
+ settled)]))
+ [(merge-with merge spare pardons) ()]
+ (reverse records))
+ loosen (fn [sha {:keys [kind measure delta], :as change}]
+ (let [taken (if (= :grow kind)
+ (- (get-in spare [sha measure] 0) (get-in left [sha measure] 0))
+ 0)]
+ (cond
+ (zero? taken) change
+ (= taken delta) (assoc change :kind :slack)
+ :else (assoc change :delta (- delta taken) :slack taken))))]
+ (for [{:keys [sha], :as record} settled]
+ (update record :changes #(map (partial loosen sha) %)))))
+
+(defn counted
+ "The `records` without the changes to budgets of [[uncounted-linters]], or the commits that leaves empty."
+ [records]
+ (->> records
+ (map (fn [record]
+ (update record :changes (partial remove (comp uncounted-linters peek :measure)))))
+ (filter (comp seq :changes))))
+
+(defn changed?
+ "Did the commit of `record` change a counted budget at all, even by changes that cancel out?"
+ [{:keys [changes]}]
+ (not-every? (comp uncounted-linters peek :measure) changes))
+
+(defn settle
+ "The `records`, the whole history newest first, as the summaries count them.
+ That is with `verdicts` applied by [[pardon]], spare budget that was taken back counted as slack, without
+ what [[counted]] leaves out, and with the raises [[suspects]] still flags kept on each record as `:doubted`.
+ The `verdicts` hold `:pardons` and `:recounts` as [[pardon]] takes them, and `:judged`, every commit with a
+ verdict."
+ [{:keys [judged], :as verdicts} records]
+ (let [records (pardon (assoc verdicts :spare (spare-budget judged records)) records)
+ ;; asked of what is left of each raise once its slack is taken out
+ doubted (into {} (map (juxt :sha :changes)) (suspects judged records))]
+ (for [{:keys [sha], :as record} (counted records)]
+ (cond-> record (doubted sha) (assoc :doubted (doubted sha))))))
+
+;;; -------------------------------------------------- Report --------------------------------------------------
+
+(defn- instant ^Instant [date]
+ (.toInstant (OffsetDateTime/parse date)))
+
+(defn unify-authors
+ "The `records` with one name per person.
+ Every commit, and every cause of a shrink, whose author email matches takes the author name of the newest of them.
+ Commits under one name already count as one person."
+ [records]
+ (let [newest (reduce (fn [acc {:keys [email author date]}]
+ (cond-> acc
+ ;; committer dates carry offsets, so compare them as instants, not as text
+ (and email (.isBefore ^Instant (get-in acc [email :at] Instant/MIN) (instant date)))
+ (assoc email {:at (instant date), :author author})))
+ {}
+ (concat records (mapcat #(apply concat (vals (:causes %))) records)))
+ rename (fn [{:keys [email], :as commit}]
+ (cond-> commit (newest email) (assoc :author (:author (newest email)))))]
+ (for [record records]
+ (cond-> (rename record)
+ (:causes record) (update :causes update-vals #(mapv rename %))))))
+
+(defn attributions
+ "One entry per commit and measure it is responsible for moving, across `records`.
+ An entry is the commit's `:sha`, `:author`, `:pr` and `:subject`, with the `:measure` and its `:delta`.
+ A grow belongs to the commit that raised the budget and a shrink to its causes.
+ A grow that has causes was a shrink before a pardoned raise was taken out of it, and belongs to them too.
+ The unexplained part of a shrink belongs to the shrinking commit too.
+ When that commit only lowered budgets, the entry is `:unattributed?` and has no `:author`."
+ [records]
+ (for [{:keys [changes causes unaccounted tighten?], :as record} records
+ :let [commit (dissoc record :changes :causes :unaccounted :tighten? :email :doubted)]
+ {:keys [kind measure delta]} changes
+ :when (#{:shrink :grow} kind)
+ :let [explained (concat (get causes measure)
+ (when-let [left (get unaccounted measure)]
+ [(cond-> (assoc commit :delta left)
+ tighten? (assoc :author nil :unattributed? true))]))]
+ ;; a shrink can turn into a net raise once a pardoned raise is taken out of it, and keeps its causes
+ entry (if (and (= kind :grow) (empty? explained))
+ [(assoc commit :delta delta)]
+ explained)]
+ (assoc entry :measure measure)))
+
+(defn totals
+ "Per measure, how far `records` shrank and grew its budget: `{measure {:shrink n, :grow n}}`."
+ [records]
+ (reduce (fn [acc {:keys [kind measure delta]}]
+ (cond-> acc
+ (#{:shrink :grow} kind) (update-in [measure kind] (fnil + 0) delta)))
+ {}
+ (mapcat :changes records)))
+
+(defn by-commit
+ "Net change each commit is responsible for in `entries` ([[attributions]]), best first.
+ Leaves out what no commit explains."
+ [entries]
+ (->> (remove :unattributed? entries)
+ (group-by :sha)
+ (map (fn [[_ entries]]
+ (assoc (dissoc (first entries) :measure :delta)
+ :net (reduce + (map :delta entries))
+ :measures (update-vals (group-by :measure entries) #(reduce + (map :delta %))))))
+ (sort-by (juxt :net :sha))))
+
+;; TODO (Chris 2026-10-10) -- also rank by team. The module config gives each module a `:team`, so a count could be
+;; charged to the team that owns the file. People move between teams, so a ranking by author's team needs a
+;; record of who was on which team when.
+(defn leaderboard
+ "One row per author across `records`, in author order.
+ A row holds how far they `:shrunk` and `:grown` budgets and the `:net` of the two, and the `:linters` they
+ introduced with the `:ignores` those started with.
+ A newly discouraged symbol counts as a linter: it is a new rule with its own budget.
+ A linter that starts with more ignores was the bigger one to land, and an `:unlimited` one counts none.
+ The row for what no commit explains is `:unattributed?` and has no `:author`."
+ [records]
+ (let [blank {:shrunk 0
+ :grown 0
+ :net 0
+ :linters 0
+ :ignores 0}
+ moved (update-vals (group-by :author (attributions records))
+ (fn [entries]
+ (let [deltas (map :delta entries)]
+ {:shrunk (reduce + (filter neg? deltas))
+ :grown (reduce + (filter pos? deltas))
+ :net (reduce + deltas)})))
+ introduced (reduce (fn [acc [author budget]]
+ (-> acc
+ (update-in [author :linters] (fnil inc 0))
+ (update-in [author :ignores] (fnil + 0) (if (number? budget) budget 0))))
+ {}
+ (for [{:keys [author changes]} records
+ {:keys [kind new]} changes
+ :when (= kind :introduce)]
+ [author new]))]
+ (->> (merge-with merge moved introduced)
+ (map (fn [[author row]]
+ (cond-> (merge blank row {:author author})
+ (nil? author) (assoc :unattributed? true))))
+ (sort-by :author))))
+
+(def ^:private measure-suffixes
+ {[:prod :ignore] ""
+ [:test :ignore] " (test)"
+ [:prod :config] " (config)"
+ [:modules :module] " (modules)"})
+
+(defn- measure-name [[side kind linter]]
+ (str linter (measure-suffixes [side kind])))
+
+(defn- budget-name [budget]
+ (cond
+ (nil? budget) "none"
+ (keyword? budget) (name budget)
+ :else (str budget)))
+
+(defn- commit-ref [commit]
+ (select-keys commit [:sha :pr :author :subject :date]))
+
+(defn- named-deltas
+ "The entries of `by-measure`, a map from measure to delta, largest change first, with the measure named."
+ [by-measure]
+ (for [[measure delta] (sort-by (juxt (comp - abs val) (comp str key)) by-measure)]
+ {:measure (measure-name measure), :delta delta}))
+
+(defn- by-kind
+ "The commits in `records` that made a change of one of `kinds`, each with `describe` of those changes as its
+ `:items`."
+ [records kinds describe]
+ (for [record records
+ :let [changes (filter (comp kinds :kind) (:changes record))]
+ :when (seq changes)]
+ {:commit (commit-ref record), :items (map describe changes)}))
+
+(defn report
+ "What `records`, as [[settle]] returns them, say, as plain data: measures are named and budgets are strings.
+
+ - `:commits` counts the commits that changed a counted budget.
+ - `:totals` has a row of `:measure`, `:shrunk`, `:grown` and `:net` per measure, and `:total` their sums.
+ - `:approximate` names the measures among them whose credit is approximate: those budgeted per symbol.
+ - `:best` and `:worst` are the commits behind the largest net shrink and net raise, if any: the `:commit`,
+ its `:net` and its `:measures`.
+ - `:introduced`, `:seeded`, `:slack`, `:unlimited`, `:unaccounted` and `:suspects` each list commits with
+ `:items`. Those are the new linters, the first budgets of new ratchets, the spare budget that was taken
+ back, the moves into or out of `:unlimited`, the shrinks of the automation that no commit explains, and
+ the raises beyond the suppressions added that have no verdict.
+ - `:board` is the [[leaderboard]]."
+ [records]
+ (let [ranked (by-commit (attributions records))
+ biggest (fn [{:keys [net measures], :as entry}]
+ {:commit (commit-ref entry), :net net, :measures (named-deltas measures)})
+ rows (->> (totals records)
+ (map (fn [[measure {:keys [shrink grow] :or {shrink 0, grow 0}}]]
+ {:measure (measure-name measure)
+ :shrunk shrink
+ :grown grow
+ :net (+ shrink grow)}))
+ (sort-by (juxt :net :measure)))]
+ {:commits (count records)
+ :totals rows
+ :approximate (sort (distinct (for [{:keys [kind measure per-symbol?]} (mapcat :changes records)
+ :when (and per-symbol? (#{:shrink :grow} kind))]
+ (measure-name measure))))
+ :total (into {} (for [k [:shrunk :grown :net]] [k (reduce + (map k rows))]))
+ :best (when (some-> (first ranked) :net neg?) (biggest (first ranked)))
+ :worst (when (some-> (last ranked) :net pos?) (biggest (last ranked)))
+ :introduced (by-kind records #{:introduce}
+ (fn [{:keys [measure key new]}]
+ {:measure (str (measure-name measure) (when key (str " " (subs (str key) 1))))
+ :budget (budget-name new)}))
+ :seeded (by-kind records #{:seed}
+ (fn [{:keys [measure new]}]
+ {:measure (measure-name measure)
+ :budget (budget-name new)
+ :size (if (number? new) new 0)}))
+ :slack (for [record records
+ :let [items (for [{:keys [kind measure delta slack]} (:changes record)
+ :when (or slack (= :slack kind))]
+ {:measure (measure-name measure), :size (or slack delta)})]
+ :when (seq items)]
+ {:commit (commit-ref record), :items items})
+ :unlimited (by-kind records #{:limit :unlimit}
+ (fn [{:keys [measure old new]}]
+ {:measure (measure-name measure), :old (budget-name old), :new (budget-name new)}))
+ :board (leaderboard records)
+ :unaccounted (for [{:keys [unaccounted tighten?], :as record} records
+ :when (and tighten? (seq unaccounted))]
+ {:commit (commit-ref record), :items (named-deltas unaccounted)})
+ :suspects (for [{:keys [doubted], :as record} records
+ :when (seq doubted)]
+ {:commit (commit-ref record)
+ :items (for [{:keys [measure delta added]} doubted]
+ {:measure (measure-name measure), :delta delta, :added added})})}))
+
+(defn series
+ "One point per commit in `records`, the whole history newest first, in the order they landed.
+ A point holds how far the commit `:shrunk` and `:grown` the budgets in `settled`, those records as [[settle]]
+ returns them, and the `:level` after it: the sum of every counted numeric budget.
+ The rest of its change to the level counts for nobody.
+ It is split into the budgets the commit `:introduced` and `:seeded`, its moves into or out of `:unlimited`, and
+ what is `:excused`: pardoned, recounted or spare budget, and the shrinks that only took such budget back.
+ The six parts add up to the change in `:level`.
+ A point is `:changed?` when its commit changed a counted budget at all, though its parts may cancel out."
+ [records settled]
+ (let [numeric #(if (number? %) % 0)
+ credited (into {}
+ (for [{:keys [sha changes]} settled]
+ [sha (reduce (fn [acc {:keys [kind delta]}]
+ (cond-> acc (#{:shrink :grow} kind) (update kind + delta)))
+ {:shrink 0, :grow 0}
+ changes)]))
+ part {:introduce :introduced
+ :seed :seeded
+ :limit :unlimited
+ :unlimit :unlimited
+ ;; whatever of a raise or shrink is not credited below
+ :shrink :excused
+ :grow :excused}
+ raised (fn [{:keys [changes]}]
+ (reduce (fn [acc {:keys [kind measure key old new]}]
+ (cond-> acc
+ (not (uncounted-linters (peek measure)))
+ ;; a newly discouraged symbol carries its own budget; see [[budget-changes]]
+ (update (part kind) + (if key (numeric new) (- (numeric new) (numeric old))))))
+ {:introduced 0, :seeded 0, :unlimited 0, :excused 0}
+ changes))]
+ (rest (reductions (fn [point {:keys [sha], :as record}]
+ (let [{:keys [shrink grow]} (get credited sha {:shrink 0, :grow 0})
+ parts (raised record)]
+ (merge (commit-ref record)
+ (update parts :excused - shrink grow)
+ {:shrunk shrink
+ :grown grow
+ :level (+ (:level point) (reduce + (vals parts)))
+ :changed? (changed? record)})))
+ {:level 0}
+ (reverse records)))))
+
+(defn- spans
+ "The `[start end]` dates of each `unit`, newest first, from the one holding `today` back to the one holding `oldest`.
+ The function `floor` moves a date to the start of its unit."
+ [floor ^ChronoUnit unit oldest today]
+ (let [first-start ^LocalDate (floor oldest)]
+ (for [^LocalDate start (take-while #(not (.isBefore ^LocalDate % first-start))
+ (iterate #(.minus ^LocalDate % 1 unit) (floor today)))]
+ [start (.plus start 1 unit)])))
+
+(defn periods
+ "All time, then every week (from its Monday) and every calendar month from the first of `records` up to
+ `today`, an ISO date, newest first.
+ Each is a map of `:id`, `:kind`, `:label`, the `:from` date and the `:to` date it ends before, and the
+ [[report]] of the records committed in it.
+ The `records` are as [[settle]] returns them."
+ [today records]
+ (let [day (fn [record] (LocalDate/parse (subs (:date record) 0 10)))
+ today (LocalDate/parse today)
+ oldest (reduce (fn [^LocalDate a ^LocalDate b] (if (.isBefore b a) b a)) today (map day records))
+ monday (fn [^LocalDate date] (.minusDays date (dec (.getValue (.getDayOfWeek date)))))
+ month (fn [^LocalDate date] (.withDayOfMonth date 1))
+ text (fn [pattern ^LocalDate date]
+ (.format (DateTimeFormatter/ofPattern pattern Locale/ENGLISH) date))
+ within (fn [^LocalDate start ^LocalDate end]
+ (report (filter (fn [record]
+ (let [^LocalDate date (day record)]
+ (and (not (.isBefore date start)) (.isBefore date end))))
+ records)))]
+ (concat
+ [{:id "all", :kind "all", :label "All time", :report (report records)}]
+ (for [[^LocalDate start end] (spans monday ChronoUnit/WEEKS oldest today)]
+ {:id (str "week-" start)
+ :kind "week"
+ :label (str (text "d MMM" start) " to " (text "d MMM yyyy" (.plusDays start 6)))
+ :from (str start)
+ :to (str end)
+ :report (within start end)})
+ (for [[start end] (spans month ChronoUnit/MONTHS oldest today)]
+ {:id (str "month-" (text "yyyy-MM" start))
+ :kind "month"
+ :label (text "MMMM yyyy" start)
+ :from (str start)
+ :to (str end)
+ :report (within start end)}))))
+
+(def ^:private page-template
+ "The HTML page [[page]] fills in, relative to the repo root."
+ "mage/resources/kondo-ratchets-history.html")
+
+(defn script-json
+ "The `data` as JSON that is safe inside an HTML script element."
+ [data]
+ ;; a `<` can end the element or, as `<!--<script>`, stop its real end from being seen
+ (str/replace (json/write-str data) "<" "\\u003c"))
+
+(defn- page
+ "The single-file HTML page showing `data`."
+ [data]
+ (str/replace (slurp (fs/file u/project-root-directory page-template)) "__DATA__" (script-json data)))
+
+;;; ------------------------------------------------- Terminal -------------------------------------------------
+
+(defn- signed [n]
+ (if (zero? n) "0" (format "%+d" n)))
+
+(defn- commit-line [{:keys [sha pr subject]}]
+ (str (subs sha 0 (min 10 (count sha))) (when pr (str " #" pr)) " " (c/dark subject)))
+
+(defn- table
+ "Lines for `rows` of strings, the first of them the header.
+ The first column is left-aligned and the rest right-aligned.
+ The `colors` hold, per column, a function from a cell below the header to its color function, or nil."
+ [colors rows]
+ (let [widths (apply map (fn [& cells] (apply max (map count cells))) rows)]
+ (map-indexed (fn [r row]
+ (str/trimr
+ (str/join " "
+ (map-indexed (fn [i cell]
+ (let [color (cond
+ (zero? r) c/dark
+ (nth colors i) ((nth colors i) cell)
+ :else identity)]
+ (color (format (str "%" (when (zero? i) "-") (nth widths i) "s")
+ cell))))
+ row))))
+ rows)))
+
+(defn- tint
+ "A column color for [[table]]: `color`, with a zero left dim."
+ [color]
+ (fn [cell]
+ (if (= "0" cell) c/dark color)))
+
+(defn- net-tint
+ "The column color for a net change: green for a net shrink, red for a net raise and the default color for none."
+ [cell]
+ (case (first cell)
+ \- c/green
+ \+ c/red
+ identity))
+
+(defn- colored-delta
+ "The number `n` with its sign: green for a shrink and red for a raise."
+ [n]
+ (cond
+ (neg? n) (c/green (signed n))
+ (pos? n) (c/red (signed n))
+ :else "0"))
+
+(defn- section [title lines]
+ (when (seq lines)
+ (concat ["" (c/bold title)] (map #(str " " %) lines))))
+
+(defn- totals-lines [totals total]
+ (when (seq totals)
+ (let [cells (juxt (comp signed :shrunk) (comp signed :grown) (comp signed :net))]
+ (table [nil (tint c/green) (tint c/red) net-tint]
+ (concat [["" "shrunk" "grown" "net"]]
+ (for [row totals] (cons (:measure row) (cells row)))
+ [(cons "total" (cells total))])))))
+
+(def ^:private items-shown
+ "How many items of one commit a list shows, in the terminal and on the page, before it sums the rest."
+ 6)
+
+(defn- biggest-lines
+ "Lines for a `:best` or `:worst` of a [[report]]: the commit, its net change, then that change per linter.
+ The linters past [[items-shown]] are summed."
+ [{:keys [commit net measures]}]
+ (let [[shown more] (split-at items-shown measures)
+ width (apply max (map (comp count signed :delta) measures))
+ row (fn [delta label]
+ (str " " (colored-delta delta) (apply str (repeat (- width (count (signed delta))) " "))
+ " " label))]
+ (concat [(commit-line commit)
+ (format "%s net, across %d budget%s:" (colored-delta net) (count measures)
+ (if (= 1 (count measures)) "" "s"))]
+ (for [{:keys [measure delta]} shown]
+ (row delta measure))
+ (when (seq more)
+ [(row (reduce + (map :delta more)) (format "%d more budgets" (count more)))]))))
+
+(defn- group-lines
+ "Lines for `groups`, the commits of a [[report]] list: each commit, then `describe` of each of its `:items`."
+ [groups describe]
+ (for [{:keys [commit items]} groups
+ line (cons (commit-line commit) (map #(str " " (describe %)) items))]
+ line))
+
+(defn- seed-lines
+ "Lines for the `:seeded` commits of a [[report]]: a line per budget, with those past [[items-shown]] summed."
+ [groups]
+ (for [{:keys [commit items]} groups
+ :let [[shown more] (split-at items-shown items)]
+ line (concat [(commit-line commit)]
+ (for [{:keys [measure budget]} shown]
+ (str " " measure " starting at " budget))
+ (when (seq more)
+ [(format " %d more budgets, starting at %d in all" (count more) (reduce + (map :size more)))]))]
+ line))
+
+(defn- suspect-lines
+ "Lines for the `:suspects` of a [[report]]: a line per raise, with those past [[items-shown]] summed, then how
+ to settle them."
+ [groups]
+ (when (seq groups)
+ (concat
+ (for [{:keys [commit items]} groups
+ :let [[shown more] (split-at items-shown items)]
+ line (concat [(commit-line commit)]
+ (for [{:keys [measure delta added]} shown]
+ (format " %s %s, with %d suppressions added" (colored-delta delta) measure added))
+ (when (seq more)
+ [(format " %s over %d more budgets, with %d suppressions added"
+ (colored-delta (reduce + (map :delta more)))
+ (count more)
+ (reduce + (map :added more)))]))]
+ line)
+ ["Settle each with: ./bin/mage kondo-ratchets-history --pardon|--confirm <commit or PR> --why <reason>"])))
+
+(defn summary
+ "Lines for the terminal saying what `report` ([[report]]) holds, for the period called `period`, in which
+ `changed` commits changed a budget ([[changed?]])."
+ [period changed {:keys [totals total approximate best worst introduced seeded slack unlimited unaccounted
+ suspects]}]
+ (concat
+ [(c/bold (format "Ratchet changes %s: %d commits" period changed))]
+ (section "Total deltas"
+ (concat (totals-lines totals total)
+ (when (seq approximate)
+ [(c/dark (str "Credit for " (str/join ", " approximate) " is approximate: "
+ "budgeted per symbol, counted here per ignore."))])))
+ (section "Biggest improvement" (some-> best biggest-lines))
+ (section "Biggest regression" (some-> worst biggest-lines))
+ (section "New linters and measures"
+ (group-lines introduced (fn [{:keys [measure budget]}]
+ (c/green (str measure " starting at " budget)))))
+ (section "New ratchets over existing debt" (seed-lines seeded))
+ (section "Spare budget that was taken back"
+ (group-lines slack (fn [{:keys [measure size]}]
+ (str (signed size) " " measure))))
+ (section "Moved into or out of :unlimited"
+ (group-lines unlimited (fn [{:keys [measure old new]}]
+ (str measure " " old " -> " new))))
+ (section "Shrinks no commit accounts for"
+ (group-lines unaccounted (fn [{:keys [measure delta]}]
+ (str (signed delta) " " measure))))
+ (section "Raises beyond the suppressions added, with no verdict" (suspect-lines suspects))))
+
+;;; ---------------------------------------------------- Task --------------------------------------------------
+
+(defn- resolve-commit [repo rev]
+ (let [{:keys [exit out]} (git-result repo ["rev-parse" "--verify" "--quiet" (str rev "^{commit}")])]
+ (if (zero? exit)
+ (first out)
+ (u/exit (str "Not a commit: " rev) 1))))
+
+(def ^:private default-days 7)
+
+(defn request
+ "What the task is asked to do, from its `since` commit and `options`.
+ Returns `[:since sha]`, `[:all]` or `[:days n]` for a summary, `[:html file]` for the page of every period, or
+ `[:verdict [kind target]]` to record a verdict.
+ Exits when more than one is asked for, or when `--why` comes without a verdict."
+ [since {:keys [all days html pardon confirm recount why]}]
+ (let [asked (cond-> []
+ since (conj "a commit")
+ all (conj "--all")
+ days (conj "--days")
+ html (conj "--html")
+ pardon (conj "--pardon")
+ confirm (conj "--confirm")
+ recount (conj "--recount"))]
+ (when (next asked)
+ (u/exit (str "Give only one of " (str/join ", " asked) ".") 1))
+ (when (and why (not (or pardon confirm recount)))
+ (u/exit "Give --why only with --pardon, --confirm or --recount." 1))
+ (cond
+ since [:since since]
+ pardon [:verdict [:pardon pardon]]
+ confirm [:verdict [:confirm confirm]]
+ recount [:verdict [:recount recount]]
+ html [:html html]
+ all [:all]
+ :else [:days (or days default-days)])))
+
+(def ^:private progress
+ "The [[records]] callbacks that name each commit as it is analysed."
+ {:starting (fn [n] (println (c/dark (format "Analysing %d commits that changed a ratchet file" n))))
+ :analysed (fn [record] (println (c/dark (str " " (commit-line record)))))})
+
+(defn- ratchet-commit
+ "The one of `records`, the commits that changed a ratchet file, that `target` names.
+ A target is a commit, or a PR as `1234` or `#1234`. Exits when there is not exactly one."
+ [repo records target]
+ (if-let [pr (second (re-matches #"#?(\d{1,6})" target))]
+ (let [found (filter #(= (parse-long pr) (:pr %)) records)]
+ (if (= 1 (count found))
+ (first found)
+ (u/exit (format "Found %d commits for PR #%s that changed a ratchet file." (count found) pr) 1)))
+ (let [sha (resolve-commit repo target)]
+ (or (first (filter #(= sha (:sha %)) records))
+ (u/exit (str "Commit " (subs sha 0 10) " did not change a ratchet file.") 1)))))
+
+(defn- verdict!
+ "Record in the verdicts file a verdict of `kind` on the commit `target` names, as a sha or a PR number, with
+ the reason `why`.
+ A `:pardon` counts the commit's budget raises against nobody and a `:confirm` keeps them as growth.
+ A `:recount` says the commit only changed how suppressions are counted, so neither its raises nor its own
+ shrinks count."
+ [repo kind target why]
+ (let [record (ratchet-commit repo (records repo progress) target)
+ changes (filter (comp (covered-kinds kind) :kind) (:changes record))
+ ;; who recorded it and when, for the reader of the page: most verdicts are on the recorder's own commits
+ by (first (:out (git-result repo ["config" "user.name"])))
+ entry (cond-> (assoc (select-keys record [:sha :pr :subject]) :verdict kind)
+ why (assoc :why why)
+ by (assoc :by by)
+ true (assoc :on (str (LocalDate/now))))
+ others (remove #(= (:sha record) (:sha %)) (read-verdicts repo))]
+ (when (empty? changes)
+ (u/exit (str "Nothing to " (name kind) ": " (commit-line record) " raised no budget.") 1))
+ (when (and (not= :confirm kind) (not why))
+ (u/exit (str "A " (name kind) " needs a reason: add --why <reason>.") 1))
+ (spit (:verdicts-file repo) (render-verdicts (concat others [entry])))
+ (println (str ({:pardon "Pardoned ", :confirm "Confirmed ", :recount "Recounted "} kind) (commit-line record)))
+ (doseq [{:keys [measure delta]} changes]
+ (println (str " " (signed delta) " " (measure-name measure))))))
+
+(defn- verdict-options
+ "The verdicts [[settle]] takes, from the `entries` of the verdicts file.
+ The function `record` gives the record of a sha."
+ [entries record]
+ {:judged (set (map :sha entries))
+ :recounts (set (map :sha (filter #(= :recount (:verdict %)) entries)))
+ :pardons (into {}
+ (for [{:keys [sha verdict]} entries
+ :when (#{:pardon :recount} verdict)]
+ [sha (into {}
+ (for [{:keys [kind measure delta]} (:changes (record sha))
+ :when (= :grow kind)]
+ [measure delta]))]))})
+
+(defn- rulings
+ "The `entries` of the verdicts file for the page: each commit, its verdict and reason, and the changes the
+ verdict is about.
+ The function `record` gives the record of a sha."
+ [entries record]
+ (for [{:keys [sha verdict why by on]} entries
+ :let [commit (record sha)]]
+ {:commit (commit-ref commit)
+ :verdict (name verdict)
+ :why why
+ :by by
+ :on on
+ :raises (for [{:keys [kind measure delta]} (:changes commit)
+ :when (contains? (covered-kinds verdict) kind)]
+ {:measure (measure-name measure), :delta delta})}))
+
+(defn- repo-url
+ "The https URL of the repository on GitHub, from its `origin` remote."
+ [repo]
+ (-> (first (git repo "remote" "get-url" "origin"))
+ (str/replace #"^git@github\.com:" "https://github.com/")
+ (str/replace #"\.git$" "")))
+
+(defn- summarize
+ "Bring the cache up to `HEAD`, then print or write what `by` and `arg`, from [[request]], ask for."
+ [repo by arg]
+ (let [records (unify-authors (records repo progress))
+ record (into {} (map (juxt :sha identity)) records)
+ entries (filter (comp record :sha) (read-verdicts repo))
+ ;; a verdict on one commit changes what later ones count for, so the whole history is settled before a
+ ;; period is picked out of it
+ settled (settle (verdict-options entries record) records)]
+ (if (= :html by)
+ (let [today (str (LocalDate/now))]
+ (spit arg (page {:repo (repo-url repo)
+ :generated today
+ :series (series records settled)
+ :verdicts (rulings entries record)
+ :shown items-shown
+ :excluded (for [[linter why] uncounted-linters]
+ {:linter (str linter), :why why})
+ :periods (periods today settled)}))
+ (println "Wrote" arg))
+ (let [[title shas] (case by
+ :since [(str "since " (subs arg 0 10)) (ratchet-commits repo (str arg ".." (:head repo)))]
+ :all ["of all time" (map :sha records)]
+ :days [(format "in the last %d days" arg)
+ (ratchet-commits repo (format "--since=%d.days.ago" arg) (:head repo))])
+ in-range? (comp (set shas) :sha)]
+ ;; counted from the records before verdicts, since a commit can lose every change to them
+ (run! println (summary title
+ (count (filter (every-pred in-range? changed?) records))
+ (report (filter in-range? settled))))))))
+
+(defn run
+ "Do what the task's `options` and `arguments` ask for, on `repo` ([[repo]])."
+ [repo {:keys [options arguments]}]
+ (let [[by arg] (request (some->> (first arguments) (resolve-commit repo)) options)]
+ (if (= :verdict by)
+ (verdict! repo (first arg) (second arg) (:why options))
+ (summarize repo by arg))))
+
+(defn history
+ "Bring the cache up to `HEAD`, then print a [[summary]] of the ratchet changes since the commit given as the
+ first argument, over all time with `--all`, or else over the last `--days` days.
+ With `--html`, write the [[page]] of every week, every month and all time to that file instead.
+ With `--pardon`, `--confirm` or `--recount`, record that verdict on a commit and print nothing else."
+ [parsed]
+ (run (repo {}) parsed))
diff --git a/mage/test/mage/core_test.clj b/mage/test/mage/core_test.clj
index f03b9438e40..fa8ab7f4e27 100644
--- a/mage/test/mage/core_test.clj
+++ b/mage/test/mage/core_test.clj
@@ -19,6 +19,7 @@
[mage.fix-unused-requires-test]
[mage.generate-docs-test]
[mage.kondo-ratchet-test]
+ [mage.kondo-ratchets-history-test]
[mage.merge-kondo-ratchets-test]
[mage.merge-yaml-migrations-test]
[mage.modules-test]
diff --git a/mage/test/mage/kondo_ratchets_history_test.clj b/mage/test/mage/kondo_ratchets_history_test.clj
new file mode 100644
index 00000000000..4f6fb11223e
--- /dev/null
+++ b/mage/test/mage/kondo_ratchets_history_test.clj
@@ -0,0 +1,791 @@
+(ns mage.kondo-ratchets-history-test
+ (:require
+ [babashka.fs :as fs]
+ [babashka.json :as json]
+ [babashka.process :as p]
+ [clojure.edn :as edn]
+ [clojure.string :as str]
+ [clojure.test :refer [deftest is testing]]
+ [mage.color :as c]
+ [mage.kondo-ratchets-history :as history]))
+
+;;; ------------------------------------------------- Budgets --------------------------------------------------
+
+(defn- changes
+ "The [[history/budget-changes]] between the ratchet files `before` and `after`, where the commit added the linters
+ and discouraged symbols in `added`."
+ [before after added]
+ (history/budget-changes (history/budget-view before after)
+ {:new-measure? (comp added peek)
+ :new-symbol? (fn [_linter sym] (added sym))}))
+
+(deftest budget-changes-test
+ (testing "each kind of change to a budget"
+ (is (= [{:measure [:prod :config :shrunk], :old 2, :new nil, :kind :shrink, :delta -2}
+ {:measure [:prod :ignore :capped], :old :unlimited, :new 4, :kind :limit}
+ {:measure [:prod :ignore :first-budget], :old nil, :new 6, :kind :grow, :delta 6}
+ {:measure [:prod :ignore :grown], :old 1, :new 3, :kind :grow, :delta 2}
+ {:measure [:prod :ignore :new-linter], :old nil, :new 7, :kind :introduce}
+ {:measure [:prod :ignore :shrunk], :old 5, :new 2, :kind :shrink, :delta -3}
+ {:measure [:prod :ignore :uncapped], :old 9, :new :unlimited, :kind :unlimit}]
+ (changes {:prod {:ignore-counts {:capped :unlimited
+ :grown 1
+ :same 1
+ :shrunk 5
+ :uncapped 9}
+ :config-counts {:shrunk 2}}}
+ {:prod {:ignore-counts {:capped 4
+ :first-budget 6
+ :grown 3
+ :new-linter 7
+ :same 1
+ :shrunk 2
+ :uncapped :unlimited}}}
+ #{:new-linter}))))
+ (testing "the first budgets of a new ratchet file or a new kind of budget are seeds, unless the linter is new"
+ (is (= [{:measure [:modules :module :uses-any], :old nil, :new 4, :kind :seed}
+ {:measure [:prod :config :existing], :old nil, :new 2, :kind :seed}
+ {:measure [:prod :config :new-linter], :old nil, :new 3, :kind :introduce}]
+ (changes {:prod {:ignore-counts {:existing 5}}}
+ {:prod {:ignore-counts {:existing 5}, :config-counts {:existing 2, :new-linter 3}}
+ :modules {:uses-any 4}}
+ #{:new-linter}))))
+ (testing "a first budget in a ratchet that exists but holds nothing yet is growth, not a seed"
+ (is (= [{:measure [:prod :config :existing], :old nil, :new 2, :kind :grow, :delta 2}]
+ (changes {:prod {:ignore-counts {}, :config-counts {}}}
+ {:prod {:ignore-counts {}, :config-counts {:existing 2}}}
+ #{}))))
+ (testing "a newly discouraged symbol is an introduction, and the rest of its linter's budget still moves"
+ (is (= [{:measure [:prod :ignore :discouraged-var], :kind :introduce, :key :clojure.core/eval, :new 6}
+ {:measure [:prod :ignore :discouraged-var]
+ :old 3
+ :new 2
+ :per-symbol? true
+ :kind :shrink
+ :delta -1}]
+ (changes {:prod {:discouraged-var-counts {:clojure.core/prn 3}}}
+ {:prod {:discouraged-var-counts {:clojure.core/prn 2, :clojure.core/eval 6}}}
+ #{:clojure.core/eval}))))
+ (testing "moving a linter's budget to per-symbol budgets, or test budgets to their own file, changes nothing"
+ (is (= []
+ (changes {:prod {:ignore-counts {:discouraged-var 5, :deprecated-var 9}}}
+ {:prod {:ignore-counts {:deprecated-var 6}, :discouraged-var-counts {:clojure.core/prn 3}}
+ :test {:ignore-counts {:deprecated-var 3}, :discouraged-var-counts {:clojure.core/prn 2}}}
+ #{})))))
+
+;;; ------------------------------------------------ Attribution -----------------------------------------------
+
+(deftest attribute-test
+ (testing "walks back until the shrink is explained, netting the growth that hid in its slack"
+ (is (= {:open {}
+ :causes {:a [{:sha "hid", :delta 1} {:sha "removed", :delta -3}]}}
+ (history/attribute {:a -2}
+ [[{:sha "tighten"} {}]
+ [{:sha "hid"} {:a 1, :other -4}]
+ [{:sha "removed"} {:a -3}]
+ [{:sha "earlier"} {:a -5}]]))))
+ (testing "reports what no commit explains"
+ (is (= {:open {:a -1, :b -4}, :causes {:a [{:sha "removed", :delta -2}]}}
+ (history/attribute {:a -3, :b -4} [[{:sha "removed"} {:a -2}]])))))
+
+(deftest parse-log-test
+ (testing "reads each commit, the PR number from its subject, and the blobs of the files it changed"
+ (is (= [{:sha "aaa"
+ :author "Ada"
+ :date "2026-10-01T00:00:00Z"
+ :subject "Fix it (#12)"
+ :pr 12
+ :files [{:path "src/a.clj", :old "111", :new "222"}
+ {:path "test/b c.clj", :old "000", :new "333"}]}
+ {:sha "bbb"
+ :author "Bob"
+ :date "2026-09-30T00:00:00Z"
+ :subject "No PR here"
+ :pr nil
+ :files []}]
+ (history/parse-log
+ ["\u0001aaa\u001fAda\[email protected]\u001f2026-10-01T00:00:00Z\u001fFix it (#12)"
+ ""
+ ":100644 100644 111 222 M\tsrc/a.clj"
+ ":000000 100644 000 333 A\ttest/b c.clj"
+ "\u0001bbb\u001fBob\[email protected]\u001f2026-09-30T00:00:00Z\u001fNo PR here"])))))
+
+(deftest tightening-test
+ (testing "holds only for a commit that changed ratchet files alone and did nothing but lower budgets"
+ (is (= [true true false false false false]
+ (map (fn [[paths kinds]] (history/tightening? paths kinds))
+ [[[".clj-kondo/ratchets.edn"] [:shrink]]
+ [[".clj-kondo/ratchets.edn" ".clj-kondo/ratchets-test.edn"] [:shrink :limit]]
+ ;; a feature commit that also shrinks
+ [[".clj-kondo/ratchets.edn" "src/metabase/a.clj"] [:shrink]]
+ ;; a seeding commit that also shrinks
+ [[".clj-kondo/ratchets.edn"] [:shrink :grow]]
+ ;; a ratchet commit that lowers nothing
+ [[".clj-kondo/ratchets.edn"] [:limit]]
+ ;; a merge commit, which lists no paths without a merge diff mode
+ [[] [:shrink]]])))))
+
+(deftest counts-test
+ (testing "counts each linter of an ignore, on the side the path belongs to, when the vector spans lines"
+ (let [source "#_{:clj-kondo/ignore [:deprecated-var
+ :unused-binding]}
+(foo)
+"]
+ (is (= [{[:prod :ignore :deprecated-var] 1, [:prod :ignore :unused-binding] 1}
+ {[:test :ignore :deprecated-var] 1, [:test :ignore :unused-binding] 1}
+ {}]
+ [(history/counts "src/metabase/a.clj" source)
+ (history/counts "test/metabase/a_test.clj" source)
+ (history/counts "docs/a.clj" source)])))))
+
+(deftest actual-delta-test
+ (let [before "#_{:clj-kondo/ignore [:deprecated-var
+ :unused-binding]}
+(foo)
+"
+ after "#_{:clj-kondo/ignore [:deprecated-var
+ :type-mismatch]}
+(foo)
+"
+ path "src/metabase/a.clj"
+ commit {:files [{:path path, :old "old", :new "new"}]}]
+ (testing "sees an edit to the continuation line of an ignore vector alone"
+ (is (= {[:prod :ignore :unused-binding] -1, [:prod :ignore :type-mismatch] 1}
+ (history/actual-delta {"old" {path (history/counts path before)}
+ "new" {path (history/counts path after)}}
+ commit))))
+ (testing "counts nothing for a file that cannot be read on one side"
+ (is (= {}
+ (history/actual-delta {"old" {path (history/counts path before)}
+ "new" {path ::history/unreadable}}
+ commit))))))
+
+;;; -------------------------------------------------- Verdicts ------------------------------------------------
+
+(def ^:private a* [:prod :ignore :a])
+
+(deftest suspects-test
+ (testing "flags a raise beyond the suppressions its commit added, unless the commit has a verdict"
+ (is (= [{:sha "stale", :changes [{:measure [:prod :ignore :a], :kind :grow, :delta 8, :added 0}]}]
+ (history/suspects
+ #{"judged"}
+ [{:sha "stale", :changes [{:measure [:prod :ignore :a], :kind :grow, :delta 8, :added 0}
+ {:measure [:prod :ignore :b], :kind :grow, :delta 2, :added 2}
+ {:measure [:prod :ignore :c], :kind :shrink, :delta -1}]}
+ {:sha "honest", :changes [{:measure [:prod :ignore :a], :kind :grow, :delta 1, :added 1}]}
+ {:sha "judged", :changes [{:measure [:prod :ignore :a], :kind :grow, :delta 5, :added 0}]}])))))
+
+(deftest pardon-test
+ (testing "a pardoned raise is no growth, and the commit's other raises still are"
+ (is (= [{:sha "stale", :changes [{:measure :a, :kind :pardon, :delta 3} {:measure :c, :kind :grow, :delta 1}]}
+ {:sha "ratchet", :changes [{:measure :d, :kind :pardon, :delta 9}]}]
+ (history/pardon
+ {:pardons {"stale" {:a 3}, "ratchet" {:d 9}}}
+ [{:sha "stale", :changes [{:measure :a, :kind :grow, :delta 3} {:measure :c, :kind :grow, :delta 1}]}
+ {:sha "ratchet", :changes [{:measure :d, :kind :grow, :delta 9}]}]))))
+ (testing "a shrink that takes a pardoned raise back loses that part, and the credit for it"
+ (is (= [{:sha "tighten"
+ :changes [{:measure :a, :kind :shrink, :delta -2}]
+ :causes {:a [{:sha "fix", :delta -2}], :b []}}]
+ (history/pardon
+ {:pardons {"stale" {:a 3, :b 4}}}
+ [{:sha "tighten"
+ :changes [{:measure :a, :kind :shrink, :delta -5} {:measure :b, :kind :shrink, :delta -4}]
+ :causes {:a [{:sha "stale", :delta -3} {:sha "fix", :delta -2}]
+ :b [{:sha "stale", :delta -4}]}}]))))
+ (testing "a pardoned commit keeps the credit for what it removed beyond its own raise"
+ (is (= [{:sha "tighten"
+ :changes [{:measure :a, :kind :shrink, :delta -2}]
+ :causes {:a [{:sha "stale", :delta -2}]}}]
+ (history/pardon
+ {:pardons {"stale" {:a 5}}}
+ [{:sha "tighten"
+ :changes [{:measure :a, :kind :shrink, :delta -7}]
+ :causes {:a [{:sha "stale", :delta -7}]}}]))))
+ (testing "a pardoned raise is taken back once, by the oldest shrinks after it"
+ (is (= [[:shrink -4 [{:sha "stale", :delta -3} {:sha "fix", :delta -1}]] nil nil]
+ (map (fn [{:keys [changes causes]}]
+ (when-let [{:keys [kind delta]} (first changes)]
+ [kind delta (:a causes)]))
+ (history/pardon
+ {:pardons {"stale" {:a 5}}}
+ ;; newest first: the raise of 5 comes back as 2 and then 3
+ ;; what the same commit explains after that is a real removal
+ [{:sha "third"
+ :changes [{:measure :a, :kind :shrink, :delta -4}]
+ :causes {:a [{:sha "stale", :delta -3} {:sha "fix", :delta -1}]}}
+ {:sha "second"
+ :changes [{:measure :a, :kind :shrink, :delta -3}]
+ :causes {:a [{:sha "stale", :delta -3}]}}
+ {:sha "first"
+ :changes [{:measure :a, :kind :shrink, :delta -2}]
+ :causes {:a [{:sha "stale", :delta -2}]}}])))))
+ (testing "a recount keeps no credit for a later shrink, even of a budget it did not raise"
+ (is (= [{:sha "tighten", :changes [], :causes {:a []}}]
+ (history/pardon
+ {:pardons {"regroup" {:f 5}}, :recounts #{"regroup"}}
+ [{:sha "tighten"
+ :changes [{:measure :a, :kind :shrink, :delta -4}]
+ :causes {:a [{:sha "regroup", :delta -4}]}}]))))
+ (testing "a recount loses its own shrinks as well as its raises"
+ (is (= [{:sha "regroup"
+ :changes [{:measure :f, :kind :pardon, :delta 5}]
+ :causes {:e [{:sha "regroup", :delta -4}]}}]
+ (history/pardon
+ {:pardons {"regroup" {:f 5}}, :recounts #{"regroup"}}
+ [{:sha "regroup"
+ :changes [{:measure :e, :kind :shrink, :delta -4} {:measure :f, :kind :grow, :delta 5}]
+ :causes {:e [{:sha "regroup", :delta -4}]}}])))))
+
+(deftest slack-test
+ (let [raise (fn [sha delta added] {:sha sha, :changes [{:measure a*, :kind :grow, :delta delta, :added added}]})
+ tighten (fn [sha delta cause]
+ {:sha sha
+ :tighten? true
+ :changes [{:measure a*, :kind :shrink, :delta delta}]
+ :causes {a* [{:sha cause, :delta delta}]}})
+ kinds (fn [records]
+ (for [{:keys [sha changes doubted]} records]
+ [sha (map (juxt :kind :delta :slack) changes) (boolean doubted)]))]
+ (testing "a raise that nothing used and a later commit took back is slack, and neither side counts"
+ (is (= [["stale" [[:slack 8 nil]] false]]
+ (kinds (history/settle {:judged #{}} [(tighten "tighten" -8 "stale") (raise "stale" 8 0)])))))
+ (testing "only the part that was taken back is slack; what was added is growth, and the rest is still doubted"
+ (is (= [["mixed" [[:grow 3 2]] true]]
+ (kinds (history/settle {:judged #{}} [(tighten "tighten" -2 "mixed") (raise "mixed" 5 1)])))))
+ (testing "a raise nobody has taken back yet stays growth and is doubted"
+ (is (= [["fresh" [[:grow 8 nil]] true]]
+ (kinds (history/settle {:judged #{}} [(raise "fresh" 8 0)])))))
+ (testing "a raise made while removing suppressions is all slack, and keeps the credit for the removal"
+ (is (= [["tighten" [[:shrink -3 nil]] false] ["odd" [[:slack 5 nil]] false]]
+ (kinds (history/settle {:judged #{}} [(tighten "tighten" -8 "odd") (raise "odd" 5 -3)])))))
+ (testing "a raise of a budget kept per symbol is never slack or doubted, since its count is approximate"
+ (is (= [["tighten" [[:shrink -1 nil]] false] ["symbols" [[:grow 2 nil]] false]]
+ (kinds (history/settle {:judged #{}}
+ [(tighten "tighten" -1 "symbols")
+ (update-in (raise "symbols" 2 1) [:changes 0] assoc :per-symbol? true)])))))
+ (testing "a raise by the commit that repaired a broken ratchet file is never slack or doubted"
+ (is (= [["tighten" [[:shrink -8 nil]] false] ["repair" [[:grow 8 nil]] false]]
+ (kinds (history/settle {:judged #{}}
+ [(tighten "tighten" -8 "repair")
+ (update-in (raise "repair" 8 0) [:changes 0] assoc :bridged? true)])))))
+ (testing "a confirmed raise is left as growth, and its return as a shrink"
+ (is (= [["tighten" [[:shrink -8 nil]] false] ["kept" [[:grow 8 nil]] false]]
+ (kinds (history/settle {:judged #{"kept"}} [(tighten "tighten" -8 "kept") (raise "kept" 8 0)])))))))
+
+(deftest counted-test
+ (testing "budgets of linters that are not counted drop out, with the commits that changed nothing else"
+ (is (= [{:sha "mixed", :changes [{:measure [:prod :ignore :deprecated-var], :kind :grow, :delta 1}]}]
+ (history/counted
+ [{:sha "mixed", :changes [{:measure [:prod :ignore :deprecated-var], :kind :grow, :delta 1}
+ {:measure [:prod :config :metabase/prefer-with-dynamic-fn-redefs]
+ :kind :grow
+ :delta 1}]}
+ {:sha "only", :changes [{:measure [:test :ignore :metabase/prefer-with-dynamic-fn-redefs]
+ :kind :shrink
+ :delta -2}]}])))))
+
+(deftest render-verdicts-test
+ (testing "the verdicts file reads back as the verdicts written to it"
+ (let [verdicts [{:sha "aaa", :pr 12, :subject "Say \"hi\" (#12)", :verdict :pardon, :why "A stale budget."}
+ {:sha "bbb", :subject "No PR or reason", :verdict :confirm}]]
+ (is (= verdicts
+ (edn/read-string (history/render-verdicts verdicts)))))))
+
+;;; -------------------------------------------------- Report --------------------------------------------------
+
+(deftest unify-authors-test
+ (testing "commits and causes that share an author email take the newest name used with it"
+ ;; the older commit has the later clock time, in a zone ahead of UTC
+ (let [newer {:sha "new", :email "b@x", :date "2026-10-02T01:00:00Z"}
+ older {:sha "old", :email "b@x", :date "2026-10-02T02:30:00+02:00"}
+ other {:sha "other", :author "Ada", :email "a@x", :date "2026-09-02T00:00:00Z"}
+ as (fn [author commit] (assoc commit :author author))]
+ (is (= [(assoc (as "Bryan Maass" newer) :causes {:a [(as "Bryan Maass" older) other]})
+ (as "Bryan Maass" older)]
+ (history/unify-authors
+ [(assoc (as "Bryan Maass" newer) :causes {:a [(as "bryan" older) other]})
+ (as "bryan" older)]))))))
+
+(def ^:private a [:prod :ignore :a])
+(def ^:private b [:test :ignore :b])
+(def ^:private new-linter [:prod :config :new-linter])
+
+(def ^:private records
+ "Three commits, newest first: the automation, a feature that grows one budget and introduces a linter, and a
+ commit that lowers a budget by more than anything explains."
+ [{:sha "tighten"
+ :author "automation"
+ :subject "Tighten ratchets"
+ :date "2026-10-06T10:00:00Z"
+ :tighten? true
+ :changes [{:measure a, :kind :shrink, :delta -5} {:measure b, :kind :shrink, :delta -1}]
+ :causes {a [{:sha "fix", :author "Ada", :subject "Fix", :delta -4}]
+ b [{:sha "fix", :author "Ada", :subject "Fix", :delta -2}
+ {:sha "hid", :author "Bob", :subject "Hide", :delta 1}]}
+ :unaccounted {a -1}}
+ {:sha "feature"
+ :author "Bob"
+ :subject "Feature"
+ :date "2026-10-05T10:00:00Z"
+ :changes [{:measure a, :kind :grow, :delta 3, :added 3, :old 4, :new 7}
+ {:measure new-linter, :kind :introduce, :old nil, :new 9}]}
+ {:sha "recount"
+ :author "Cy"
+ :subject "Count fewer things"
+ :date "2026-09-30T23:00:00Z"
+ :changes [{:measure b, :kind :shrink, :delta -7, :old 9, :new 2}]
+ :causes {b [{:sha "recount", :author "Cy", :subject "Count fewer things", :delta -2}]}
+ :unaccounted {b -5}}])
+
+(deftest attribution-test
+ (testing "credits a shrink to its causes, a grow to its commit, and the unexplained rest to the commit that shrank"
+ (is (= {:totals {a {:shrink -5, :grow 3}, b {:shrink -8}}
+ :by-commit [["recount" -7] ["fix" -6] ["hid" 1] ["feature" 3]]
+ :leaderboard [[nil true -1 0 -1 0 0]
+ ["Ada" nil -6 0 -6 0 0]
+ ["Bob" nil 0 4 4 1 9]
+ ["Cy" nil -7 0 -7 0 0]]}
+ {:totals (history/totals records)
+ :by-commit (map (juxt :sha :net) (history/by-commit (history/attributions records)))
+ :leaderboard (map (juxt :author :unattributed? :shrunk :grown :net :linters :ignores)
+ (history/leaderboard records))}))))
+
+(deftest pardoned-shrink-test
+ (testing "a shrink that is a net raise once a pardoned raise is taken out of it still goes to its causes"
+ (is (= [["hid" "Bob" 3]]
+ (map (juxt :sha :author :delta)
+ (history/attributions
+ (history/pardon
+ {:pardons {"stale" {a 5}}}
+ [{:sha "tighten"
+ :author "automation"
+ :tighten? true
+ :changes [{:measure a, :kind :shrink, :delta -2}]
+ :causes {a [{:sha "hid", :author "Bob", :delta 3}
+ {:sha "stale", :author "Cy", :delta -5}]}}])))))))
+
+(deftest report-test
+ (testing "names measures and picks out the commits behind the biggest changes"
+ (is (= {:commits 3
+ :total {:shrunk -13, :grown 3, :net -10}
+ :totals [[":b (test)" -8 0 -8] [":a" -5 3 -2]]
+ :best ["recount" -7 [{:measure ":b (test)", :delta -7}]]
+ :worst ["feature" 3 [{:measure ":a", :delta 3}]]
+ :introduced [["feature" [{:measure ":new-linter (config)", :budget "9"}]]]
+ :unaccounted [["tighten" [{:measure ":a", :delta -1}]]]
+ :suspects []}
+ (let [report (history/report (history/settle {:judged #{}} records))
+ biggest (juxt (comp :sha :commit) :net :measures)
+ groups (partial map (juxt (comp :sha :commit) :items))]
+ (-> (select-keys report [:commits :total])
+ (assoc :totals (map (juxt :measure :shrunk :grown :net) (:totals report))
+ :best (biggest (:best report))
+ :worst (biggest (:worst report))
+ :introduced (groups (:introduced report))
+ :unaccounted (groups (:unaccounted report))
+ :suspects (groups (:suspects report)))))))))
+
+(deftest approximate-credit-test
+ (testing "names the measures that are budgeted per symbol, whose credit is approximate"
+ (is (= [":discouraged-namespace (test)" ":discouraged-var"]
+ (:approximate
+ (history/report
+ [{:sha "mixed"
+ :author "Ada"
+ :changes [{:measure [:prod :ignore :discouraged-var], :kind :grow, :delta 1, :per-symbol? true}
+ {:measure [:test :ignore :discouraged-namespace], :kind :shrink, :delta -2, :per-symbol? true}
+ ;; exact: a config-level budget, and a flat one from before per-symbol budgets
+ {:measure [:prod :config :discouraged-var], :kind :grow, :delta 4}
+ {:measure [:test :ignore :discouraged-var], :kind :grow, :delta 5}
+ {:measure a, :kind :grow, :delta 3}]}]))))))
+
+(deftest series-test
+ (testing "splits each commit's change to the total budget into what is credited and what counts for nobody"
+ (let [records [{:sha "tighten", :changes [{:measure a, :kind :shrink, :delta -2, :old 5, :new 3}]}
+ {:sha "uncounted"
+ :changes [{:measure [:prod :ignore :metabase/prefer-with-dynamic-fn-redefs]
+ :kind :shrink
+ :delta -9
+ :old 9
+ :new nil}]}
+ {:sha "mixed"
+ :changes [{:measure [:prod :ignore :discouraged-var], :kind :introduce, :key :x/y, :new 4}
+ {:measure b, :kind :seed, :old nil, :new 3}
+ {:measure new-linter, :kind :unlimit, :old 2, :new :unlimited}
+ {:measure [:prod :ignore :metabase/prefer-with-dynamic-fn-redefs]
+ :kind :grow
+ :delta 8
+ :old 1
+ :new 9}]}
+ {:sha "pardoned", :changes [{:measure a, :kind :grow, :delta 5, :old nil, :new 5}]}]
+ settled (history/settle {:pardons {"pardoned" {a 5}}, :judged #{}} records)]
+ ;; sha, shrunk, grown, introduced, seeded, unlimited, excused, level, changed
+ (is (= [["pardoned" 0 0 0 0 0 5 5 true]
+ ["mixed" 0 0 4 3 -2 0 10 true]
+ ["uncounted" 0 0 0 0 0 0 10 false]
+ ["tighten" -2 0 0 0 0 0 8 true]]
+ (map (juxt :sha :shrunk :grown :introduced :seeded :unlimited :excused :level :changed?)
+ (history/series records settled)))))))
+
+(deftest periods-test
+ (testing "covers all time, then each week from its Monday and each month, back to the first commit"
+ (is (= [["all" "All time" nil nil 3 -10]
+ ["week-2026-10-05" "5 Oct to 11 Oct 2026" "2026-10-05" "2026-10-12" 2 -3]
+ ["week-2026-09-28" "28 Sep to 4 Oct 2026" "2026-09-28" "2026-10-05" 1 -7]
+ ["month-2026-10" "October 2026" "2026-10-01" "2026-11-01" 2 -3]
+ ["month-2026-09" "September 2026" "2026-09-01" "2026-10-01" 1 -7]]
+ (map (juxt :id :label :from :to (comp :commits :report) (comp :net :total :report))
+ (history/periods "2026-10-10" (history/settle {:judged #{}} records)))))))
+
+(deftest script-json-test
+ (testing "data that could end or hide the end of a script element reads back unchanged, with no `<` in it"
+ (let [data {:subject "<!--<script> and </script>"}
+ text (history/script-json data)]
+ (is (= [false data]
+ [(str/includes? text "<") (json/read-str text)])))))
+
+;;; ------------------------------------------------- Terminal -------------------------------------------------
+
+(defn- headlines
+ "The lines of `lines` that are not indented or blank: the title and the section headings."
+ [lines]
+ (remove #(or (str/blank? %) (str/starts-with? % " ")) lines))
+
+(deftest summary-test
+ (binding [c/*disable-colors* true]
+ (let [lines (history/summary "of all time" 3 (history/report (history/settle {:judged #{}} records)))]
+ (testing "has a section for each part of the report that holds something"
+ (is (= ["Ratchet changes of all time: 3 commits"
+ "Total deltas"
+ "Biggest improvement"
+ "Biggest regression"
+ "New linters and measures"
+ "Shrinks no commit accounts for"]
+ (headlines lines))))
+ (testing "lists the first six budgets of a commit and sums the rest"
+ (is (= [" seed Seed"
+ " :l0 starting at 0"
+ " :l1 starting at 1"
+ " :l2 starting at 2"
+ " :l3 starting at 3"
+ " :l4 starting at 4"
+ " :l5 starting at 5"
+ " 2 more budgets, starting at 13 in all"]
+ (->> (history/summary "of all time"
+ 1
+ {:seeded [{:commit {:sha "seed", :author "Ada", :subject "Seed"}
+ :items (for [i (range 8)]
+ {:measure (str ":l" i), :budget (str i), :size i})}]})
+ (drop-while #(not= "New ratchets over existing debt" %))
+ rest))))
+ (testing "sums the budgets past the first six of the biggest change and of a raise with no verdict"
+ (let [commit {:sha "big", :author "Ada", :subject "Big"}
+ measures (for [i (range 8)] {:measure (str ":l" i), :delta (- i), :added 0})
+ lines (history/summary "of all time" 1 {:best {:commit commit, :net -28, :measures measures}
+ :suspects [{:commit commit
+ :items (map #(update % :delta -) measures)}]})]
+ (is (= [" -13 2 more budgets"
+ " +13 over 2 more budgets, with 0 suppressions added"]
+ (filter #(str/includes? % "more budgets") lines)))))
+ (testing "names no author"
+ (is (= []
+ (filter #(re-find #"Ada|Bob|Cy|automation" %) lines)))))))
+
+;;; ---------------------------------------------------- Task --------------------------------------------------
+
+(defn- exits?
+ "Does asking for `since` and `options` make the task exit?"
+ [[since options]]
+ (try
+ (with-out-str (history/request since options))
+ false
+ (catch clojure.lang.ExceptionInfo e
+ (some? (:babashka/exit (ex-data e))))))
+
+(deftest request-test
+ (testing "reads what to do from the commit and the options"
+ (is (= [[:days 7] [:days 3] [:all] [:since "abc"] [:html "page.html"] [:verdict [:recount "12"]]]
+ (map (fn [[since options]] (history/request since options))
+ [[nil {}]
+ [nil {:days 3}]
+ [nil {:all true}]
+ ["abc" {}]
+ [nil {:html "page.html"}]
+ [nil {:recount "12", :why "The same ignores."}]]))))
+ (testing "exits when asked for two things at once, or for a reason with no verdict"
+ (is (= [true true true true]
+ (map exits? [[nil {:all true, :days 3}]
+ ["abc" {:html "page.html"}]
+ [nil {:pardon "12", :confirm "13"}]
+ [nil {:days 3, :why "No verdict to explain."}]])))))
+
+;;; ---------------------------------------------- Against a repository ----------------------------------------
+
+(def ^:private isolated
+ "Environment that keeps the user's and the system's git configuration out of the fixture."
+ {"GIT_CONFIG_GLOBAL" "/dev/null", "GIT_CONFIG_NOSYSTEM" "1"})
+
+(defn- commit!
+ "Write `files`, a map from path to content, in the repository at `dir` and commit them as `author` on `day` of
+ September 2026."
+ [dir author day subject files]
+ (doseq [[path content] files]
+ (fs/create-dirs (fs/parent (fs/path dir path)))
+ (if content
+ (spit (str (fs/path dir path)) content)
+ (fs/delete (fs/path dir path))))
+ (let [date (format "2026-09-%02dT10:00:00Z" day)
+ email (str (str/lower-case author) "@example.com")
+ git (fn [& args]
+ (apply p/shell {:dir (str dir)
+ :out :string
+ :err :string
+ :extra-env (merge isolated
+ {"GIT_AUTHOR_NAME" author
+ "GIT_AUTHOR_EMAIL" email
+ "GIT_AUTHOR_DATE" date
+ "GIT_COMMITTER_NAME" author
+ "GIT_COMMITTER_EMAIL" email
+ "GIT_COMMITTER_DATE" date})}
+ "git" "-c" "commit.gpgsign=false" "-c" "core.hooksPath=/dev/null" args))]
+ (git "add" "-A")
+ (git "commit" "-q" "-m" subject)))
+
+(defn- with-repo!
+ "Call `f` with a [[history/repo]] over a new repository holding `commits`, then delete it.
+ Each commit is `[author day subject files]`, as [[commit!]] takes them."
+ [commits f]
+ (let [root (fs/create-temp-dir {:prefix "ratchets-history"})
+ dir (fs/create-dirs (fs/path root "repo"))]
+ (try
+ (p/shell {:dir (str dir), :out :string, :extra-env isolated} "git" "init" "-q" "-b" "master")
+ (p/shell {:dir (str dir), :out :string, :extra-env isolated}
+ "git" "remote" "add" "origin" "[email protected]:example/ratchets.git")
+ (doseq [[author day subject files] commits]
+ (commit! dir author day subject files))
+ (f (history/repo {:dir (str dir)
+ :cache (fs/path root "cache")
+ :verdicts (fs/file (str root) "verdicts.edn")
+ :env isolated}))
+ (finally
+ (fs/delete-tree root)))))
+
+(defn- lines [& lines]
+ (str (str/join "\n" lines) "\n"))
+
+(def ^:private ratchets ".clj-kondo/ratchets.edn")
+
+(def ^:private story
+ "Chris adds a ratchet over three ignores. Ada removes an ignore, and Bob edits only the continuation line of a
+ multi-line ignore to drop a linter. The automation tightens. Cy raises one budget by 2 for 1 new ignore and
+ gives another linter a first budget of 5 for no ignores at all. The automation tightens again."
+ (let [source "src/app/a.clj"]
+ [["Chris" 1 "Add ratchets (#1)"
+ {ratchets "{:ignore-counts {:deprecated-var 2, :unused-binding 1}}\n"
+ source (lines "(ns app.a)"
+ "#_{:clj-kondo/ignore [:deprecated-var]}"
+ "(a)"
+ "#_{:clj-kondo/ignore [:deprecated-var"
+ " :unused-binding]}"
+ "(b)")}]
+ ["Ada" 2 "Stop using a (#2)"
+ {source (lines "(ns app.a)"
+ "(a)"
+ "#_{:clj-kondo/ignore [:deprecated-var"
+ " :unused-binding]}"
+ "(b)")}]
+ ["Bob" 3 "Use the binding (#3)"
+ {source (lines "(ns app.a)"
+ "(a)"
+ "#_{:clj-kondo/ignore [:deprecated-var"
+ " ]}"
+ "(b)")}]
+ ["automation" 4 "Tighten ratchets (#4)"
+ {ratchets "{:ignore-counts {:deprecated-var 1}}\n"}]
+ ["Cy" 5 "Add a feature (#5)"
+ {ratchets "{:ignore-counts {:deprecated-var 3, :type-mismatch 5}}\n"
+ "src/app/b.clj" (lines "(ns app.b)" "#_{:clj-kondo/ignore [:deprecated-var]}" "(c)")}]
+ ["automation" 6 "Tighten ratchets (#6)"
+ {ratchets "{:ignore-counts {:deprecated-var 2}}\n"}]]))
+
+(defn- with-fixture-repo! [f]
+ (with-repo! story f))
+
+(def ^:private deprecated [:prod :ignore :deprecated-var])
+(def ^:private mismatch [:prod :ignore :type-mismatch])
+(def ^:private unused [:prod :ignore :unused-binding])
+
+(defn- causes-by
+ "The `causes` of a record as the author, PR and delta of each, per measure."
+ [causes]
+ (update-vals (or causes {}) #(map (juxt :author :pr :delta) %)))
+
+(deftest records-test
+ (testing "reads a repository's history: seeds, tightens credited to the commits before them, and raises"
+ (is (= [[6 "automation" true
+ [[:shrink deprecated -1 nil] [:shrink mismatch -5 nil]]
+ ;; both only take back what Cy's commit raised beyond what it added
+ {deprecated [["Cy" 5 -1]], mismatch [["Cy" 5 -5]]}]
+ ;; a first budget in a ratchet that already existed is growth
+ [5 "Cy" nil [[:grow deprecated 2 1] [:grow mismatch 5 0]] {}]
+ [4 "automation" true
+ [[:shrink deprecated -1 nil] [:shrink unused -1 nil]]
+ ;; Bob's commit touched no line that names the ignore marker
+ {deprecated [["Ada" 2 -1]], unused [["Bob" 3 -1]]}]
+ [1 "Chris" nil [[:seed deprecated nil nil] [:seed unused nil nil]] {}]]
+ (with-fixture-repo!
+ (fn [repo]
+ (vec (for [{:keys [pr author tighten? changes causes]} (history/records repo)]
+ [pr author tighten?
+ (map (juxt :kind :measure :delta :added) changes)
+ (causes-by causes)]))))))))
+
+(deftest series-adds-up-test
+ (testing "the credited change and the parts that count for nobody add up to each change in the total budget"
+ (with-fixture-repo!
+ (fn [repo]
+ (let [records (history/records repo)
+ points (history/series records (history/settle {:judged #{}} records))
+ parts (juxt :shrunk :grown :introduced :seeded :unlimited :excused)]
+ (is (= {:levels [3 1 8 2]
+ :sums [3 -2 7 -6]}
+ {:levels (map :level points)
+ :sums (map #(reduce + (parts %)) points)})))))))
+
+(deftest run-test
+ (binding [c/*disable-colors* true]
+ (with-fixture-repo!
+ (fn [repo]
+ (let [summary #(str/split-lines (with-out-str (history/run repo {:options {:all true}, :arguments []})))
+ total (fn [lines] (some #(when (str/starts-with? % " total ") (str/split (str/trim %) #"\s+")) lines))
+ warned? (fn [lines] (boolean (some #{"Raises beyond the suppressions added, with no verdict"} lines)))]
+ (testing "counts the ignore that was added as growth, and the spare budget that was taken back as nothing"
+ (is (= [["total" "-2" "+1" "-1"] false]
+ ((juxt total warned?) (summary)))))
+ (testing "summarizes only the commits after the one given"
+ (let [after (some #(when (= 4 (:pr %)) (:sha %)) (history/records repo))
+ lines (str/split-lines (with-out-str (history/run repo {:options {}, :arguments [after]})))]
+ (is (= [(str "Ratchet changes since " (subs after 0 10) ": 2 commits") ["total" "0" "+1" "+1"]]
+ [(first lines) (total lines)]))))
+ (testing "writes the page, with the repository's GitHub URL taken from its SSH remote"
+ (let [file (str (fs/path (fs/parent (:verdicts-file repo)) "page.html"))
+ _ (with-out-str (history/run repo {:options {:html file}, :arguments []}))
+ data (json/read-str (second (re-find #"id=\"data\">(.*?)</script>" (slurp file))))]
+ (is (= ["https://github.com/example/ratchets" 6 "all" 4]
+ ((juxt :repo :shown (comp :id first :periods) (comp count :series)) data)))))
+ ;; a PR that changed no ratchet file, a commit that raised nothing, no reason, a start that is no commit
+ (testing "refuses a verdict or a start it cannot act on"
+ (is (= [1 1 1 1]
+ (for [request [{:options {:pardon "2", :why "Not a ratchet commit."}, :arguments []}
+ {:options {:pardon "4", :why "It only lowered budgets."}, :arguments []}
+ {:options {:pardon "5"}, :arguments []}
+ {:options {}, :arguments ["not-a-commit"]}]]
+ (try
+ (with-out-str (history/run repo request))
+ nil
+ (catch clojure.lang.ExceptionInfo e
+ (:babashka/exit (ex-data e))))))))
+ (testing "a pardon, given by PR number, is recorded and takes out the raises and what took them back"
+ (with-out-str (history/run repo {:options {:pardon "5", :why "A stale budget."}, :arguments []}))
+ (is (= {:verdicts [[5 "Add a feature (#5)" :pardon "A stale budget."]]
+ :total ["total" "-2" "0" "-2"]
+ :warned? false}
+ {:verdicts (map (juxt :pr :subject :verdict :why) (edn/read-string (slurp (:verdicts-file repo))))
+ :total (total (summary))
+ :warned? (warned? (summary))}))))))))
+
+(deftest unreadable-ratchet-test
+ (testing "a ratchet file that does not parse is unreadable, with a warning"
+ (let [err (java.io.StringWriter.)]
+ (is (= [::history/unreadable true]
+ [(binding [*err* err]
+ (#'history/read-ratchet "abc123" ".clj-kondo/ratchets.edn" "{:ignore-counts {:a 1}"))
+ (str/includes? (str err) "WARNING: .clj-kondo/ratchets.edn at abc123 does not parse")]))))
+ (testing "nothing changes across an unreadable ratchet file, in either direction"
+ (is (= [[] []]
+ [(changes {:prod ::history/unreadable} {:prod {:ignore-counts {:a 1}}} #{})
+ (changes {:prod {:ignore-counts {:a 1}}} {:prod ::history/unreadable} #{})]))))
+
+(deftest unreadable-gap-test
+ (testing "the repair of a broken ratchet file carries the change across the gap, and only it is marked bridged"
+ (let [tests ".clj-kondo/ratchets-test.edn"]
+ (is (= [[4 "Bob" [[:grow [:prod :ignore :a] 3 true]]]
+ [3 "Dee" [[:grow [:test :ignore :b] 3 nil]]]
+ [2 "Ada" []]
+ ;; the commit that adds the test ratchet file is read with both sides as one
+ [1 "Chris" [[:seed [:prod :ignore :a] nil nil] [:seed [:prod :ignore :b] nil nil]]]]
+ (binding [*err* (java.io.StringWriter.)]
+ (with-repo!
+ [["Chris" 1 "Add a ratchet (#1)"
+ {ratchets "{:ignore-counts {:a 2}}\n"
+ tests "{:ignore-counts {:b 1}}\n"}]
+ ["Ada" 2 "Break the ratchet file (#2)"
+ {ratchets "{:ignore-counts {:a 2\n"}]
+ ["Dee" 3 "Raise a test budget while it is broken (#3)"
+ {tests "{:ignore-counts {:b 4}}\n"}]
+ ["Bob" 4 "Repair it, with a raise (#4)"
+ {ratchets "{:ignore-counts {:a 5}}\n"}]]
+ (fn [repo]
+ (vec (for [{:keys [pr author changes]} (history/records repo)]
+ [pr author (map (juxt :kind :measure :delta :bridged?) changes)]))))))))))
+
+(deftest module-measure-test
+ (testing "a module measure is introduced only when the commit also adds what counts it, and seeded otherwise"
+ (let [counter "dev/src/dev/kondo_ratchet.clj"
+ modules ".clj-kondo/config/modules/ratchets.edn"]
+ (is (= [[[:introduce [:modules :module :ns-prefixes]] [:seed [:modules :module :uses-any]]]]
+ (with-repo!
+ [["Chris" 1 "Count uses (#1)"
+ {counter "{:uses-any (count uses)}\n"}]
+ ["Cy" 2 "Ratchet the modules (#2)"
+ {modules "{:ns-prefixes 3, :uses-any 1}\n"
+ counter "{:uses-any (count uses), :ns-prefixes (count prefixes)}\n"}]]
+ (fn [repo]
+ (mapv #(map (juxt :kind :measure) (:changes %)) (history/records repo)))))))))
+
+(deftest unreadable-test-ratchet-removed-test
+ (testing "a broken test ratchet file that is removed marks the prod changes its budgets are folded into"
+ (let [tests ".clj-kondo/ratchets-test.edn"]
+ (is (= [[:grow [:prod :ignore :b] 3 true]]
+ (binding [*err* (java.io.StringWriter.)]
+ (with-repo!
+ [["Chris" 1 "Add ratchets (#1)"
+ {ratchets "{:ignore-counts {:a 2}}\n"
+ tests "{:ignore-counts {:b 1}}\n"}]
+ ["Ada" 2 "Break the test ratchet file (#2)"
+ {tests "{:ignore-counts {:b 1\n"}]
+ ["Bob" 3 "Fold it into the other, with a raise (#3)"
+ {ratchets "{:ignore-counts {:a 2, :b 4}}\n"
+ tests nil}]]
+ (fn [repo]
+ (mapv (juxt :kind :measure :delta :bridged?)
+ (:changes (first (history/records repo))))))))))))
+
+(deftest newly-discouraged-symbol-test
+ (testing "the first budget of a newly discouraged symbol is where it starts, not slack that a shrink takes back"
+ (let [config ".clj-kondo/config.edn"
+ ignore "#_{:clj-kondo/ignore [:discouraged-var]}"
+ source (fn [& forms] (apply lines "(ns app.a)" (interleave (repeat ignore) forms)))
+ budget (fn [counts] (str {:ignore-counts {}, :discouraged-var-counts counts} "\n"))]
+ (is (= [[4 [[:shrink nil]] {[:prod :ignore :discouraged-var] [["Bob" 2 -1]]}]
+ [3 [[:introduce :clojure.core/eval]] {}]]
+ (with-repo!
+ [["Chris" 1 "Add a ratchet (#1)"
+ {ratchets (budget {:clojure.core/prn 2})
+ config "{:linters {:discouraged-var {clojure.core/prn {}}}}\n"
+ "src/app/a.clj" (source "(prn 1)" "(prn 2)" "(eval 1)")}]
+ ["Bob" 2 "Stop one prn (#2)"
+ {"src/app/a.clj" (source "(prn 1)" "(eval 1)")}]
+ ["Ada" 3 "Discourage eval (#3)"
+ {ratchets (budget {:clojure.core/prn 2, :clojure.core/eval 1})
+ config "{:linters {:discouraged-var {clojure.core/prn {}, clojure.core/eval {}}}}\n"}]
+ ["automation" 4 "Tighten ratchets (#4)"
+ {ratchets (budget {:clojure.core/prn 1, :clojure.core/eval 1})}]]
+ (fn [repo]
+ (vec (for [{:keys [pr changes causes]} (take 2 (history/records repo))]
+ [pr
+ (map (juxt :kind :key) changes)
+ (causes-by causes)])))))))))