Boîte à Outils Migration Framework + Langage

What this pack solves

Real migrations — JavaScript to TypeScript, CommonJS to ESM, React class components to hooks, Express to Hono, Python 2 to Python 3, Vue 2 to Vue 3 — fail for the same reason: someone tries to do them in one giant branch. Six weeks in, the branch has 800 files changed, conflicts with every merge to main, and nobody can confidently ship it.

This pack is the AI-era version of how to actually finish one. The pattern is the same regardless of source/target: baseline → codemod → typecheck → test → ship a slice → repeat. The tools below let each step happen in minutes, not days, so the slice size can stay small enough to land before lunch.

Install in this order

1. Codemod — AI-Powered Code Migration CLI (start here). The center of the rig. Scaffolds, shares, and runs large-scale code migrations as multi-step YAML workflows. First-class ast-grep support, a community registry of pre-built codemods (React class→hooks, Mocha→Jest, CommonJS→ESM, etc.), and AI-assisted authoring when no registry codemod fits.
2. ast-grep — Structural Code Search and Rewrite Tool. The actual rewrite engine under most modern codemods. Pattern-match by AST shape instead of regex — $VAR.then($CB) matches every promise-callback you want to rewrite to await, regardless of whitespace or names. Use it standalone for one-off rewrites, or as the Codemod CLI's backend.
3. TypeScript — JavaScript with Syntax for Types. The destination for JS→TS migrations. Install with --noImplicitAny off initially, flip it on per directory as you migrate.
4. TypeScript Go — Native TypeScript Compiler Port in Go. Drop-in tsc replacement, ~10× faster typecheck. Critical during migrations because you'll run typecheck after every codemod batch — a 2-minute tsc round becomes a 12-second loop, and 12 seconds is the difference between staying in flow and context-switching to Slack.
5. tsx — The Fastest Way to Run TypeScript in Node.js. Lets you execute .ts files directly during migration without a build step. Crucial when half your codebase is JS and half is TS and you don't want to set up two parallel build pipelines.
6. Mypy — Optional Static Type Checker for Python. The Python equivalent of "flip on typecheck per directory." Use --strict per module, not project-wide. Pair with a py.typed marker so downstream consumers see your types.
7. Ruff — Python Linter and Formatter in One Fast CLI. For Python 2→3 migrations specifically, Ruff's pyupgrade ruleset auto-fixes most modernization patterns: print x → print(x), u"str" → "str", super(Foo, self) → super(), dict.iteritems() → dict.items(). One ruff check --select UP --fix pass handles thousands of mechanical changes.
8. Ty — Astral's Fast Python Type Checker. The Rust-based alternative to Mypy from the same team that ships Ruff. Worth trialing in parallel — when feedback latency drops from 8 seconds to 200ms, you actually keep typing while it runs.
9. Hono — Ultrafast Web Framework for the Edge. The destination if you're migrating off Express. API surface is close enough that handler-by-handler porting is mechanical: req.body → await c.req.json(), res.json(x) → c.json(x), middleware signature is similar. Bonus: runs on Cloudflare/Bun/Node, so you can host the migrated routes anywhere.
10. Claude Code Agent: Legacy Modernizer. The catch-all for what codemods can't touch: dead config files, abandoned modules, version-sniff branches that haven't fired since IE 11. The agent reads the codebase, proposes a teardown order, and writes the PRs. Use it for the 20% that's judgment-heavy, not the 80% that's mechanical.

How they fit together

        ┌──────────────────────────────────┐
        │  Codemod CLI  (orchestrator)     │
        │    └─ ast-grep  (rewrite engine) │
        └──────────────────────────────────┘
                       │
      ┌────────────────┼────────────────┐
      ▼                ▼                ▼
   JS → TS         Python 2 → 3      Legacy archaeology
   ─────────       ──────────       ──────────────────
   TypeScript      Ruff (--select UP)  Legacy Modernizer
   TypeScript-Go   Mypy / Ty             (agent)
   tsx (run TS)
                                  ┌──────────────┐
                                  │ Express→Hono │
                                  │   Hono       │
                                  └──────────────┘
                       │
                       ▼
             Slice ships in 1-3 PRs

The migration loop you run, per slice:

1. Baseline — pick the next ~20-50 files. Snapshot test output and bundle size.
2. Codemod — run Codemod CLI (or ast-grep directly) against just that slice. Inspect the diff.
3. Typecheck — TypeScript-Go / Ty in watch mode. Fix the errors codemods couldn't infer.
4. Test — run the existing test suite on the slice. tsx lets you do this without rebuilding.
5. Ship — open the PR, merge, ship. Move to the next slice tomorrow.

If any slice takes more than 2 days, the slice is too big. Cut it.

Tradeoffs you'll hit

• Codemod CLI vs hand-written jscodeshift — Codemod CLI wraps ast-grep and a registry. Hand-rolled jscodeshift gives you full JS API control. Start with Codemod CLI; only drop to jscodeshift when the registry doesn't have your transform and ast-grep patterns can't express it.
• Mypy vs Ty — Mypy is the incumbent, more mature, slower. Ty is fast enough to keep open in your editor without lag. Run both during the migration: Mypy in CI for thoroughness, Ty locally for the inner loop.
• TypeScript-Go vs tsc — TypeScript-Go is the official Microsoft port, faster but not 100% feature-complete yet. Use it for the inner-loop typecheck during migration; keep tsc as the source of truth in CI until parity ships.
• Express→Hono vs Express→Fastify — Hono runs on edge runtimes (Cloudflare Workers, Bun, Deno) AND Node, with a near-identical handler API. Fastify is Node-only but more mature for traditional servers. Pick Hono if you're modernizing toward edge; Fastify if you're staying on Node and want the most mature option.
• Codemod-everything vs Legacy Modernizer — codemods do the 80% mechanical work in minutes. The Legacy Modernizer agent handles the 20% that needs judgment (dead code, abandoned features, conditional branches). Don't make the agent do mechanical work; don't make codemods do archaeology.

Common pitfalls

• Codemod sliced too big — "convert all 800 files to TS in one PR" guarantees the PR never lands. Migrate by directory, not by language. Each PR should be small enough to review in one sitting.
• Forgetting the typecheck loop is slow — running tsc --noEmit after every codemod pass is the migration step that kills your day. Install TypeScript-Go on day one. The 10× speedup is the difference between this being fun and being a chore.
• Codemod registry copy-paste without reading — registry codemods are starting points, not gospel. Open the YAML, read the patterns, run on one file first, eyeball the diff before unleashing on the codebase.
• Mypy --strict everywhere on day one — fastest way to give up. Enable per module via [mypy-yourpackage.submodule] blocks, expand outward.
• Express→Hono one-shot rewrite — port routes in groups, run both servers behind a router (Hono mounted under /v2), cut over endpoint by endpoint. Don't flip the whole app at once.
• Trusting codemods on tests — codemods will happily "migrate" a broken test suite into a still-broken test suite. Run the tests after every codemod batch. If tests were green before and red after, the codemod missed something — that's the bug you want to find right then, not in production three weeks later.