Skip to content

Commit b987c41

Browse files
ryansolidClaude via Cursorcursoragent
authored
chore(size): measure the minified allowance against the minified recorded with each cap (#3822)
* chore(size): measure the minified allowance against the minified recorded with each cap Each cap records the minified size measured when it was set (capMinified inline, { cap, minified } in floor-caps.json). Over the brotli cap, a scenario fails when head minified exceeds the recorded size + 20 B, so growth cannot creep across PRs; the base comparison stays as the fail-safe for a cap without one. The warning states the headroom left. The ratchet pairs the recorded minified with each lowered cap and otherwise only lowers it (--minified-only records missing ones); check-floor-caps freezes a floor's recorded minified like its cap. Co-authored-by: Claude via Cursor <[email protected]> * chore(size): wrap the ratchet's ledger lines at 80 columns Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * chore(size): seed recorded minified from CI on next @ c54fb10 Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * chore(size): re-seed recorded minified from CI on next @ fff1615 #3812, #3814 and #3811 moved minified +30 to +69 B after the first seed (c54fb10); re-seeded from scratch at the tip, every cap unchanged. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> --------- Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent fff1615 commit b987c41

9 files changed

Lines changed: 499 additions & 132 deletions

File tree

‎scripts/size/README.md‎

Lines changed: 63 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -20,43 +20,66 @@ monotonic in the input: a change of a few minified bytes moves a scenario's
2020
brotli by ±50–90 B, so a brotli-only gate failed PRs for noise and every
2121
"fix" either raised a cap (permanently) or golfed the code until the layout
2222
came out lucky. Minified bytes are deterministic, so the gate (`gate.mjs`)
23-
uses them to tell noise from growth. Per scenario:
24-
25-
| brotli vs cap | minified vs base | verdict |
26-
| ------------- | ------------------------------------- | ------------------------------ |
27-
| at or under | anything | **pass** |
28-
| over | grew by ≤ `MINIFIED_ALLOWANCE` (20 B) | **pass with a warning** |
29-
| over | grew by more | **fail** |
30-
| over | no base measurement | **fail** (the cap is absolute) |
31-
32-
"Base" is the PR's base commit (`pull_request.base.sha`, the first parent
33-
of the merge commit CI measures as the head), measured in the same run
34-
with the head's harness; on a push to `next` it is the commit before the
35-
push. The warning — in the job summary, the PR size comment and as an
36-
annotation — reads _over brotli cap by N B, minified +M B — layout noise;
37-
cap will be re-based at the next ratchet_. The allowance is one constant,
38-
`MINIFIED_ALLOWANCE` in `gate.mjs`; a scenario may set its own with
39-
`minifiedAllowance` in `scenarios.js` (none does).
23+
uses them to tell noise from growth.
24+
25+
Every cap records the **minified size measured when it was set**:
26+
`capMinified` beside an inline `limit` in `scenarios.js`, and
27+
`{ "cap", "minified" }` entries in `floor-caps.json`. Per scenario:
28+
29+
| brotli vs cap | head minified | verdict |
30+
| ------------- | ---------------------------------------------------- | ----------------------- |
31+
| at or under | anything | **pass** |
32+
| over | ≤ recorded minified + `MINIFIED_ALLOWANCE` (20 B) | **pass with a warning** |
33+
| over | more | **fail** |
34+
| over | no recorded minified: grew ≤ 20 B over the PR's base | pass with a warning |
35+
| over | no recorded minified: grew more, or no base | **fail** |
36+
37+
The allowance is measured against the recorded size, not per PR, so growth
38+
cannot creep across PRs: on an over-cap scenario, two successive +15 B PRs
39+
do not both pass — the second is +30 B over the recorded size. The warning
40+
(job summary, PR size comment, annotation) states the headroom left:
41+
_over brotli cap by N B; minified M B vs R B recorded with the cap (+D B) —
42+
H B of the 20 B minified allowance left; +P B minified over this PR's base_.
43+
A failure carries the same numbers, so a PR whose own change is small can
44+
see that earlier growth used the allowance up.
45+
46+
The last two rows are the fail-safe for a cap without a recorded minified (a
47+
new scenario that did not record one): the gate compares with the PR's base
48+
(`pull_request.base.sha`, the first parent of the merge commit CI measures
49+
as the head; on a push to `next`, the commit before the push), measured in
50+
the same run with the head's harness, and the summary says so. The
51+
allowance is one constant, `MINIFIED_ALLOWANCE` in `gate.mjs`; a scenario
52+
may set its own with `minifiedAllowance` in `scenarios.js` (none does).
4053

4154
Real growth is still a decision made in the PR: lower the bytes, or raise
42-
the scenario's cap in the same PR with a dated reason in its ledger. Raising
43-
a frozen floor cap (below) additionally needs a `Size-Exception:` line in
44-
the PR body — the override for growth the maintainer has accepted.
55+
the scenario's cap **and its recorded minified** in the same PR, measured
56+
together by CI, with a dated reason in its ledger. A new scenario records
57+
both. Raising a frozen floor's cap or its recorded minified (below)
58+
additionally needs a `Size-Exception:` line in the PR body — the override
59+
for growth the maintainer has accepted.
4560

4661
Locally, `npm run size` is the absolute gate (any scenario over its cap
4762
fails); `node gate.mjs head.json base.json` applies the PR rule to two
4863
`size.mjs --json` files, and `npm test` runs the decision's tests.
4964

5065
## The ratchet
5166

52-
Noise that passed with a warning leaves a scenario over its cap; savings
53-
leave caps loose. `npm run ratchet` re-bases every cap on what the tree
54-
measures now — measured + 10 B rounded up to 0.01 KB — and **only ever
55-
lowers** a cap. It rewrites the inline caps in `scenarios.js` and the frozen
56-
floors in `floor-caps.json`, adds a dated ledger line above each lowered
57-
cap, and prints the lowered inline caps and the lowered **frozen floors** as
58-
separate tables, so a floor change is seen as one. A scenario still over its
59-
cap is listed and left alone: the ratchet does not raise.
67+
Savings leave caps loose. `npm run ratchet` re-bases every cap on what the
68+
tree measures now — measured + 10 B rounded up to 0.01 KB — and **only ever
69+
lowers** a cap. A lowered cap records the minified measured with it (one
70+
measurement; if that minified is higher, brotli still shrank, and the
71+
ratchet lists it). A cap it does not lower only ever has its recorded
72+
minified **lowered**, or recorded for the first time; it is never raised —
73+
that loosens the gate like a cap raise, so it takes a PR (and, on a floor,
74+
a `Size-Exception:`). The ratchet rewrites `scenarios.js` and
75+
`floor-caps.json`, adds a dated ledger line above each cap it changes, and
76+
prints the inline caps and the **frozen floors** as separate tables, so a
77+
floor change is seen as one. Scenarios still over their cap, or above their
78+
recorded minified, are listed and left alone: the ratchet does not raise,
79+
so a scenario that landed over its cap on noise stays over it, held to its
80+
recorded minified + 20 B, until code shrinks or a PR re-bases it.
81+
`--minified-only` leaves every cap alone and only records or lowers
82+
minified sizes.
6083

6184
Run it once per RC, on `next`, from CI's numbers — local and CI artifacts
6285
differ by tens of brotli bytes:
@@ -124,8 +147,9 @@ maintainer accepted the cost (read from the PR body when the run starts —
124147
edit the body, then re-run). Ten weeks of individually justified 10–300 B
125148
bumps took the signals floor from 7.1 to 9.9 KB; the freeze makes the next
126149
one a decision, not a paragraph. See
127-
`documentation/plans/size-reduction-audit.md`. The ratchet may lower a
128-
frozen floor like any cap.
150+
`documentation/plans/size-reduction-audit.md`. Each floor's recorded
151+
minified is frozen the same way (raising it, or removing it, needs the
152+
exception). The ratchet may lower a frozen floor like any cap.
129153

130154
## Attribution
131155

@@ -176,3 +200,12 @@ breaks.
176200
`compare` job (which ran after `check`) into a parallel `base` job that
177201
`check` waits on, and pushes to `next` now compare against the previous
178202
commit instead of the absolute cap. No cap changed.
203+
- **2026-10-06 — recorded minified (#3822).** Measured per PR, the
204+
allowance let an over-cap scenario creep: each +15 B PR passed against its
205+
own base. Every cap now records the minified size measured when it was
206+
set, and the allowance is measured against that. The warning states the
207+
headroom left instead of promising a re-base (the lower-only ratchet
208+
cannot re-base an over-cap scenario). Seeded by the ratchet's
209+
`--minified-only` mode from CI's measurement of `next` @ fff1615ee (Size
210+
run 37443080193); every cap unchanged. The base comparison remains the fail-safe
211+
for a cap without a recorded minified.

‎scripts/size/check-floor-caps.mjs‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@
1212
// Compares floor-caps.json at HEAD with the same file at <base-ref>. Exits
1313
// non-zero if any cap increased, unless SIZE_EXCEPTION (the PR body, in CI)
1414
// contains a line starting with "Size-Exception:" that names the reason.
15-
// A cap absent at the base (a new floor scenario) is allowed.
15+
// A cap absent at the base (a new floor scenario) is allowed. The minified
16+
// size recorded with each cap (`{ cap, minified }` entries; the gate
17+
// measures minified growth against it) is frozen the same way: raising it
18+
// loosens the gate exactly as raising the cap does. A recorded minified
19+
// absent at the base (an entry still in the old string form) is allowed.
1620

1721
import { readFileSync } from "node:fs";
1822
import { execFileSync } from "node:child_process";
@@ -54,12 +58,15 @@ try {
5458
}
5559

5660
const exception = /^\s*Size-Exception:\s*\S/m.test(process.env.SIZE_EXCEPTION ?? "");
61+
const entry = e => (typeof e === "string" ? { cap: e } : e);
5762
let raised = [];
58-
for (const [name, cap] of Object.entries(head)) {
63+
for (const [name, value] of Object.entries(head)) {
5964
if (!(name in baseCaps)) continue;
60-
const before = toBytes(baseCaps[name]);
61-
const after = toBytes(cap);
62-
if (after > before) raised.push(` ${name}: ${baseCaps[name]} -> ${cap}`);
65+
const was = entry(baseCaps[name]);
66+
const now = entry(value);
67+
if (toBytes(now.cap) > toBytes(was.cap)) raised.push(` ${name}: ${was.cap} -> ${now.cap}`);
68+
if (typeof was.minified === "number" && !(now.minified <= was.minified))
69+
raised.push(` ${name}: recorded minified ${was.minified} B -> ${now.minified ?? "removed"}`);
6370
}
6471

6572
if (raised.length === 0) {

‎scripts/size/floor-caps.json‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,30 @@
11
{
2-
"signals: core floor (createSignal/Memo/Effect/Root/flush)": "7.35 KB",
3-
"app: render + one signal (the simple-app floor)": "9.86 KB",
4-
"app: hydrating (no stores) with Show/For/Loading/Errored/lazy": "17.71 KB",
5-
"page: base server components (hydrating + dynamic + frames + sf reference)": "44.84 KB",
6-
"page: live server components (base + live/GET + action + isPending/latest)": "48.51 KB",
7-
"server: floor (getRequestEvent + isServer)": "1.34 KB",
8-
"server: renderToString (the server-render floor)": "20.42 KB"
2+
"signals: core floor (createSignal/Memo/Effect/Root/flush)": {
3+
"cap": "7.35 KB",
4+
"minified": 20133
5+
},
6+
"app: render + one signal (the simple-app floor)": {
7+
"cap": "9.86 KB",
8+
"minified": 27687
9+
},
10+
"app: hydrating (no stores) with Show/For/Loading/Errored/lazy": {
11+
"cap": "17.71 KB",
12+
"minified": 52567
13+
},
14+
"page: base server components (hydrating + dynamic + frames + sf reference)": {
15+
"cap": "44.84 KB",
16+
"minified": 145599
17+
},
18+
"page: live server components (base + live/GET + action + isPending/latest)": {
19+
"cap": "48.51 KB",
20+
"minified": 157562
21+
},
22+
"server: floor (getRequestEvent + isServer)": {
23+
"cap": "1.34 KB",
24+
"minified": 3324
25+
},
26+
"server: renderToString (the server-render floor)": {
27+
"cap": "20.42 KB",
28+
"minified": 71813
29+
}
930
}

‎scripts/size/gate.mjs‎

Lines changed: 70 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,19 @@
33
//
44
// Caps are brotli bytes, and brotli is what ships, so a scenario under its
55
// cap passes whatever its minified size did. Over the cap is not enough to
6-
// fail: brotli's layout moves ±50–90 B on minified changes of a few bytes, so
7-
// a PR fails a scenario only when it is over its brotli cap AND its minified
8-
// growth over the PR's base exceeds MINIFIED_ALLOWANCE (or the scenario's
9-
// `minifiedAllowance`). Over the cap within the allowance passes with a
10-
// warning — layout noise, left for the next ratchet (ratchet.mjs) to re-base.
11-
// The base is the PR's base commit, or on a push to next the commit before
12-
// it. Without a base measurement (a new scenario, a base the head's harness
13-
// could not measure, a local run) the cap is absolute, as it always was.
6+
// fail: brotli's layout moves ±50–90 B on minified changes of a few bytes.
7+
// Each cap records the minified size measured when it was set
8+
// (`capMinified`), and a scenario fails only when it is over its brotli cap
9+
// AND its minified size exceeds that recorded size by more than
10+
// MINIFIED_ALLOWANCE (or the scenario's `minifiedAllowance`). Over the cap
11+
// within the allowance passes with a warning stating the headroom left.
12+
// Measuring against the recorded size, not the PR's base, bounds growth
13+
// across PRs: two +15 B PRs on an over-cap scenario cannot both pass.
14+
//
15+
// Fail-safe: a cap with no recorded minified falls back to the minified
16+
// growth over the PR's base (the PR's base commit, or on a push to next the
17+
// commit before it). Without that either (a new scenario, a base the head's
18+
// harness could not measure, a local run) the cap is absolute.
1419
//
1520
// Usage: node gate.mjs <head.json> [base.json]
1621
// Exits non-zero when any scenario fails. In GitHub Actions each warning
@@ -23,43 +28,76 @@ import { fileURLToPath } from "node:url";
2328
// counts as real. Minified is the deterministic unit; brotli is not.
2429
export const MINIFIED_ALLOWANCE = 20;
2530

31+
const signed = d => `${d >= 0 ? "+" : "−"}${Math.abs(d)} B`;
32+
const bytes = n => `${n.toLocaleString("en-US")} B`;
33+
const REAL_GROWTH =
34+
"real growth: reduce it, or raise the cap and its recorded minified in this PR with a reason (frozen floors need `Size-Exception:`)";
35+
2636
/**
27-
* One scenario's verdict.
28-
* @returns {{ name: string, verdict: "pass" | "warn" | "fail", overBy?: number,
29-
* minDelta?: number, allowance?: number, message: string }}
37+
* One scenario's verdict. `against` says what the minified size was judged
38+
* against: the minified recorded with the cap, or (fail-safe) the base.
39+
* @returns {{ name: string, verdict: "pass" | "warn" | "fail",
40+
* against?: "recorded" | "base" | "none", overBy?: number, minDelta?: number,
41+
* baseDelta?: number, headroom?: number, allowance?: number, message: string }}
3042
*/
3143
export function decide(head, base) {
3244
const { name } = head;
3345
if (head.error) return { name, verdict: "fail", message: `failed to bundle: ${head.error}` };
3446
if (head.size <= head.limit) return { name, verdict: "pass", message: "within its cap" };
3547
const overBy = head.size - head.limit;
3648
const allowance = head.minifiedAllowance ?? MINIFIED_ALLOWANCE;
37-
if (!base || base.error || typeof base.minified !== "number")
49+
const hasBase = base && !base.error && typeof base.minified === "number";
50+
const baseDelta = hasBase ? head.minified - base.minified : undefined;
51+
const thisPR = hasBase ? `; ${signed(baseDelta)} minified over this PR's base` : "";
52+
53+
if (typeof head.capMinified === "number") {
54+
const minDelta = head.minified - head.capMinified;
55+
const headroom = allowance - minDelta;
56+
const vs = `minified ${bytes(head.minified)} vs ${bytes(head.capMinified)} recorded with the cap (${signed(minDelta)})`;
57+
const common = { name, against: "recorded", overBy, minDelta, baseDelta, headroom, allowance };
58+
if (headroom >= 0)
59+
return {
60+
...common,
61+
verdict: "warn",
62+
message: `over brotli cap by ${overBy} B; ${vs} — ${headroom} B of the ${allowance} B minified allowance left${thisPR}`
63+
};
64+
return {
65+
...common,
66+
verdict: "fail",
67+
message: `over brotli cap by ${overBy} B; ${vs} — ${-headroom} B past the ${allowance} B minified allowance${thisPR}. ${REAL_GROWTH}`
68+
};
69+
}
70+
71+
if (!hasBase)
3872
return {
3973
name,
4074
verdict: "fail",
75+
against: "none",
4176
overBy,
4277
allowance,
43-
message: `over brotli cap by ${overBy} B, no base measurement to compare minified growth against`
78+
message: `over brotli cap by ${overBy} B; no minified recorded with the cap and no base measurement to compare against`
4479
};
45-
const minDelta = head.minified - base.minified;
46-
const signed = `${minDelta >= 0 ? "+" : "−"}${Math.abs(minDelta)} B`;
47-
if (minDelta <= allowance)
80+
const headroom = allowance - baseDelta;
81+
const common = {
82+
name,
83+
against: "base",
84+
overBy,
85+
minDelta: baseDelta,
86+
baseDelta,
87+
headroom,
88+
allowance
89+
};
90+
const vs = `no minified recorded with the cap, so judged against this PR's base: minified ${signed(baseDelta)}`;
91+
if (headroom >= 0)
4892
return {
49-
name,
93+
...common,
5094
verdict: "warn",
51-
overBy,
52-
minDelta,
53-
allowance,
54-
message: `over brotli cap by ${overBy} B, minified ${signed} — layout noise; cap will be re-based at the next ratchet`
95+
message: `over brotli cap by ${overBy} B; ${vs} — ${headroom} B of the ${allowance} B minified allowance left`
5596
};
5697
return {
57-
name,
98+
...common,
5899
verdict: "fail",
59-
overBy,
60-
minDelta,
61-
allowance,
62-
message: `over brotli cap by ${overBy} B, minified ${signed} (allowance ${allowance} B) — real growth: reduce it, or raise the cap in this PR with a reason (frozen floors need \`Size-Exception:\`)`
100+
message: `over brotli cap by ${overBy} B; ${vs} — ${-headroom} B past the ${allowance} B minified allowance. ${REAL_GROWTH}`
63101
};
64102
}
65103

@@ -101,6 +139,12 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
101139
`::${v.verdict === "warn" ? "warning" : "error"} title=${prop(`size: ${v.name}`)}::${data(v.message)}`
102140
);
103141
}
142+
const fallback = verdicts.filter(v => v.against === "base" || v.against === "none");
143+
if (fallback.length)
144+
console.log(
145+
`\ngate: ${fallback.length} over-cap scenario(s) have no minified recorded with the cap; ` +
146+
"judged against the base instead (fail-safe)."
147+
);
104148
const failed = verdicts.some(v => v.verdict === "fail");
105149
const warned = verdicts.filter(v => v.verdict === "warn").length;
106150
console.log(

0 commit comments

Comments
 (0)