Automated Refactoring Engine

Relevant source files

The following files were used as context for generating this wiki page:

• refactoring_engine.py
• refactor_handlers.py
• repo_analyzer.py
• code_review_2025_10/REFACTORING_PLAN.md
• GUIDES/ARCHITECTURE.md

The Automated Refactoring Engine is a core system within CodeBot designed to perform safe structural changes to Python code. It enables the decomposition of monolithic files, extraction of repeated code, and transformation of functional code into object-oriented structures. The engine utilizes Abstract Syntax Tree (AST) analysis to understand code relationships, ensuring that refactoring proposals maintain functional integrity while improving maintainability.

This system operates through a multi-stage pipeline: code analysis, semantic grouping, proposal generation, and validation. It is integrated into the Telegram bot interface, allowing users to trigger refactoring operations on their saved snippets and review structural suggestions before application.

Sources: refactoring_engine.py:1-12, refactor_handlers.py:1-40

System Architecture

The refactoring system is divided into a backend analysis engine (RefactoringEngine) and a frontend interaction layer (RefactorHandlers). The engine focuses on the logic of code transformation, while the handlers manage user state, file retrieval via the infrastructure facade, and the interactive approval workflow.

High-Level Component Interaction

The following diagram illustrates how a user request flows from the Telegram UI through the analysis engine and back to the storage layer.

Core Engine Components

The engine relies on two primary classes to process code: CodeAnalyzer for parsing and RefactoringEngine for transformation logic.

CodeAnalyzer

The CodeAnalyzer uses the ast module to perform deep inspection of the source code. It identifies functions, classes, decorators, docstrings, and global variables. A critical feature of the analyzer is its ability to identify "sections" based on markers in the comments (e.g., # 1) USER MANAGEMENT), which helps preserve semantic cohesion during file splitting.

Key responsibilities include:

• AST Parsing: Converting raw code into an Abstract Syntax Tree.
• Dependency Calculation: Determining which functions call others to keep related logic together.
• Complexity Metrics: Calculating cyclomatic complexity to identify refactoring candidates.
• Section Identification: Mapping code lines to domain "slugs" like users, finance, or api_clients.

Sources: refactoring_engine.py:73-183

RefactoringEngine

The RefactoringEngine implements the logic for different refactoring types. It uses the data provided by the analyzer to group code and generate new file structures.

Feature	Description
Domain Priority	Uses CANONICAL_DOMAIN_PRIORITY to rank domain importance (e.g., users > finance).
Oversplitting Protection	Configuration for preferred_min_groups and preferred_max_groups to prevent excessive file creation.
Collocation	Automatically assigns classes to the most relevant function group to keep entities and their logic in the same module.
Circular Import Resolution	Detects Strong Components (SCC) using Tarjan's algorithm and resolves cycles by merging modules or creating a shared_core layer.

Sources: refactoring_engine.py:186-210, refactoring_engine.py:848-950

Refactoring Types and Logic

The engine supports several specific refactoring strategies, defined by the RefactorType enum.

Function Splitting (Decomposition)

When splitting a file, the engine groups functions using a multi-pass algorithm:

1. Section Pass: Groups by identified comment headers.
2. Domain Pass: Classifies functions as io, compute, or helpers.
3. Prefix Pass: Groups by naming conventions (e.g., functions starting with user_).
4. Affinity Pass: Merges groups based on dependency links and name similarity.

Sources: refactoring_engine.py:315-410

OOP Transformation

The CONVERT_TO_CLASSES type transforms top-level functions into methods within a service class. The engine generates an __init__ method and injects the self parameter into function signatures, updating internal calls where necessary.

Sources: refactoring_engine.py:535-585

Dependency and Circular Import Management

To ensure that refactored code remains runnable, the engine performs automated import injection and cycle resolution.

Import Injection Logic

When a file is split, the engine identifies which symbols (functions or classes) are now in different modules. It then injects relative imports (e.g., from .users import User) into the new files.

Cycle Resolution (Tarjan's Algorithm)

If the engine detects a circular dependency between new modules, it attempts to resolve it using two strategies:

1. Merging: If the modules are closely related and not "canonical" domains, they are merged back into a single file.
2. Shared Core: If both are canonical (e.g., users and finance), it creates a _shared_core.py file using lazy imports via importlib to break the runtime cycle.

Sources: refactoring_engine.py:848-930

User Interaction and Handlers

The RefactorHandlers class provides the interface for the Telegram bot. It manages the state of "pending proposals" to allow users to preview changes before they are committed to the database.

Refactoring Workflow

Metadata Storage

When a refactoring is approved, the system saves metadata about the operation, including the original file name, the new files created, and a summary of the changes. This is performed via the insert_refactor_metadata call in the infrastructure facade.

Sources: refactor_handlers.py:438-456

Summary

The Automated Refactoring Engine provides a robust framework for managing technical debt within the CodeBot repository. By combining AST-based code analysis with sophisticated grouping algorithms and circular dependency resolution, it allows for the safe decomposition of large modules into clean, domain-driven architectures. Its integration with the Telegram bot ensures that these powerful developer tools are accessible through a simple, interactive chat interface.

Sources: code_review_2025_10/REFACTORING_PLAN.md:100-140, refactor_handlers.py:450-465