wexample-wex-addon-dev-python 12.2.0__tar.gz → 13.0.1__tar.gz

{wexample_wex_addon_dev_python-12.2.0 → wexample_wex_addon_dev_python-13.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-wex-addon-dev-python
-Version: 12.2.0
+Version: 13.0.1
 Summary: Python dev addon for wex
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -15,10 +15,10 @@ Requires-Dist: griffe>=2.0.2
 Requires-Dist: networkx
 Requires-Dist: pylint
 Requires-Dist: pyright
-Requires-Dist: wexample-api>=6.7.0
-Requires-Dist: wexample-filestate-python>=8.2.0
-Requires-Dist: wexample-wex-addon-ai>=11.3.0
-Requires-Dist: wexample-wex-addon-app>=27.0.0
+Requires-Dist: wexample-api>=6.8.0
+Requires-Dist: wexample-filestate-python>=9.0.0
+Requires-Dist: wexample-wex-addon-ai>=12.0.0
+Requires-Dist: wexample-wex-addon-app>=28.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 # wex_addon_dev_python
 
-Version: 12.2.0
+Version: 13.0.1
 
 Python dev addon for wex
 
@@ -112,10 +112,10 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - networkx: 
 - pylint: 
 - pyright: 
-- wexample-api: >=6.7.0
-- wexample-filestate-python: >=8.2.0
-- wexample-wex-addon-ai: >=11.3.0
-- wexample-wex-addon-app: >=27.0.0
+- wexample-api: >=6.8.0
+- wexample-filestate-python: >=9.0.0
+- wexample-wex-addon-ai: >=12.0.0
+- wexample-wex-addon-app: >=28.0.0
 
 ## Versioning & Compatibility Policy
 

{wexample_wex_addon_dev_python-12.2.0 → wexample_wex_addon_dev_python-13.0.1}/README.md

@@ -1,6 +1,6 @@
 # wex_addon_dev_python
 
-Version: 12.2.0
+Version: 13.0.1
 
 Python dev addon for wex
 
@@ -86,10 +86,10 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 - networkx: 
 - pylint: 
 - pyright: 
-- wexample-api: >=6.7.0
-- wexample-filestate-python: >=8.2.0
-- wexample-wex-addon-ai: >=11.3.0
-- wexample-wex-addon-app: >=27.0.0
+- wexample-api: >=6.8.0
+- wexample-filestate-python: >=9.0.0
+- wexample-wex-addon-ai: >=12.0.0
+- wexample-wex-addon-app: >=28.0.0
 
 ## Versioning & Compatibility Policy
 

{wexample_wex_addon_dev_python-12.2.0 → wexample_wex_addon_dev_python-13.0.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-wex-addon-dev-python"
-version = "12.2.0"
+version = "13.0.1"
 description = "Python dev addon for wex"
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -24,10 +24,10 @@ dependencies = [
     "networkx",
     "pylint",
     "pyright",
-    "wexample-api>=6.7.0",
-    "wexample-filestate-python>=8.2.0",
-    "wexample-wex-addon-ai>=11.3.0",
-    "wexample-wex-addon-app>=27.0.0",
+    "wexample-api>=6.8.0",
+    "wexample-filestate-python>=9.0.0",
+    "wexample-wex-addon-ai>=12.0.0",
+    "wexample-wex-addon-app>=28.0.0",
 ]
 
 [project.readme]

{wexample_wex_addon_dev_python-12.2.0 → wexample_wex_addon_dev_python-13.0.1}/src/wexample_wex_addon_dev_python/commands/code/rename.py

@@ -32,8 +32,7 @@ if TYPE_CHECKING:
 @option(
     name="kind",
     type=str,
-    required=False,
-    default="package",
+    required=True,
     description="Symbol kind to rename. Step 1 supports only 'package'.",
 )
 @option(
@@ -69,6 +68,18 @@ def python__code__rename(
     from wexample_app.response.failure_response import FailureResponse
     from wexample_app.response.table_response import TableResponse
 
+    from wexample_wex_addon_dev_python.refactor.python_class_rename_handler import (
+        PythonClassRenameHandler,
+    )
+    from wexample_wex_addon_dev_python.refactor.python_constant_rename_handler import (
+        PythonConstantRenameHandler,
+    )
+    from wexample_wex_addon_dev_python.refactor.python_function_rename_handler import (
+        PythonFunctionRenameHandler,
+    )
+    from wexample_wex_addon_dev_python.refactor.python_module_rename_handler import (
+        PythonModuleRenameHandler,
+    )
     from wexample_wex_addon_dev_python.refactor.python_package_rename_handler import (
         PythonPackageRenameHandler,
     )
@@ -85,38 +96,49 @@ def python__code__rename(
             ),
         )
 
-    if kind_enum is not SymbolKind.PACKAGE:
+    handler_class = {
+        SymbolKind.PACKAGE: PythonPackageRenameHandler,
+        SymbolKind.MODULE: PythonModuleRenameHandler,
+        SymbolKind.CLASS: PythonClassRenameHandler,
+        SymbolKind.FUNCTION: PythonFunctionRenameHandler,
+        SymbolKind.CONSTANT: PythonConstantRenameHandler,
+    }.get(kind_enum)
+    if handler_class is None:
         return FailureResponse(
             kernel=context.kernel,
-            message=(
-                f"--kind {kind_enum.value} not implemented yet "
-                "(step 1 covers 'package' only)."
-            ),
+            message=f"--kind {kind_enum.value} not implemented yet.",
         )
 
     scope_roots = app_workdir.get_code_scope_paths(context.kernel)
 
-    handler = PythonPackageRenameHandler(
+    handler = handler_class(
         scope_roots=scope_roots,
         source=source,
         target=target,
         dry_run=dry_run,
     )
+
+    spinner = context.io.spinner(
+        label=f"Scanning {len(scope_roots)} root(s) for '{source}' ({kind_enum.value})…"
+    )
     try:
-        report = handler.run()
-    except FileNotFoundError as e:
-        return FailureResponse(kernel=context.kernel, message=str(e))
-    except ValueError as e:
-        # Ambiguous match (multiple packages) or invalid dotted name.
-        return FailureResponse(kernel=context.kernel, message=str(e))
-    except RuntimeError as e:
-        # Preflight failure (permissions, target exists). Plan was thrown away,
-        # no file has been written — safe to surface as a clean failure.
-        return FailureResponse(kernel=context.kernel, message=str(e))
+        try:
+            report = handler.run()
+        except FileNotFoundError as e:
+            return FailureResponse(kernel=context.kernel, message=str(e))
+        except ValueError as e:
+            # Ambiguous match (multiple matches) or invalid dotted name.
+            return FailureResponse(kernel=context.kernel, message=str(e))
+        except RuntimeError as e:
+            # Preflight failure (permissions, target exists). Plan was thrown
+            # away, no file has been written — surface as a clean failure.
+            return FailureResponse(kernel=context.kernel, message=str(e))
+    finally:
+        spinner.stop()
 
     mode = "APPLIED" if not dry_run else "DRY-RUN"
     context.io.log(
-        f"[{mode}] {report.package_dir_old} → {report.package_dir_new}"
+        f"[{mode}] {report.source_path} → {report.target_path}"
     )
     context.io.log(
         f"[{mode}] scope={len(scope_roots)} root(s) "

{wexample_wex_addon_dev_python-12.2.0 → wexample_wex_addon_dev_python-13.0.1}/src/wexample_wex_addon_dev_python/file/python_pyproject_toml_file.py

@@ -24,7 +24,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
     ) -> bool:
         from packaging.requirements import Requirement
         from packaging.utils import canonicalize_name
-        from wexample_filestate_python.helpers.toml import toml_sort_string_array
+        from wexample_filestate_python.helper.toml import toml_sort_string_array
 
         new_name = canonicalize_name(spec.name)
 
@@ -118,7 +118,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
 
     def optional_group_array(self, group: str):
         """Ensure and return project.optional-dependencies[group] as multi-line array."""
-        from wexample_filestate_python.helpers.toml import (
+        from wexample_filestate_python.helper.toml import (
             toml_ensure_array,
             toml_ensure_table,
         )
@@ -162,7 +162,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
 
     def _dependencies_array(self):
         """Ensure and return project.dependencies as a multi-line TOML array."""
-        from wexample_filestate_python.helpers.toml import toml_ensure_array
+        from wexample_filestate_python.helper.toml import toml_ensure_array
 
         project = self._project_table()
         deps, _ = toml_ensure_array(project, "dependencies")
@@ -187,7 +187,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
         if not import_name:
             return
 
-        from wexample_filestate_python.helpers.toml import toml_ensure_table
+        from wexample_filestate_python.helper.toml import toml_ensure_table
 
         tool_tbl, _ = toml_ensure_table(content, ["tool"])
         pdm_tbl, _ = toml_ensure_table(tool_tbl, ["pdm"])
@@ -207,7 +207,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
     def _enforce_project_metadata(
         self, content: dict, project_name: str | None, project_version: str | None
     ) -> None:
-        from wexample_filestate_python.helpers.toml import toml_ensure_table
+        from wexample_filestate_python.helper.toml import toml_ensure_table
 
         project_tbl, _ = toml_ensure_table(content, ["project"])
         if project_name:
@@ -267,7 +267,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
         if not import_name:
             return
 
-        from wexample_filestate_python.helpers.toml import toml_ensure_table
+        from wexample_filestate_python.helper.toml import toml_ensure_table
 
         tool_tbl, _ = toml_ensure_table(content, ["tool"])
 
@@ -298,8 +298,8 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
         ]
 
     def _ensure_dev_dependencies(self, content: dict) -> None:
-        from wexample_filestate_python.helpers.package import package_normalize_name
-        from wexample_filestate_python.helpers.toml import (
+        from wexample_filestate_python.helper.package import package_normalize_name
+        from wexample_filestate_python.helper.toml import (
             toml_get_string_value,
             toml_sort_string_array,
         )
@@ -325,8 +325,8 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
         )
 
     def _normalize_dependencies(self, content: dict) -> None:
-        from wexample_filestate_python.helpers.package import package_normalize_name
-        from wexample_filestate_python.helpers.toml import (
+        from wexample_filestate_python.helper.package import package_normalize_name
+        from wexample_filestate_python.helper.toml import (
             toml_get_string_value,
             toml_sort_string_array,
         )
@@ -385,7 +385,7 @@ class PythonPyprojectTomlFile(AppDependenciesConfigFileMixin, TomlFile):
 
     def _project_table(self):
         """Ensure and return the [project] table."""
-        from wexample_filestate_python.helpers.toml import toml_ensure_table
+        from wexample_filestate_python.helper.toml import toml_ensure_table
 
         doc = self.read_parsed()
         project, _ = toml_ensure_table(doc, ["project"])

{wexample_wex_addon_dev_python-12.2.0 → wexample_wex_addon_dev_python-13.0.1}/src/wexample_wex_addon_dev_python/python_addon_manager.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
 
 class PythonAddonManager(SelectionContributingAddonMixin, AbstractAddonManager):
     def get_local_configurable_keys(self) -> list[dict]:
-        from wexample_wex_addon_dev_python.helpers.pdm import (
+        from wexample_wex_addon_dev_python.helper.pdm import (
             apply_pdm_bin_dir,
             detect_pdm_bin_dir,
         )

wexample_wex_addon_dev_python-13.0.1/src/wexample_wex_addon_dev_python/refactor/abstract_python_path_rename_handler.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_wex_addon_dev_python.refactor.abstract_python_rename_handler import (
+    AbstractPythonRenameHandler,
+)
+from wexample_wex_addon_dev_python.refactor.python_common import (
+    RenameReport,
+    iter_python_files,
+    rewrite_imports,
+)
+from wexample_wex_addon_dev_python.refactor.rename_plan import RenamePlan
+
+
+@base_class
+class AbstractPythonPathRenameHandler(AbstractPythonRenameHandler):
+    """Common shell for renames that boil down to moving one filesystem entry
+    (a package directory, a single .py file…) and rewriting every dotted
+    import statement that targets it.
+
+    Subclasses only customise *what* to locate on disk and *how* the new path
+    is derived. The plan, the report, and the per-file rewrite loop live here.
+    """
+
+    _resolved_source_path: Path | None = private_field(
+        default=None,
+        description="Source path located by `_find_source_path` during "
+        "compute_plan; used to build the report when `path_renames` is empty "
+        "(e.g. merge mode).",
+    )
+    _resolved_target_path: Path | None = private_field(
+        default=None,
+        description="Target path derived from the source during compute_plan; "
+        "used by the report alongside `_resolved_source_path`.",
+    )
+
+    def compute_plan(self) -> RenamePlan:
+        plan = RenamePlan()
+        source_path = self._find_source_path()
+        target_path = self._derive_target_path(source_path)
+        self._resolved_source_path = source_path
+        self._resolved_target_path = target_path
+        self._plan_path_move(plan, source_path, target_path)
+        self._plan_target_parent_creation(plan, target_path)
+
+        for py_file in iter_python_files(self.scope_roots):
+            plan.files_scanned += 1
+            new_source = rewrite_imports(
+                py_file, self._source_parts, self._target_parts
+            )
+            if new_source is not None:
+                plan.rewrites[py_file] = new_source
+
+        return plan
+
+    def _build_report(self, plan: RenamePlan) -> RenameReport:
+        return RenameReport(
+            files_changed=list(plan.rewrites.keys()),
+            files_scanned=plan.files_scanned,
+            source_path=self._resolved_source_path,
+            target_path=self._resolved_target_path,
+        )
+
+    @abstract_method
+    def _derive_target_path(self, source_path: Path) -> Path:
+        """Return where `source_path` should be moved to on disk."""
+
+    @abstract_method
+    def _find_source_path(self) -> Path:
+        """Locate the unique filesystem entry that matches `source`."""
+
+    def _plan_path_move(
+        self, plan: RenamePlan, source_path: Path, target_path: Path
+    ) -> None:
+        """Default move: one atomic path rename. Subclasses may override to
+        merge into an existing target (`PythonPackageRenameHandler`)."""
+        plan.path_renames.append((source_path, target_path))
+
+    def _plan_target_parent_creation(
+        self, plan: RenamePlan, target_path: Path
+    ) -> None:
+        """Walk up from `target_path.parent` and queue every missing ancestor
+        directory plus an empty `__init__.py` so the move can land inside a
+        valid Python package even when the user renames across parents."""
+        parent = target_path.parent
+        missing: list[Path] = []
+        while not parent.exists():
+            missing.append(parent)
+            up = parent.parent
+            if up == parent:
+                raise RuntimeError(
+                    f"Cannot find any existing ancestor for {target_path}"
+                )
+            parent = up
+
+        # Outermost-first so each `mkdir` finds its own parent in place.
+        for directory in reversed(missing):
+            plan.directories_to_create.append(directory)
+            plan.rewrites[directory / "__init__.py"] = ""

wexample_wex_addon_dev_python-13.0.1/src/wexample_wex_addon_dev_python/refactor/abstract_python_rename_handler.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_wex_addon_dev_python.refactor.applier import (
+    NaiveRenameApplier,
+    RenameApplier,
+)
+from wexample_wex_addon_dev_python.refactor.python_common import RenameReport
+from wexample_wex_addon_dev_python.refactor.rename_plan import RenamePlan
+
+
+@base_class
+class AbstractPythonRenameHandler(BaseClass):
+    """Top-level shell for any Python rename, regardless of what gets renamed
+    (a package directory, a single module file, a class/function/constant
+    inside a module, …).
+
+    Subclasses decide what the plan looks like (`compute_plan`) and how the
+    report describes the operation (`_build_report`). Everything else — field
+    layout, init validation, three-phase orchestration — lives here so every
+    flavour of rename stays strictly consistent.
+    """
+    dry_run: bool = public_field(
+        default=True,
+        description="When True, return the plan/report without touching the "
+        "filesystem.",
+    )
+    scope_roots: list[Path] = public_field(
+        description="Roots scanned for both source location and rewrites.",
+    )
+    source: str = public_field(
+        description="Dotted source name (e.g. 'mylib.helpers.Color').",
+    )
+    target: str = public_field(
+        description="Dotted target name (e.g. 'mylib.helpers.Tone').",
+    )
+    _source_parts: tuple[str, ...] = private_field(
+        factory=tuple,
+        description="Cached `source.split('.')`; set in __attrs_post_init__.",
+    )
+    _target_parts: tuple[str, ...] = private_field(
+        factory=tuple,
+        description="Cached `target.split('.')`; set in __attrs_post_init__.",
+    )
+
+    def __attrs_post_init__(self) -> None:
+        self._execute_super_attrs_post_init_if_exists()
+        if not self.scope_roots:
+            raise ValueError("scope_roots must contain at least one path")
+        self._source_parts = tuple(self.source.split("."))
+        self._target_parts = tuple(self.target.split("."))
+        if not all(self._source_parts) or not all(self._target_parts):
+            raise ValueError(
+                "source and target must be dotted names without empty parts"
+            )
+
+    @abstract_method
+    def compute_plan(self) -> RenamePlan:
+        """Phase 1: scan and build the plan. No write yet."""
+
+    def run(
+        self,
+        applier: RenameApplier | None = None,
+    ) -> RenameReport:
+        """Compute plan → preflight → apply (or stop after compute in dry-run)."""
+        plan = self.compute_plan()
+        report = self._build_report(plan)
+
+        if self.dry_run:
+            return report
+
+        problems = plan.preflight()
+        if problems:
+            joined = "\n  - ".join(problems)
+            raise RuntimeError(f"Plan preflight failed:\n  - {joined}")
+
+        (applier or NaiveRenameApplier()).apply(plan)
+        return report
+
+    @abstract_method
+    def _build_report(self, plan: RenamePlan) -> RenameReport:
+        """Compose the user-facing report once the plan is built."""

wexample_wex_addon_dev_python-13.0.1/src/wexample_wex_addon_dev_python/refactor/abstract_python_symbol_rename_handler.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import libcst as cst
+from wexample_helpers.classes.abstract_method import abstract_method
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+
+from wexample_wex_addon_dev_python.refactor.abstract_python_rename_handler import (
+    AbstractPythonRenameHandler,
+)
+from wexample_wex_addon_dev_python.refactor.python_common import (
+    SKIP_DIR_NAMES,
+    RenameReport,
+    iter_python_files,
+    rewrite_symbol_references,
+)
+from wexample_wex_addon_dev_python.refactor.rename_plan import RenamePlan
+
+
+@base_class
+class AbstractPythonSymbolRenameHandler(AbstractPythonRenameHandler):
+    """Common shell for renames that target a module-level symbol — a class,
+    a function, a constant. The .py file containing the definition is NOT
+    moved; only the symbol's name changes inside it, and every consumer that
+    imports or references it follows.
+
+    V1 limitation: in-place rename only — the parent module of source and
+    target must match. Cross-module symbol moves are deferred.
+    """
+
+    _definition_file: Path | None = private_field(
+        default=None,
+        description="Set during compute_plan() once the symbol's defining file "
+        "is located; used by `_build_report` to fill source/target paths.",
+    )
+
+    def __attrs_post_init__(self) -> None:
+        super().__attrs_post_init__()
+        if len(self._source_parts) < 2 or len(self._target_parts) < 2:
+            raise ValueError(
+                "symbol source/target must be fully dotted (e.g. 'pkg.mod.Symbol')"
+            )
+        if self._source_parts[:-1] != self._target_parts[:-1]:
+            raise ValueError(
+                "symbol rename only supports in-place rename — parent module "
+                f"must match. Got source={'.'.join(self._source_parts[:-1])} "
+                f"target={'.'.join(self._target_parts[:-1])}"
+            )
+
+    def compute_plan(self) -> RenamePlan:
+        plan = RenamePlan()
+        parent_parts = self._source_parts[:-1]
+        old_name = self._source_parts[-1]
+        new_name = self._target_parts[-1]
+
+        def_file = self._find_definition_file()
+        self._definition_file = def_file
+
+        for py_file in iter_python_files(self.scope_roots):
+            plan.files_scanned += 1
+            is_def = py_file.resolve() == def_file.resolve()
+            new_source = rewrite_symbol_references(
+                py_file,
+                parent_parts=parent_parts,
+                old_name=old_name,
+                new_name=new_name,
+                is_definition_file=is_def,
+            )
+            if new_source is not None:
+                plan.rewrites[py_file] = new_source
+
+        return plan
+
+    def _add_unique(
+        self, results: list[Path], seen: set[str], path: Path
+    ) -> None:
+        key = str(path.resolve())
+        if key in seen:
+            return
+        seen.add(key)
+        results.append(path)
+
+    def _build_report(self, plan: RenamePlan) -> RenameReport:
+        return RenameReport(
+            files_changed=list(plan.rewrites.keys()),
+            files_scanned=plan.files_scanned,
+            source_path=self._definition_file,
+            target_path=self._definition_file,
+        )
+
+    def _candidate_parent_files(self, parent_parts: tuple[str, ...]) -> list[Path]:
+        """Return every .py file whose dotted module name equals parent_parts.
+
+        Two layouts considered: `parent_parts/__init__.py` (package init) and
+        `<parent[:-1]>/parent[-1].py` (single-module file).
+        """
+        if not parent_parts:
+            return []
+        leaf = parent_parts[-1]
+        outer_parts = parent_parts[:-1]
+        n_outer = len(outer_parts)
+
+        results: list[Path] = []
+        seen: set[str] = set()
+
+        for root in self.scope_roots:
+            for init_file in root.rglob("__init__.py"):
+                if any(p in SKIP_DIR_NAMES for p in init_file.parent.parts):
+                    continue
+                pkg_dir = init_file.parent
+
+                # Case A: this package directory IS the parent module.
+                if (
+                    len(pkg_dir.parts) >= len(parent_parts)
+                    and pkg_dir.parts[-len(parent_parts):] == parent_parts
+                ):
+                    self._add_unique(results, seen, init_file)
+
+                # Case B: the parent module is `<pkg_dir>/<leaf>.py` and the
+                # package's dotted tail equals `outer_parts`.
+                if (
+                    n_outer == 0
+                    or (
+                        len(pkg_dir.parts) >= n_outer
+                        and pkg_dir.parts[-n_outer:] == outer_parts
+                    )
+                ):
+                    candidate = pkg_dir / f"{leaf}.py"
+                    if candidate.is_file():
+                        self._add_unique(results, seen, candidate)
+
+        return results
+
+    def _find_definition_file(self) -> Path:
+        """Locate the unique .py file that declares this symbol at module level.
+
+        The parent dotted name may resolve to either a module file
+        (`pkg/sub.py`) or a package init (`pkg/sub/__init__.py`). We check
+        both, parse them, and ask the subclass `_is_definition_node` whether
+        any top-level statement defines our symbol.
+        """
+        parent_parts = self._source_parts[:-1]
+        old_name = self._source_parts[-1]
+        candidates = self._candidate_parent_files(parent_parts)
+
+        matches: list[Path] = []
+        for candidate in candidates:
+            try:
+                module = cst.parse_module(candidate.read_text(encoding="utf-8"))
+            except (cst.ParserSyntaxError, OSError):
+                continue
+            if any(
+                self._is_definition_node(stmt, old_name)
+                for stmt in module.body
+            ):
+                matches.append(candidate)
+
+        unique = list({str(m): m for m in matches}.values())
+        if not unique:
+            roots_str = ", ".join(str(r) for r in self.scope_roots)
+            raise FileNotFoundError(
+                f"No top-level {self._kind_label()} '{old_name}' found in "
+                f"any module matching '{'.'.join(parent_parts)}' under: {roots_str}"
+            )
+        if len(unique) > 1:
+            joined = "\n  ".join(str(m) for m in unique)
+            raise ValueError(
+                f"Multiple files define '{self.source}', refine the dotted name:\n  {joined}"
+            )
+        return unique[0]
+
+    @abstract_method
+    def _is_definition_node(
+        self, node: cst.CSTNode, name: str
+    ) -> bool:
+        """Return True if `node` is a top-level definition of `name` of this
+        handler's kind (class / function / constant)."""
+
+    @abstract_method
+    def _kind_label(self) -> str:
+        """Human-readable label of this rename kind for error messages."""