Import Surgeon

Precision import refactoring tool — rewrite, migrate, and sanitize Python imports project-wide with safety and accuracy.

⚡ Quick Start

Prerequisites

• Python 3.8+
• Git initialized repository (recommended for safety)

Installation

# Install from source
pip install .

# Or for development
pip install -e ".[dev]"

Usage in 5 Seconds

Move MyClass from legacy.utils to core.models and apply changes immediately:

import-surgeon --old-module legacy.utils --new-module core.models --symbols MyClass --apply --rewrite-dotted

Before & After

Input (src/main.py):

from legacy.utils import MyClass

def main():
    obj = MyClass()

Output:

from core.models import MyClass

def main():
    obj = MyClass()

✨ Features

🛡️ Core Capabilities

• AST-Powered: Uses LibCST for syntax-aware refactoring, avoiding regex pitfalls.
• Dotted Rewrite: Updates direct usages like legacy.utils.MyClass() to core.models.MyClass() with --rewrite-dotted.
• Batch Migrations: define complex moves in a migrations.yaml file.
• Rollback: Automatic backup generation and one-command rollback (--rollback).

🚀 Performance & Workflow

• Parallel Processing: Multi-core support with --jobs for large codebases.
• Interactive Mode: TUI for selecting migrations via --interactive.
• Git Integration: Optional clean-repo checks and auto-commit functionality.
• Formatting: Integrated black and isort support via --format.

🛠️ Configuration

CLI Arguments

YAML Configuration (migrate.yaml)

For batch operations, use a configuration file:

migrations:
  - old_module: "legacy.db"
    new_module: "core.database"
    symbols: ["Connection", "Cursor"]
  - old_module: "utils.string"
    new_module: "common.text"
    symbols: ["slugify"]

Run with:

import-surgeon --config migrate.yaml --apply

🏗️ Architecture

Directory Structure

src/import_surgeon/
├── cli.py               # Entry point and argument parsing
└── modules/
    ├── analysis.py      # AST analysis logic
    ├── config.py        # YAML config loader
    ├── cst_utils.py     # LibCST transformers (The "Brain")
    ├── file_ops.py      # File discovery and management
    ├── git_ops.py       # Git integration (clean check, commit)
    ├── interactive.py   # TUI implementation
    ├── process.py       # Main processing orchestration
    └── rollback.py      # Backup restoration logic

How It Works

1. Discovery: Scans target for .py files, respecting .gitignore and exclusions.
2. Analysis: Parses each file into a CST (Concrete Syntax Tree) using LibCST.
3. Transformation: Visits the CST to identify and rewrite imports and usages based on provided rules.
4. Verification: Formats code (optional) and checks for syntax validity.
5. Execution: Writes changes to disk (atomic write) or displays a diff (dry-run).
6. Reporting: Generates a JSON summary for auditing or rollback.

🐞 Troubleshooting

Debug Mode

Enable verbose logging to trace execution:

import-surgeon --verbose --verbose ...

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork & Clone: Clone your fork locally.
2. Setup: Install dev dependencies:

   pip install -e ".[dev]"
   

3. Test: Run the test suite:

   python -m pytest
   

4. Lint: Ensure code style compliance:

   ruff check .
   black .
   

5. Submit: Open a Pull Request with a clear description of changes.

🗺️ Roadmap

We are currently in Phase 2.

• Phase 1 (Completed): AST Engine, CLI, YAML Config, Git Integration, Rollback.
• Phase 2 (Current): Interactive TUI, Symbol Dependency Analysis.
• Phase 3 (Next): Public Python API, Pre-Commit Hooks, IDE Integration.
• Phase 4 (Future): AI-Driven Refactoring Advisor, Self-Healing Imports.

See ROADMAP.md for details.