📘 Technical Design 005 — Dead Code Removal and Cleanup¶

🧭 1. Summary¶

Remove unused and superseded code to reduce maintenance burden and keep the alpha-stage codebase lean and focused. This includes removing legacy shims, unused imports, dead utility functions, and outdated helper methods that have been superseded by the new unified API structure.

At a glance:

• Immediate removal of zero-reference symbols without deprecation period
• Clean up legacy shims that duplicate builder/facade functionality
• Remove outdated test utilities and temporary scaffolding code
• Update documentation and examples to remove references to deleted code
• Maintain test coverage by migrating tests to use current APIs

📚 2. Context and Problem Statement¶

The reflection subsystem has undergone significant refactoring through TD-003 and TD-004, resulting in: - Unified facade-based APIs (resolve/scan/hints/annotations/invoke/create) - Modular internal structure with focused components - Legacy code paths that are no longer used or needed

This accumulated technical debt increases maintenance burden and creates confusion about which APIs to use.

2.1 Goals¶

1. Reduce maintenance burden: Remove unused code that requires ongoing maintenance
2. Improve clarity: Eliminate confusion between old and new API patterns
3. Lean codebase: Keep alpha-stage code focused on current architecture
4. Clean slate: Prepare foundation for future development without legacy distractions

2.2 Non-Goals (Out of Scope)¶

• Changing current public APIs or their behavior
• Performance optimizations beyond removing unused code paths
• Adding new features or capabilities
• Backwards compatibility (alpha stage allows immediate removal)

2.3 Assumptions and Constraints¶

• Alpha stage allows immediate removal without deprecation period
• All functionality is preserved through current APIs
• Test coverage must be maintained through migration to current APIs
• No external consumers depend on internal/legacy symbols

🧩 3. Design Overview¶

Systematic identification and removal of dead code through automated analysis and manual verification, organized by category for safe, reviewable changes.

3.1 Dead Code Categories¶

3.2 Removal Strategy¶

3.3 Removal/Deprecation Policy¶

• Immediate removal: No deprecation period (alpha stage policy)
• No aliasing: Remove symbols completely rather than creating aliases
• Clean migration: Update all references to use current APIs in same PR
• Scoped PRs: Group removals by subsystem for easier review and rollback

📐 4. Detailed API Surface¶

4.1 Identification Methods¶

# Zero-reference detection
grep -r "def function_name\|class ClassName" src/ tests/
grep -r "function_name\|ClassName" src/ tests/ --exclude-from=<definition_files>

# Import analysis
python -c "import ast; # analyze import usage patterns"

# TODO/FIXME analysis
grep -r "TODO\|FIXME\|XXX\|HACK" src/ tests/ docs/

4.2 Removal Process¶

# Example systematic removal process
1. Identify dead symbol: grep -r "function_name" --include="*.py"
2. Verify zero usage: ensure no imports or references
3. Remove definition and any related code
4. Update imports in affected files
5. Run tests to verify no breakage
6. Update documentation if referenced

4.3 Migration Patterns¶

# Legacy pattern → Current API migration examples

# Before: Direct helper usage
from loryth.common.reflection.legacy_helper import old_function
result = old_function(param)

# After: Use unified facade
from loryth.common.reflection import reflection
result = reflection.resolve.type(param)

⚙️ 5. Semantics¶

5.1 Detection Criteria¶

• Zero references: No imports, function calls, or inheritance relationships
• Superseded functionality: Same capability available through current unified API
• Test-only utilities: Helper functions only used in deprecated test patterns

5.2 Safety Checks¶

• All tests pass after removal
• No import errors in any module
• Documentation builds without dead links
• Examples execute successfully

5.3 Rollback Strategy¶

• Each PR scoped to single subsystem for atomic rollback
• Git history preserves removed code for potential restoration
• Clear commit messages document what was removed and why

🧪 6. Examples (concise)¶

6.1 Zero-Reference Symbol Removal¶

# REMOVE: Unused utility function
def unused_helper_function(param):
    """This function has no callers in the codebase."""
    return param.upper()

# No migration needed - truly unused

6.2 Legacy Shim Replacement¶

# REMOVE: Legacy shim
def resolve_type_legacy(type_name: str):
    """Legacy helper - use reflection.resolve.type() instead."""
    return reflection.resolve_type(type_name)

# MIGRATE: Update all usage sites
# Old: result = resolve_type_legacy("MyClass")
# New: result = reflection.resolve.type("MyClass")

6.3 Outdated TODO Cleanup¶

# REMOVE: Completed TODO
class HighFidelityTypeHintProvider:
    def process_hints(self, obj):
        # TODO: Add caching support - DONE in TD-004
        return self._process_with_cache(obj)

✅ 7. Acceptance Criteria¶

• All zero-reference symbols identified and removed
• Legacy shims replaced with current API usage
• Test coverage maintained or improved
• All tests pass after removal
• Documentation updated to remove dead references
• Examples execute without errors
• No import errors across codebase
• CHANGELOG updated with removal summary
• Performance maintained (no regression from cleanup)

🚀 8. Rollout and Migration¶

Phase 1: Analysis and Planning (1 day)¶

• Run automated dead code detection
• Manually categorize findings
• Create removal plan with prioritized order

Phase 2: Zero-Reference Removal (1 day)¶

• Remove clearly unused functions and classes
• Clean up unused imports
• Verify tests pass

Phase 3: Legacy Shim Migration (2 days)¶

• Identify superseded helper functions
• Update usage sites to current APIs
• Remove old implementations

Phase 4: Documentation Cleanup (1 day)¶

• Update examples and guides
• Remove references to deleted symbols
• Update CHANGELOG

⚠️ 9. Risks and Mitigations¶

• Risk: Accidentally removing code still used in non-obvious ways
• Mitigation: Multi-step verification (grep, static analysis, test runs)
• Risk: Breaking tests during migration
• Mitigation: Run test suite after each removal; atomic PRs for rollback
• Risk: Documentation becomes outdated
• Mitigation: Include docs update in same PR as code removal
• Risk: Future need for removed functionality
• Mitigation: Git history preserves code; alpha policy allows restoration if needed

📈 10. Progress¶

Legend: [x] = complete, [ ] = pending

• Identify zero-reference symbols via automated analysis
• Catalog legacy shims and superseded helpers
• Remove unused imports and dead utility functions
• Migrate legacy API usage to current facades
• Clean up outdated TODO/FIXME comments
• Update test utilities to use current patterns
• Remove temporary scaffolding and debug code
• Update documentation and examples
• Verify all tests pass and no import errors
• Update CHANGELOG with removal summary

📝 11. Changelog¶

• 2025-09-28 — TD-005 Complete: Successfully identified and removed dead code including unused imports (sys from high_fidelity_type_hints.py, logging from augmentation.py), cleaned up outdated comments (FIXME in python_import_resolver.py, TODO in member_types/base.py). All 153 tests pass.
• 2025-09-28 — Initial draft using proper template format; identified removal categories and systematic approach

📖 12. Glossary¶

• Dead Code: Code that is defined but never executed or referenced
• Legacy Shim: Helper function that duplicates functionality available in current APIs
• Zero-reference Symbol: Function or class with no imports or usage in codebase
• Alpha Stage Policy: Development phase allowing immediate breaking changes without deprecation