[MEDIUM] Refactor large files for better maintainability

[forest6511]

🟡 Priority: MEDIUM

Problem

Several core files violate Single Responsibility Principle and exceed maintainability thresholds:

internal/core/downloader.go:  1,543 lines ⚠️
cmd/gdl/main.go:              1,481 lines ⚠️
internal/recovery/advisor.go:   994 lines ⚠️

Industry guideline: Files >500 lines become difficult to maintain and test.

Impact

• Priority: 🟡 Medium
• Effort: Large (1-2 weeks)
• Benefit: Improved maintainability, easier testing, better code organization

Current Issues

1. Cognitive Load: Difficult to understand entire file scope
2. Testing Complexity: Large files require large test files
3. Merge Conflicts: More likely in frequently-modified large files
4. Code Navigation: Harder to find specific functionality

Proposed Refactoring

1. internal/core/downloader.go (1,543 lines → ~400 lines × 4 files)

Split into:

• downloader.go - Core Downloader struct and public API (~400 lines)
• http_download.go - HTTP-specific download logic (~300 lines)
• resume_download.go - Resume functionality (~300 lines)
• validation.go - Request validation and pre-checks (~250 lines)
• helpers.go - Utility functions (~250 lines)

Benefits:

• Clearer separation of concerns
• Easier to test individual components
• Better code discoverability

2. cmd/gdl/main.go (1,481 lines → ~300 lines × 5 files)

Split into:

• main.go - Entry point and core CLI setup (~200 lines)
• download.go - Download command implementation (~300 lines)
• plugin_commands.go - Plugin subcommands (~250 lines)
• flags.go - Flag definitions and parsing (~300 lines)
• progress.go - Progress display logic (~250 lines)
• helpers.go - Utility functions (~180 lines)

Benefits:

• Plugin commands separated from download logic
• Easier to add new subcommands
• Better testability for each command

3. internal/recovery/advisor.go (994 lines → ~300 lines × 3 files)

Split into:

• advisor.go - Core RecoveryAdvisor and analysis (~400 lines)
• actions.go - RecoveryAction types and definitions (~300 lines)
• strategies.go - Recovery strategy implementations (~294 lines)

Benefits:

• Action definitions separated from advisor logic
• Easier to add new recovery strategies

Implementation Approach

Phase 1: Safe Extraction (Week 1)

1. Create new files with extracted code
2. Ensure all tests pass after each extraction
3. Update imports across the codebase
4. No functional changes, pure refactoring

Phase 2: Optimization (Week 2)

1. Identify duplicated code across new files
2. Extract common patterns
3. Improve naming and documentation
4. Verify test coverage maintained

Risks & Mitigation

• Risk: Breaking existing functionality
  • Mitigation: Run full test suite after each extraction
• Risk: Import cycles
  • Mitigation: Careful planning of dependencies
• Risk: Breaking external API usage
  • Mitigation: Public API remains unchanged (internal only)

Acceptance Criteria

• No file >800 lines (hard limit)
• Target: Most files <500 lines
• All tests pass
• Test coverage maintained (≥current levels)
• No breaking changes to public API
• Documentation updated for new file structure
• CI/CD passes

Testing Strategy

• Run tests after each file extraction
• Verify integration tests pass
• Check examples still work
• Benchmark performance (no regressions)

Non-Goals

• ❌ Not adding new features during refactoring
• ❌ Not changing public APIs
• ❌ Not optimizing performance (separate effort)

Related Issues

• May help with: #[resume] - Clearer structure for resume integration
• May help with: #[protocol handlers] - Better organization for protocol routing