Project 31: Codebase Migration Assistant
Project 31: Codebase Migration Assistant
Build a Kiro CLI workflow that automates codebase migrations between languages or frameworks - converting JavaScript to TypeScript, React Class components to Hooks, or even entire framework migrations.
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | Expert (Level 4) |
| Time Estimate | 1 month |
| Primary Language | TypeScript |
| Alternative Languages | Python |
| Prerequisites | Projects 1-25, deep understanding of AST manipulation |
| Key Topics | Semantic preservation, type inference, incremental migration, behavior equivalence |
| Kiro CLI Concepts | Custom agents, file system operations, hooks, checkpoints, testing integration |
| Main Book Reference | “Working Effectively with Legacy Code” by Michael Feathers |
1. Learning Objectives
By completing this project, you will:
- Master semantic-preserving code transformations: Understand how to convert code between languages while maintaining identical behavior
- Implement incremental migration strategies: Learn to break large migrations into safe, reversible steps with checkpoint-based rollback
- Design type inference systems: Build logic that derives TypeScript types from JavaScript runtime behavior and usage patterns
- Create automated test validation workflows: Ensure migration correctness by running tests after each transformation
- Build production-grade migration tooling: Understand the patterns used by tools like jscodeshift, ts-migrate, and React codemods
2. Deep Theoretical Foundation
2.1 What Is Code Migration?
Code migration is the systematic transformation of a codebase from one form to another while preserving its semantic behavior. This is fundamentally different from rewriting - migration maintains the logical structure while changing the syntactic representation.
THE MIGRATION TRANSFORMATION SPECTRUM
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ SYNTACTIC SEMANTIC │
│ CHANGES CHANGES │
│ ◀──────────────────────────────────────────────────────────────────▶ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Rename │ │ JS → TS │ │ Class → │ │ REST → │ │ Monolith │ │
│ │ Variable │ │ (add │ │ Hooks │ │ GraphQL │ │ → Micro- │ │
│ │ │ │ types) │ │ │ │ │ │ services │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ Mechanical Type Pattern API Architecture │
│ (AST-only) Addition Transform Redesign Decomposition │
│ │
│ RISK: Low RISK: Med RISK: High RISK: High RISK: V.High │
│ AUTOMATION: AUTOMATION: AUTOMATION: AUTOMATION: AUTOMATION: │
│ 100% 80% 60% 40% 20% │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Key Insight: The further right you go on this spectrum, the more human judgment is required. AI can automate the mechanical parts but should defer to humans for semantic decisions.
2.2 The Three Laws of Safe Migration
From “Working Effectively with Legacy Code” (Feathers, Ch. 2):
THE THREE LAWS OF SAFE MIGRATION
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ LAW 1: BEHAVIOR PRESERVATION │
│ ──────────────────────────────── │
│ "If you can't prove the new code behaves identically, │
│ you haven't migrated - you've rewritten." │
│ │
│ Verification methods: │
│ • Unit tests (before = after) │
│ • Property-based tests (random inputs, same outputs) │
│ • Snapshot tests (serialized output comparison) │
│ • Type checks (if adding types) │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ LAW 2: INCREMENTAL TRANSFORMATION │
│ ────────────────────────────────── │
│ "Never migrate more than you can safely roll back." │
│ │
│ Strategies: │
│ • File-by-file migration │
│ • Function-by-function within files │
│ • Checkpoint after each successful step │
│ • Keep old and new code running in parallel │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ LAW 3: DEPENDENCY ORDER │
│ ───────────────────────── │
│ "Migrate leaves before branches, imports before exports." │
│ │
│ Order of operations: │
│ 1. Utility modules (no internal dependencies) │
│ 2. Data models / types │
│ 3. Business logic │
│ 4. API layer │
│ 5. UI components │
│ 6. Entry points │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.3 JavaScript to TypeScript: The Canonical Migration
The JS→TS migration is the most common and best-understood migration path. Understanding it deeply teaches principles applicable to all migrations.
JS → TS MIGRATION PIPELINE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ PHASE 1: INFRASTRUCTURE │
│ ───────────────────────── │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 1. Add tsconfig.json with permissive settings │ │
│ │ • "allowJs": true │ │
│ │ • "noImplicitAny": false (initially) │ │
│ │ • "strict": false (initially) │ │
│ │ │ │
│ │ 2. Install TypeScript and @types/* packages │ │
│ │ • npm install --save-dev typescript │ │
│ │ • npm install --save-dev @types/node @types/react ... │ │
│ │ │ │
│ │ 3. Update build scripts │ │
│ │ • tsc for type checking │ │
│ │ • ts-node for development │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 2: FILE CONVERSION (Per File) │
│ ─────────────────────────────────── │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ helpers.js │ ──▶ │ helpers.ts │ ──▶ │ Tests Pass? │ │
│ │ │ │ (renamed) │ │ │ │
│ │ function add( │ │ function add( │ │ Yes: Continue │ │
│ │ a, b │ │ a: number, │ │ No: Rollback │ │
│ │ ) { ... } │ │ b: number │ │ │ │
│ │ │ │ ): number {...} │ │ │ │
│ └──────────────────┘ └──────────────────┘ └────────────────┘ │
│ │
│ Transformation steps: │
│ 1. Rename .js → .ts │
│ 2. Fix import extensions (.js → .ts or remove) │
│ 3. Add explicit types to function parameters │
│ 4. Add explicit return types │
│ 5. Fix any type errors │
│ 6. Run tests │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 3: STRICTNESS ESCALATION │
│ ────────────────────────────── │
│ │
│ Enable strict mode incrementally: │
│ │
│ Round 1: "noImplicitAny": true │
│ Fix all implicit any errors │
│ │
│ Round 2: "strictNullChecks": true │
│ Handle null/undefined everywhere │
│ │
│ Round 3: "strict": true │
│ Full TypeScript strictness │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.4 Type Inference Strategies
When migrating from JavaScript, types must be inferred. This is where AI provides significant value:
TYPE INFERENCE HIERARCHY
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ INFERENCE SOURCE CONFIDENCE EXAMPLE │
│ ──────────────────────────────────────────────────────────────────── │
│ │
│ 1. JSDoc annotations HIGHEST /** @param {n} │
│ Already documented types * @returns {s} │
│ */ │
│ │
│ 2. TypeScript inference HIGH const x = 5; │
│ When TS can determine type // number │
│ │
│ 3. Usage analysis MEDIUM function f(x) { │
│ How the value is used return x + 1; │
│ } │
│ // x: number │
│ │
│ 4. Test data analysis MEDIUM it('test', () =>│
│ What values are passed in tests f(42)); │
│ // f: (n) => ? │
│ │
│ 5. AI semantic analysis LOWER // variable name│
│ Based on naming conventions userId │
│ // likely string│
│ │
│ 6. Fallback: explicit any LOWEST function f( │
│ When all else fails x: any │
│ ) │
│ │
└─────────────────────────────────────────────────────────────────────────┘
AI-ASSISTED TYPE INFERENCE
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ INPUT (JavaScript): │
│ ─────────────────── │
│ function processUser(user) { │
│ const name = user.firstName + ' ' + user.lastName; │
│ const age = new Date().getFullYear() - user.birthYear; │
│ return { name, age, email: user.email }; │
│ } │
│ │
│ AI ANALYSIS: │
│ ───────────── │
│ • user.firstName, user.lastName → string (concatenation) │
│ • user.birthYear → number (arithmetic operation) │
│ • user.email → string (common pattern) │
│ • Return type: { name: string, age: number, email: string } │
│ │
│ OUTPUT (TypeScript): │
│ ──────────────────── │
│ interface User { │
│ firstName: string; │
│ lastName: string; │
│ birthYear: number; │
│ email: string; │
│ } │
│ │
│ interface ProcessedUser { │
│ name: string; │
│ age: number; │
│ email: string; │
│ } │
│ │
│ function processUser(user: User): ProcessedUser { │
│ const name = user.firstName + ' ' + user.lastName; │
│ const age = new Date().getFullYear() - user.birthYear; │
│ return { name, age, email: user.email }; │
│ } │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.5 React Class to Hooks Migration
This migration is more complex because it involves behavioral patterns, not just types:
CLASS → HOOKS TRANSFORMATION
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ CLASS COMPONENT HOOKS EQUIVALENT │
│ ─────────────────────── ───────────────── │
│ │
│ class Counter extends Component { function Counter() { │
│ │
│ state = { count: 0 }; ──▶ const [count, setCount] │
│ = useState(0); │
│ │
│ componentDidMount() { ──▶ useEffect(() => { │
│ fetchData(); fetchData(); │
│ } }, []); │
│ │
│ componentDidUpdate(prev) { ──▶ useEffect(() => { │
│ if (prev.id !== this.props.id) // runs on id change │
│ refetch(); refetch(); │
│ } }, [id]); │
│ │
│ componentWillUnmount() { ──▶ useEffect(() => { │
│ cleanup(); return () => cleanup(); │
│ } }, []); │
│ │
│ handleClick = () => { ──▶ const handleClick = () => { │
│ this.setState({ count: setCount(c => c + 1); │
│ this.state.count + 1 }; │
│ }); │
│ }; │
│ │
│ render() { ──▶ return ( │
│ return ( <button │
│ <button onClick={handleClick}> │
│ onClick={this.handleClick}> {count} │
│ {this.state.count} </button> │
│ </button> ); │
│ ); } │
│ } │
│ } │
│ │
└─────────────────────────────────────────────────────────────────────────┘
LIFECYCLE MAPPING DIAGRAM
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ CLASS LIFECYCLE ┌─────────────────┐ HOOKS │
│ ─────────────── │ useEffect() │ ───── │
│ │ │ │
│ componentDidMount ───▶ │ deps: [] │ (run once on mount) │
│ │ │ │
│ componentDidUpdate ───▶ │ deps: [x,y] │ (run when x,y change) │
│ │ │ │
│ componentWillUnmount───▶ │ return () => │ (cleanup function) │
│ │ cleanup() │ │
│ │ │ │
│ getDerivedState ────▶ │ useMemo() │ (derived calculations) │
│ FromProps │ │ │
│ │ │ │
│ shouldComponentUpdate──▶ │ React.memo() │ (memoize component) │
│ │ │ │
│ getSnapshotBefore ────▶ │ useRef() + │ (capture before update) │
│ Update │ useLayoutEffect│ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.6 The Checkpoint Pattern for Safe Migration
Kiro CLI’s checkpoint system is essential for migration safety:
CHECKPOINT-BASED MIGRATION FLOW
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ Start: migration-start │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Migrate file 1 │───▶ Tests pass? ───▶ Create checkpoint-file-1 │
│ │ helpers.js → .ts │ │ │ │
│ └──────────────────┘ │ ▼ │
│ │ ┌──────────────────┐ │
│ │ │ Migrate file 2 │ │
│ │ │ utils.js → .ts │ │
│ │ └────────┬─────────┘ │
│ │ │ │
│ │ ▼ │
│ │ Tests pass? │
│ │ │ │ │
│ │ Yes │ │ No │
│ │ ▼ │ │
│ │ checkpoint- │ │
│ │ file-2 │ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ Continue ┌───────────────────┐ │
│ │ ... │ ROLLBACK to │ │
│ │ │ checkpoint-file-1 │ │
│ │ │ │ │
│ │ │ Analyze failure │ │
│ │ │ Fix the issue │ │
│ │ │ Retry migration │ │
│ │ └───────────────────┘ │
│ │ │
│ Tests fail during ──────────┘ │
│ any migration step │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Checkpoint naming convention:
migration-{timestamp}-{phase}-{file-or-step}
Examples:
• migration-20241222-infrastructure-tsconfig
• migration-20241222-file-src-utils-helpers
• migration-20241222-strictness-noImplicitAny
3. Complete Project Specification
3.1 What You Will Build
A Kiro CLI agent that:
- Analyzes a JavaScript/React codebase to create a migration plan
- Converts files incrementally with checkpoint-based safety
- Infers and adds TypeScript types using AI
- Transforms React Class components to Hooks
- Validates each step with tests before proceeding
- Provides rollback capability on failures
3.2 Functional Requirements
| Requirement | Description |
|---|---|
| Codebase Analysis | Scan project structure, identify file types, map dependencies |
| Migration Planning | Create ordered list of files to migrate based on dependency graph |
| File Transformation | Convert .js to .ts, add types, update imports |
| Pattern Transformation | Convert Class → Hooks, CommonJS → ESM |
| Type Inference | Use AI to infer types from usage patterns |
| Test Validation | Run tests after each file, abort on failure |
| Checkpoint Management | Create/restore checkpoints at each step |
| Progress Reporting | Show migration status and remaining work |
3.3 Non-Functional Requirements
- Safety: Never leave codebase in broken state
- Reversibility: Any change can be undone
- Idempotency: Running migration twice produces same result
- Observability: Clear logging of all transformations
4. Solution Architecture
4.1 System Architecture Diagram
┌──────────────────────────────────────────────────────────────────────────────┐
│ MIGRATION ASSISTANT ARCHITECTURE │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ CLI INTERFACE │ │
│ │ kiro-cli --agent migration-assistant │ │
│ │ > "Migrate this codebase from JavaScript to TypeScript" │ │
│ └────────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ MIGRATION ORCHESTRATOR │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Analyzer │ │ Planner │ │ Executor │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Scan files │ │ • Order files │ │ • Transform │ │ │
│ │ │ • Map deps │ │ • Create plan │ │ • Validate │ │ │
│ │ │ • Detect types │ │ • Est. effort │ │ • Checkpoint │ │ │
│ │ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │ │
│ │ │ │ │ │ │
│ │ └───────────────────┼───────────────────┘ │ │
│ │ │ │ │
│ └──────────────────────────────┼──────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ TRANSFORMATION ENGINE │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Type Inferrer │ │ Code │ │ Pattern │ │ │
│ │ │ │ │ Transformer │ │ Converter │ │ │
│ │ │ • JSDoc parse │ │ │ │ │ │ │
│ │ │ • Usage anal. │ │ • Rename file │ │ • Class→Hooks │ │ │
│ │ │ • AI inference │ │ • Add types │ │ • CJS→ESM │ │ │
│ │ │ │ │ • Fix imports │ │ • Default exp. │ │ │
│ │ └───────────────┘ └───────────────┘ └────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SAFETY LAYER │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Test Runner │ │ Checkpoint │ │ Rollback │ │ │
│ │ │ (Hook) │ │ Manager │ │ Handler │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Jest/Vitest │ │ • Save state │ │ • Detect fail │ │ │
│ │ │ • Validate │ │ • Track files │ │ • Restore │ │ │
│ │ │ • Report │ │ • Timestamp │ │ • Report │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
4.2 Data Flow Diagram
MIGRATION DATA FLOW
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ USER REQUEST │
│ "Migrate src/utils/ to TypeScript" │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ ANALYSIS PHASE │ │
│ │ │ │
│ │ Input: Source directory │ │
│ │ Output: FileAnalysis[] │ │
│ │ │ │
│ │ { │ │
│ │ path: "src/utils/helpers.js", │ │
│ │ imports: ["lodash", "./constants"], │ │
│ │ exports: ["formatDate", "parseNumber"], │ │
│ │ hasJSDoc: true, │ │
│ │ linesOfCode: 145, │ │
│ │ complexity: "medium" │ │
│ │ } │ │
│ └───────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ PLANNING PHASE │ │
│ │ │ │
│ │ Input: FileAnalysis[] │ │
│ │ Output: MigrationPlan │ │
│ │ │ │
│ │ { │ │
│ │ phases: [ │ │
│ │ { name: "infrastructure", files: [...] }, │ │
│ │ { name: "utilities", files: [...] }, │ │
│ │ { name: "components", files: [...] } │ │
│ │ ], │ │
│ │ estimatedTime: "2 hours", │ │
│ │ totalFiles: 12 │ │
│ │ } │ │
│ └───────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ EXECUTION PHASE (Per File) │ │
│ │ │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ Checkpoint│─▶│ Transform │─▶│ Test │─▶│ Next or │ │ │
│ │ │ Create │ │ File │ │ Validate │ │ Rollback │ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
4.3 Key Data Structures
// Core types for migration assistant
interface FileAnalysis {
path: string;
type: 'javascript' | 'typescript' | 'jsx' | 'tsx';
imports: ImportAnalysis[];
exports: ExportAnalysis[];
hasJSDoc: boolean;
hasReactClasses: boolean;
linesOfCode: number;
complexity: 'low' | 'medium' | 'high';
dependencyDepth: number; // How many files depend on this
}
interface MigrationPlan {
phases: MigrationPhase[];
estimatedTime: string;
totalFiles: number;
warnings: string[];
}
interface MigrationPhase {
name: string;
description: string;
files: FileMigration[];
dependencies: string[]; // Phase names this depends on
}
interface FileMigration {
sourcePath: string;
targetPath: string;
transformations: Transformation[];
estimatedEffort: 'low' | 'medium' | 'high';
}
interface Transformation {
type: 'rename' | 'addTypes' | 'classToHooks' | 'updateImports';
description: string;
automated: boolean;
requiresReview: boolean;
}
interface MigrationState {
plan: MigrationPlan;
currentPhase: number;
currentFile: number;
completedFiles: string[];
failedFiles: FileMigrationError[];
checkpoints: Checkpoint[];
startedAt: Date;
status: 'planning' | 'executing' | 'paused' | 'completed' | 'failed';
}
interface Checkpoint {
id: string;
timestamp: Date;
phase: string;
file: string;
gitCommit: string;
description: string;
}
5. Phased Implementation Guide
Phase 1: Analysis Foundation (Days 1-7)
Goals:
- Build file scanning and analysis
- Create dependency graph
- Implement basic type detection
Tasks:
- Create file scanner that identifies JS/TS/JSX/TSX files
- Parse imports/exports using AST (babel parser)
- Build dependency graph using topological sort
- Detect JSDoc annotations
- Identify React class components
Milestone Checkpoint:
$ kiro-cli --agent migration-assistant
> "Analyze src/ for migration"
[Analysis] Scanning src/...
├── Found 156 JavaScript files
├── Found 23 React class components
├── Dependency depth: 5 levels
└── Estimated migration effort: 45 files/hour
Hint 1: Start with a simple regex-based import detector before moving to full AST parsing.
Hint 2: Use @babel/parser with { sourceType: 'module', plugins: ['jsx'] } for JavaScript files.
Phase 2: Migration Planning (Days 8-14)
Goals:
- Create ordered migration plan
- Estimate effort per file
- Generate human-readable plan
Tasks:
- Implement topological sort for file ordering
- Group files into logical phases
- Estimate effort based on complexity metrics
- Generate plan preview for user approval
- Store plan as JSON for resumability
Milestone Checkpoint:
> "Create migration plan"
[Plan] Generated migration plan:
┌────────────────────────────────────────────────────────────────────┐
│ Phase 1: Infrastructure (3 files) │
├────────────────────────────────────────────────────────────────────┤
│ - Add tsconfig.json │
│ - Add @types packages │
│ - Update build scripts │
├────────────────────────────────────────────────────────────────────┤
│ Phase 2: Utilities (12 files, ~30 min) │
├────────────────────────────────────────────────────────────────────┤
│ - src/utils/helpers.js → .ts │
│ - src/utils/validators.js → .ts │
│ - ... │
└────────────────────────────────────────────────────────────────────┘
Proceed with migration? [Y/n]
Hint 3: Leaf modules (no internal dependencies) should be migrated first - they are the safest starting point.
Phase 3: Type Inference Engine (Days 15-21)
Goals:
- Extract types from JSDoc
- Infer types from usage patterns
- Use AI for complex inference
Tasks:
- Parse JSDoc comments with
doctrine - Build usage analyzer (track how values are used)
- Create AI prompts for type inference
- Generate TypeScript interfaces
- Handle common patterns (arrays, objects, callbacks)
Milestone Checkpoint:
> "Migrate src/utils/helpers.js"
[Inference] Analyzing helpers.js...
├── Found 3 JSDoc annotations
├── Inferred 5 types from usage
├── AI suggested 2 additional types
[Types] Generated interfaces:
interface User {
id: string;
name: string;
email: string;
}
Proceed with transformation? [Y/n]
Hint 4: For AI inference, provide 3-5 lines of context around each function, including any calls to it.
Phase 4: Transformation Engine (Days 22-28)
Goals:
- Rename files safely
- Add type annotations
- Update imports across codebase
Tasks:
- Implement file renaming with git mv
- Build AST transformer for type insertion
- Update import statements project-wide
- Handle edge cases (re-exports, barrel files)
- Integrate with test runner hook
Milestone Checkpoint:
> "Start migration"
[Migration] Phase 2: Utilities
[File 1/12] helpers.js → helpers.ts
├── Added 8 type annotations
├── Inferred return types for 3 functions
├── Updated 15 import statements in other files
├── [Hook: test] Running tests... ✓ (24/24 passing)
└── ✓ Checkpoint created: migration-20241222-utils-helpers
[File 2/12] validators.js → validators.ts...
Phase 5: Pattern Transformation (Days 29-35)
Goals:
- Convert React class components to hooks
- Handle lifecycle methods correctly
- Preserve component behavior
Tasks:
- Detect class component patterns
- Map lifecycle methods to hooks
- Convert state to useState
- Handle refs, context, error boundaries
- Validate with React-specific tests
Hint 5: Error boundaries cannot be converted to hooks - they must remain class components.
6. Testing Strategy
6.1 Unit Tests
describe('TypeInference', () => {
it('should infer number from arithmetic usage', () => {
const code = `
function double(x) {
return x * 2;
}
`;
const types = inferTypes(code);
expect(types.parameters.x).toBe('number');
expect(types.returnType).toBe('number');
});
it('should extract types from JSDoc', () => {
const code = `
/**
* @param {string} name
* @returns {boolean}
*/
function isValid(name) {
return name.length > 0;
}
`;
const types = extractJSDocTypes(code);
expect(types.parameters.name).toBe('string');
expect(types.returnType).toBe('boolean');
});
});
6.2 Integration Tests
describe('FileMigration', () => {
it('should migrate JS file to TS with types', async () => {
const input = `
export function add(a, b) {
return a + b;
}
`;
const output = await migrateFile(input, 'helpers.js');
expect(output).toContain('function add(a: number, b: number): number');
expect(output).not.toContain('any');
});
it('should update imports in dependent files', async () => {
await migrateFile('helpers.js');
const consumer = fs.readFileSync('consumer.ts', 'utf-8');
expect(consumer).toContain("from './helpers'");
expect(consumer).not.toContain("from './helpers.js'");
});
});
6.3 Rollback Tests
describe('Checkpoint Rollback', () => {
it('should restore to checkpoint on test failure', async () => {
const checkpoint = await createCheckpoint('before-migration');
await migrateFile('helpers.js');
// Simulate test failure
mockTestRunner.mockReturnValue({ passed: false });
await runTests();
// Should auto-rollback
const currentFile = fs.readFileSync('helpers.js', 'utf-8');
expect(currentFile).toBe(originalContent);
});
});
7. Common Pitfalls and Debugging
7.1 Common Migration Failures
| Pitfall | Symptom | Solution |
|---|---|---|
| Circular dependencies | Migration order fails | Detect cycles in dependency graph, migrate together |
| Dynamic imports | Missed import updates | Search for require() and dynamic import() |
| Implicit any spreading | Types don’t propagate | Enable noImplicitAny early to catch issues |
| React context types | Runtime errors | Extract context types separately before migration |
| Test file migration | Tests fail after migration | Migrate test files with their source files |
7.2 Debugging Strategies
1. Enable verbose transformation logging:
const transformer = createTransformer({
onTransform: (node, change) => {
console.log(`[Transform] ${node.type}: ${change.description}`);
}
});
2. Validate AST before and after:
const beforeAST = parse(originalCode);
const afterAST = parse(transformedCode);
// Compare structure
expect(afterAST.body.length).toBe(beforeAST.body.length);
3. Use TypeScript compiler API for validation:
import * as ts from 'typescript';
function validateTypes(code: string): ts.Diagnostic[] {
const program = ts.createProgram(['temp.ts'], {
noEmit: true,
strict: true
});
return ts.getPreEmitDiagnostics(program);
}
8. Extensions and Challenges
8.1 Beginner Extensions
- Add support for migrating test files alongside source files
- Generate migration report with statistics
- Add dry-run mode that shows changes without applying
8.2 Intermediate Extensions
- Support React Class to Hooks conversion
- Handle monorepo structures with multiple packages
- Add ESLint auto-fix for common issues post-migration
8.3 Advanced Extensions
- Multi-language migration (Python 2 to 3, Vue 2 to 3)
- Machine learning model to predict migration difficulty
- Parallel migration with conflict resolution
9. Real-World Connections
9.1 Industry Tools Using These Patterns
| Tool | Pattern Used | Company |
|---|---|---|
| ts-migrate | Incremental TS migration | Airbnb |
| jscodeshift | AST transformation | |
| react-codemod | Class to Hooks | React Team |
| flow-to-ts | Type system migration | Khan Academy |
9.2 Production Migration Stories
- Airbnb’s TypeScript Migration: 2+ million lines over 2 years using ts-migrate
- Stripe’s React Migration: 500+ class components to hooks with automated testing
- Microsoft’s TypeScript Adoption: Gradual strictness escalation pattern
10. Self-Assessment Checklist
Understanding Verification
- I can explain why leaf modules should be migrated first
- I can describe the difference between syntactic and semantic migration
- I can list at least 3 sources of type inference (JSDoc, usage, AI)
- I can explain why checkpoints are essential for safe migration
- I can describe the lifecycle method to hooks mapping
Implementation Verification
- My analyzer correctly identifies file dependencies
- My planner creates a valid topological order
- Type inference works for simple functions
- Checkpoints are created before each file transformation
- Rollback works when tests fail
- Import statements are updated across the codebase
Integration Verification
- The full migration flow works on a sample project
- AI inference improves type coverage beyond what’s possible with JSDoc alone
- The migration can be paused and resumed
- Progress is visible throughout the migration
11. Completion Criteria
Minimum Viable Completion
- Analyzes JavaScript codebase and creates migration plan
- Renames .js to .ts files
- Adds explicit
anytypes where needed - Creates checkpoints after each file
- Runs tests after each transformation
Full Completion
- Infers types from JSDoc and usage patterns
- Uses AI for complex type inference
- Converts React class components to hooks
- Updates all import statements automatically
- Provides detailed migration report
Excellence (Going Above and Beyond)
- Handles monorepo structures
- Parallel migration with smart ordering
- Machine learning-based difficulty prediction
- Visual diff tool for reviewing changes
- Resume from any checkpoint
This guide was expanded from LEARN_KIRO_CLI_MASTERY.md. For the complete learning path, see the README.