Skill: charlie-morrison/codebase-migration-planner (version 1.0.1)

--- name: codebase-migration-planner description: Plan complex codebase migrations — framework upgrades, language transitions, architecture refactors. Analyze dependencies, estimate effort, map migration paths, generate phased plans, and track progress. --- # Codebase Migration Planner Plan and execute large-scale codebase migrations systematically. Whether it's React class→hooks, Express→Fastify, Python 2→3, monolith→microservices, or JavaScript→TypeScript — this skill maps the current state, identifies migration paths, estimates effort, and generates a phased execution plan. Use when: "plan a migration", "migrate from X to Y", "upgrade from v1 to v2", "rewrite this in TypeScript", "how much work to migrate", "migration effort estimate", or planning a major framework/language change. ## Commands ### 1. `assess` — Migration Assessment Analyze the current codebase to understand migration scope. #### Step 1: Inventory Current State ```bash echo "=== Codebase Inventory ===" # Language distribution echo "--- Language Distribution ---" find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \ -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \ -o -name "*.vue" -o -name "*.svelte" -o -name "*.css" -o -name "*.scss" \) \ -not -path '*/node_modules/*' -not -path '*/vendor/*' -not -path '*/dist/*' -not -path '*/.git/*' 2>/dev/null | \ sed 's/.*\.//' | sort | uniq -c | sort -rn # Total lines of code echo "--- Lines of Code ---" find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \ -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \ -not -path '*/node_modules/*' -not -path '*/vendor/*' -not -path '*/dist/*' 2>/dev/null | \ xargs wc -l 2>/dev/null | tail -1 # Framework/library detection echo "--- Frameworks & Libraries ---" if [ -f "package.json" ]; then python3 -c " import json d = json.load(open('package.json')) deps = {**d.get('dependencies',{}), **d.get('devDependencies',{})} frameworks = { 'react': 'React', 'next': 'Next.js', 'vue': 'Vue.js', 'nuxt': 'Nuxt', 'angular': 'Angular', 'svelte': 'Svelte', '@sveltejs/kit': 'SvelteKit', 'express': 'Express', 'fastify': 'Fastify', 'koa': 'Koa', 'hapi': 'Hapi', 'jest': 'Jest', 'vitest': 'Vitest', 'mocha': 'Mocha', 'cypress': 'Cypress', 'webpack': 'Webpack', 'vite': 'Vite', 'esbuild': 'esbuild', 'rollup': 'Rollup', 'tailwindcss': 'Tailwind CSS', 'styled-components': 'styled-components', 'prisma': 'Prisma', 'typeorm': 'TypeORM', 'sequelize': 'Sequelize', 'redux': 'Redux', 'zustand': 'Zustand', 'mobx': 'MobX', } found = [(v, deps[k]) for k, v in frameworks.items() if k in deps] for name, ver in sorted(found): print(f' {name}: {ver}') " 2>/dev/null fi # Test count TEST_COUNT=$(find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) \ -not -path '*/node_modules/*' 2>/dev/null | wc -l) echo "Test files: $TEST_COUNT" # Configuration files echo "--- Configuration ---" for f in tsconfig.json jsconfig.json .babelrc babel.config.* webpack.config.* vite.config.* \ rollup.config.* .eslintrc* eslint.config.* biome.json prettier* jest.config.* \ vitest.config.* next.config.* nuxt.config.* svelte.config.*; do ls $f 2>/dev/null done ``` #### Step 2: Migration Target Analysis Based on what the user wants to migrate to, analyze: - API surface differences between old and new - Configuration changes needed - Incompatible patterns that need rewriting - Available codemods or migration tools #### Step 3: Scope Estimation ```bash echo "=== Migration Scope ===" # Count files that need migration (depends on migration type) # Example: JS → TS migration echo "--- Files Requiring Migration ---" find . -name "*.js" -o -name "*.jsx" | \ grep -v node_modules | grep -v dist | grep -v build | wc -l # Group by directory (to plan phases) echo "--- Files by Directory ---" find . \( -name "*.js" -o -name "*.jsx" \) \ -not -path '*/node_modules/*' -not -path '*/dist/*' 2>/dev/null | \ xargs -I{} dirname {} | sort | uniq -c | sort -rn | head -20 # Complexity per directory (rough effort indicator) echo "--- Complexity by Directory ---" for dir in $(find . -maxdepth 2 -type d -not -path '*/.git*' -not -path '*/node_modules*' -not -path '*/dist*' 2>/dev/null); do LOC=$(find "$dir" -maxdepth 1 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" \) 2>/dev/null | \ xargs wc -l 2>/dev/null | tail -1 | awk '{print $1}') [ "$LOC" -gt 0 ] 2>/dev/null && echo " $dir: $LOC lines" done | sort -t: -k2 -rn | head -15 ``` ### 2. `plan` — Generate Migration Plan Produce a phased migration plan with effort estimates. ```markdown # Migration Plan: [From] → [To] Generated: [date] Estimated total effort: X person-weeks ## Phase 0: Preparation (Week 1) - [ ] Set up new tooling alongside old (dual support) - [ ] Add configuration for target framework - [ ] Ensure CI runs both old and new test suites - [ ] Create migration tracking document - Effort: 2-3 days ## Phase 1: Foundation (Week 2-3) Target: shared utilities, types, constants - [ ] Migrate `src/utils/` (N files, ~X lines) - [ ] Migrate `src/types/` (N files, ~X lines) - [ ] Migrate `src/constants/` (N files, ~X lines) - Effort: N days - Risk: Low (leaf modules, no dependents to break) ## Phase 2: Core Libraries (Week 4-5) Target: internal libraries used by features - [ ] Migrate `src/lib/` (N files, ~X lines) - [ ] Update imports in consuming files - [ ] Run full test suite after each library - Effort: N days - Risk: Medium (other code depends on these) ## Phase 3: Features (Week 6-8) Target: feature modules, one at a time - [ ] Migrate `src/features/auth/` (N files) - [ ] Migrate `src/features/users/` (N files) - [ ] ... (ordered by dependency — leaf features first) - Effort: N days - Risk: Medium-High (user-facing code) ## Phase 4: Cleanup (Week 9) - [ ] Remove old tooling and configuration - [ ] Update CI to remove dual-support - [ ] Update documentation - [ ] Final integration testing - Effort: 2-3 days ## Rollback Strategy At any phase, the old code still works alongside the new: - Revert the phase's commits - Restore old configuration - No data migration needed (this is code-only) ``` ### 3. `codemods` — Find Available Codemods Search for automated migration tools: ```bash echo "=== Available Codemods ===" # Common migration codemods # React if rg -q "from ['\"]react['\"]" -g '*.{tsx,jsx}' 2>/dev/null; then echo "React codemods:" echo " - npx @codemod/cli --transform react/19/migration" echo " - npx react-codemod rename-unsafe-lifecycles" echo " - npx react-codemod update-react-imports" fi # TypeScript adoption if [ -f "jsconfig.json" ] || find . -name "*.js" -not -path '*/node_modules/*' 2>/dev/null | head -1 | grep -q .; then echo "JS → TS codemods:" echo " - npx ts-migrate setup ." echo " - npx @codemod/cli --transform js-to-ts" fi # Express → Fastify if rg -q "require\(['\"]express['\"]\)|from ['\"]express['\"]" 2>/dev/null; then echo "Express → Fastify migration:" echo " - Manual migration (no automated codemod)" echo " - Key changes: app.get → fastify.get, middleware → hooks/plugins" fi # Vue 2 → Vue 3 if rg -q "from ['\"]vue['\"]" -g '*.{vue,js,ts}' 2>/dev/null; then echo "Vue codemods:" echo " - npx @vue/compat" echo " - gogocode-cli -s ./src -t vue2-to-vue3 -o ./src" fi ``` ### 4. `track` — Migration Progress Tracking Update a `MIGRATION.md` tracking file: ```markdown # Migration Progress: JS → TypeScript | Directory | Files | Migrated | Remaining | Status | |-----------|-------|----------|-----------|--------| | src/utils/ | 12 | 12 | 0 | ✅ Complete | | src/lib/ | 8 | 5 | 3 | 🔄 In Progress | | src/features/auth/ | 6 | 0 | 6 | ⏳ Pending | | src/features/users/ | 15 | 0 | 15 | ⏳ Pending | | src/pages/ | 22 | 0 | 22 | ⏳ Pending | | **Total** | **63** | **17** | **46** | **27%** | Last updated: 2026-04-28 ``` ### 5. `risks` — Risk Assessment Analyze migration risks: - **Dependency compatibility**: Do all dependencies support the target? - **Test coverage**: Which migrated files lack tests? - **API surface**: Which public APIs might change? - **Data compatibility**: Any serialization/deserialization changes? - **Performance**: Known performance differences between old/new? ```bash # Check if major dependencies support the target echo "=== Dependency Compatibility ===" if [ -f "package.json" ]; then python3 -c " import json d = json.load(open('package.json')) deps = list(d.get('dependencies', {}).keys()) print(f'Production dependencies to verify: {len(deps)}') for dep in deps[:20]: print(f' {dep} — check compatibility with target') " 2>/dev/null fi ``` ### 6. `effort` — Effort Estimation Estimate person-hours based on file analysis: | Factor | Weight | Notes | |--------|--------|-------| | Lines of code | 1 hr per 200 LOC | Mechanical changes | | Complex files (>300 LOC) | 2x multiplier | Need careful migration | | Files without tests | 1.5x multiplier | Need manual verification | | API boundary files | 2x multiplier | Risk of breaking consumers | | Configuration files | 2 hrs each | Need deep understanding | ``` Estimated effort: Simple files (< 100 LOC, with tests): 35 files × 0.5 hr = 17.5 hrs Medium files (100-300 LOC): 20 files × 1.5 hr = 30 hrs Complex files (> 300 LOC): 8 files × 4 hr = 32 hrs Config/build files: 5 files × 2 hr = 10 hrs Testing/verification: 20% buffer = 18 hrs Total: ~108 hours (~2.7 person-weeks) ``` ## Output Formats - **text** (default): Human-readable plan with tables - **json**: `{assessment: {}, plan: {phases: []}, risks: [], effort: {}, codemods: []}` - **markdown**: Stakeholder-ready document with Gantt-style timeline ## Common Migration Types This skill handles any migration, but excels at: - **JS → TypeScript**: File-by-file, incremental adoption - **React class → hooks**: Component-by-component - **Express → Fastify**: Route-by-route - **Webpack → Vite**: Config rewrite + plugin mapping - **Jest → Vitest**: Near-drop-in with config changes - **Vue 2 → Vue 3**: Composition API + breaking changes - **REST → GraphQL**: Schema-first, resolver mapping - **Monolith → Microservices**: Domain-driven decomposition ## Notes - Does not execute migrations — generates plans and tracks progress - Effort estimates are based on heuristics and should be validated with team knowledge - Codemod recommendations may have version-specific availability - For large migrations (>100 files), recommend incremental approach with dual-support period - Migration tracking file (`MIGRATION.md`) should be committed for team visibility


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)