Codemod — refactor at scale

50+ call sites of the same change is a codemod, not 50 manual edits.

Tools

Process

1. Define the transform — write or find a codemod. Express as: "for every <pattern>, replace with <replacement>".
2. Dry run on a few files — verify the transform does what you expect.
3. Dry run on the whole codebase — generates a diff but doesn't write.
4. Review the diff — visual review of the proposed changes. Look for false positives.
5. Apply — run with --write. Commit the diff with a "codemod:" prefix.
6. Verify — tests + typecheck + lint pass.
7. Open the PR — descriptive title + body explaining the codemod source.

Example: jscodeshift for a React API rename

// codemods/rename-useLayoutEffect.js
module.exports = function(fileInfo, api) {
  const j = api.jscodeshift;
  return j(fileInfo.source)
    .find(j.CallExpression, { callee: { name: 'useLayoutEffect' } })
    .replaceWith(p => j.callExpression(j.identifier('useInsertionEffect'), p.value.arguments))
    .toSource();
};

Run:

npx jscodeshift -t codemods/rename-useLayoutEffect.js src/ --dry --print  # preview
npx jscodeshift -t codemods/rename-useLayoutEffect.js src/                  # apply

Example: ts-morph for type-aware rename

// codemods/rename-method.ts
import { Project } from "ts-morph";
const project = new Project({ tsConfigFilePath: "tsconfig.json" });
project.getSourceFiles().forEach(sf => {
  sf.forEachDescendant(node => {
    if (node.getKindName() === 'MethodDeclaration' && node.getName() === 'oldName') {
      node.rename('newName');  // type-aware; updates all call sites
    }
  });
});
project.save();

Example: comby (language-agnostic)

# Rename all `foo(:[args])` to `bar(:[args])` across all .ts files
comby 'foo(:[args])' 'bar(:[args])' -d src -extensions ts -in-place

Hard rules

• Dry run before write. Always preview the diff.
• One transform per PR. Don't combine codemods with feature work.
• Verify with tests + typecheck. A codemod that breaks the type checker is a codemod that introduced a bug.
• Save the codemod script in codemods/ for future re-runs and as historical record.
• Document false positives in the PR description if you had to skip files.

Integration with /upgrade

When /upgrade <pkg> --major is invoked, this skill is the first call:

1. Read the upgrade guide
2. Find or write the matching codemods
3. Dry-run → review → apply per codemod
4. Then run the test suite + ship

References

• jscodeshift: https://github.com/facebook/jscodeshift
• ts-morph: https://ts-morph.com/
• comby: https://comby.dev/
• bowler: https://pybowler.io/
• ast-grep: https://ast-grep.github.io/
• React codemod registry: https://github.com/reactjs/react-codemod