# TypeScript Migration Checklist

**Issue:** #6 - Convert JavaScript to TypeScript
**Reference:** See `typescript-architecture.md` for detailed architecture

---

## Pre-Migration Setup

### Environment Setup
- [ ] Install TypeScript: `npm install --save-dev typescript @types/node`
- [ ] Install type definitions: `npm install --save-dev @types/jest`
- [ ] Install TS tooling: `npm install --save-dev ts-jest ts-node`
- [ ] Install TypeScript ESLint: `npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin`
- [ ] Create `tsconfig.json` (copy from architecture doc)
- [ ] Create `tsconfig.build.json` (copy from architecture doc)
- [ ] Update `jest.config.js` → `jest.config.ts`
- [ ] Update ESLint config for TypeScript
- [ ] Update `package.json` scripts

### Verify Setup
- [ ] Run `npx tsc --version` (should show v5.3+)
- [ ] Run `npx tsc --noEmit` (should compile without errors initially)
- [ ] Run `npm run type-check` script
- [ ] Verify path aliases work in IDE

---

## Phase 1: Foundation (Days 1-3)

### Type Definitions
- [ ] Create `src/types/` directory
- [ ] Create `src/types/core.types.ts`
  - [ ] `Position` interface
  - [ ] `Square` interface
  - [ ] `Color` type
  - [ ] `AlgebraicNotation` type
  - [ ] `FEN` and `PGN` types
  - [ ] `Direction` interfaces
  - [ ] `BoardGrid` type
  - [ ] `CastlingRights` interface
- [ ] Create `src/types/piece.types.ts`
  - [ ] `PieceType` enum
  - [ ] `IPiece` interface
  - [ ] `IBoard` interface
  - [ ] `PromotionPiece` type
- [ ] Create `src/types/game.types.ts`
  - [ ] `GameStatus` enum
  - [ ] `DrawReason` enum
  - [ ] `IGameState` interface
  - [ ] `GameConfig` interface
  - [ ] `TimeControl` interface
- [ ] Create `src/types/move.types.ts`
  - [ ] `SpecialMove` enum
  - [ ] `Move` interface
  - [ ] `MoveResult` interface
  - [ ] `MoveError` enum
- [ ] Create `src/types/ui.types.ts`
  - [ ] `DOMElementId` enum
  - [ ] `GameEvent` enum
  - [ ] Event payload types
  - [ ] `IEventBus` interface
- [ ] Create `src/types/index.ts` (barrel export)
- [ ] **Validation:** `tsc --noEmit` succeeds on types

### Utilities Migration
- [ ] Create `src/utils/` directory
- [ ] Migrate `Constants.ts`
  - [ ] Convert constants to enums/types
  - [ ] Add type exports
  - [ ] Update imports to use types
  - [ ] Test compilation
- [ ] Migrate `Helpers.ts`
  - [ ] Add function parameter types
  - [ ] Add return types
  - [ ] Add JSDoc comments
  - [ ] Test compilation
- [ ] Migrate `EventBus.ts`
  - [ ] Implement `IEventBus` interface
  - [ ] Use generic types for events
  - [ ] Add type-safe event handlers
  - [ ] Test compilation
- [ ] **Validation:** Run `npm test` on utilities

---

## Phase 2: Core Models (Days 4-7)

### Piece Classes
- [ ] Create `src/pieces/` directory
- [ ] Migrate `Piece.ts` (base class)
  - [ ] Implement `IPiece` interface
  - [ ] Make abstract where appropriate
  - [ ] Add type annotations to all methods
  - [ ] Add generic constraints
  - [ ] Test compilation
  - [ ] Run tests: `npm test Piece`
- [ ] Migrate `Pawn.ts`
  - [ ] Extend typed `Piece` class
  - [ ] Type all methods
  - [ ] Handle en passant typing
  - [ ] Test compilation
  - [ ] Run tests: `npm test Pawn`
- [ ] Migrate `Knight.ts`
  - [ ] Extend typed `Piece` class
  - [ ] Type movement methods
  - [ ] Test compilation
  - [ ] Run tests: `npm test Knight`
- [ ] Migrate `Bishop.ts`
  - [ ] Extend typed `Piece` class
  - [ ] Type sliding moves
  - [ ] Test compilation
  - [ ] Run tests: `npm test Bishop`
- [ ] Migrate `Rook.ts`
  - [ ] Extend typed `Piece` class
  - [ ] Type sliding moves
  - [ ] Test compilation
  - [ ] Run tests: `npm test Rook`
- [ ] Migrate `Queen.ts`
  - [ ] Extend typed `Piece` class
  - [ ] Type sliding moves
  - [ ] Test compilation
  - [ ] Run tests: `npm test Queen`
- [ ] Migrate `King.ts`
  - [ ] Extend typed `Piece` class
  - [ ] Type castling methods
  - [ ] Test compilation
  - [ ] Run tests: `npm test King`

### Game Models
- [ ] Create `src/game/` directory
- [ ] Migrate `Board.ts`
  - [ ] Implement `IBoard` interface
  - [ ] Type `grid` as `BoardGrid`
  - [ ] Type all methods
  - [ ] Add null safety checks
  - [ ] Test compilation
  - [ ] Run tests: `npm test Board`
- [ ] Migrate `GameState.ts`
  - [ ] Implement `IGameState` interface
  - [ ] Type all properties
  - [ ] Type all methods
  - [ ] Use enums for status
  - [ ] Test compilation
  - [ ] Run tests: `npm test GameState`

### Phase 2 Validation
- [ ] All piece tests pass
- [ ] All game model tests pass
- [ ] No implicit `any` types (check with ESLint)
- [ ] `npm run type-check` succeeds
- [ ] Code coverage maintained (80%+)

---

## Phase 3: Engine & Controllers (Days 8-10)

### Chess Engine
- [ ] Create `src/engine/` directory
- [ ] Migrate `MoveValidator.ts`
  - [ ] Import all types
  - [ ] Type all static methods
  - [ ] Type validation results
  - [ ] Add null safety
  - [ ] Test compilation
  - [ ] Run tests: `npm test MoveValidator`
- [ ] Migrate `SpecialMoves.ts`
  - [ ] Import all types
  - [ ] Type special move handlers
  - [ ] Type castling logic
  - [ ] Type en passant logic
  - [ ] Type promotion logic
  - [ ] Test compilation
  - [ ] Run tests: `npm test SpecialMoves`

### Controllers
- [ ] Create `src/controllers/` directory
- [ ] Migrate `GameController.ts`
  - [ ] Import all types
  - [ ] Type constructor config
  - [ ] Type event handlers
  - [ ] Type move methods
  - [ ] Type game state methods
  - [ ] Add return type annotations
  - [ ] Test compilation
  - [ ] Run tests: `npm test GameController`
- [ ] Migrate `DragDropHandler.ts`
  - [ ] Import UI types
  - [ ] Type DOM event handlers
  - [ ] Type drag state
  - [ ] Type drop validation
  - [ ] Test compilation
  - [ ] Run tests: `npm test DragDropHandler`

### Phase 3 Validation
- [ ] All engine tests pass
- [ ] All controller tests pass
- [ ] Integration tests pass
- [ ] No type errors in dependencies
- [ ] `npm run lint` succeeds
- [ ] Code coverage maintained

---

## Phase 4: Views & Integration (Days 11-14)

### Views
- [ ] Create `src/views/` directory
- [ ] Migrate `BoardRenderer.ts`
  - [ ] Import all types
  - [ ] Type render methods
  - [ ] Type DOM manipulation
  - [ ] Type event binding
  - [ ] Use `DOMElementId` enum
  - [ ] Test compilation
  - [ ] Run tests: `npm test BoardRenderer`

### Main Entry Point
- [ ] Migrate `main.ts`
  - [ ] Import all typed modules
  - [ ] Type initialization logic
  - [ ] Type event setup
  - [ ] Test compilation
  - [ ] Manual testing in browser

### Build Configuration
- [ ] Configure production build
  - [ ] Verify `tsconfig.build.json`
  - [ ] Test build: `npm run build:prod`
  - [ ] Check output in `dist/`
  - [ ] Verify source maps
- [ ] Update HTML
  - [ ] Update script references to `dist/main.js`
  - [ ] Test loading in browser
  - [ ] Verify no console errors
- [ ] Configure bundler (if needed)
  - [ ] Install Rollup/Webpack for TypeScript
  - [ ] Configure bundler
  - [ ] Test bundled output

### Testing Migration
- [ ] Migrate test files to TypeScript
  - [ ] Rename `.test.js` → `.test.ts`
  - [ ] Add type imports
  - [ ] Type test data
  - [ ] Type mock objects
  - [ ] Run all tests: `npm test`
- [ ] Update test configuration
  - [ ] Verify `jest.config.ts`
  - [ ] Test coverage: `npm run test:coverage`
  - [ ] Verify 80%+ coverage maintained

### Documentation
- [ ] Generate API documentation
  - [ ] Install `typedoc`: `npm install --save-dev typedoc`
  - [ ] Configure TypeDoc
  - [ ] Generate docs: `npx typedoc`
- [ ] Update README.md
  - [ ] Add TypeScript section
  - [ ] Update build instructions
  - [ ] Update development workflow
- [ ] Update inline documentation
  - [ ] Add TSDoc comments to public APIs
  - [ ] Document complex type definitions
  - [ ] Add usage examples

### Phase 4 Validation
- [ ] All tests pass (unit + integration + E2E)
- [ ] Production build succeeds
- [ ] Application runs in browser
- [ ] No console errors
- [ ] No TypeScript errors
- [ ] No ESLint errors
- [ ] Code coverage 80%+
- [ ] Documentation generated

---

## Final Cleanup & Release

### Remove Legacy Code
- [ ] Delete `js/` directory (after confirming all migrated)
- [ ] Remove temporary `.d.ts` files
- [ ] Clean up old build artifacts
- [ ] Update `.gitignore` for TypeScript

### Quality Checks
- [ ] Run full test suite: `npm test`
- [ ] Run coverage: `npm run test:coverage`
- [ ] Run linting: `npm run lint`
- [ ] Run type checking: `npm run type-check`
- [ ] Run production build: `npm run build`
- [ ] Manual testing checklist:
  - [ ] Start new game
  - [ ] Make legal moves
  - [ ] Attempt illegal moves (should prevent)
  - [ ] Test special moves (castling, en passant, promotion)
  - [ ] Test check/checkmate detection
  - [ ] Test undo/redo
  - [ ] Test move history display
  - [ ] Test captured pieces display
  - [ ] Test game save/load
  - [ ] Test resignation
  - [ ] Test draw offer/accept

### Performance Testing
- [ ] Measure bundle size: `du -sh dist/main.js`
- [ ] Compare to JS version
- [ ] Measure load time
- [ ] Measure move performance (should be <10ms)
- [ ] Check memory usage

### Documentation Review
- [ ] README.md complete
- [ ] Architecture doc reviewed
- [ ] Migration checklist reviewed
- [ ] API documentation accurate
- [ ] All ADRs documented

### Deployment
- [ ] Tag release: `git tag v2.0.0-typescript`
- [ ] Update CHANGELOG.md
- [ ] Create release notes
- [ ] Deploy to production
- [ ] Monitor for errors

---

## Success Criteria

All items must be checked before considering migration complete:

### Technical
- [ ] Zero TypeScript compilation errors
- [ ] Zero ESLint errors
- [ ] Zero runtime errors in browser console
- [ ] 100% of tests passing
- [ ] 80%+ code coverage maintained
- [ ] No implicit `any` types (verify with `noImplicitAny`)
- [ ] Production build succeeds

### Functional
- [ ] All chess rules enforced correctly
- [ ] All UI interactions work
- [ ] Game state persists correctly
- [ ] Move history accurate
- [ ] Special moves work (castle, en passant, promotion)
- [ ] Check/checkmate detection works
- [ ] Undo/redo works

### Developer Experience
- [ ] Full IDE autocomplete
- [ ] Type errors are clear and actionable
- [ ] Refactoring is safe (rename/move operations)
- [ ] Build time <10 seconds
- [ ] Test execution <5 seconds

### Documentation
- [ ] Architecture documented
- [ ] Migration process documented
- [ ] API documentation generated
- [ ] README updated
- [ ] All type definitions documented

---

## Rollback Plan

If migration must be abandoned:

1. **Immediate Rollback:**
   - [ ] Switch HTML to reference `js/main.js` instead of `dist/main.js`
   - [ ] Verify old JS version still works
   - [ ] Document reason for rollback

2. **Partial Migration Preservation:**
   - [ ] Keep `src/types/` directory (useful for future attempts)
   - [ ] Keep successfully migrated modules
   - [ ] Document what was completed
   - [ ] Create hybrid build (JS + TS)

3. **Full Rollback:**
   - [ ] Remove `tsconfig.json` and `tsconfig.build.json`
   - [ ] Remove TypeScript dependencies
   - [ ] Delete `src/` directory
   - [ ] Restore original `package.json` scripts
   - [ ] Document lessons learned

---

## Notes & Tips

### Common Issues

**Issue:** Path aliases not working in IDE
- **Solution:** Restart TypeScript server in VS Code (Cmd+Shift+P → "TypeScript: Restart TS Server")

**Issue:** Circular dependency errors
- **Solution:** Use interfaces instead of classes in type definitions; use dependency injection

**Issue:** Type inference too broad
- **Solution:** Add explicit type annotations; use `as const` for literals

**Issue:** DOM types not found
- **Solution:** Ensure `"lib": ["DOM"]` is in `tsconfig.json`

### Best Practices

1. **Commit frequently** - after each file migration
2. **Test before moving on** - don't migrate next file until current tests pass
3. **Use type inference** - don't over-annotate; let TypeScript infer when possible
4. **Avoid `any`** - use `unknown` if truly unknown type
5. **Document complex types** - add comments for non-obvious type choices
6. **Pair program** - complex type challenges benefit from two perspectives

### Time Estimates

- Phase 1: 3 days
- Phase 2: 4 days
- Phase 3: 3 days
- Phase 4: 4 days
- **Total: 14 days (2-3 weeks)**

Adjust based on team size and TypeScript experience.

---

## Migration Log

Document issues, decisions, and learnings during migration:

| Date | Phase | Issue | Resolution | Notes |
|------|-------|-------|------------|-------|
| | | | | |
| | | | | |
| | | | | |

---

**End of Checklist**
