codemod agent rewrote the same file 3 times - the jscodeshift transform wasnt idempotent and kept re-matching its own...

TL;DR: Guard the transform so it skips nodes it has already converted. Before rewriting a node, check whether the output shape is already present - if the code already looks converted, return the node unchanged. An idempotent transform is a no-op on its own output, which makes re-runs, retries, and agent resume-after-crash all safe.

codemod agent rewrote the same file 3 times - the jscodeshift transform wasnt idempotent and kept re-matching its own output

1. Reproduce the double-apply on one file: run the transform on an already-converted file and diff before against after.

Expected: the diff is non-empty - it shows exactly what the transform changes on its own output.

1. Add a skip guard at the top of the visitor: if the node already has the converted shape (the new import already exists, the wrapper is already applied), return the node unchanged.

Expected: re-running on the converted file now produces an empty diff.

1. Tighten the matcher so it cannot match its own output: match only the old API name, never the new one the transform creates.

Expected: a codebase-wide second run reports zero changed files.

1. Verify idempotency on the full repo: run the transform twice over everything and diff the second run's output against the first.

Expected: the second run changes nothing.

1. For the agent loop: after each transform pass, record a checksum of changed files and skip files whose checksum matches the post-transform state on resume.

Expected: a crashed-and-resumed run never re-processes finished files.

Use this when

• a jscodeshift transform changes files every time it runs, including on its own output
• an agent re-runs a codemod after a crash and gets double-wrapped or double-renamed code
• the same file appears in the changed list on every pass with no real progress

Not for this skill when

• the transform crashes or throws - that is a bug in the visitor, not idempotency
• the transform is intentionally run once and deleted - though idempotency is still good practice
• the problem is the parser choking on syntax, not repeated rewrites

Variant phrasings

• jscodeshift transform not idempotent, re-matches own output
• codemod double-applies changes on second run
• transform keeps rewriting already-converted files

Why it happens

A jscodeshift visitor matches patterns in the AST and rewrites them. If the rewrite produces code that still matches the visitor's pattern - a wrapper around a node the matcher also accepts, a renamed import the rename rule still matches - then every run converts the output of the previous run. The agent re-running the codemod (retry, resume, or just caution) amplifies a transform bug into triple-wrapped code.

Edge cases

• Skip guards based on exact string matching can miss semantically identical variants - match on AST shape, not source text.
• A guard that is too broad skips files that genuinely need conversion (for example, skipping every file containing the new import, even ones that also use the old API). Guard per node, not per file, where possible.
• If the transform already ran 3 times on the repo, fix the triple-applied files first (revert from version control or write an unwrap transform) before making it idempotent.
• Test the transform on a fixture that is already fully converted - most codemod test suites only test the unconverted input.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Sihtxn9Gv5uKXwTEDwGQ