Review the transform, not every output line. Read the script or recipe, check a stratified sample of changed files, verify invariants with tests and type checks, and confirm the codemod is idempotent. Keep hand edits in separate commits so reviewers can skim the mechanical part and focus on judgment calls.
Why line by line review fails
A diff of a thousand files invites two bad outcomes: approving without reading, or a reviewer burning a day and still missing something. Both happen because the diff mixes one idea repeated many times with the few places where the idea went wrong.
Tools in this space tend to describe themselves the same way. The jscodeshift project says its runner executes a transform for each file and reports how many files were or were not transformed. OpenRewrite describes recipes that run prepackaged refactorings. In both, the unit of review is the rule, and the output is evidence about the rule.
A review recipe
- Read the rule. What pattern does it match, and what does it produce? Look for patterns broader than the description says.
- Find the exceptions. Check the summary of files skipped or unchanged. Skipped files are where the rule did not apply, and often where the hard cases live.
- Sample by group. Group changed files by directory or type and read a few from each group, not only the first ones in the diff.
- Search the diff for outliers. Use a diff stat and sort by lines changed. A file with ten times the usual change is worth reading.
- Run the checks. Type checks, linters and the test suite. A codemod that compiles but changes behavior is the dangerous case, so look hardest at tests for those areas.
- Run it again. A second run of the transform on the result should produce no changes. If it does, the rule is not stable.
- Check what it did not touch. Search the codebase for the old pattern. Leftovers need manual work, and you want the list.
Split commits for readability
| Commit | Content | Review effort |
|---|---|---|
| 1 | Codemod output only | Skim, sample, check invariants |
| 2 | Manual fixes for leftovers | Read carefully |
| 3 | Config, build and dependency changes | Read carefully |
| 4 | New tests | Read carefully |
Say in the pull request description which command produced commit one, with its version, so anyone can reproduce it. A reviewer who can regenerate the commit can trust it far more than one who has to guess.
Security specific checks
Give extra attention to hunks that touch authentication, authorization checks, input validation, escaping, cryptographic calls and file paths. A transform that rewrites a call pattern might drop an argument that happened to be a safety flag. Search the diff for removed lines containing words like verify, escape, sanitize, secure and permission, and read each one.
Also treat the codemod itself as a dependency. Pin its version and prefer one maintained by the framework authors or a project you already trust.
What to do when the rule is wrong
Do not hand edit hundreds of files. Fix the rule, regenerate, and review again. Hand edits on top of a flawed transform make the next run impossible to reproduce.
Quick check
How many files should I sample?
Enough to cover each directory or file type at least once, plus the largest changes.
Is a passing test suite enough to approve?
Only if the suite covers the areas touched. Check coverage for the changed paths first.
Safeguard fix pull requests are off by default with every category on Manual, so each proposed change goes to a human reviewer. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
