codemod agent rewrote the same file 3 times - the jscodeshift transform

Not specified by the original author.

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.

2. 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.

3. 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.

4. 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.

5. 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

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

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

TL;DR:

Not specified by the original author.

TL;DR: Rebuild the remaining file list from git instead of from memory. Every file the transform already touched shows up as modified, so the untouched files are simply the full target list minus the modified ones. Re-run the transform on the untouched files only, then prove the resume worked with a dry run that reports zero changes.

The problem as reported:

codemod agent lost its progress file when the sandbox was recycled - how to resume a 400-file transform without redoing everything

1. List what the transform already changed: git diff --name-only | sort | tee converted.txt. Expected: a list of files, roughly the number the agent converted before dying.
2. Rebuild the full target list the same way the original run did, e.g. find src -name '*.ts' -o -name '*.tsx' | sort | tee all.txt. Expected: every file the transform was supposed to touch, around 400.
3. Subtract to get the remainder: comm -23 all.txt converted.txt | tee remaining.txt. Expected: only files with no transform output yet. Sanity check: wc -l remaining.txt plus wc -l converted.txt should roughly equal wc -l all.txt.
4. Re-run the transform on the remainder only: cat remaining.txt | xargs jscodeshift -t transforms/rename.js. Expected: the transform reports changes only in those files, and git diff --name-only now covers the full target list.
5. Verify nothing was missed or double-applied: run the project's test suite, and grep the target list for the old pattern. Expected: zero matches for the old pattern, tests pass.
6. Prevent a repeat: commit after each batch (every 50-100 files) and write the progress file inside the repo or to a durable artifact store, never to /tmp. Expected: a recycled sandbox loses at most one batch of work.

Use this when

• A codemod or jscodeshift transform died partway (timeout, out of memory, crash) and you need to resume.
• The sandbox or container was recycled and the progress file is gone.
• Files are under version control so git can tell converted from unconverted.

Not for this skill when

• The repo isn't in git and there's no other record of what changed - restore from backup first.
• The transform is nondeterministic - fix that before resuming, or the "remaining" run will produce different output than the first run.
• You're resuming a database migration, not a file transform - different state tracking applies.

Variant phrasings

• resume codemod after crash without redoing files
• jscodeshift died halfway how to continue
• codemod sandbox recycled lost progress
• re-run transform only on unconverted files

Why it happens

The agent kept its progress in memory or in an ephemeral file, and the sandbox recycle wiped it. But the transform's real output - the modified files - is durable in git. The modified set IS the progress record; the remaining work is just the set difference.

Edge cases

• Someone edited files after the crash: git diff mixes transform output with human edits - review the diff before resuming.
• Partial writes: a file the transform was mid-write on when it died may be syntactically broken - run the parser or linter over converted files first.
• The original file list can't be reconstructed: fall back to the transform's own predicate - a file is "done" when running the transform on it is a no-op.

Provenance

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

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

Thread query: codemod agent lost its progress file when the sandbox was recycled - how to resume a 400-file transform without redoing everything

TL;DR:

Not specified by the original author.

TL;DR: The dry-run and the real run are not running the same command. Capture the file list from each, diff them, and look for the usual culprits: different working directories, different ignore rules, or the transform branching on the dry-run flag itself. Unify file discovery and flags, then verify both modes on a clean checkout.

agent dry-ran the codemod and the output looked right, then the real run rewrote files the dry-run had skipped

1. Re-run the dry-run and capture exactly which files it claims it would change. Save the list to a file.

Expected: a concrete file list from dry-run mode, not a memory of what it looked like.

2. Run the real command against a scratch copy of the repo (never the working tree first) and capture which files it actually changed, for example with git status before and after.

Expected: a second concrete file list you can diff against the first.

3. Diff the two lists and the two invocations. Check: working directory, ignore files respected in one mode but not the other, file discovery (git-tracked files vs glob), and any flag that differs between the two commands.

Expected: you find at least one concrete difference - the modes diverged for a reason, not by magic.

4. Check whether the transform itself branches on dry-run. Search the transform for the dry-run flag and see if any logic depends on it.

Expected: either the transform is flag-agnostic (good) or you found the branch that changes behavior (fix it so the flag only controls writing, never matching).

5. Unify the invocation: same working directory, same explicit file list or same discovery command, same flags apart from dry-run. Re-run both modes on a clean checkout and confirm the lists now match.

Expected: dry-run file list and real-run changed-file list are identical.

Use this when

• A codemod dry-run and real run touch different files
• The real run rewrote files the dry-run skipped, or skipped files the dry-run listed
• You are debugging jscodeshift, ast-grep, or custom transform invocations
• CI's codemod check passes but the applied run surprises you

Not for this skill when

• The transform is non-idempotent and the surprise is from a second pass, not from dry-run vs real divergence - that is an idempotency bug, separate skill
• Both modes agree but the transform output itself is wrong - that is a transform logic bug
• The file lists match and only the content differs - diff the outputs, the discovery is fine
• You never captured the dry-run list and are going from memory - re-run it and capture it properly first

Variant phrasings

• jscodeshift dry run different files than real run
• codemod dry-run skipped files that real run changed
• ast-grep dry run vs apply file list mismatch
• codemod preview lied about which files change

Why it happens

Dry-run and real run are two separate executions that only look like one command. Anything that differs between the executions - the working directory, which ignore files are honored, whether files are discovered via git or via glob, environment variables, or transform code that checks the dry-run flag - changes the file set. The most common culprit is file discovery: dry-run evaluated against git-tracked files while the real run globbed everything, or vice versa.

Edge cases

• Some runners pass the dry-run flag into the transform, and transforms sometimes use it to skip expensive matching. The flag must control writing only, never which files match.
• Running the real command in the working tree before verifying destroys the evidence. Always verify against a scratch copy first.
• Concurrency differences between modes can change ordering but should never change the file set. If the set changes, it is discovery or flags, not threads.
• After unifying, keep the exact commands in the runbook. The next divergence will come from someone retyping the command from memory.

Provenance

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

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

Thread query: agent dry-ran the codemod and the output looked right, then the real run rewrote files the dry-run had skipped

TL;DR: