Skip to content

Commit b50ede7

Browse files
committed
refactor: move the type-surface check out of the runtime gate
Splits this pull request along the seam between the two issues it was serving. What remains is #765: does the built artifact still work. The type surface, which is #749, moves to the follow-up that also carries the API compatibility check, so it lands together with the thing that classifies it rather than ahead of it. The motivation is that the gate's `types` check answered "did anything change" and then asked a human to decide whether the change was breaking, via `gate:accept` and a committed digest. That decision is now made mechanically by the differ. Landing the acknowledgment here and deleting it days later would put code through `main` twice, and would discard review effort already spent on it. Removed: `checkTypes`, `typesDigest`, `diffLines`, `listTypeFiles`, `isReleaseCandidate`, `isMinorOrMajorBump`, the `types` field in `accepted.json`, and their tests. The acknowledgment survives for `size`, which has no automatic classifier: there is no principled way to decide that a bundle growing 4% was intended. One thing worth calling out, because a refactor could have reintroduced it silently. `checkSize` stayed quiet on a failed registry fetch and relied on `checkTypes` having already failed the run for the same reason. With `checkTypes` gone, that deferral would have turned a registry failure into a silent skip, which is exactly the fail-open this gate was fixed for earlier. `checkSize` now reports it itself, and a test pins it.
1 parent 3ac02bd commit b50ede7

4 files changed

Lines changed: 135 additions & 577 deletions

File tree

‎.github/workflows/test.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ jobs:
6363
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
6464
# Checks the packed tarball the publish job uploads verbatim, so this
6565
# verifies the exact bytes that ship. No `npm ci` needed: the gate uses
66-
# node builtins plus `tar`, and downloads the published release to compare
67-
# against with `npm pack reactfire@latest` (see release-gate/README.md).
66+
# node builtins plus `tar`, and downloads the release to compare against
67+
# with `npm pack` (see release-gate/README.md).
6868
- name: Release gate
6969
run: node scripts/release-gate.mjs reactfire-${{ github.run_id }}/reactfire.tgz
7070
verify-loads:

‎release-gate/README.md‎

Lines changed: 62 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -9,33 +9,39 @@ Implemented by [`scripts/release-gate.mjs`](../scripts/release-gate.mjs). It use
99
only node builtins plus `tar` and `npm pack`, so the CI job needs no `npm ci` and
1010
cannot itself be broken by a dependency change.
1111

12-
The `types` and `size` checks compare against the release currently on npm, which
13-
the gate downloads with `npm pack`. That is what
14-
[#749](https://github.com/FirebaseExtended/reactfire/issues/749) specifies, and
15-
it cannot drift: a copy checked into the repo goes stale the moment a release is
16-
published without refreshing it, and reactfire is published by hand. The bundle
17-
checks need no network and always run.
12+
This covers the **runtime** half of the release checks: does the built artifact
13+
still work. The **type** half, diffing the emitted `.d.ts` against the published
14+
release and applying semver to it, is
15+
[#749](https://github.com/FirebaseExtended/reactfire/issues/749) and is handled
16+
separately. It needs `typescript`, and keeping it out of this file is what lets
17+
the gate stay dependency-free.
18+
19+
The `size` check compares against the release currently on npm, which the gate
20+
downloads with `npm pack`. That cannot drift: a copy checked into the repo goes
21+
stale the moment a release is published without refreshing it, and reactfire is
22+
published by hand. The bundle checks need no network and always run.
1823

1924
### Which release it compares against
2025

2126
The newest published release **sharing the candidate's major** (`reactfire@^4`
2227
for a 4.x build), not the `latest` dist-tag.
2328

24-
Using `latest` breaks the entire v4 line the moment 5.0.0 takes that tag. Every
25-
v4 candidate then reads as a release that is not a bump, because a lower major
26-
can never register as one, so maintenance releases, minors, and even the stamped
27-
canary builds CI produces would all fail against a type surface from a different
28-
major line. That is every v4 pull request, not just release cuts.
29+
Using `latest` breaks the entire v4 line the moment 5.0.0 takes that tag. A 4.2.7
30+
compared against 5.0.0 is a different version but not an increase, because a
31+
lower major can never register as a bump, so maintenance releases, minors, and
32+
even the stamped canary builds CI produces would all be measured against an
33+
artifact from a different major line. That is every v4 pull request, not just
34+
release cuts.
2935

3036
Derived from the candidate rather than read from a per-branch dist-tag on
3137
purpose: a `v4` tag would have to be maintained correctly on every publish, and
3238
reactfire is published by hand, so it would drift. Same reasoning that ruled out
3339
a committed baseline.
3440

3541
When the candidate's major has nothing published yet (the `v5` line before 5.0.0
36-
ships), the gate falls back to `latest` and says so. Comparing a v5 build against
37-
the v4 surface is not meaningful, but it is better than skipping the checks
38-
outright, and the version rule still reads a major bump correctly.
42+
ships), the gate falls back to `latest` and says so. A v5 build measured against
43+
the v4 artifact is a weak comparison, but it is better than skipping the checks
44+
outright, and a genuine size regression still shows up against either baseline.
3945

4046
The ways that download can fail are treated differently, on purpose:
4147

@@ -69,13 +75,12 @@ are caught by this gate (verified by running it against the published 4.2.4 and
6975

7076
## Checks
7177

72-
| Check | What it catches |
73-
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
74-
| `no-cjs-in-esm` | A CJS module inlined into **any** ESM chunk, i.e. the #759 crash. Matches the bare `require` identifier, since the output is minified and the shipped 4.2.5 bundle never literally wrote `require(`. |
75-
| `externals` | Externals getting inlined (duplicate React instance, the shim regression) or new dependencies leaking out as runtime imports. |
76-
| `exports-map` | Any path in `exports` / `main` / `module` / `typings` missing from the tarball. |
77-
| `types` | Any change to the emitted `.d.ts` versus the published release, i.e. the #749 class. Covers added and removed declaration files as well as changed ones. On a release commit, also fails a changed type surface cut as a patch bump. |
78-
| `size` | Packed tarball and entry-point gzip size moving more than ±2% from the published release. |
78+
| Check | What it catches |
79+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80+
| `no-cjs-in-esm` | A CJS module inlined into **any** ESM chunk, i.e. the #759 crash. Matches the bare `require` identifier, since the output is minified and the shipped 4.2.5 bundle never literally wrote `require(`. |
81+
| `externals` | Externals getting inlined (duplicate React instance, the shim regression) or new dependencies leaking out as runtime imports. |
82+
| `exports-map` | Any path in `exports` / `main` / `module` / `typings` missing from the tarball. |
83+
| `size` | Packed tarball and entry-point gzip size moving more than ±2% from the published release. |
7984

8085
### What `size` is and is not
8186

@@ -119,74 +124,48 @@ The local pack stages from `git ls-files` plus `dist/`, not the working tree.
119124
untracked scratch work under `src/`. Staging keeps a local run comparable with
120125
what CI packs from a clean checkout.
121126

122-
## Accepting a change
127+
## Accepting a size change
123128

124-
A type or size change is not by itself a regression: adding a hook legitimately
125-
changes the type surface. What the gate refuses is a change nobody looked at. So
126-
when the change is intended:
129+
Size is the one check with no way to tell an intended change from a regression:
130+
there is no principled basis for deciding that a bundle growing 4% was meant. So
131+
when it was:
127132

128133
```sh
134+
npx tsc && npx vite build # accept measures the current build
129135
npm run gate:accept
130136
```
131137

132-
Then **commit `accepted.json` in the same pull request**. It records a digest of
133-
the type surface, the measured sizes, and the published version they were taken
134-
against:
138+
Then **commit `accepted.json` in the same pull request**:
135139

136140
```json
137141
{
138142
"against": "4.2.6",
139-
"types": "sha256:...",
140143
"size": { "packed": 130982, "sizes": { "dist/index.js": { "bytes": 0, "gzip": 16068 } } }
141144
}
142145
```
143146

144-
That file is the acknowledgement, and it is deliberately a fingerprint rather
145-
than a copy of every `.d.ts`. A checked-in copy would be a second type surface to
146-
maintain; a digest is a few lines, and reviewing the pull request that changes it
147-
means answering the question
148-
[#749](https://github.com/FirebaseExtended/reactfire/issues/749) is really about:
149-
150-
- Is this additive (a patch bump is fine), or non-additive (needs a minor or
151-
major bump plus a changelog note)?
152-
153-
Two properties make it hard to misuse. The digest covers the exact surface that
154-
was accepted, so editing the types afterwards invalidates it rather than riding
155-
along. And it is scoped to the published version it was taken against, so it
156-
expires on the next release instead of silently carrying forward.
157-
158-
At release time the gate also checks the bump itself: once `package.json` carries
159-
a different `major.minor.patch` from the published release, a changed type
160-
surface may not ship as a patch. During normal development the two match (the
161-
bump is its own commit, e.g. `7f93210` "4.2.6"), so there is nothing to assert
162-
and the rule stays quiet.
163-
164-
The comparison is on the numeric core, not the version string, because CI stamps
165-
an experimental version into `package.json` before packing
166-
(`4.2.6-exp.<sha>` while 4.2.6 is published). A string comparison read every
167-
pull-request build as a release candidate and then, since the core matched, as a
168-
patch bump, which would have failed the first pull request to legitimately change
169-
the type surface. For the same reason the recorded sizes are matched within the
170-
tolerance rather than byte-exactly: `gate:accept` runs locally, its numbers are
171-
compared against a CI build, and the stamp alone makes those differ.
172-
173-
Semantic additive/non-additive classification via api-extractor would remove the
174-
judgement call, but it is a much larger project and deliberately not attempted
175-
here.
147+
It is scoped to the published version it was taken against, so a new release
148+
expires it instead of letting it silently carry forward.
149+
150+
The recorded sizes are matched within the tolerance rather than byte-exactly.
151+
`gate:accept` runs locally, its numbers get compared against a CI build, and the
152+
two are never byte-identical: CI stamps an experimental version into the bundle
153+
before packing (`4.2.6-exp.<sha>`), which measured about +0.5% on the tarball.
154+
Exact matching would mean no acknowledgment ever applied in CI, so an intended
155+
size change could not be landed at all.
176156

177157
## Relationship to the test-suite type-check
178158

179159
`tsconfig.test.json` type-checks `test/` against the library's public types, and
180160
[#750](https://github.com/FirebaseExtended/reactfire/pull/750) added guards there
181-
naming the `ObservableStatus` regression directly. That is the better tool for
182-
the cases it covers, and it is not duplicated here.
161+
naming the `ObservableStatus` regression directly. That covers the type side from
162+
source, and nothing here duplicates it.
183163

184-
The two answer different questions. The test-suite check asserts that documented
185-
consumer usage still compiles, from source, for the patterns someone wrote a test
186-
for. This gate inventories the type surface **in the packed tarball**, whether or
187-
not a test exercises it. Both regressions that shipped were invisible to source-
188-
level checks: the artifact regressed while the source was fine. The remaining
189-
four checks have no test-suite equivalent at all.
164+
Neither reaches what these checks do. Both regressions that shipped were
165+
invisible to source-level checking, because the source was fine and only the
166+
emitted artifact regressed: a source type-check cannot see that the ESM bundle
167+
acquired a `require` call, and the test suite never loads the packed tarball at
168+
all. These four checks have no test-suite equivalent.
190169

191170
## Entry-point load test
192171

@@ -223,16 +202,20 @@ for is present in 4.2.5, the package just does not run.
223202

224203
## Not covered
225204

226-
Item 7 of [#765](https://github.com/FirebaseExtended/reactfire/issues/765) is not
227-
implemented:
205+
**Item 6 of [#765](https://github.com/FirebaseExtended/reactfire/issues/765),**
206+
the published `.d.ts` diff, which that issue notes is tracked in
207+
[#749](https://github.com/FirebaseExtended/reactfire/issues/749). It lands
208+
separately, with the check that classifies a type change as additive or
209+
breaking, so that the diff and its interpretation arrive together.
228210

229-
- **Runtime smoke render in CI** against a Next App Router and a Vite app,
230-
rendering a data hook against the packed build.
211+
**Item 7 of [#765](https://github.com/FirebaseExtended/reactfire/issues/765),**
212+
a runtime smoke render in CI against a Next App Router and a Vite app, rendering
213+
a data hook against the packed build.
231214

232-
Its original justification was being the only check that catches a runtime
233-
regression by observing it. The entry-load test above now does that for the
234-
#759 class, so item 7's remaining unique value is narrower: failures that appear
235-
only in a browser or bundler context and not on a Node import. Worth re-scoping
236-
against roughly a day of work plus permanent CI minutes and flake surface.
215+
Item 7's original justification was being the only check that catches a runtime
216+
regression by observing it. The entry-load test above now does that for the #759
217+
class, so its remaining unique value is narrower: failures that appear only in a
218+
browser or bundler context and not on a Node import. Worth re-scoping against
219+
roughly a day of work plus permanent CI minutes and flake surface.
237220

238-
Neither is required to close the two holes that actually shipped.
221+
Neither is required to close the runtime hole that actually shipped.

0 commit comments

Comments
 (0)