Mainline/docs/LEGACY_CLEANUP_CHECKLIST.md

# Legacy Code Cleanup - Actionable Checklist

## Phase 1: Safe Removals (0 Risk, Run Immediately)

These modules have ZERO dependencies and can be removed without any testing:

### Files to Delete

```bash
# Core modules (402 lines total)
rm /home/dietpi/src/Mainline/engine/emitters.py (25 lines)
rm /home/dietpi/src/Mainline/engine/beautiful_mermaid.py (4107 lines) 
rm /home/dietpi/src/Mainline/engine/pipeline_viz.py (364 lines)

# Test files (2145 bytes)
rm /home/dietpi/src/Mainline/tests/test_emitters.py

# Configuration/cleanup
# Remove from pipeline.py: introspect_pipeline_viz() method calls
# Remove from pipeline.py: introspect_animation() references to pipeline_viz
```

### Verification Commands

```bash
# Verify emitters.py has zero references
grep -r "from engine.emitters\|import.*emitters" /home/dietpi/src/Mainline --include="*.py" | grep -v "__pycache__" | grep -v ".venv"
# Expected: NO RESULTS

# Verify beautiful_mermaid.py only used by pipeline_viz
grep -r "beautiful_mermaid" /home/dietpi/src/Mainline --include="*.py" | grep -v "__pycache__" | grep -v ".venv"
# Expected: Only one match in pipeline_viz.py

# Verify pipeline_viz.py has zero real usage
grep -r "pipeline_viz\|CameraLarge\|PipelineIntrospection" /home/dietpi/src/Mainline --include="*.py" | grep -v "__pycache__" | grep -v ".venv" | grep -v "engine/pipeline_viz.py"
# Expected: Only references in pipeline.py's introspection method
```

### After Deletion - Cleanup Steps

1. Remove these lines from `engine/pipeline.py`:

```python
# Remove method: introspect_pipeline_viz() (entire method)
def introspect_pipeline_viz(self) -> None:
    # ... remove this entire method ...
    pass

# Remove method call from introspect():
self.introspect_pipeline_viz()

# Remove import line:
elif "pipeline_viz" in node.module or "CameraLarge" in node.name:
```

2. Update imports in `engine/pipeline/__init__.py` if pipeline_viz is exported

3. Run test suite to verify:
```bash
mise run test
```

---

## Phase 2: Audit Required

### Action Items

#### 2.1 Pygame Backend Check

```bash
# Find all preset definitions
grep -r "display.*=.*['\"]pygame" /home/dietpi/src/Mainline --include="*.py" --include="*.toml"

# Search preset files
grep -r "display.*pygame" /home/dietpi/src/Mainline/engine/presets.toml
grep -r "pygame" /home/dietpi/src/Mainline/presets.toml

# If NO results: Safe to remove
rm /home/dietpi/src/Mainline/engine/display/backends/pygame.py
# And remove from DisplayRegistry.__init__: cls.register("pygame", PygameDisplay)
# And remove import: from engine.display.backends.pygame import PygameDisplay

# If results exist: Keep the backend
```

#### 2.2 Kitty Backend Check

```bash
# Find all preset definitions
grep -r "display.*=.*['\"]kitty" /home/dietpi/src/Mainline --include="*.py" --include="*.toml"

# Search preset files  
grep -r "display.*kitty" /home/dietpi/src/Mainline/engine/presets.toml
grep -r "kitty" /home/dietpi/src/Mainline/presets.toml

# If NO results: Safe to remove
rm /home/dietpi/src/Mainline/engine/display/backends/kitty.py
# And remove from DisplayRegistry.__init__: cls.register("kitty", KittyDisplay)
# And remove import: from engine.display.backends.kitty import KittyDisplay

# If results exist: Keep the backend
```

#### 2.3 Animation Module Check

```bash
# Search for actual usage of AnimationController, create_demo_preset, create_pipeline_preset
grep -r "AnimationController\|create_demo_preset\|create_pipeline_preset" /home/dietpi/src/Mainline --include="*.py" | grep -v "animation.py" | grep -v "test_" | grep -v ".venv"

# If NO results: Safe to remove
rm /home/dietpi/src/Mainline/engine/animation.py

# If results exist: Keep the module
```

---

## Phase 3: Known Future Removals (Don't Remove Yet)

These modules are marked deprecated and still in use. Plan to remove after their clients are migrated:

### Schedule for Removal

#### After scroll.py clients migrated:
```bash
rm /home/dietpi/src/Mainline/engine/scroll.py
```

#### Consolidate legacy modules:
```bash
# After render.py functions are no longer called from adapters:
# Move render.py to engine/legacy/render.py
# Consolidate render.py with effects/legacy.py

# After layers.py functions are no longer called:
# Move layers.py to engine/legacy/layers.py
# Move effects/legacy.py functions alongside
```

#### After legacy adapters are phased out:
```bash
rm /home/dietpi/src/Mainline/engine/pipeline/adapters.py (or move to legacy)
```

---

## How to Verify Changes

After making changes, run:

```bash
# Run full test suite
mise run test

# Run with coverage
mise run test-cov

# Run linter
mise run lint

# Check for import errors
python3 -c "import engine.app; print('OK')"
```

---

## Summary of File Changes

### Phase 1 Deletions (Safe)

| File | Lines | Purpose | Verify With |
|------|-------|---------|------------|
| engine/emitters.py | 25 | Unused protocols | `grep -r emitters` |
| engine/beautiful_mermaid.py | 4107 | Unused diagram renderer | `grep -r beautiful_mermaid` |
| engine/pipeline_viz.py | 364 | Unused visualization | `grep -r pipeline_viz` |
| tests/test_emitters.py | 2145 bytes | Tests for emitters | Auto-removed with module |

### Phase 2 Conditional

| File | Size | Condition | Action |
|------|------|-----------|--------|
| engine/display/backends/pygame.py | 9185 | If not in presets | Delete or keep |
| engine/display/backends/kitty.py | 5305 | If not in presets | Delete or keep |
| engine/animation.py | 340 | If not used | Safe to delete |

### Phase 3 Future

| File | Lines | When | Action |
|------|-------|------|--------|
| engine/scroll.py | 156 | Deprecated | Plan removal |
| engine/render.py | 274 | Still used | Consolidate later |
| engine/layers.py | 272 | Still used | Consolidate later |

---

## Testing After Cleanup

1. **Unit Tests**: `mise run test`
2. **Coverage Report**: `mise run test-cov`
3. **Linting**: `mise run lint`
4. **Manual Testing**: `mise run run` (run app in various presets)

### Expected Test Results After Phase 1

- No new test failures
- test_emitters.py collection skipped (module removed)
- All other tests pass
- No import errors

---

## Rollback Plan

If issues arise after deletion:

```bash
# Check git status
git status

# Revert specific deletions
git restore engine/emitters.py
git restore engine/beautiful_mermaid.py
# etc.

# Or full rollback
git checkout HEAD -- engine/
git checkout HEAD -- tests/
```

---

## Notes

- All Phase 1 deletions are verified to have ZERO usage
- Phase 2 requires checking presets (can be done via grep)
- Phase 3 items are actively used but marked for future removal
- Keep test files synchronized with module deletions
- Update AGENTS.md after Phase 1 completion