Incremental Codebase Migration

# Incremental Migration Pattern ## Step 1: Generate Migration Manifest ```bash # Create a manifest of all files to migrate claude -p "Analyze src/ and create a migration manifest for JS-to-TypeScript conversion. For each file, include: - file path - dependency depth (leaf=0, higher=more deps) - estimated complexity (low/medium/high) - dependencies (files it imports) Sort by dependency depth ascending (leaves first). Output as JSON to migration-manifest.json" ``` ## Step 2: CLAUDE.md — Migration Rules ```markdown # Migration: JavaScript → TypeScript ## Rules - Process files in dependency order (leaves first) - Rename .js → .ts (.jsx → .tsx for React files) - Add explicit types for all function parameters and returns - Use `unknown` instead of `any` — add TODO for complex cases - Preserve all existing JSDoc comments - Do NOT change any runtime behavior - Run tests after each file conversion ## Type Strategy - Shared types go to src/types/[module].ts - Inline types for single-use cases - Use branded types for IDs: type UserId = string & { __brand: "UserId" } ## Progress Tracking - Update migration-manifest.json status: pending → done after each file - Commit after each successfully migrated file ``` ## Step 3: Automated Migration Loop ```bash #!/bin/bash # migrate-incremental.sh MANIFEST="migration-manifest.json" PENDING=$(jq '[.[] | select(.status == "pending")] | length' $MANIFEST) echo "Migration: $PENDING files remaining" for FILE in $(jq -r '.[] | select(.status == "pending") | .path' $MANIFEST | head -5); do echo "--- Migrating: $FILE ---" claude -p "Migrate $FILE from JavaScript to TypeScript. Follow the migration rules in CLAUDE.md. After conversion, run: npx tsc --noEmit && npm test" # Check if tests pass if npm test --silent; then # Update manifest jq "(.[] | select(.path == \"$FILE\")).status = \"done\"" $MANIFEST > tmp.json mv tmp.json $MANIFEST git add -A && git commit -m "migrate: convert $FILE to TypeScript" echo "PASS: $FILE migrated successfully" else echo "FAIL: $FILE — reverting" git checkout -- . fi done ``` ## Step 4: Progress Dashboard ```bash # Check migration progress jq '{ total: length, done: [.[] | select(.status == "done")] | length, pending: [.[] | select(.status == "pending")] | length, pct: (([.[] | select(.status == "done")] | length) * 100 / length | floor) }' migration-manifest.json ```