Codemods skill for Claude Code

# Codemod recipes

Working starting points for each tool. Run every recipe on a fixture first, then on one
directory, then everywhere.

## ast-grep: one-off rewrite

```bash
ast-grep run -l ts -p 'console.log($$$ARGS)' -r 'logger.debug($$$ARGS)' src            # preview diff
ast-grep run -l ts -p 'console.log($$$ARGS)' -r 'logger.debug($$$ARGS)' src --update-all  # apply
ast-grep run -l ts -p 'console.log($$$ARGS)' -r 'logger.debug($$$ARGS)' src --interactive # per match
```

Install: `npm i -g @ast-grep/cli` (binary `ast-grep`; `sg` alias on some installs) or
`brew install ast-grep`.

## ast-grep: rule file with constraints

`rules/prefer-object-hasown.yml`:

```yaml
id: prefer-object-hasown
language: TypeScript
rule:
  pattern: $OBJ.hasOwnProperty($KEY)
  not:
    inside:
      kind: call_expression
      pattern: Object.prototype.hasOwnProperty.call($$$)
fix: Object.hasOwn($OBJ, $KEY)
message: Use Object.hasOwn instead of obj.hasOwnProperty
severity: warning
```

```bash
ast-grep scan -r rules/prefer-object-hasown.yml src               # report + diff preview
ast-grep scan -r rules/prefer-object-hasown.yml src --update-all  # apply
```

Metavariables: `$X` one node, `$$$` zero or more nodes, `$_` match without capturing.
Metavariables do not match inside string literal contents; for strings use `regex:` on a
captured node with `constraints`. Keep the rule in the repo afterwards as a lint rule to
stop the old pattern returning (`ast-grep scan` in CI with an `sgconfig.yml`).

## jscodeshift: rename an import and its call sites

`codemods/rename-fetch-user.js`:

```js
// fetchUser -> getUser for imports from "@/api"; aliased imports keep their local name.
module.exports = function transform(file, api) {
  const j = api.jscodeshift;
  const root = j(file.source);
  let changed = false;
  let renameCalls = false;

  root
    .find(j.ImportDeclaration, { source: { value: "@/api" } })
    .find(j.ImportSpecifier, { imported: { name: "fetchUser" } })
    .forEach((path) => {
      const aliased = path.node.local && path.node.local.name !== "fetchUser";
      path.node.imported = j.identifier("getUser");
      if (!aliased) {
        path.node.local = j.identifier("getUser");
        renameCalls = true;
      }
      changed = true;
    });

  if (renameCalls) {
    root
      .find(j.CallExpression, { callee: { type: "Identifier", name: "fetchUser" } })
      .forEach((path) => {
        path.node.callee = j.identifier("getUser");
      });
  }

  return changed ? root.toSource({ quote: "double" }) : undefined; // undefined = skip file
};
```

```bash
npx jscodeshift -t codemods/rename-fetch-user.js --parser=tsx --extensions=ts,tsx --dry --print src/one-file.ts
npx jscodeshift -t codemods/rename-fetch-user.js --parser=tsx --extensions=ts,tsx src
```

Notes: `--parser=tsx` handles both TS and TSX; returning `undefined` reports the file as
skipped; recast preserves untouched formatting but run the project formatter afterwards.
Write fixture tests with `jscodeshift/dist/testUtils` (`defineInlineTest`) for anything
beyond a trivial rename.

## Python: LibCST (format-preserving)

```python
# codemods/rename_call.py  -- python3 -m pip install libcst
import sys, pathlib, libcst as cst

class Rename(cst.CSTTransformer):
    def leave_Call(self, orig, updated):
        f = updated.func
        if isinstance(f, cst.Attribute) and f.attr.value == "fetch_user" \
           and isinstance(f.value, cst.Name) and f.value.value == "api":
            return updated.with_changes(func=f.with_changes(attr=cst.Name("get_user")))
        return updated

for path in map(pathlib.Path, sys.argv[1:]):
    src = path.read_text()
    out = cst.parse_module(src).visit(Rename()).code
    if out != src:
        path.write_text(out); print("changed", path)
```

`python3 codemods/rename_call.py $(git ls-files '*.py')`. For simple Python renames,
`ast-grep -l py` is often enough.

## OpenRewrite (Java/Kotlin, Maven or Gradle)

Run a published recipe without changing the build file (Maven):

```bash
mvn -U org.openrewrite.maven:rewrite-maven-plugin:dryRun \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3
# review target/rewrite/rewrite.patch, then:
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3
```

Custom declarative recipe in `rewrite.yml` at the project root:

```yaml
type: specs.openrewrite.org/v1beta/recipe
name: com.acme.RenameLegacyClient
displayName: Rename LegacyClient to HttpClient
recipeList:
  - org.openrewrite.java.ChangeType:
      oldFullyQualifiedTypeName: com.acme.net.LegacyClient
      newFullyQualifiedTypeName: com.acme.net.HttpClient
  - org.openrewrite.java.ChangeMethodName:
      methodPattern: com.acme.net.HttpClient send(..)
      newMethodName: execute
```

Activate with `-Drewrite.activeRecipes=com.acme.RenameLegacyClient`. Gradle uses the
`org.openrewrite.rewrite` plugin with `rewriteDryRun` / `rewriteRun` tasks. Check recipe
names in the OpenRewrite recipe catalog for your target versions.

## comby (any language, structural-ish)

```bash
comby 'assertEquals(:[expected], :[actual])' 'assertThat(:[actual]).isEqualTo(:[expected])' .java -d src/test   # preview diff
comby 'assertEquals(:[expected], :[actual])' 'assertThat(:[actual]).isEqualTo(:[expected])' .java -d src/test -i  # in place
```

`:[hole]` matches balanced text including nested parentheses; good for languages without
an ast-grep grammar, or templates. It is not type-aware; review matches carefully.

## Official codemods first

Before writing your own for a framework upgrade, check for maintained ones:
`npx @next/codemod`, `npx codemod react/19/...` (codemod.com registry),
`npx storybook automigrate`, `ng update` (Angular schematics), `pyupgrade`,
`django-upgrade`, `ruff check --fix` with `UP` rules, `go fix`, `cargo fix --edition`,
`dotnet upgrade-assistant`. Use them, then hand-fix the remainder.