Refactor RecursiveImportTransformer to reduce complexity and improve maintainability

[coderabbitai]

Problem

The RecursiveImportTransformer in crates/cribo/src/code_generator/import_transformer.rs (1899 lines) suffers from high complexity and poor separation of concerns, making it difficult to understand, test, and maintain.

Current Issues

• Monolithic design: Single large struct handles multiple concerns (import tracking, expression transformation, namespace handling)
• Tight coupling: State tracking and transformation logic are intertwined
• High complexity: Multiple transformation methods with complex conditional logic
• Poor testability: Difficult to unit test individual components
• Repetitive code: Lots of boilerplate AST node creation

Proposed Architectural Improvements

1. Implement Visitor Pattern

• Extract separate visitor classes for different transformation concerns:
  • ImportVisitor for import statement transformations
  • ExpressionVisitor for expression transformations
  • NamespaceVisitor for namespace object handling

2. Create Transformation Context

• Extract state tracking into a dedicated TransformationContext struct:
  • Import aliases (import_aliases)
  • Local variables (local_variables)
  • Module-specific flags (is_entry_module, is_wrapper_init)
  • Symbol renames and deferred imports

3. Use Builder Pattern for AST Construction

• Create helper builder methods to reduce repetitive AST node creation:
  • AstBuilder::create_assignment()
  • AstBuilder::create_attribute_access()
  • AstBuilder::create_namespace_object()

4. Implement State Machine for Module States

• Model module states (entry, wrapper, inlined) with clear state transitions
• Use enum or trait-based approach to clarify conditional behaviors
• Reduce complex nested conditionals

5. Add Comprehensive Unit Tests

• Test each modular component independently
• Cover edge cases in import resolution
• Test namespace creation and symbol rewriting
• Validate AST transformations

Implementation Plan

1. Phase 1: Extract TransformationContext and basic visitor structure
2. Phase 2: Implement specific visitor classes for each concern
3. Phase 3: Add AST builder helpers
4. Phase 4: Implement state machine for module handling
5. Phase 5: Add comprehensive test coverage

References

• PR: refactor: split the code_generator.rs and remove lib+dead code #171
• Original Discussion: refactor: split the code_generator.rs and remove lib+dead code #171 (comment)
• File: crates/cribo/src/code_generator/import_transformer.rs (lines 1-1899)

Benefits

• Improved maintainability: Clearer separation of concerns
• Better testability: Individual components can be unit tested
• Enhanced readability: Smaller, focused methods and classes
• Reduced complexity: State machine eliminates nested conditionals
• Easier debugging: Isolated transformation logic