atomctl/specs/002-refactor-ast-gen/research.md

Phase 0: Research Findings

Research Overview

Conducted comprehensive analysis of existing /projects/atomctl/pkg/ast/route/ implementation to understand current architecture, identify improvement opportunities, and establish refactoring strategy.

Key Findings

1. Current Architecture Analysis

File Structure:

• route.go (272 lines): Core parsing logic with mixed responsibilities
• builder.go (155 lines): Template data construction
• render.go (54 lines): Rendering coordination entry point
• renderer.go (23 lines): Template rendering wrapper
• router.go.tpl (47 lines): Go template for code generation

Architecture Pattern: Monolithic design with functional approach, lacking clear component boundaries

2. Comparison with Refactored Provider Module

Aspect	Current Route Module	Refactored Provider Module
Architecture	Monolithic, flat	Component-based, layered
Components	5 files, unclear boundaries	15+ files, clear separation
Error Handling	Simple, uses panic	Comprehensive error collection
Extensibility	Limited	Highly extensible
Test Coverage	Minimal	Comprehensive test strategy
Configuration	Hardcoded	Configurable system

3. Identified Problems

Design Principle Violations:

• DRY: Duplicate import parsing and AST traversal logic with provider module
• SRP: route.go handles parsing, validation, and construction
• OCP: Adding new parameter types requires core code changes
• DIP: Direct dependencies between components

Code Quality Issues:

• Use of panic instead of proper error handling
• Hardcoded paths and package names
• Complex type judgment logic without abstraction
• Insufficient test coverage

4. Refactoring Strategy

Decision: Adopt the successful patterns from pkg/ast/provider refactoring Rationale:

• Proven architecture that SOLID principles
• Maintains backward compatibility
• Provides clear migration path
• Leverages existing shared utilities

Alternatives Considered:

• Minimal fixes to existing code (rejected: doesn't address architectural issues)
• Complete rewrite (rejected: too risky, breaks compatibility)
• Incremental refactoring (selected: balances improvement and stability)

Research-Driven Decisions

1. Architecture Decision

Decision: Component-based architecture following provider patterns Components to Create:

• RouteParser (coordinator)
• CommentParser (annotation parsing)
• ImportResolver (import processing)
• RouteBuilder (route construction)
• RouteValidator (validation logic)
• RouteRenderer (template rendering)

2. Compatibility Decision

Decision: Maintain full backward compatibility Requirements:

• Preserve existing @Router and @Bind annotation syntax
• Keep cmd/gen_route.go interface unchanged
• Ensure generated code output remains identical

3. Testing Strategy Decision

Decision: Test-driven development approach Approach:

• Write comprehensive tests first (contract tests)
• Refactor implementation to make tests pass
• Maintain test coverage throughout refactoring

4. Performance Decision

Decision: Maintain current performance characteristics Targets:

• <2s parsing for typical projects
• Minimal memory overhead
• No performance regression

Implementation Strategy

Phase 1: Design & Contracts

1. Define new component interfaces based on provider patterns
2. Create data models and contracts
3. Establish test scenarios and acceptance criteria

Phase 2: Task Implementation

1. Implement new component architecture
2. Migrate existing logic incrementally
3. Maintain compatibility through testing

Phase 3: Validation

1. Comprehensive testing across all scenarios
2. Performance validation
3. Integration testing with existing systems

Risk Assessment

Low Risk:

• Backward compatibility maintained
• Incremental refactoring approach
• Proven architectural patterns

Medium Risk:

• Complex parameter handling logic migration
• Template system integration
• Error handling standardization

Mitigation Strategies:

• Comprehensive test coverage
• Incremental implementation with validation
• Rollback capability at each stage

Success Criteria

1. Code Quality: Clear separation of concerns, SOLID compliance
2. Maintainability: Component-based architecture with clear boundaries
3. Testability: Comprehensive test coverage with clear contract tests
4. Compatibility: Zero breaking changes to existing functionality
5. Performance: No performance regression

Conclusion

The research confirms that refactoring pkg/ast/route using the successful patterns from pkg/ast/provider is the optimal approach. This will improve code maintainability, testability, and extensibility while preserving all existing functionality.

Decision Status: ✅ APPROVED - Proceed to Phase 1 design