/shift

Language Migration Reference

Purpose: Execute a language-level transition — adding or strengthening a type system, crossing a runtime major version, or porting across a language break. Covers JS → TS, TS non-strict → strict, Python 2 → 3 residual pockets, Node LTS major bumps, Go toolchain/module upgrades, and Java 8 → 17/21. The focus is runtime-behavior diffs and incremental rollout, not syntactic rewrites alone.

Scope Boundary

• Shift lang: executes a specific language / runtime transition with inference strategy, staged strictness, and runtime-behavior-diff verification.
• Shift migrate (default): general migration planning at the architectural layer.
• Shift framework: framework version jumps — may trigger a lang follow-up (e.g., Spring Boot 3 requires Java 17+).
• Zen: refactor within the current language version — no runtime or type-system change.
• detect Recipe: detects end-of-life runtimes — produces the input, does not execute.

If the request is "enable strict: true" → lang. If it is "add types to one file for readability" → Zen.

Common Migration Paths

Capture project-specific diffs you encounter in .agents/shift.md.

Type-Inference Strategy (JS → TS / loose → strict)

Order matters — do not attempt the strictest config on day one.

1. allowJs + checkJs: false: compile passes, no type coverage yet.
2. File-by-file opt-in via // @ts-check on JS or rename leaf modules first (utils / pure functions) before entry points.
3. noImplicitAny: surfaces the untyped surface area — expect many findings; triage into unknown (validate at boundary) vs any (explicit tech-debt comment with ticket).
4. strictNullChecks: highest-value flag; run in isolation, fix null paths, then commit.
5. strictFunctionTypes + strictPropertyInitialization: lower-volume fixes, enable together.
6. noUncheckedIndexedAccess: last — high noise, high value for correctness.

Never enable strict: true wholesale on a large codebase in one PR. A 500-error PR is unreviewable and unrevertable.

Runtime Behavior Diffs

Type-system changes do not alter runtime. Runtime / version bumps do — these are the real risks:

• Node LTS: run the full test suite on the new major before the engines bump. Watch for punycode removal, util._extend removal, weak cipher defaults, fetch body streaming changes. Node 22 LTS: require(esm) allows synchronous import of ES modules (reduces the CJS→ESM migration surface); native WebSocket eliminates ws dependency for simple cases; Maglev JIT changes warm-up latency profile — re-benchmark latency-sensitive paths.
• Go: 1.22 loop-variable semantics change silently — go vet flags some cases but not all; audit goroutine-in-loop call sites manually.
• Java 17 / 21: default charset is UTF-8 from 18+ (was platform-dependent) — file I/O round-trips may change. Virtual threads expose pinning on synchronized / native methods.
• Python 3.13: free-threaded build (--disable-gil) is opt-in and experimental — do not enable in production without extensive concurrency testing. JIT tier-2 compiler is also experimental; disable with PYTHON_JIT=0 if benchmarks regress. locals() snapshot semantics changed — code that mutated locals() breaks silently.
• Python 3: dict ordering is insertion-ordered from 3.7 — code that relied on set-like ordering now silently depends on insertion order.

Verification pattern: run the same deterministic workload on old and new runtimes, compare output byte-for-byte (or with a normalizer for timestamps). Diff the two. Unexplained diffs block promotion.

Workflow (overlays ASSESS → ... → COMPLETE)

ASSESS   →  pin source / target versions exactly (runtime + stdlib minor)
         →  inventory: files by language, existing type coverage %, deprecated-API usage
         →  capture CI matrix — does it already test target version?

PLAN     →  incremental strictness ladder or file-conversion order (leaves first)
         →  runtime-diff test harness (deterministic workload, old vs new)
         →  flag strategy: compiler flag per phase, not per file

PREPARE  →  scaffold type stubs / declaration files for untyped deps
         →  add CI lane running target runtime in parallel (not replacing)
         →  codemod for mechanical rewrites (e.g., `ioutil` → `io`/`os`, `print` → `print()`)

EXECUTE  →  one strictness flag or one file batch per PR
         →  keep green on both old and new runtime until cutover
         →  resolve each flag's findings before enabling the next

VERIFY   →  type coverage % target met (e.g., ≥95% non-any)
         →  runtime-diff harness: zero unexplained diffs
         →  benchmark: startup / hot-path within envelope

COMPLETE →  drop old runtime from CI matrix
         →  remove `allowJs` / compat shims
         →  document type-debt ledger (remaining `any` / `unknown` with tickets)

Anti-Patterns

• Declaring any everywhere to "get it compiling" — ships type pollution that later readers trust.
• Bumping Node major in the lockfile without the CI matrix catching it on the old major first.
• Enabling strict: true + every sub-flag simultaneously — findings cannot be triaged.
• Porting Python 2 → 3 by running 2to3 and calling it done — str/bytes issues surface only at I/O boundaries.
• Upgrading Java major and switching GC at the same time — perf regressions become unattributable.
• Leaving // @ts-ignore / # type: ignore without a linked ticket — becomes permanent.

Handoff

• → Builder: per-phase conversion tasks with file list and target flag.
• → Radar: runtime-diff harness; add tests at the boundaries where str/bytes, null/undefined, or numeric precision surfaced diffs.
• → Gear: CI matrix updates, runtime-image bumps, lockfile regen.
• → Sentinel: review crypto/TLS-related runtime changes (OpenSSL default diffs, JDK TLS changes).
• ← detect: consumes "runtime EOL" findings as the trigger.