codemod-runner

Codemod Runner

Apply automated code transformations at scale using the right AST tool for the job — with scope assessment, batch execution, and idempotency verification before committing.

Tool Selection

flowchart TD
    Start([Codemod task received]) --> Q1{Language?}
    Q1 -->|Python| Q2{Transformation type?}
    Q1 -->|JavaScript / TypeScript| Q3{Needs full type info?}
    Q1 -->|Multi-language or<br>language-agnostic| Comby["comby<br>Structural search-replace<br>Works on any language<br>Pattern: comby 'old' 'new' .py"]
    Q2 -->|Rename, rewrite,<br>API migration| LibCST["LibCST<br>Preserves formatting<br>Python CST with type safety<br>pip install libcst"]
    Q2 -->|Lightweight search-replace<br>or regex-like patterns| Comby
    Q3 -->|Yes — needs type resolution,<br>cross-file inference| TSMorph["ts-morph<br>Full TypeScript compiler API<br>npx ts-morph-cli or use API<br>Best for typed refactors"]
    Q3 -->|No — structural only| Q4{Ecosystem preference?}
    Q4 -->|AST patterns preferred| AstGrep["ast-grep<br>Fast structural search<br>npm install -g @ast-grep/cli<br>sg run -p 'pattern' -r 'rewrite'"]
    Q4 -->|Codemod ecosystem,<br>existing transforms| JSCodeshift["jscodeshift<br>Facebook codemod runner<br>npx jscodeshift -t transform.js src/"]
    Comby --> Scope
    LibCST --> Scope
    TSMorph --> Scope
    AstGrep --> Scope
    JSCodeshift --> Scope
    Scope([Proceed to scope assessment])

Phase 1 — Scope Assessment (run before any transformation)

Assess impact size before touching files:

# Count affected files
rg -l 'old-pattern' | wc -l

# Preview first 25 affected files (saves to batch list)
rg -l 'old-pattern' | head -25 > batch.list
cat batch.list

# Count total occurrences (not just files)
rg -c 'old-pattern' | awk -F: '{sum+=$2} END {print sum}'

If the file count exceeds 50, process in batches using batch.list:

# Build per-batch lists of 25 files each
rg -l 'old-pattern' | split -l 25 - batch-
ls batch-*  # batch-aa, batch-ab, ...