Skip to content

perf(cli): upgrade binds jscodeshift to each parser once per codemod - #11721

Merged
josephfarina merged 3 commits into
mainfrom
speed/codemod-parser-once
Nov 14, 2026
Merged

josephfarina merged 3 commits into
mainfrom
speed/codemod-parser-once

Conversation

@josephfarina

@josephfarina josephfarina commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Maintainer impact

upgrade spends a large share of a run building copies of jscodeshift. For every file a code codemod reads, the runner called jscodeshift.withParser(parser), which builds a new copy of jscodeshift's helpers (its builders, node types and template tags). Every copy is alike. Over a 239-file Next.js app, that copying (jscodeshift's enrichCore) takes about 150 ms of each upgrade run.

Intended invariant

Every upgrade run prints the same output and leaves the same files: each file's transform gets a jscodeshift bound to the file's parser, as before.

Change

  • assets/codemods/run-codemod.mjs: runCodeCodemod binds each parser it needs (tsx or babel) once per run and gives every file of that parser the same jscodeshift. Each file's transform still gets its own parse-error marker around it (markingSourceParseErrors), which wraps the shared jscodeshift without changing it.

Declared difference

None in output or in the files upgrade writes.

Evidence

Wall time, warm, a fresh process per call, base and change interleaved, n=11, median of the paired difference (95% CI):

  • upgrade --from 0.6.8 --path app --json over a 239-file Next.js app: 1,844 → 1,701 ms, −154 ms [−172, −133], −7.7%
  • the same in text output: 1,847 → 1,700 ms, −152 ms [−176, −138], −7.9%
  • upgrade --from 0.6.8 --path lib --json over the app's 35-file lib: 1,520 → 1,291 ms, −237 ms [−252, −215], −15%
  • upgrade --list --json (control, scans nothing): +0.5%, CI spans 0

Identity: every run above prints the same stdout and stderr and exits the same. A replay of 40 upgrade argument forms (every mix of --from 0.1.5 to 0.7.5, --path app, src, tests, lib and ., --apply, --json, --list, --help), each run on a fresh copy of the app, 20 page templates, a lib and a tests folder, in a Core-only project and in one with a large TypeScript integration: 80 of 80 runs print the same stdout and stderr, exit the same, and leave the same files (28 of them change files).

Scope

Components: CLI upgrade codemod runner

  • No intended public API, product behavior, visual direction, or policy change.
  • Product changes discovered during the work were removed or split.
  • Public text and artifacts contain no internal Meta context.

Testing

  • New assets/codemods/run-codemod.test.mjs: a run over five files of two parsers binds each parser once (it fails on the old code, which binds once per file), and it writes the same files and names the same changed files as one run per file, each of which binds a fresh jscodeshift.
  • The assets/codemods, api/upgrade and upgrade command suites pass (109 files, 1,288 tests).
  • Full CLI suite on Node 24.22.1 at the first revision: 817 files pass, 1 skipped. The second revision changes only the new test.
  • check:changesets and Prettier pass.

runCodeCodemod called `jscodeshift.withParser(parser)` for every file it
read. Each call builds a new copy of jscodeshift's helpers (its builders,
node types and template tags), and every copy is alike, so a run over a
large app spent its time building copies. A run now binds each parser it
needs once and hands every file of that parser the same jscodeshift.
Each file's transform still gets its own parse-error marker around it.
@vercel

vercel Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 14, 2026 11:42am UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 14, 2026
@astracat-bot

astracat-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 14, 2026, 11:47 AM UTC

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes for one test claim; the parser cache itself checks out.

  • run-codemod.test.mjs:91-94 and the description's Testing section say the test matches a run that binds a fresh jscodeshift for every file, but that reference run goes through the same runCodeCodemod cache and binds once per parser (2 binds for the 5 files), so the assertion compares the change with itself: build the reference from one runCodeCodemod call per file and compare the written files, or drop the assertion, its comment and the sentence.

The existing codemod and upgrade suites pass on this head, the new call-count assertion fails on main as described, and a true per-file run of the test's fixture writes the same files as the shared run.

Claims and files checked
  • Claim: each per-file withParser call built a new, identical copy of jscodeshift's helpers. Verified: jscodeshift's withParser rebuilds builders, types, templates, filters and mappings on every call.
  • Claim: about 150 ms saved per upgrade of a 239-file app. Consistent, not reproduced: one bind costs about 0.1 ms, and the 0.6.8 range runs about seven code codemods over every file.
  • Claim: runCodeCodemod binds each parser once per run and hands every file of that parser the same jscodeshift. Verified: run-codemod.mjs:490-515.
  • Claim: each file still gets its own parse-error marker that wraps the shared jscodeshift without changing it. Verified: run-codemod.mjs:525; the wrapper only traps calls.
  • Claim: output and written files do not change. Verified: the codemod and upgrade suites pass, and a per-file run of the fixture writes the same bytes.
  • Claim: the timing table and the 80-run identity replay. Not rerun: the measured app is not in the repository.
  • Claim: no public API, product behavior or policy change. Verified: no export, command, option or default changes.
  • Claim: the new test binds each parser once and fails on the old code. Verified: it fails on main with 5 binds and passes here with 2.
  • Claim: the new test gives the same result as a run that binds a fresh jscodeshift for every file. False: the reference run binds once per parser.
  • Claim: the assets/codemods, api/upgrade and upgrade suites pass (109 files, 1,288 tests). Verified: same counts.
  • Claim: check:changesets and Prettier pass. Verified.
  • Changeset: once per codemod instead of once per file, about 150 ms faster on a 240-file app, output unchanged. Verified, with the file count rounded from the 239-file measurement.
  • File packages/cli/assets/codemods/run-codemod.mjs: clear.
  • File packages/cli/assets/codemods/run-codemod.test.mjs: the finding above.
  • File .changeset/codemod-parser-once.md: clear.
  • File scripts/vitest-node-durations.json: clear.

Automated review (maintainer link)

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

🔎 Preview · 4db07eb

Storybook · Sandbox · built from this PR's head

Current run: The current CI run concluded cancelled. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet. The CI workflow found no room under the CI ceiling and its required checks were cancelled, so re-run it to get their results; Lint, CLI Smoke Test and Codemod Verify passed.

The test now compares the shared-parser run with one runCodeCodemod call per file, each of which binds a fresh jscodeshift, so the earlier test finding is fixed. The bind-count assertion fails on main (5 binds) and passes here (2), and the existing codemod and upgrade suites pass.

Claims and files checked
  • Claim: each per-file withParser call built a new, identical copy of jscodeshift's helpers. Verified: jscodeshift's withParser builds a new core and copies builders, types, templates, filters and mappings onto it on every call.
  • Claim: that copying costs about 150 ms of each upgrade run on a 239-file app. Consistent, not reproduced: one bind costs 0.1–0.3 ms, and the measured app is not in the repository.
  • Claim: every file's transform still gets a jscodeshift bound to that file's parser. Verified: run-codemod.mjs:514-515.
  • Claim: runCodeCodemod binds each parser once per run and shares it across that parser's files. Verified: run-codemod.mjs:490-515; 2 binds for the five-file fixture.
  • Claim: each file keeps its own parse-error marker, which wraps the shared jscodeshift without changing it. Verified: run-codemod.mjs:525; the wrapper only traps calls.
  • Claim: no difference in output or in the files upgrade writes. Verified: the codemod and upgrade suites pass, and the shared run writes the same bytes as per-file runs.
  • Claim: the timing table and the 80-run identity replay. Not rerun: the measured app is not in the repository.
  • Claim: no public API, product behaviour or policy change, and no internal context. Verified: no export, command, option or default changes, and the added text is clean.
  • Claim: the new test binds each parser once and fails on the old code. Verified: it fails on main with 5 binds and passes here with 2.
  • Claim: the new test writes the same files and names the same changed files as one run per file, each binding afresh. Verified: the reference makes one runCodeCodemod call per file (5 binds) and both assertions pass.
  • Claim: the codemod, api/upgrade and upgrade command suites pass (109 files, 1,288 tests). Verified: same counts on this head.
  • Claim: the full CLI suite passed at the first revision, and the second revision changes only the new test. The first part is not rerun; the second is verified.
  • Claim: check:changesets and Prettier pass. Verified.
  • Changeset: upgrade binds once per parser per codemod instead of once per file. Verified.
  • Changeset: about 150 ms faster on a 240-file app. Consistent with the description's 239-file measurement, not reproduced.
  • Changeset: output does not change. Verified.
  • File .changeset/codemod-parser-once.md: clear.
  • File packages/cli/assets/codemods/run-codemod.mjs: clear.
  • File packages/cli/assets/codemods/run-codemod.test.mjs: clear; the earlier test finding is fixed.
  • File scripts/vitest-node-durations.json: clear.

Automated review (maintainer link)

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet. The CI workflow found no room under the CI ceiling and its required checks were cancelled, so re-run it to get their results; Lint, CLI Smoke Test and Codemod Verify passed.

This revision only merges main with no conflict, so the parser cache and its test are unchanged since the last review. The new test still fails against the base runner (5 binds) and passes here (2), and the codemod and upgrade suites pass.

Claims and files checked
  • Claim: each per-file withParser call built a new, identical copy of jscodeshift's helpers. Verified: jscodeshift's withParser copies builders, types, templates, filters and mappings onto a new function on every call.
  • Claim: that copying costs about 150 ms of each upgrade run on a 239-file app. Consistent, not reproduced: one warm bind costs about 0.09 ms and --from 0.6.8 runs eight Core code codemods per file; the measured app is not in the repository.
  • Claim: every file's transform still gets a jscodeshift bound to that file's parser. Verified: run-codemod.mjs:514-515.
  • Claim: runCodeCodemod binds each parser once per run and shares it across that parser's files. Verified: run-codemod.mjs:490-502; 2 binds for the five-file fixture.
  • Claim: each file keeps its own parse-error marker, which wraps the shared jscodeshift without changing it. Verified: run-codemod.mjs:525; the wrapper only traps calls.
  • Claim: no difference in output or in the files upgrade writes. Verified: the shared run writes the same bytes as one-file runs, and the codemod and upgrade suites pass.
  • Claim: the timing table and the 80-run identity replay. Not rerun: the measured app is not in the repository.
  • Claim: no public API, product behaviour or policy change, and no internal context. Verified: no export, command, option or default changes, and the added text is clean.
  • Claim: the new test binds each parser once and fails on the old code. Verified: it fails on the base runner with 5 binds and passes here with 2.
  • Claim: the new test writes the same files and names the same changed files as one run per file, each binding afresh. Verified: run-codemod.test.mjs:123-133.
  • Claim: the codemod, api/upgrade and upgrade command suites pass (109 files, 1,288 tests). Verified: same counts on this head.
  • Claim: the full CLI suite passed at the first revision, and the second revision changes only the new test. The first part is not rerun; the second is verified.
  • Claim: check:changesets and Prettier pass. Verified.
  • Changeset: upgrade binds once per parser per codemod instead of once per file. Verified.
  • Changeset: about 150 ms faster on a 240-file app. Consistent with the description's 239-file measurement, not reproduced.
  • Changeset: output does not change. Verified.
  • File .changeset/codemod-parser-once.md: clear.
  • File packages/cli/assets/codemods/run-codemod.mjs: clear.
  • File packages/cli/assets/codemods/run-codemod.test.mjs: clear.
  • File scripts/vitest-node-durations.json: clear.

Automated review (maintainer link)

@josephfarina
josephfarina merged commit 6fe368b into main Nov 14, 2026
128 of 134 checks passed
@github-actions
github-actions Bot deleted the speed/codemod-parser-once branch November 15, 2026 06:03

This branch was successfully deployed

1 active deployment
Preview — 4db07eb8 Deployed Nov 14, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant