sarj-python-lint 0.81.2__tar.gz → 0.81.4__tar.gz

{sarj_python_lint-0.81.2 → sarj_python_lint-0.81.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.81.2
+Version: 0.81.4
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-0.81.2 → sarj_python_lint-0.81.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.81.2"
+version = "0.81.4"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]

sarj_python_lint-0.81.4/src/sarj_python_lint/rules/no_redundant_module_alias_exports.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_SYS_SOURCES = frozenset({"sys"})
+
+
+@final
+class NoRedundantModuleAliasExports(Rule):
+    id: str = "no-redundant-module-alias-exports"
+    code: str = "SARJ440"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Do not replace the current module through `sys.modules`.",
+        rationale=(
+            "Replacing the current module mutates import identity at runtime in a way static tools cannot model. "
+            "It makes introspection, reloads, circular imports, state, and monkeypatch behavior surprising."
+        ),
+        remediation=(
+            "Import the canonical path inside maintained code. If a compatibility module is still required, expose "
+            "its supported names with explicit same-name imports grouped by source module."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only module-scope assignments through an unconditional, unshadowed stdlib `sys` import are checked.",
+            "Assignments inside functions, classes, and `TYPE_CHECKING` branches are excluded.",
+            "Literal-key registrations, child-module registrations, method calls, reads, and arbitrary registries are excluded.",
+            "Generated source, malformed source, and stub files (`.pyi`) are outside this rule's scope.",
+            "No autofix is offered because the intended compatibility surface and identity requirements need review.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="current-module-replacement",
+                title="Do not replace a compatibility module at runtime",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "legacy/settings.py",
+                        "import sys\n\n"
+                        "from canonical import settings as _canonical\n\n\n"
+                        "sys.modules[__name__] = _canonical\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("legacy/settings.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="explicit-compatibility-exports",
+                title="Expose the supported compatibility surface explicitly",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "legacy/settings.py",
+                        "from canonical.settings import (\n    Settings as Settings,\n    load as load,\n)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("legacy/settings.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if path.suffix != ".py" or "modules" not in source or "__name__" not in source or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree, module_scope_only=True)
+        if not imports.builtin_is_unshadowed("__name__"):
+            return []
+        direct_sys_bindings = _direct_sys_bindings(tree)
+        findings = [
+            Diagnostic(
+                path=path,
+                line=target.lineno,
+                col=target.col_offset + 1,
+                code=self.code,
+                message=(
+                    "Do not replace the current module through `sys.modules[__name__]`; expose compatibility names "
+                    "with explicit imports and update maintained callers to the canonical module."
+                ),
+            )
+            for statement in _module_statements(tree.body)
+            for target in _assignment_targets(statement)
+            if _is_current_module_target(target, imports, direct_sys_bindings)
+        ]
+        return sorted(findings, key=lambda finding: (finding.line, finding.col, finding.code))
+
+
+def _direct_sys_bindings(tree: ast.Module) -> frozenset[str]:
+    bindings: set[str] = set()
+    for statement in tree.body:
+        match statement:
+            case ast.Import(names=names):
+                bindings.update(alias.asname or "sys" for alias in names if alias.name == "sys")
+            case ast.ImportFrom(module="sys", level=0, names=names):
+                bindings.update(alias.asname or "modules" for alias in names if alias.name == "modules")
+            case _:
+                pass
+    return frozenset(bindings)
+
+
+def _module_statements(statements: list[ast.stmt]) -> list[ast.stmt]:
+    result: list[ast.stmt] = []
+    pending = list(reversed(statements))
+    while pending:
+        statement = pending.pop()
+        result.append(statement)
+        pending.extend(reversed(_module_control_flow_bodies(statement)))
+    return result
+
+
+def _module_control_flow_bodies(statement: ast.stmt) -> list[ast.stmt]:
+    match statement:
+        case ast.If() if _is_type_checking_guard(statement.test):
+            return list(statement.orelse)
+        case ast.If() | ast.For() | ast.AsyncFor() | ast.While():
+            return [*statement.body, *statement.orelse]
+        case ast.With() | ast.AsyncWith():
+            return list(statement.body)
+        case ast.Try() | ast.TryStar():
+            return [
+                *statement.body,
+                *(nested for handler in statement.handlers for nested in handler.body),
+                *statement.orelse,
+                *statement.finalbody,
+            ]
+        case ast.Match():
+            return [nested for match_case in statement.cases for nested in match_case.body]
+        case _:
+            return []
+
+
+def _assignment_targets(statement: ast.stmt) -> list[ast.expr]:
+    match statement:
+        case ast.Assign(targets=targets):
+            return [nested for target in targets for nested in _nested_targets(target)]
+        case ast.AnnAssign(target=target):
+            return _nested_targets(target)
+        case _:
+            return []
+
+
+def _nested_targets(target: ast.expr) -> list[ast.expr]:
+    if isinstance(target, (ast.Tuple, ast.List)):
+        return [nested for element in target.elts for nested in _nested_targets(element)]
+    return [target]
+
+
+def _is_current_module_target(
+    target: ast.expr,
+    imports: ImportIndex,
+    direct_sys_bindings: frozenset[str],
+) -> bool:
+    match target:
+        case ast.Subscript(
+            value=value,
+            slice=ast.Name(id="__name__", ctx=ast.Load()),
+            ctx=ast.Store(),
+        ):
+            root = value.value if isinstance(value, ast.Attribute) else value
+            return (
+                isinstance(root, ast.Name)
+                and root.id in direct_sys_bindings
+                and imports.resolves(value, sources=_SYS_SOURCES, symbol="modules")
+            )
+        case _:
+            return False
+
+
+def _is_type_checking_guard(node: ast.expr) -> bool:
+    return (isinstance(node, ast.Name) and node.id == "TYPE_CHECKING") or (
+        isinstance(node, ast.Attribute)
+        and isinstance(node.value, ast.Name)
+        and node.value.id in {"typing", "typing_extensions"}
+        and node.attr == "TYPE_CHECKING"
+    )

{sarj_python_lint-0.81.2 → sarj_python_lint-0.81.4}/src/sarj_python_lint/rules/stepdown.py

@@ -34,7 +34,7 @@ _SELF_NAMES = frozenset({"self", "cls"})
 
 # These decorators preserve an ordinary callable definition and do not register
 # it through user code at definition time. Unknown decorators are movement barriers.
-_ORDER_TRANSPARENT_DECORATORS = frozenset({"classmethod", "staticmethod", "final", "override"})
+_ORDER_TRANSPARENT_DECORATORS = frozenset({"classmethod", "staticmethod"})
 
 #: A repeated singledispatch implementation name cannot identify one movable target.
 _DISCARD_NAME = "_"
@@ -65,6 +65,7 @@ class Stepdown(Rule):
         limitations=(
             "Generated files, tests, `__main__.py`, mutual recursion, and helpers with multiple callers are excluded.",
             "Decorated definitions and dynamic references that cannot prove a sole caller are not reported.",
+            "Only bare builtin classmethod/staticmethod decorators without any visible rebinding are treated as transparent; other decorators remain ordering barriers.",
         ),
         examples=(
             RuleExample(
@@ -108,11 +109,14 @@ class Stepdown(Rule):
         tree = parse_or_none(path, source)
         if tree is None:
             return []
-        diags = _check_module_scope(path, tree, self.code)
+        transparent = _unshadowed_builtin_decorators(tree)
+        diags = _check_module_scope(path, tree, self.code, transparent)
         classes = [node for node in _walk(tree) if isinstance(node, ast.ClassDef)]
         family_external = _family_external_refs(classes)
         for cls in classes:
-            diags.extend(_check_class_scope(path, cls, self.code, family_external.get(id(cls), frozenset())))
+            diags.extend(
+                _check_class_scope(path, cls, self.code, family_external.get(id(cls), frozenset()), transparent)
+            )
         diags.sort(key=lambda d: (d.line, d.col))
         return diags
 
@@ -121,7 +125,7 @@ def _last_by_name[DefT: _Def](defs: Sequence[DefT]) -> dict[str, DefT]:
     return {definition.name: definition for definition in defs}
 
 
-def _check_module_scope(path: Path, tree: ast.Module, code: str) -> list[Diagnostic]:
+def _check_module_scope(path: Path, tree: ast.Module, code: str, transparent: frozenset[str]) -> list[Diagnostic]:
     defs = [n for n in tree.body if isinstance(n, _SCOPE_NODES)]
     counts = Counter(d.name for d in defs)
     unique_defs = {name: d for d in defs if counts[name := d.name] == 1}
@@ -156,15 +160,19 @@ def _check_module_scope(path: Path, tree: ast.Module, code: str) -> list[Diagnos
     for name, d in unique_defs.items():
         if not isinstance(d, _DEF_NODES) or not _is_private_helper_name(name):
             continue
-        if name in pinned or name in shadowed or _has_order_sensitive_decorator(d):
+        if name in pinned or name in shadowed or _has_order_sensitive_decorator(d, transparent):
             continue
         diags.extend(
-            _flag_if_above_single_caller(path, code, name, node=d, graph=graph, defs=all_defs, ref_lines=ref_lines)
+            _flag_if_above_single_caller(
+                path, code, name, node=d, graph=graph, defs=all_defs, ref_lines=ref_lines, transparent=transparent
+            )
         )
     return diags
 
 
-def _check_class_scope(path: Path, cls: ast.ClassDef, code: str, external_callers: frozenset[str]) -> list[Diagnostic]:
+def _check_class_scope(
+    path: Path, cls: ast.ClassDef, code: str, external_callers: frozenset[str], transparent: frozenset[str]
+) -> list[Diagnostic]:
     methods = [n for n in cls.body if isinstance(n, _DEF_NODES)]
     counts = Counter(m.name for m in methods)
     unique = {name: m for m in methods if counts[name := m.name] == 1}
@@ -197,10 +205,17 @@ def _check_class_scope(path: Path, cls: ast.ClassDef, code: str, external_caller
     for name, m in unique.items():
         if not _is_private_helper_name(name):
             continue
-        if name in pinned or name in shadowed or name in external_callers or _has_order_sensitive_decorator(m):
+        if (
+            name in pinned
+            or name in shadowed
+            or name in external_callers
+            or _has_order_sensitive_decorator(m, transparent)
+        ):
             continue
         diags.extend(
-            _flag_if_above_single_caller(path, code, name, node=m, graph=graph, defs=all_methods, ref_lines=ref_lines)
+            _flag_if_above_single_caller(
+                path, code, name, node=m, graph=graph, defs=all_methods, ref_lines=ref_lines, transparent=transparent
+            )
         )
     return diags
 
@@ -214,6 +229,7 @@ def _flag_if_above_single_caller(
     graph: dict[str, set[str]],
     defs: Mapping[str, ast.stmt],
     ref_lines: dict[tuple[str, str], int],
+    transparent: frozenset[str],
 ) -> list[Diagnostic]:
     callers = [c for c, callees in graph.items() if name in callees]
     if len(callers) != 1:
@@ -224,7 +240,9 @@ def _flag_if_above_single_caller(
     if isinstance(defs[caller], ast.ClassDef):
         return []
     caller_node = defs[caller]
-    if isinstance(caller_node, (ast.FunctionDef, ast.AsyncFunctionDef)) and _has_order_sensitive_decorator(caller_node):
+    if isinstance(caller_node, (ast.FunctionDef, ast.AsyncFunctionDef)) and _has_order_sensitive_decorator(
+        caller_node, transparent
+    ):
         return []
     if _reaches(graph, name, caller):
         return []
@@ -338,15 +356,38 @@ def _is_private_helper_name(name: str) -> bool:
     return not (name.startswith("__") and name.endswith("__"))
 
 
-def _has_order_sensitive_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
-    for decorator in node.decorator_list:
-        target = decorator.func if isinstance(decorator, ast.Call) else decorator
-        match target:
-            case ast.Name(id=name) | ast.Attribute(attr=name) if name in _ORDER_TRANSPARENT_DECORATORS:
-                continue
+def _unshadowed_builtin_decorators(tree: ast.Module) -> frozenset[str]:
+    bound: set[str] = set()
+    for node in _walk(tree):
+        match node:
+            case ast.ImportFrom(names=names) if any(alias.name == "*" for alias in names):
+                return frozenset()
+            case (
+                ast.Name(id=name, ctx=ast.Store() | ast.Del())
+                | ast.arg(arg=name)
+                | ast.FunctionDef(name=name)
+                | ast.AsyncFunctionDef(name=name)
+                | ast.ClassDef(name=name)
+            ):
+                bound.add(name)
+            case ast.alias(name=name, asname=asname):
+                bound.add(asname or name.split(".")[0])
+            case (
+                ast.ExceptHandler(name=str() as name)
+                | ast.MatchAs(name=str() as name)
+                | ast.MatchStar(name=str() as name)
+                | ast.MatchMapping(rest=str() as name)
+            ):
+                bound.add(name)
             case _:
-                return True
-    return False
+                pass
+    return _ORDER_TRANSPARENT_DECORATORS - bound
+
+
+def _has_order_sensitive_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef, transparent: frozenset[str]) -> bool:
+    return any(
+        not isinstance(decorator, ast.Name) or decorator.id not in transparent for decorator in node.decorator_list
+    )
 
 
 def _deferred_body(node: ast.stmt) -> list[ast.stmt]:
@@ -626,7 +667,18 @@ def _direct_scope_bindings(node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[
 
 
 def _lambda_bindings(node: ast.Lambda) -> set[str]:
-    return _argument_names(node.args)
+    bound = _argument_names(node.args)
+    stack: list[ast.AST] = [node.body]
+    while stack:
+        current = stack.pop()
+        if isinstance(current, ast.Lambda):
+            stack.extend(current.args.defaults)
+            stack.extend(default for default in current.args.kw_defaults if default is not None)
+            continue
+        if isinstance(current, ast.NamedExpr):
+            bound.update(_target_names(current.target))
+        stack.extend(_child_nodes(current))
+    return bound
 
 
 def _argument_names(args: ast.arguments) -> set[str]:

{sarj_python_lint-0.81.2 → sarj_python_lint-0.81.4}/src/sarj_python_lint/rules/typed_error_reasons.py

@@ -32,23 +32,54 @@ class TypedErrorReasons(Rule):
     id = "typed-error-reasons"
     code = "SARJ435"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Exception aggregates presentation strings instead of typed error reasons.",
+        summary="Review joined exception strings for fixed reason identities versus dynamic context.",
         rationale=(
-            "A collection of rendered sentences has no stable identity for API clients, UI formatting, telemetry, "
-            "or exhaustive handling; consumers must display or parse text that should be presentation-only."
+            "Fixed reason identities benefit from stable codes for API clients, UI formatting, telemetry, and "
+            "exhaustive handling. Open-ended values such as file paths remain typed context, not an enum domain."
         ),
         remediation=(
-            "Replace `list[str]` with a nominal reason type: usually a record containing a `StrEnum` code and typed "
-            "context. Format that structure only at the presentation boundary."
+            "If the strings are fixed reason identities, use a `StrEnum` code with typed context. Keep dynamic "
+            "paths and messages as typed context; format presentation separately."
         ),
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only an Error/Exception subclass whose direct Error/Exception base is visible in the class declaration is checked.",
-            "The constructor must have exactly one non-self parameter, annotated exactly `list[str]`, and join that same parameter inside `super().__init__(...)`.",
+            "The class name and a direct base name must end in Error or Exception; this naming convention does not prove exception inheritance or resolve shadowed bases.",
+            "The constructor must have exactly one non-self parameter and no variadic parameters, annotated exactly `list[str]`, and a literal string separator must join it inside `super().__init__(...)`.",
+            "This warning requests manual review; joining strings does not prove a finite reason domain, so contextual string lists may also match and must not automatically become enums.",
             "Formatting delegated to another function, legacy `typing.List`, mixed constructor context, tests, and generated files are intentionally not inferred.",
         ),
         examples=(
+            RuleExample(
+                example_id="dynamic-context-review",
+                title="Review a contextual list without converting paths to enum values",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/errors.py",
+                        "class MissingFilesError(Exception):\n    def __init__(self, paths: list[str]) -> None:\n        super().__init__(', '.join(paths))\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/errors.py"),
+                expected_count=1,
+                public=True,
+                scenario="dynamic-context",
+            ),
+            RuleExample(
+                example_id="dynamic-context-kept-typed",
+                title="Keep arbitrary paths as typed context without an enum",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/errors.py",
+                        "class MissingFilesError(Exception):\n    def __init__(self, paths: list[str]) -> None:\n        self.paths = paths\n        super().__init__('Files are missing')\n\ndef render_error(error: MissingFilesError) -> str:\n    return ', '.join(error.paths)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/errors.py"),
+                expected_count=0,
+                public=True,
+                scenario="dynamic-context",
+            ),
             RuleExample(
                 example_id="rendered-reason-list",
                 title="An exception renders raw reason strings",
@@ -135,8 +166,9 @@ class TypedErrorReasons(Rule):
                     code=self.code,
                     severity=Severity.WARNING,
                     message=(
-                        f"`{error_class.name}` joins `{parameter.arg}: list[str]` into its message; carry nominal "
-                        "reason codes with typed context and format them at the presentation boundary"
+                        f"`{error_class.name}` joins `{parameter.arg}: list[str]` into its message; if these are "
+                        "fixed reason identities, carry typed codes. Keep dynamic context such as paths or messages "
+                        "as typed context and format presentation separately"
                     ),
                 )
             )
@@ -156,6 +188,8 @@ def _tail(node: ast.expr) -> str:
 
 
 def _sole_string_list_parameter(function: ast.FunctionDef) -> ast.arg | None:
+    if function.args.vararg is not None or function.args.kwarg is not None:
+        return None
     parameters = [
         argument
         for argument in (
@@ -221,6 +255,8 @@ def _joins_parameter(node: ast.AST, parameter: str) -> TypeGuard[ast.Call]:
         isinstance(node, ast.Call)
         and isinstance(node.func, ast.Attribute)
         and node.func.attr == "join"
+        and isinstance(node.func.value, ast.Constant)
+        and isinstance(node.func.value.value, str)
         and len(node.args) == 1
         and not node.keywords
         and isinstance(node.args[0], ast.Name)

sarj_python_lint-0.81.2/src/sarj_python_lint/rules/no_redundant_module_alias_exports.py

@@ -1,190 +0,0 @@
-from __future__ import annotations
-
-import ast
-from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, ClassVar, final, override
-
-from sarj_python_lint.rule_base import (
-    AutofixPolicy,
-    Diagnostic,
-    ExampleFile,
-    ExampleOutcome,
-    Rule,
-    RuleCategory,
-    RuleDocumentation,
-    RuleExample,
-    Severity,
-    parse_or_none,
-)
-from sarj_python_lint.rules._paths import is_generated
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-_MIN_ALIAS_STATEMENTS = 4
-
-
-@final
-class NoRedundantModuleAliasExports(Rule):
-    id: str = "no-redundant-module-alias-exports"
-    code: str = "SARJ440"
-    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="Do not copy names before replacing a compatibility module.",
-        rationale=(
-            "A compatibility module that replaces itself in `sys.modules` already exposes the canonical module. "
-            "Copying every public attribute first duplicates the API surface and invites drift."
-        ),
-        remediation=(
-            "Delete the forwarding assignments and keep the canonical module import plus the final "
-            "`sys.modules[__name__] = alias` replacement. Import the canonical path inside maintained code."
-        ),
-        category=RuleCategory.MAINTAINABILITY,
-        autofix=AutofixPolicy.NONE,
-        limitations=(
-            "Only otherwise-pure compatibility modules with a final, unconditional self-replacement are checked.",
-            "Forwarding must use exact same-name assignments such as `Thing = canonical.Thing`.",
-            "Conditional, nested, computed, annotated, chained, destructured, or mixed-purpose modules are excluded.",
-            "Generated source, malformed source, and stub files (`.pyi`) are outside this rule's scope.",
-            "No autofix is offered because attribute access can have side effects and circular imports require review.",
-        ),
-        examples=(
-            RuleExample(
-                example_id="self-replacing-compatibility-module",
-                title="Remove bindings that the canonical module replacement supersedes",
-                outcome=ExampleOutcome.MATCH,
-                files=(
-                    ExampleFile.python(
-                        "legacy/settings.py",
-                        "import sys\n\n"
-                        "from canonical import settings as _canonical\n\n\n"
-                        "Settings = _canonical.Settings\n"
-                        "load = _canonical.load\n"
-                        "sys.modules[__name__] = _canonical\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("legacy/settings.py"),
-                expected_count=1,
-                public=True,
-            ),
-            RuleExample(
-                example_id="pure-module-alias",
-                title="Replace the compatibility module without copying its attributes",
-                outcome=ExampleOutcome.NO_MATCH,
-                files=(
-                    ExampleFile.python(
-                        "legacy/settings.py",
-                        "import sys\n\n"
-                        "from canonical import settings as _canonical\n\n\n"
-                        "sys.modules[__name__] = _canonical\n",
-                    ),
-                ),
-                focus_path=PurePosixPath("legacy/settings.py"),
-                expected_count=0,
-                public=True,
-            ),
-        ),
-    )
-    description: str = documentation.summary
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if path.suffix != ".py" or "sys.modules" not in source or is_generated(path, source):
-            return []
-        tree = parse_or_none(path, source)
-        if tree is None:
-            return []
-        first_forward = _redundant_forward(tree)
-        if first_forward is None:
-            return []
-        return [
-            Diagnostic(
-                path=path,
-                line=first_forward.lineno,
-                col=first_forward.col_offset + 1,
-                code=self.code,
-                severity=Severity.ERROR,
-                message=(
-                    "Delete the forwarding assignments; this compatibility module already replaces itself with "
-                    "the canonical module."
-                ),
-            )
-        ]
-
-
-def _redundant_forward(tree: ast.Module) -> ast.Assign | None:
-    body = list(tree.body)
-    if body and _is_docstring(body[0]):
-        body.pop(0)
-    while body and isinstance(body[0], ast.ImportFrom) and body[0].module == "__future__":
-        body.pop(0)
-    if len(body) < _MIN_ALIAS_STATEMENTS or not _imports_sys(body[0]):
-        return None
-    alias = _canonical_alias(body[1])
-    if alias is None or not _replaces_current_module(body[-1], alias):
-        return None
-    forwards = body[2:-1]
-    if not forwards:
-        return None
-    for statement in forwards:
-        if not _is_same_name_forward(statement, alias):
-            return None
-    return forwards[0] if isinstance(forwards[0], ast.Assign) else None
-
-
-def _is_docstring(statement: ast.stmt) -> bool:
-    return (
-        isinstance(statement, ast.Expr)
-        and isinstance(statement.value, ast.Constant)
-        and isinstance(statement.value.value, str)
-    )
-
-
-def _imports_sys(statement: ast.stmt) -> bool:
-    return (
-        isinstance(statement, ast.Import)
-        and len(statement.names) == 1
-        and statement.names[0].name == "sys"
-        and (statement.names[0].asname is None)
-    )
-
-
-def _canonical_alias(statement: ast.stmt) -> str | None:
-    match statement:
-        case ast.Import(names=[ast.alias(asname=alias)]) if alias is not None:
-            return alias
-        case ast.ImportFrom(module=module, names=[ast.alias(name=name, asname=alias)]) if (
-            module is not None and name != "*" and alias is not None
-        ):
-            return alias
-        case _:
-            return None
-
-
-def _is_same_name_forward(statement: ast.stmt, alias: str) -> bool:
-    match statement:
-        case ast.Assign(
-            targets=[ast.Name(id=target, ctx=ast.Store())],
-            value=ast.Attribute(value=ast.Name(id=owner, ctx=ast.Load()), attr=attribute, ctx=ast.Load()),
-        ):
-            return owner == alias and target == attribute and target not in {"sys", "__name__", alias}
-        case _:
-            return False
-
-
-def _replaces_current_module(statement: ast.stmt, alias: str) -> bool:
-    match statement:
-        case ast.Assign(
-            targets=[
-                ast.Subscript(
-                    value=ast.Attribute(value=ast.Name(id="sys", ctx=ast.Load()), attr="modules", ctx=ast.Load()),
-                    slice=ast.Name(id="__name__", ctx=ast.Load()),
-                    ctx=ast.Store(),
-                )
-            ],
-            value=ast.Name(id=replacement, ctx=ast.Load()),
-        ):
-            return replacement == alias
-        case _:
-            return False