import-mend 0.1.0__tar.gz

import_mend-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/

import_mend-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: import-mend
+Version: 0.1.0
+Summary: Detect and repair broken Python imports after refactoring, with zero runtime cost
+License: MIT
+Keywords: ast,developer-tools,imports,refactoring,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: libcst>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# import-check
+
+Detect and repair broken Python imports after refactoring — with zero runtime cost.
+
+## What it does
+
+After a codebase refactoring (manual or autonomous), module paths shift. Every file that
+imported moved symbols now references a path that no longer exists. `import-check` fixes
+this retroactively:
+
+1. **Inventories** symbols before and after using git history + AST (no code executed)
+2. **Detects** moves, renames, splits, and merges in the migration map
+3. **Rewrites** all broken imports in-place using `libcst` (format-preserving)
+4. **Verifies** every import via filesystem + AST checks (zero runtime loading)
+
+## Installation
+
+```bash
+pip install import-check
+```
+
+## Usage
+
+```bash
+# Full pipeline: fix then verify
+python -m import_check run
+
+# Fix broken imports only
+python -m import_check fix
+
+# Verify imports only (CI gate)
+python -m import_check check
+
+# With options
+python -m import_check run \
+  --source-dirs src lib \
+  --git-ref HEAD~3 \
+  --format json \
+  --log-level DEBUG
+```
+
+## Programmatic API
+
+```python
+from import_check import fix, check, run
+
+# Full pipeline
+result = run(root="/path/to/project", source_dirs=["src"], git_ref="HEAD~1")
+
+# Fix only
+fix_results = fix(root=".", git_ref="abc123")
+
+# Check only
+errors = check(root=".", encapsulation_check=True)
+```
+
+## Configuration
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.import_check]
+source_dirs = ["src", "lib"]
+exclude_patterns = [".venv", "__pycache__", "node_modules"]
+git_ref = "HEAD"
+encapsulation_check = true
+output_format = "human"   # or "json"
+log_level = "INFO"        # or "DEBUG", "ERROR"
+check_stubs = true        # .pyi stub fallback
+check_getattr = true      # __getattr__ suppression
+```
+
+## Design
+
+- **Deterministic-first:** AST-based analysis handles the common case. LLM integration
+  for residuals is out of scope — the structured error list is the handoff contract.
+- **Zero runtime cost:** The checker never loads a module. Safe in any environment.
+- **Generic:** Works on any Python project with git. No project-specific config required.
+- **Single dependency:** Only `libcst` beyond the standard library.
+
+## License
+
+MIT

import_mend-0.1.0/README.md

@@ -0,0 +1,83 @@
+# import-check
+
+Detect and repair broken Python imports after refactoring — with zero runtime cost.
+
+## What it does
+
+After a codebase refactoring (manual or autonomous), module paths shift. Every file that
+imported moved symbols now references a path that no longer exists. `import-check` fixes
+this retroactively:
+
+1. **Inventories** symbols before and after using git history + AST (no code executed)
+2. **Detects** moves, renames, splits, and merges in the migration map
+3. **Rewrites** all broken imports in-place using `libcst` (format-preserving)
+4. **Verifies** every import via filesystem + AST checks (zero runtime loading)
+
+## Installation
+
+```bash
+pip install import-check
+```
+
+## Usage
+
+```bash
+# Full pipeline: fix then verify
+python -m import_check run
+
+# Fix broken imports only
+python -m import_check fix
+
+# Verify imports only (CI gate)
+python -m import_check check
+
+# With options
+python -m import_check run \
+  --source-dirs src lib \
+  --git-ref HEAD~3 \
+  --format json \
+  --log-level DEBUG
+```
+
+## Programmatic API
+
+```python
+from import_check import fix, check, run
+
+# Full pipeline
+result = run(root="/path/to/project", source_dirs=["src"], git_ref="HEAD~1")
+
+# Fix only
+fix_results = fix(root=".", git_ref="abc123")
+
+# Check only
+errors = check(root=".", encapsulation_check=True)
+```
+
+## Configuration
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.import_check]
+source_dirs = ["src", "lib"]
+exclude_patterns = [".venv", "__pycache__", "node_modules"]
+git_ref = "HEAD"
+encapsulation_check = true
+output_format = "human"   # or "json"
+log_level = "INFO"        # or "DEBUG", "ERROR"
+check_stubs = true        # .pyi stub fallback
+check_getattr = true      # __getattr__ suppression
+```
+
+## Design
+
+- **Deterministic-first:** AST-based analysis handles the common case. LLM integration
+  for residuals is out of scope — the structured error list is the handoff contract.
+- **Zero runtime cost:** The checker never loads a module. Safe in any environment.
+- **Generic:** Works on any Python project with git. No project-specific config required.
+- **Single dependency:** Only `libcst` beyond the standard library.
+
+## License
+
+MIT

import_mend-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "import-mend"
+version = "0.1.0"
+description = "Detect and repair broken Python imports after refactoring, with zero runtime cost"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+keywords = ["imports", "refactoring", "ast", "static-analysis", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "libcst>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[project.scripts]
+import-mend = "import_mend.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/import_mend"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+
+[tool.import_mend]
+source_dirs = ["src"]
+exclude_patterns = [".venv", "__pycache__", "node_modules", ".git"]
+git_ref = "HEAD"
+encapsulation_check = true
+output_format = "human"
+log_level = "INFO"
+check_stubs = true
+check_getattr = true

import_mend-0.1.0/src/import_mend/__init__.py

@@ -0,0 +1,262 @@
+# @summary
+# Public API facade for the import_mend tool.
+# Provides three entry points: fix() for deterministic import rewriting,
+# check() for smoke-testing all imports, and run() for fix-then-check.
+# Loads configuration from pyproject.toml [tool.import_mend] with overrides.
+# Exports: fix, check, run, ImportCheckConfig, RunResult, FixResult, ImportError
+# Deps: tomllib/tomli, logging, pathlib, import_mend.schemas,
+#       import_mend.inventory, import_mend.differ, import_mend.fixer,
+#       import_mend.checker
+# @end-summary
+
+"""Public API facade for the import_mend tool.
+
+Provides three entry points:
+
+- :func:`fix` — deterministic import rewriting based on git-diff inventory.
+- :func:`check` — smoke-test all imports for resolution and encapsulation.
+- :func:`run` — fix then check (the full pipeline).
+
+Configuration is loaded from ``pyproject.toml`` ``[tool.import_mend]`` section
+with programmatic overrides applied on top.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import fields
+from pathlib import Path
+
+from .schemas import (
+    FixResult,
+    ImportCheckConfig,
+    ImportError,
+    RunResult,
+)
+
+__all__ = [
+    "fix",
+    "check",
+    "run",
+    "ImportCheckConfig",
+    "RunResult",
+    "FixResult",
+    "ImportError",
+]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_config(root: Path, **overrides: object) -> ImportCheckConfig:
+    """Load configuration with resolution order: defaults < pyproject.toml < overrides.
+
+    Reads ``[tool.import_mend]`` from ``pyproject.toml`` at *root* (if it exists),
+    merges with dataclass defaults, then applies any keyword overrides.
+
+    Args:
+        root: Project root directory containing ``pyproject.toml``.
+        **overrides: Keyword arguments that override both defaults and file values.
+
+    Returns:
+        Fully resolved :class:`ImportCheckConfig`.
+    """
+    # --- 1. Start with dataclass defaults (implicit via constructor) ---
+    defaults: dict[str, object] = {}
+
+    # --- 2. Read pyproject.toml if present ---
+    pyproject_path = root / "pyproject.toml"
+    file_values: dict[str, object] = {}
+
+    if pyproject_path.is_file():
+        try:
+            import tomllib  # Python 3.11+
+        except ModuleNotFoundError:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        try:
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+            file_values = data.get("tool", {}).get("import_mend", {})
+        except Exception:  # noqa: BLE001
+            logging.getLogger("import_mend").warning(
+                "Failed to parse pyproject.toml at %s, using defaults", pyproject_path,
+            )
+
+    # --- 3. Merge: defaults < file < overrides ---
+    # Collect valid field names from the dataclass.
+    valid_fields = {f.name for f in fields(ImportCheckConfig)}
+
+    merged: dict[str, object] = {}
+
+    # Apply file values (only recognised keys).
+    for key, value in file_values.items():
+        if key in valid_fields:
+            merged[key] = value
+
+    # Apply programmatic overrides (highest priority).
+    for key, value in overrides.items():
+        if key in valid_fields:
+            merged[key] = value
+
+    # Always set root.
+    merged["root"] = root
+
+    return ImportCheckConfig(**merged)  # type: ignore[arg-type]
+
+
+def _setup_logging(config: ImportCheckConfig) -> logging.Logger:
+    """Configure the ``import_mend`` logger with the level from *config*.
+
+    Format: ``%(levelname)s: %(message)s``.
+
+    Args:
+        config: Configuration with ``log_level`` field.
+
+    Returns:
+        The configured :class:`logging.Logger`.
+    """
+    logger = logging.getLogger("import_mend")
+    logger.setLevel(config.log_level.upper())
+
+    # Avoid duplicate handlers on repeated calls.
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+        logger.addHandler(handler)
+
+    return logger
+
+
+# ---------------------------------------------------------------------------
+# Public entry points
+# ---------------------------------------------------------------------------
+
+
+def fix(root: str | Path | None = None, **config_overrides: object) -> FixResult:
+    """Deterministic fix pipeline: diff git inventories, then rewrite imports.
+
+    Steps:
+        1. Resolve *root* (defaults to cwd).
+        2. Load configuration.
+        3. Setup logging.
+        4. Get changed files since ``git_ref``.
+        5. Build old (git) and new (filesystem) symbol inventories.
+        6. Diff inventories to produce a migration map.
+        7. If no migrations, return an empty :class:`FixResult`.
+        8. Collect all Python files across configured source directories.
+        9. Apply import fixes using the migration map.
+        10. Return the :class:`FixResult`.
+
+    Args:
+        root: Project root directory. Defaults to the current working directory.
+        **config_overrides: Overrides forwarded to :func:`_load_config`.
+
+    Returns:
+        :class:`FixResult` summarising files modified and fixes applied.
+    """
+    from . import differ, fixer, inventory
+
+    # 1. Resolve root.
+    resolved_root = Path(root).resolve() if root is not None else Path.cwd().resolve()
+
+    # 2. Load config.
+    config = _load_config(resolved_root, **config_overrides)
+
+    # 3. Setup logging.
+    logger = _setup_logging(config)
+
+    # 4. Get changed files.
+    changed_files = inventory.get_changed_files(config.git_ref, resolved_root)
+    logger.info("Found %d changed files", len(changed_files))
+
+    if not changed_files:
+        return FixResult()
+
+    # 5. Build old and new inventories.
+    old_inv = inventory.build_old_inventory(changed_files, config.git_ref, resolved_root)
+    logger.info("Built old inventory: %d symbols", sum(len(v) for v in old_inv.values()))
+
+    new_inv = inventory.build_inventory(changed_files, resolved_root)
+    logger.info("Built new inventory: %d symbols", sum(len(v) for v in new_inv.values()))
+
+    # 6. Diff inventories.
+    migration_map = differ.diff_inventories(old_inv, new_inv)
+    logger.info("Migration map: %d entries", len(migration_map))
+
+    # 7. If no migrations, return empty result.
+    if not migration_map:
+        return FixResult()
+
+    # 8. Collect all Python files.
+    all_files = inventory.collect_python_files(
+        config.source_dirs, resolved_root, config.exclude_patterns,
+    )
+    logger.info("Applying fixes to %d files", len(all_files))
+
+    # 9. Apply fixes.
+    result = fixer.apply_fixes(migration_map, all_files, resolved_root)
+
+    return result
+
+
+def check(
+    root: str | Path | None = None, **config_overrides: object
+) -> list[ImportError]:
+    """Smoke-test all imports for resolution and encapsulation errors.
+
+    Steps:
+        1. Resolve *root* (defaults to cwd).
+        2. Load configuration.
+        3. Setup logging.
+        4. Collect all Python files across configured source directories.
+        5. Run import checks.
+
+    Args:
+        root: Project root directory. Defaults to the current working directory.
+        **config_overrides: Overrides forwarded to :func:`_load_config`.
+
+    Returns:
+        List of :class:`ImportError` records. Empty if all imports are clean.
+    """
+    from . import checker, inventory
+
+    # 1. Resolve root.
+    resolved_root = Path(root).resolve() if root is not None else Path.cwd().resolve()
+
+    # 2. Load config.
+    config = _load_config(resolved_root, **config_overrides)
+
+    # 3. Setup logging.
+    logger = _setup_logging(config)
+
+    # 4. Collect all Python files.
+    all_files = inventory.collect_python_files(
+        config.source_dirs, resolved_root, config.exclude_patterns,
+    )
+    logger.info("Checking imports in %d files", len(all_files))
+
+    # 5. Run checker.
+    errors = checker.check_imports(all_files, resolved_root, config)
+
+    logger.info("Found %d import errors", len(errors))
+
+    return errors
+
+
+def run(root: str | Path | None = None, **config_overrides: object) -> RunResult:
+    """Run the full pipeline: fix imports, then check for remaining errors.
+
+    Args:
+        root: Project root directory. Defaults to the current working directory.
+        **config_overrides: Overrides forwarded to :func:`_load_config`.
+
+    Returns:
+        :class:`RunResult` containing the fix result and any remaining errors.
+    """
+    fix_result = fix(root=root, **config_overrides)
+    remaining_errors = check(root=root, **config_overrides)
+
+    return RunResult(fix_result=fix_result, remaining_errors=remaining_errors)