hanzo-tools-refactor¶

Advanced refactoring with LSP/AST support. FAST parallel processing for large codebases.

Installation¶

pip install hanzo-tools-refactor

Or as part of the full toolkit:

pip install hanzo-mcp[tools-all]

Overview¶

hanzo-tools-refactor provides intelligent code refactoring:

rename - Rename symbol across entire codebase
rename_batch - Batch rename multiple symbols
extract_function - Extract code into a new function
extract_variable - Extract expression into a variable
inline - Inline a function or variable
move - Move symbol to another file
change_signature - Modify function parameters
find_references - Find all references to a symbol
organize_imports - Clean up and sort imports

Quick Start¶

# Rename a symbol
refactor(action="rename", file="main.py", line=10, column=5, new_name="newName")

# Batch rename multiple symbols
refactor(
    action="rename_batch",
    renames=[
        {"old": "foo", "new": "bar"},
        {"old": "baz", "new": "qux"}
    ],
    path="./src"
)

# Change function signature
refactor(
    action="change_signature",
    file="utils.py",
    line=15,
    add_parameter={"name": "timeout", "default": "30"}
)

# Find references
refactor(action="find_references", file="models.py", line=25, column=8)

Actions Reference¶

rename¶

Rename a symbol at a specific location.

refactor(
    action="rename",
    file="/path/to/file.py",
    line=42,
    column=10,
    new_name="betterName"
)

Parameters: - file (required): File containing the symbol - line (required): Line number (1-based) - column (required): Column number (1-based) - new_name (required): New name for the symbol

rename_batch¶

Rename multiple symbols across the codebase in parallel.

refactor(
    action="rename_batch",
    renames=[
        {"old": "getUserData", "new": "fetchUserData"},
        {"old": "setUserData", "new": "updateUserData"},
        {"old": "deleteUserData", "new": "removeUserData"}
    ],
    path="./src",
    parallel=True  # Default: true
)

Parameters: - renames (required): List of {old, new} pairs - path: Directory to search (default: current directory) - parallel: Process in parallel (default: true)

extract_function¶

Extract selected code into a new function.

refactor(
    action="extract_function",
    file="/path/to/file.py",
    start_line=20,
    end_line=30,
    new_name="processData"
)

Parameters: - file (required): Source file - start_line (required): First line of code to extract - end_line (required): Last line of code to extract - new_name: Name for the new function

extract_variable¶

Extract an expression into a variable.

refactor(
    action="extract_variable",
    file="/path/to/file.py",
    line=15,
    start_column=10,
    end_column=45,
    new_name="calculatedValue"
)

Parameters: - file (required): Source file - line (required): Line containing the expression - start_column: Start of expression - end_column: End of expression - new_name: Variable name

inline¶

Inline a function or variable at its call sites.

refactor(
    action="inline",
    file="/path/to/file.py",
    line=10,
    column=5
)

Parameters: - file (required): Source file - line (required): Line of the symbol - column (required): Column of the symbol

move¶

Move a symbol to a different file.

refactor(
    action="move",
    file="/path/to/source.py",
    line=15,
    column=6,
    target_file="/path/to/destination.py"
)

Parameters: - file (required): Source file - line (required): Line of the symbol - column (required): Column of the symbol - target_file (required): Destination file

change_signature¶

Modify a function's parameters.

# Add a parameter
refactor(
    action="change_signature",
    file="api.py",
    line=20,
    add_parameter={"name": "timeout", "default": "30", "type": "int"}
)

# Remove a parameter
refactor(
    action="change_signature",
    file="api.py",
    line=20,
    remove_parameter="deprecated_param"
)

# Reorder parameters
refactor(
    action="change_signature",
    file="api.py",
    line=20,
    reorder_parameters=["user_id", "data", "options"]
)

find_references¶

Find all references to a symbol.

refactor(action="find_references", file="models.py", line=10, column=6)

Response:

{
  "symbol": "UserModel",
  "references": [
    {"file": "views.py", "line": 15, "column": 8},
    {"file": "tests/test_models.py", "line": 22, "column": 12}
  ],
  "count": 2
}

organize_imports¶

Clean up and sort imports in a file.

refactor(action="organize_imports", file="main.py")

Parallel Processing¶

The refactor tool uses parallel processing for large-scale operations:

# Parallel is enabled by default
refactor(
    action="rename_batch",
    renames=[...],  # Many renames
    path="./large_codebase",
    parallel=True   # Uses all CPU cores
)

# Disable for sequential processing
refactor(
    action="rename_batch",
    renames=[...],
    parallel=False
)

Preview Mode¶

Preview changes before applying them:

# Preview only - don't apply changes
refactor(
    action="rename",
    file="main.py",
    line=10,
    column=5,
    new_name="newName",
    preview=True
)

Response:

{
  "preview": true,
  "changes": [
    {"file": "main.py", "line": 10, "old": "oldName", "new": "newName"},
    {"file": "utils.py", "line": 25, "old": "oldName", "new": "newName"}
  ],
  "files_affected": 2
}

Examples¶

Safe Symbol Rename¶

# 1. Find all usages first
refs = refactor(action="find_references", file="models.py", line=10, column=5)

# 2. Preview the rename
preview = refactor(
    action="rename",
    file="models.py",
    line=10,
    column=5,
    new_name="BetterName",
    preview=True
)

# 3. Apply the rename
refactor(
    action="rename",
    file="models.py",
    line=10,
    column=5,
    new_name="BetterName"
)

Large-Scale Refactoring¶

# Rename multiple patterns across codebase
refactor(
    action="rename_batch",
    renames=[
        {"old": "v1_api", "new": "legacy_api"},
        {"old": "v2_api", "new": "current_api"},
        {"old": "v3_api", "new": "api"}
    ],
    path="./src",
    parallel=True
)

Extract Common Code¶

# Extract duplicated logic into a function
refactor(
    action="extract_function",
    file="handlers.py",
    start_line=45,
    end_line=60,
    new_name="validate_and_process"
)

Best Practices¶

Always preview first - Use preview=True for important refactors
Run tests after - Verify refactoring didn't break functionality
Use batch operations - rename_batch is faster than individual renames
Commit before refactoring - Have a clean git state to easily revert
Combine with LSP - Use lsp tool for initial symbol discovery