Skip to content

Commit c54fb10

Browse files
ryansolidClaude via Cursor
andauthored
chore(size): gate on brotli cap + minified growth over base; add lower-only ratchet (#3821)
A scenario now fails only when it is over its brotli cap AND grew more than MINIFIED_ALLOWANCE (20 B) minified over the PR's base; over the cap within the allowance passes with a layout-noise warning. The base measurement moves from the informational compare job (which ran after check) into a parallel base job that check waits on; pushes to next compare against the previous commit. ratchet.mjs re-bases caps to measured + 10 B, lower only, floors listed apart. Co-authored-by: Claude via Cursor <[email protected]>
1 parent 759a9b6 commit c54fb10

9 files changed

Lines changed: 541 additions & 64 deletions

File tree

‎.github/workflows/size.yml‎

Lines changed: 74 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,17 @@ name: Size
99
# ships); the retained-module-graph assertions in
1010
# packages/signals/tests/treeshake.test.ts stay the which-module diagnostic
1111
# underneath.
12-
# The check job also runs on direct pushes to next: it is self-contained
13-
# (absolute limits, no base ref), and PR-only triggering let the
14-
# +createStore scenario sit failing at a release commit unnoticed — direct
15-
# pushes never measured. The compare job stays PR-only; it needs a PR
16-
# context (base branch, comment target). The floor-cap freeze step in check
17-
# is PR-only for the same reason (it diffs against the base branch).
12+
#
13+
# Three jobs. `head` measures the commit under test; `base` (PRs only)
14+
# measures the PR's base with the head's harness; `check` — the required
15+
# status — decides with both (scripts/size/gate.mjs): a scenario fails only
16+
# when it is over its brotli cap AND grew past the minified allowance over
17+
# the base. The decision needs the base's minified numbers, so the base
18+
# measurement moved from the old informational `compare` job (which ran after
19+
# `check`) into a job `check` waits on; `head` and `base` run in parallel.
20+
# Pushes to next are gated too, against the commit before the push —
21+
# PR-only triggering let the +createStore scenario sit failing at a release
22+
# commit unnoticed.
1823
on:
1924
push:
2025
branches: [next]
@@ -26,9 +31,7 @@ permissions:
2631
pull-requests: write
2732

2833
jobs:
29-
# The hard gate: self-contained on the PR head, fails when any scenario
30-
# exceeds its limit. Never depends on the base branch.
31-
check:
34+
head:
3235
runs-on: ubuntu-latest
3336
steps:
3437
- uses: actions/checkout@v4
@@ -48,46 +51,33 @@ jobs:
4851
- run: pnpm build
4952
- run: npm ci --no-audit --no-fund
5053
working-directory: scripts/size
51-
# size.mjs gates every scenario against its cap and prints the lazy
52-
# chunks and per-package minified bytes for each, so a bump is
53-
# attributed in the same log that reports it. The JSON feeds the
54-
# compare job's PR comment.
55-
- run: npm run size -- --json size-head.json
54+
# size.mjs prints the lazy chunks and per-package minified bytes for
55+
# each scenario, so a bump is attributed in the same log that reports
56+
# it. --no-gate: the decision is check's. Uploaded on pushes too — a
57+
# push to next's size-head is what `npm run ratchet -- --from` reads.
58+
- run: npm run size -- --json size-head.json --no-gate
5659
working-directory: scripts/size
57-
- if: always() && github.event_name == 'pull_request'
58-
uses: actions/upload-artifact@v4
60+
- uses: actions/upload-artifact@v4
5961
with:
6062
name: size-head
6163
path: scripts/size/size-head.json
62-
# The floor and page caps (scripts/size/floor-caps.json) are frozen: a PR
63-
# may lower them, never raise them, unless its body carries a
64-
# `Size-Exception:` line. Compared against the PR's base branch, so
65-
# PR events only.
66-
- if: github.event_name == 'pull_request'
67-
run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
68-
- if: github.event_name == 'pull_request'
69-
run: npm run check-floor-caps -- "origin/${{ github.base_ref }}"
70-
working-directory: scripts/size
71-
env:
72-
SIZE_EXCEPTION: ${{ github.event.pull_request.body }}
7364

74-
# Best-effort base-vs-head delta comment. Builds the base branch and
75-
# measures its artifacts with the HEAD's harness (SIZE_PACKAGES_ROOT), so
76-
# both columns come from the same scenarios and the same Rolldown; the head
77-
# numbers are the check job's. Informational and never blocks:
78-
# continue-on-error keeps bootstrap PRs (and any hiccup) green. PR events
79-
# only — it needs a base ref and a comment target.
80-
compare:
81-
# always(): the comment is most useful on the PR whose check failed.
82-
if: always() && github.event_name == 'pull_request'
83-
needs: check
65+
# Builds the base and measures its artifacts with the HEAD's harness
66+
# (SIZE_PACKAGES_ROOT), so both sides come from the same scenarios and the
67+
# same Rolldown. On a PR the head is the merge commit with base.sha, so the
68+
# difference is the PR's own change; on a push it is the pushed range
69+
# (`before`), so a merge that passed with a noise warning does not turn
70+
# next red on the absolute cap. continue-on-error: a base the head's
71+
# harness cannot build or measure leaves check on absolute caps instead of
72+
# blocking.
73+
base:
8474
runs-on: ubuntu-latest
8575
continue-on-error: true
8676
steps:
8777
- uses: actions/checkout@v4
8878
- uses: actions/checkout@v4
8979
with:
90-
ref: ${{ github.event.pull_request.base.sha }}
80+
ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
9181
path: base
9282
- uses: pnpm/action-setup@v4
9383
- uses: actions/setup-node@v4
@@ -106,23 +96,50 @@ jobs:
10696
working-directory: base
10797
- run: npm ci --no-audit --no-fund
10898
working-directory: scripts/size
109-
- run: node size.mjs --json size-base.json || true
99+
- run: node size.mjs --json size-base.json --no-gate
110100
working-directory: scripts/size
111101
env:
112102
SIZE_PACKAGES_ROOT: ${{ github.workspace }}/base
103+
- uses: actions/upload-artifact@v4
104+
with:
105+
name: size-base
106+
path: scripts/size/size-base.json
107+
108+
# The hard gate (the required status). always(): it runs when base failed;
109+
# a failed head leaves no size-head artifact and fails here.
110+
check:
111+
if: always()
112+
needs: [head, base]
113+
runs-on: ubuntu-latest
114+
steps:
115+
- uses: actions/checkout@v4
116+
- uses: actions/setup-node@v4
117+
with:
118+
node-version-file: ".nvmrc"
119+
- run: npm ci --no-audit --no-fund
120+
working-directory: scripts/size
121+
# gate.mjs's own tests; scripts/size is outside the workspace `pnpm test`.
122+
- run: npm test
123+
working-directory: scripts/size
113124
- uses: actions/download-artifact@v4
114125
with:
115126
name: size-head
116127
path: scripts/size
128+
- continue-on-error: true
129+
uses: actions/download-artifact@v4
130+
with:
131+
name: size-base
132+
path: scripts/size
133+
# The job summary carries the report on every run. The comment only
134+
# goes on PRs from this repository: a fork PR's token is read-only, so
135+
# createComment answers 403. Rendered before the gate step so a failing
136+
# PR still gets its table.
117137
- run: node report.mjs size-head.json size-base.json > size-comment.md
118138
working-directory: scripts/size
119-
# The job summary carries the report on every PR. The comment only goes
120-
# on PRs from this repository: a fork PR's token is read-only, so
121-
# createComment answered 403 and the job showed as failed on every
122-
# external PR.
123139
- run: cat size-comment.md >> "$GITHUB_STEP_SUMMARY"
124140
working-directory: scripts/size
125-
- if: github.event.pull_request.head.repo.full_name == github.repository
141+
- if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
142+
continue-on-error: true
126143
uses: actions/github-script@v7
127144
with:
128145
script: |
@@ -135,3 +152,16 @@ jobs:
135152
const mine = comments.find(c => c.user.type === "Bot" && c.body.startsWith(marker));
136153
if (mine) await github.rest.issues.updateComment({ owner, repo, comment_id: mine.id, body });
137154
else await github.rest.issues.createComment({ owner, repo, issue_number, body });
155+
- run: node gate.mjs size-head.json size-base.json
156+
working-directory: scripts/size
157+
# The floor and page caps (scripts/size/floor-caps.json) are frozen: a PR
158+
# may lower them, never raise them, unless its body carries a
159+
# `Size-Exception:` line. Compared against the PR's base branch, so
160+
# PR events only. always(): reported even when the gate step failed.
161+
- if: always() && github.event_name == 'pull_request'
162+
run: git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
163+
- if: always() && github.event_name == 'pull_request'
164+
run: npm run check-floor-caps -- "origin/${{ github.base_ref }}"
165+
working-directory: scripts/size
166+
env:
167+
SIZE_EXCEPTION: ${{ github.event.pull_request.body }}

‎scripts/size/README.md‎

Lines changed: 91 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,67 @@ compiled-template scenarios — a compiled floor and a JSX todo app in CSR and
88
hydrating form — the frames client as a package, two server-component PAGES:
99
base and live, and two server-entry floors: `getRequestEvent`/`isServer` and
1010
`renderToString`) with hard brotli limits on the eager entry chunk. CI fails
11-
when a scenario exceeds its limit — that means tree-shaking regressed, or a
12-
deliberate feature landed and the limit should be bumped in the same PR with
13-
a reason.
11+
when a scenario exceeds its limit and grew more than a small minified
12+
allowance over its base (see [The gate](#the-gate)) — that means tree-shaking regressed, or a deliberate
13+
feature landed and the limit should be bumped in the same PR with a reason.
14+
15+
## The gate
16+
17+
Caps are **brotli** bytes on the eager entry chunk — brotli is what ships —
18+
set at measured + 10 B rounded up to 0.01 KB. But brotli's layout is not
19+
monotonic in the input: a change of a few minified bytes moves a scenario's
20+
brotli by ±50–90 B, so a brotli-only gate failed PRs for noise and every
21+
"fix" either raised a cap (permanently) or golfed the code until the layout
22+
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).
40+
41+
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.
45+
46+
Locally, `npm run size` is the absolute gate (any scenario over its cap
47+
fails); `node gate.mjs head.json base.json` applies the PR rule to two
48+
`size.mjs --json` files, and `npm test` runs the decision's tests.
49+
50+
## The ratchet
51+
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.
60+
61+
Run it once per RC, on `next`, from CI's numbers — local and CI artifacts
62+
differ by tens of brotli bytes:
63+
64+
```sh
65+
gh run download <run-id> -n size-head # the Size run of the push to next
66+
node ratchet.mjs --from size-head.json --note "RC.7, next @ abc1234" --dry-run
67+
node ratchet.mjs --from size-head.json --note "RC.7, next @ abc1234"
68+
```
69+
70+
Without `--from` it measures this checkout (build it first). Land the
71+
result as its own PR.
1472

1573
## Bundler
1674

@@ -62,10 +120,12 @@ the two server-entry floors have their caps in `floor-caps.json`, not in
62120
**frozen**: a PR may lower them, never raise them. `check-floor-caps.mjs`
63121
diffs the file against the PR's base branch in CI and fails on a raise unless
64122
the PR body contains a line starting with `Size-Exception:` naming why the
65-
maintainer accepted the cost. Ten weeks of individually justified 10–300 B
123+
maintainer accepted the cost (read from the PR body when the run starts —
124+
edit the body, then re-run). Ten weeks of individually justified 10–300 B
66125
bumps took the signals floor from 7.1 to 9.9 KB; the freeze makes the next
67126
one a decision, not a paragraph. See
68-
`documentation/plans/size-reduction-audit.md`.
127+
`documentation/plans/size-reduction-audit.md`. The ratchet may lower a
128+
frozen floor like any cap.
69129

70130
## Attribution
71131

@@ -75,7 +135,18 @@ the lazy chunks and the minified bytes each package contributed (`signals`,
75135
attributed in the log that reports it. Minified bytes are the attributable
76136
unit; brotli compresses across module boundaries. `node attribute.mjs [name]
77137
[--min bytes]` lists the individual dist modules of matching scenarios.
78-
`node size.mjs --json out.json` writes the results for the PR comment.
138+
`node size.mjs --json out.json` writes the results for the gate and the PR
139+
comment.
140+
141+
## CI
142+
143+
`.github/workflows/size.yml` runs three jobs. `head` builds the commit under
144+
test and measures it; `base` builds the base (above) and measures it with
145+
the head's harness (`SIZE_PACKAGES_ROOT`); the two run in parallel. `check`
146+
— the required status — waits for both, renders the summary and the PR
147+
comment (`report.mjs`), decides (`gate.mjs`) and checks the floor freeze
148+
(`check-floor-caps.mjs`). A base that cannot be built or measured leaves the
149+
caps absolute rather than blocking.
79150

80151
## Layout
81152

@@ -91,3 +162,17 @@ first). `SIZE_PACKAGES_ROOT=<checkout>` measures another checkout's built
91162
The retained-module-graph test in `packages/signals/tests/treeshake.test.ts`
92163
is the companion diagnostic that names the re-coupled module when shaking
93164
breaks.
165+
166+
## Ledger
167+
168+
- **2026-10-05 — minified allowance and ratchet.** The gate stopped failing
169+
on brotli alone: over the cap with ≤ 20 B minified growth over the base
170+
passes with a warning; caps stay brotli and are re-based downward per RC
171+
by `npm run ratchet`. Prompted by one day of noise: #3807 +63 B minified
172+
went +36 then +97 B brotli after `next` moved (a +61 B variant measured
173+
+3 / −54); #3814 +10 B minified went +50 / +56 B; #3811 +20 B minified
174+
went +55 / +89 B; #3817 reordered a condition for −20 B minified and
175+
moved one scenario −90 B brotli. The base measurement moved out of the informational
176+
`compare` job (which ran after `check`) into a parallel `base` job that
177+
`check` waits on, and pushes to `next` now compare against the previous
178+
commit instead of the absolute cap. No cap changed.

0 commit comments

Comments
 (0)