kilocode/refactor-plan/final-refactor-plan-followups.md

Refactor Code Tool: Detailed Task Implementation Plan

Overview

This plan outlines specific tasks to address the architectural and functional issues identified in the refactor code tool. Each task is designed to be independently assigned and executed, with clear starting points and success criteria.

The primary issues to address are:

1. Deprecated components that need replacement
2. Path resolution inconsistencies causing failures
3. Import handling limitations affecting move operations
4. Error handling weaknesses in various operations
5. Code organization that needs consolidation

Phase 1: Path Resolution Standardization

Context: Path handling inconsistencies are causing test failures and unreliable behavior. The resolveFilePath function is deprecated but still widely used, while the newer PathResolver class exists but isn't fully adopted.

Task 1.1: Update RefactorEngine Path Handling

Description: Refactor the RefactorEngine class to use PathResolver exclusively for all path operations.

Steps:

1. Add a PathResolver instance as a class property in RefactorEngine
2. Replace all calls to the deprecated resolveFilePath with pathResolver.resolveAbsolutePath
3. Standardize path normalization with pathResolver.normalizeFilePath
4. Update the diagnostic function to use PathResolver

Files to modify:

• src/core/tools/refactor-code/engine.ts

Success Criteria:

• No more usage of the deprecated resolveFilePath function in engine.ts
• All path operations use the PathResolver instance consistently
• Tests for the engine continue to pass

Task 1.2: Fix Path Resolution in MoveOrchestrator

Description: Address path resolution issues in the MoveOrchestrator class that are causing test failures.

Steps:

1. Review how MoveOrchestrator uses paths and ensure consistent normalization
2. Fix path handling in the verification step (verifyMoveOperation method)
3. Ensure paths in affectedFiles are properly normalized and consistent
4. Improve path error reporting to aid debugging

Files to modify:

• src/core/tools/refactor-code/operations/MoveOrchestrator.ts

Success Criteria:

• The moveOperation.test.ts passes consistently
• affectedFiles paths are properly normalized and consistent
• Diagnostic logs show correct path handling

Phase 2: Import Management Enhancement

Context: When moving functions between files, the necessary imports aren't properly transferred, leading to compilation errors.

Task 2.1: Enhance Import Analysis

Description: Improve the import analysis to better detect dependencies when moving code.

Steps:

1. Enhance SymbolExtractor to analyze and extract all imports needed by a symbol
2. Add dependency tracking for type references and variables
3. Implement better handling of nested type references
4. Add tests for import extraction with complex dependencies

Files to modify:

• src/core/tools/refactor-code/core/SymbolExtractor.ts
• Add/update tests in __tests__ directory

Success Criteria:

• Type imports are properly carried over during move operations
• Nested type dependencies are correctly identified
• Tests pass for complex dependency scenarios

Task 2.2: Update Import Transfer Logic

Description: Fix how imports are transferred during move operations.

Steps:

1. Improve the import transfer logic in MoveOrchestrator.extractAndAddSymbol
2. Ensure imports are properly added to the target file
3. Handle duplicate imports and prevent redundancy
4. Fix relative path adjustments for moved imports

Files to modify:

• src/core/tools/refactor-code/operations/MoveOrchestrator.ts
• src/core/tools/refactor-code/utils/import-manager.ts

Success Criteria:

• The "import { UserProfile } from" is properly added to target files
• Imports maintain correct relative paths after moving
• No duplicate imports are created

Phase 3: Error Handling Improvements

Context: Some operations report success even when internal steps fail, leading to inconsistent behavior.

Task 3.1: Refine Success/Failure Reporting

Description: Improve how operations report success or failure to ensure consistency.

Steps:

1. Review and fix the error handling in MoveOrchestrator.executeMoveOperation
2. Ensure symbol removal failures are properly propagated
3. Standardize error message formats for better diagnostics
4. Fix the success/failure logic in the verification step

Files to modify:

• src/core/tools/refactor-code/operations/MoveOrchestrator.ts
• src/core/tools/refactor-code/engine.ts

Success Criteria:

• Operations accurately report their true success/failure status
• Error messages provide clear, actionable information
• Logs show consistent error handling patterns

Task 3.2: Add Robust Validation and Recovery

Description: Enhance validation steps and add recovery mechanisms for common failures.

Steps:

1. Add more comprehensive validation before executing operations
2. Implement recovery strategies for common failure modes
3. Add better diagnostic information for validation failures
4. Ensure temporary files are cleaned up after failures

Files to modify:

• src/core/tools/refactor-code/engine.ts
• src/core/tools/refactor-code/operations/MoveOrchestrator.ts
• src/core/tools/refactor-code/operations/RemoveOrchestrator.ts

Success Criteria:

• More issues are caught during validation before execution
• Recovery mechanisms handle common failure scenarios
• Error messages provide clear steps to resolve issues

Phase 4: Deprecated Code Removal

Context: Several components are marked as deprecated but still in use, creating confusion and maintenance challenges.

Task 4.1: Replace Deprecated Functions

Description: Replace all deprecated functions with their modern equivalents.

Steps:

1. Replace the deprecated executeMoveOperation in move.ts with direct calls to MoveOrchestrator
2. Remove the deprecated resolveFilePath function and update all callers
3. Update all relevant import statements and references
4. Add deprecated notices to any functions that cannot be immediately removed

Files to modify:

• src/core/tools/refactor-code/operations/move.ts
• src/core/tools/refactor-code/utils/file-system.ts
• Various files that use deprecated functions

Success Criteria:

• No more calls to deprecated functions
• All functionality maintained with modern implementations
• No deprecation warnings in logs

Task 4.2: Update API Documentation

Description: Update API documentation to reflect the current architecture and best practices.

Steps:

1. Document the preferred approaches for path handling
2. Update examples in comments to use the current patterns
3. Add migration guides for any changed APIs
4. Ensure consistent documentation style across the codebase

Files to modify:

• Various files with API documentation
• Add migration guide documentation if needed

Success Criteria:

• Documentation accurately reflects the current architecture
• Examples use current best practices
• Clear guidance is provided for using the APIs

Phase 5: Code Organization Enhancements

Context: The codebase would benefit from better organization and separation of concerns.

Task 5.1: Consolidate Path Operations

Description: Ensure all path-related operations are consolidated in the PathResolver class.

Steps:

1. Review all path operations throughout the codebase
2. Move any remaining path logic to PathResolver
3. Add any missing path utility functions to PathResolver
4. Update callers to use the consolidated methods

Files to modify:

• src/core/tools/refactor-code/utils/PathResolver.ts
• Various files with path operations

Success Criteria:

• All path operations are handled by PathResolver
• No scattered path manipulation logic
• Consistent approach to path handling throughout the codebase

Task 5.2: Enhance Diagnostic Support

Description: Improve diagnostic support for troubleshooting and debugging.

Steps:

1. Create a centralized logging system for operations
2. Add detailed operation status tracking
3. Implement better file state reporting before and after operations
4. Add performance metrics for operations

Files to modify:

• Create new diagnostic utility classes
• Update operations to use enhanced diagnostics

Success Criteria:

• More detailed and consistent diagnostic information
• Easier troubleshooting of operation failures
• Better visibility into operation internals

Phase 6: Testing Enhancements

Context: Some edge cases are not well covered by tests, and test reliability could be improved.

Task 6.1: Improve Test Coverage

Description: Add tests for edge cases and improve existing test reliability.

Steps:

1. Add tests for path handling edge cases
2. Create tests for import handling with complex dependencies
3. Add tests for error recovery scenarios
4. Ensure tests are isolated and don't depend on global state

Files to modify:

• Create new test files
• Update existing test files

Success Criteria:

• Higher test coverage, especially for edge cases
• More reliable test execution
• Better test isolation

Task 6.2: Add Integration Tests

Description: Add comprehensive integration tests for common refactoring scenarios.

Steps:

1. Create integration tests for complete refactoring workflows
2. Test interactions between different operations
3. Add tests for real-world code patterns
4. Ensure tests run in a realistic environment

Files to modify:

• Create new integration test files

Success Criteria:

• End-to-end workflows are properly tested
• Real-world refactoring scenarios are covered
• Tests provide confidence in the entire system

Priority Order and Dependencies

1. Phase 1 (Path Resolution): Should be completed first as it affects all other functionality
2. Phase 3 (Error Handling): High priority as it improves reliability
3. Phase 2 (Import Management): Needed to fix the failing tests completely
4. Phase 4 (Deprecated Code): Can be done after the core functionality is stable
5. Phase 5 (Code Organization): Improves maintainability but doesn't affect functionality
6. Phase 6 (Testing): Should be done incrementally alongside other changes

Implementation Timeline

• Week 1: Complete Phase 1 (Path Resolution)
• Week 2: Complete Phase 3 (Error Handling) and start Phase 2 (Import Management)
• Week 3: Complete Phase 2 and start Phase 4 (Deprecated Code)
• Week 4: Complete Phase 4 and start Phase 5 (Code Organization)
• Week 5: Complete Phase 5 and Phase 6 (Testing)

Expected Outcomes

After completing this refactoring plan:

1. The codebase will be more maintainable with clear separation of concerns
2. Path handling will be consistent and reliable
3. Move operations will properly handle dependencies and imports
4. Error handling will be more robust and informative
5. Tests will provide better coverage and reliability
6. No deprecated code will remain in the codebase

This will result in a more reliable, maintainable, and extensible refactoring tool that meets the needs of its users.