Codemods and deprecated API cleanup

Codemods & Deprecation Cleanup

When to Use

Use when a package or framework upgrade deprecates or removes APIs across many call sites, or when upstream provides official migration schematics/codemods (@next/codemod, ng update, rector, django-upgrade, pyupgrade, cargo fix --edition).

Codemod Execution Discipline

1. Run Codemods on a Clean Tree & Separate Commits/Steps

• Never run an automated codemod on a dirty working tree mixed with manual edits.
• Run the codemod in an isolated step so its mechanical diff can be inspected line by line before applying manual edge-case fixes.

2. Vet Official vs. Custom AST Transformations

• JavaScript / TypeScript:
  • Official framework codemods (npx @next/codemod@latest <transform>, npx @tanstack/react-query-codemod, npx prisma, ng update).
  • For custom multi-file API migrations, prefer AST-aware tools (jscodeshift, ts-morph, ast-grep) over fragile regex search-and-replace when call sites span multiple lines, aliased imports, or overloaded method names.
• PHP:
  • rector/rector (vendor/bin/rector process --dry-run) with targeted rule sets (LevelSetList, LaravelSetList, SymfonySetList, PHPUnitSetList).
• Python:
  • pyupgrade, django-upgrade, ruff check --select UP, bump-pydantic, or LibCST transforms.
• Rust:
  • cargo fix and cargo clippy --fix for compiler-verified edition and deprecation migrations.

3. Mandatory Post-Codemod Audit ("Never Trust Codemod Output Blindly")

Automated codemods operate on syntax trees and often miss dynamic patterns, type nuances, or comments. After running any codemod, inspect git diff for:

1. Broken Semantics & Edge Cases:
   • Aliased or re-exported imports that the codemod skipped.
   • async/await additions where the enclosing function was not marked async or callers were not updated to handle a returned Promise.
   • Complex dynamic expressions wrapped in /* TODO */ or fallback casts (as any) inserted by the codemod.
2. Formatting & Comment Preservation:
   • Ensure the codemod did not strip important domain comments, license headers, or reformat untouched lines across the file. Run the project's formatter/linter only on the modified lines/files if needed.
3. Complete Deprecation Removal:
   • Grep for the deprecated symbol, import path, configuration key, or CLI flag across the entire repository (including test helpers, Storybook stories, seed scripts, and docs) to confirm zero stragglers remain.

Systematic Deprecation Replacement Without Codemods

When replacing deprecated APIs manually:

1. Map the old contract vs. new contract (arguments, return values, error behavior, side effects, default options).
2. Migrate call sites directly to the new canonical API rather than wrapping the new API in a permanent legacy-imitating helper—unless a temporary adapter is needed to stage a huge change, in which case mark it @deprecated with a clear removal condition.
3. Run tests with deprecation warnings elevated to errors (e.g., node --throw-deprecation, pytest -W error::DeprecationWarning, PHPUnit failOnDeprecation="true", RUSTFLAGS="-D warnings") to prove the deprecated code path is no longer triggered at runtime.