Codemod

A codemod is a program that transforms source code across a whole codebase mechanically — automated refactoring, API migrations, framework upgrades, large-scale “change all the call sites” work. The defining property: it operates on the code’s structure (AST/LST), not its text, so the transformation is deterministic and total — every match rewrites identically, nothing is left half-migrated, and the output is reviewable as a diff.

The tool landscape

• OpenRewrite (Java/JVM) — LST-based recipes; the enterprise standard. The vault’s canonical case: Uber’s JUnit 4→5 migration — 75,000+ test classes, 1.25M lines, 5,000+ diffs in 4 months, with the postmortem’s load-bearing finding: “a deterministic approach proved more practical than an AI-driven migration” (AI confined to debugging failures — seeds/Software engineering in AI era.md).
• jscodeshift (JS/TS, Meta) — the established framework; wraps codemods as testable transforms with dry-run stats. Heavily used for React/framework API migrations.
• ast-grep — structural search and rewrite; YAML-configurable patterns. More a primitive than a framework — the “grep for ASTs” you compose pipelines from.
• GritQL (Grit) — its own query/transformation language for structural matching and rewriting, “somewhere between regex and AST tools”; runs at repo scale.
• Comby — structural matching/rewrite tuned for multi-language generality (works on many grammars without per-language setup).
• Codemod.com — the platform built explicitly around code migrations/refactors/multi-step transformations; first-class ast-grep integration.
• codemod-pilot (newer) — the example-driven pole: give before → after pairs, it infers a structural transformation, previews the diff, applies across the codebase.

The design axis underneath: query/rewrite as code (OpenRewrite recipes, jscodeshift transforms — write logic in a real language) vs query/rewrite as pattern (ast-grep YAML, GritQL, Comby templates — declare the shape) vs query/rewrite as example (codemod-pilot — show the shape). Example-driven is the newest and the most LLM-adjacent: inferring the rule from instances is exactly what models are good at.

Why the category matters now

• The AI division of labor made it explicit: the Uber case is the proof — models couldn’t do the bulk migration reliably, but a deterministic codemod did, with AI assisting at the edges. Codemods are the deterministic core of the Fearless refactoring / Varick “decompose until most steps are deterministic” pattern.
• Verifiability: a codemod’s output is a diff reviewable line-by-line and re-runnable to fix-forward — the property LLM rewrites lack (each regeneration is a fresh roll of the dice). SlopCodeBench’s finding (incremental requirement changes collapse model scores) is the same observation from the eval side: whole-problem solve is not the same skill as total, consistent transformation.
• Migration is the workflow: framework upgraders (React codemods, Next.js codemods), lint-rule autofixes, and API deprecation waves are all codemods in production. The “before → after, now migrate everything” UX is a recognized product category.
• LLM-era synthesis: agents + codemods compose — the agent writes the codemod (AST manipulation is exactly the structured-output regime models handle), the codemod does the sweep. Determinism where it counts, generation where it helps.

Vault kin

• Software engineering in AI era — the Uber/OpenRewrite canon; deterministic-core/AI-assist
• Fearless refactoring — codemods as the mechanical tooling half of the solved technical problem
• Code Mode — same shape one level up: deterministic programs written by the model for tasks prompts can’t do directly
• The COT Ansible roles rewrite — spec-first mechanical transforms, humans on the seams; the codemod philosophy without the AST tooling
• nixzer (OSS) — the exotic pole: a codemod whose “AST” is the syscall trace (run it, observe, generate Nix); observation-based migration from the Dozer paper.