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

# 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

# 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:

# 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:

mise run test

---

Phase 2: Audit Required

Action Items

2.1 Pygame Backend Check

# 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

# 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

# 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:

rm /home/dietpi/src/Mainline/engine/scroll.py

Consolidate legacy modules:

# 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:

rm /home/dietpi/src/Mainline/engine/pipeline/adapters.py (or move to legacy)

---

How to Verify Changes

After making changes, run:

# 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:

# 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