chore: upgrade Node 14 -> 20 (toolchain, published packages, executables)

[aryanku-dev]

Draft. Three things are unfinished — see Before this can leave draft.

Moves all three "Node versions" this repo conflates — the toolchain, the floor the published packages declare, and the runtime pkg compiles into the standalone executables — from 14 to 20.19.5.

Node 14 went EOL in April 2023. The pin has already distorted the codebase: image-size was frozen on a vulnerable line to keep Node 14 support (#2301, now resolved by #2382), and the whole snyk-backed IntelliStory lockfile path carries istanbul ignore pragmas whose stated reason is "CI runs the suite on Node 14".

Why this isn't a version-string bump

1. The test harness could not run on Node 20. scripts/loader.js implemented getFormat/getSource/transformSource — removed in Node 16.12.0 — and needed hooks to run in the main thread so it could read global.__MOCK_IMPORTS__ and the memfs volume at fs.$vol. Node 18.19/20 moved module hooks to a dedicated worker.

2. vercel/pkg cannot build a Node 20 binary. Archived at 5.8.1; fails with No available node version satisfies 'node20'.

3. A latent bug that ships the wrong architecture. pkg ran with no --targets, so output arch follows the host. The only thing keeping the binaries x64 was one architecture: x64 line on an arm64 runner — delete it, or let GitHub change the image, and every x64 customer silently gets an arm64 binary while --version passes on the arm64 runner that built it.

The dangerous part: the coverage gate stops existing

Measured on Node 18.20.8 (same hooks architecture as 20), before this change:

$ yarn workspace @percy/logger test:coverage
Executed 150 of 150 specs SUCCESS
All files | 0 | 0 | 0 | 0
EXIT CODE = 0

The removed hooks are ignored with a warning, not an error, so execution is unaffected — the src is already valid modern ESM and Node runs it natively. But .nycrc sets instrument: false, so nyc relies entirely on babel-plugin-istanbul inside the removed hook. Coverage silently goes to zero, and nyc report --check-coverage passes on an empty coverage map because there are no files to check.

Only mock-heavy suites go red. Fix those, see green everywhere with test:coverage succeeding, and the 100% gate has been switched off for every future PR. A half-finished migration's failure mode is success. Exit code is not evidence here — assert the coverage map has content.

This also means the existing test-node20 job (added by PPLT-5844) has been enforcing nothing since it landed.

Verified on real Node 20.19.5

yarn lint clean. yarn build succeeds across 18 projects with the new Babel target.

Suite	Result
logger · config · env · cli · cli-command	150 · 82 · 123 · 27 · 189 — all pass
cli-config · cli-build · cli-snapshot · cli-upload	22 · 84 · 28 · 13 — all pass
monitoring · webdriver-utils	40 · 238 — pass
client	288 / 288 pass, 100% coverage
core · sdk-utils	see Still failing below

Correction to an earlier revision of this description. It claimed the core/sdk-utils/client failures were pre-existing and not regressions, based on a control worktree that reproduced them at master. That control was on a developer laptop, where those suites fail for local environment reasons — it does not transfer to CI, and master's Windows run at f86a18de (the commit this branches from) is green. The claim was wrong and is retracted.

What a clean control does show, run at master with the original loader on Node 20: @percy/sdk-utils cannot even load — ReferenceError: __dirname is not defined in ES module scope, because Node 20 reparses its CJS-typed test files as ESM once the dead Babel transform stops running. This branch takes it from crash-at-load to 169 specs executing.

A fourth bug was only findable on real Node 20: cli-command passed 189/189 on Node 18 but failed 14 on Node 20 with identical code. Node 20 reports packages/sdk-utils/src/index.js as format: module despite its package having no "type": "module" — while babel.config.cjs keys off that same missing field and compiles it to CommonJS. Node then parsed CommonJS output as an ES module and every export vanished. load() now declares the format Babel actually emitted.

Still failing

• @percy/sdk-utils — 8 of 169. Suite-internal, not the mechanism: driven through percy exec --testing, the /test/api control plane works correctly when exercised by hand (healthcheck 200, /test/requests accurate, the error directive honoured). The failures cluster on directives not taking effect plus a log level/namespace mismatch ([percy:test] Some error where [percy] Some error is expected), which points at state leaking between specs. Needs dedicated debugging.
• semgrep/ci — 7 blocking findings across 5 files. Not yet confirmed: semgrep reports to its cloud app rather than the job log. Strong hypothesis — .semgrepignore has no entry for scripts/, and the new loader files contain 15 path.join/resolve/readFileSync calls, i.e. the path-join-resolve-traversal rule every comparable file here is already suppressed for.
• Build & verify executable. pkg has still not been run locally, so the output filenames under explicit --targets remain unverified and the rename block matches by prefix as a guess. Note executable.sh mutates the tree (gsed -i over every package.json), so it needs a throwaway worktree rather than this one.

Fixed since the first CI run

• @percy/client — 1 failing → 288 of 288, 100% coverage. Root cause was a real regression, not a test nit: Node 20's AggregateError carries .code but an empty .message, and both client/src/proxy.js and sdk-utils/src/proxy.js classify proxy failures with err.message.includes('ECONNREFUSED'). flattenAggregateError() restores the message Node used to produce.
• @percy/cli-command (both jobs) — 99.75% → 189 of 189, 100% coverage. intelliStory.js's parser-unavailable bail was only ever covered because Node 14 couldn't install the snyk parser. Marked ignored with the reason stated, because forcing it needs a refactor (module-scope _snykModule cache + static import), not a spec.
• @percy/core's /ECONNREFUSED/ spec — fixed at source by the same message fix, with no assertion weakened.
• fail-fast: false on the ubuntu matrix — one red package was cancelling the other 16, which made a 7-failure run render as 21.
• Karma/browser — Test @percy/dom passes; and since rollup.config.js:56 was deliberately left at node: '14', there is no browser-output change to validate.

Open decisions

• rollup.config.js:56 — the third hardcoded node: '14', compiling the browser bundles. Left untouched on purpose; changing it alters code injected into customer pages.
• Add a permanent CI assertion that the coverage map is non-empty, so the gate can never silently go vacuous again.

Merge order

#2382 must merge first. Both touch packages/cli-upload/package.json; the engines sweep here rewrites it wholesale and would clobber the image-size removal.

Known breaking changes

• engines: >=20 across all 18 packages — EBADENGINE on older Node, hard fail under engine-strict. Should ship as a major.
• dist/ compiled for Node 20 — syntax errors below it. The bin/run.cjs guard turns that into a readable message for CLI users, but not for SDKs importing @percy/core directly.
• percy-linux.zip now requires glibc ≥2.28 — drops CentOS 7, RHEL 7, Amazon Linux 2, Ubuntu 18.04.
• Startup-failure exit code 0 → 1.

Also worth flagging: Node 20 reached EOL on 30 April 2026. This improves the posture substantially over Node 14 (three years of CVEs, plus OpenSSL 3 instead of an EOL 1.1.1) but will not clear a scanner rule that flags unsupported majors. Treat it as a known-temporary landing spot and schedule 22/24.

🤖 Generated with Claude Code