import-surgeon 4.0.1

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

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

Flag	Description	Default
target	File or directory to scan.	.
--old-module	Source module to move from.	None
--new-module	Destination module to move to.	None
--symbols	Comma-separated list of symbols to move.	None
--apply	Write changes to disk (default is dry-run).	False
--config	Path to YAML configuration file.	None
--rewrite-dotted	Rewrite dotted access (e.g., mod.Attr).	False
--format	Run black and isort on changed files.	False
--jobs, -j	Number of parallel workers.	1
--interactive, -i	Launch interactive TUI.	False
--rollback	Revert changes using summary JSON.	False
--verbose, -v	Increase logging verbosity.	0

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

Issue	Cause	Solution
"Git not clean"	--require-clean-git is enabled but repo has changes.	Commit/stash changes or remove the flag.
"Target not found"	The path specified does not exist.	Verify the target argument matches a real path.
Imports not updating	Symbols might be aliased or dynamically imported.	Use --verbose to see skipped files; verify symbol names.
Encoding Errors	File has non-UTF-8 encoding.	Ensure files are UTF-8 or compatible. Tool attempts auto-detection.

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.