sarj-python-lint 1.16.3__tar.gz → 1.18.0__tar.gz

{sarj_python_lint-1.16.3 → sarj_python_lint-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.16.3
+Version: 1.18.0
 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-1.16.3 → sarj_python_lint-1.18.0}/pyproject.toml

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

{sarj_python_lint-1.16.3 → sarj_python_lint-1.18.0}/src/sarj_python_lint/__main__.py

@@ -84,7 +84,18 @@ def _python_files(p: Path) -> list[Path]:
     return sorted(out)
 
 
+def _canonical_rule_ids(rule_ids: list[str]) -> list[str]:
+    aliases = {
+        alias: rule_id
+        for rule_id, cls in REGISTRY.items()
+        if (documentation := cls.documentation) is not None
+        for alias in documentation.aliases
+    }
+    return list(dict.fromkeys(rid if rid in REGISTRY else aliases.get(rid, rid) for rid in rule_ids))
+
+
 def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
+    rule_ids = _canonical_rule_ids(rule_ids)
     unknown = [rid for rid in rule_ids if rid not in REGISTRY]
     if unknown:
         sys.stderr.write(f"unknown rule(s): {', '.join(unknown)}\n")
@@ -155,6 +166,7 @@ _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
         # Keep the annotation diagnostics when SARJ094 is absent, including
         # when a concrete response_model makes the route contract complete.
         "SARJ094": frozenset({"SARJ008", "SARJ447"}),
+        "SARJ095": frozenset({"SARJ468"}),
         "SARJ099": frozenset({"SARJ420"}),
         # Any-valued mappings are the stronger correctness failure. SARJ008
         # still owns every fixed dictionary return when selected alone, while

{sarj_python_lint-1.16.3 → sarj_python_lint-1.18.0}/src/sarj_python_lint/rules/_registry.py

@@ -9,7 +9,6 @@ from sarj_python_lint.rules.complex_postgres_query_requires_architecture_review
     ComplexPostgresQueryRequiresArchitectureReview,
 )
 from sarj_python_lint.rules.defect_xfail_requires_explicit_strict import DefectXfailRequiresExplicitStrict
-from sarj_python_lint.rules.discourage_nullable_constructor_parameters import DiscourageNullableConstructorParameters
 from sarj_python_lint.rules.docstring_args_restate_signature import (
     DocstringArgsRestateSignature,
 )
@@ -136,6 +135,7 @@ from sarj_python_lint.rules.prefer_or_pattern import PreferOrPattern
 from sarj_python_lint.rules.prefer_pydantic_json_value import PreferPydanticJsonValue
 from sarj_python_lint.rules.prefer_pytest_fixture_injection import PreferPytestFixtureInjection
 from sarj_python_lint.rules.prefer_regex_fullmatch import PreferRegexFullmatch
+from sarj_python_lint.rules.prefer_required_constructor_parameters import PreferRequiredConstructorParameters
 from sarj_python_lint.rules.prefer_self_documenting_constant import (
     PreferSelfDocumentingConstant,
 )
@@ -203,7 +203,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
         NoDatabaseProgrammability.id: NoDatabaseProgrammability,
         RequireExplicitContractImplementation.id: RequireExplicitContractImplementation,
-        DiscourageNullableConstructorParameters.id: DiscourageNullableConstructorParameters,
+        PreferRequiredConstructorParameters.id: PreferRequiredConstructorParameters,
         RequirePublicDependencyContract.id: RequirePublicDependencyContract,
         RequirePreciseFactorySignature.id: RequirePreciseFactorySignature,
         RequireExplicitServiceContract.id: RequireExplicitServiceContract,

{sarj_python_lint-1.16.3 → sarj_python_lint-1.18.0}/src/sarj_python_lint/rules/prefer_immutable_module_constant.py

@@ -20,10 +20,13 @@ from sarj_python_lint.rules._paths import is_test_path, is_test_support_path
 
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from sarj_python_lint._file_context import PythonFileContext
 
 
 _CONSTANT_NAME = re.compile(r"^_?[A-Z][A-Z0-9_]*$")
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
 _MUTATING_METHODS = frozenset(
     {
         "add",
@@ -73,21 +76,25 @@ class PreferImmutableModuleConstant(Rule):
     code: str = "SARJ096"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary=("Nonempty uppercase module collections allow top-level membership or keys to change at runtime."),
+        summary=(
+            "Module collection constants should use native immutable containers or declare dictionary bindings as Final."
+        ),
         rationale=(
-            "A constant-looking collection can expose process-wide top-level mutation even when callers intend it as a "
-            "read-only lookup table."
+            "Tuple and frozenset protect collection membership. Final makes a dictionary's constant binding explicit "
+            "without changing its runtime type or concrete dictionary API."
         ),
         remediation=(
-            "When the concrete collection API is not part of the contract, use a tuple for ordered values, a frozenset for "
-            "membership, or a Mapping-typed immutable mapping for keyed values. Recursively freeze nested values when needed."
+            "When the concrete list or set API is not part of the contract, use a tuple for ordered values or a frozenset "
+            "for membership. Annotate dictionary constants with Final[dict[K, V]]. Final prevents reassignment in type-checked "
+            "code but does not freeze dictionary contents. Use MappingProxyType when runtime write protection is required."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Empty collections and collections intentionally mutated or passed to unknown calls are not reported.",
-            "The suggested replacements prevent top-level membership or key changes; tuple and MappingProxyType are shallow.",
-            "Changing list or dict to an immutable type can affect consumers, serialization, equality, and concrete API methods.",
+            "Direct declarations and declarations in module-level if/try suites are checked; repeated bindings, loops, functions, and class bodies are excluded.",
+            "Final has no runtime enforcement and permits item mutation on dictionaries; tuple and frozenset are shallow.",
+            "Changing a list or set to an immutable type can affect consumers, serialization, and concrete API methods.",
             "Test, test-support, and generated files are excluded.",
         ),
         examples=(
@@ -122,12 +129,42 @@ class PreferImmutableModuleConstant(Rule):
             RuleExample(
                 example_id="immutable-module-mapping",
                 scenario="keyed-values",
-                title="Read-only mapping used for keyed values",
+                title="Final dictionary binding used for keyed values",
                 outcome=ExampleOutcome.NO_MATCH,
                 files=(
                     ExampleFile.python(
                         "settings.py",
-                        'from collections.abc import Mapping\nfrom types import MappingProxyType\n\nROLE_LABELS: Mapping[str, str] = MappingProxyType({"admin": "Administrator"})\n',
+                        'from typing import Final\n\nROLE_LABELS: Final[dict[str, str]] = {"admin": "Administrator"}\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("settings.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="conditional-module-mapping",
+                scenario="conditional-factory",
+                title="Conditional dictionary factory needs constant intent",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "settings.py",
+                        'if voice_enabled:\n    TOOL_LABELS = dict.fromkeys(("call", "transfer"), "Voice")\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("settings.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="final-conditional-module-mapping",
+                scenario="conditional-factory",
+                title="Conditional dictionary factory declares a Final binding",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "settings.py",
+                        'from typing import Final\n\nif voice_enabled:\n    TOOL_LABELS: Final[dict[str, str]] = dict.fromkeys(("call", "transfer"), "Voice")\n',
                     ),
                 ),
                 focus_path=PurePosixPath("settings.py"),
@@ -147,13 +184,18 @@ class PreferImmutableModuleConstant(Rule):
         if tree is None:
             return []
         mutated = _mutated_names(tree)
-        shadowed_builtins = _module_bound_names(tree) & {"dict", "list", "set"}
+        module_names = _module_bound_names(tree)
+        shadowed_builtins = {"dict", "list", "set"} if "*" in module_names else module_names & {"dict", "list", "set"}
+        statements = tuple(_module_statements(tree.body))
+        final_names = _final_names(statements, context)
         findings: list[Diagnostic] = []
-        for statement in tree.body:
+        for statement in statements:
             for name, value in _bindings(statement):
                 kind = _mutable_literal_kind(value, shadowed_builtins=shadowed_builtins)
                 if kind is None or name in mutated or not _CONSTANT_NAME.fullmatch(name) or name.startswith("__"):
                     continue
+                if kind == "dict" and name in final_names:
+                    continue
                 findings.append(
                     Diagnostic(
                         path,
@@ -167,6 +209,57 @@ class PreferImmutableModuleConstant(Rule):
         return findings
 
 
+def _module_statements(body: list[ast.stmt]) -> Iterator[ast.stmt]:
+    for statement in body:
+        yield statement
+        match statement:
+            case ast.If():
+                yield from _module_statements(statement.body)
+                yield from _module_statements(statement.orelse)
+            case ast.Try() | ast.TryStar():
+                yield from _module_statements(statement.body)
+                for handler in statement.handlers:
+                    yield from _module_statements(handler.body)
+                yield from _module_statements(statement.orelse)
+                yield from _module_statements(statement.finalbody)
+            case _:
+                pass
+
+
+def _final_names(statements: tuple[ast.stmt, ...], context: PythonFileContext) -> frozenset[str]:
+    annotations = [
+        statement
+        for statement in statements
+        if isinstance(statement, ast.AnnAssign) and isinstance(statement.target, ast.Name)
+    ]
+    tree = context.tree
+    if not annotations or tree is None:
+        return frozenset()
+    non_import_bindings = _scope_bound_names(tree.body, include_imports=False)
+    return frozenset(
+        statement.target.id
+        for statement in annotations
+        if isinstance(statement.target, ast.Name)
+        and _is_final_annotation(statement.annotation, context, non_import_bindings)
+    )
+
+
+def _is_final_annotation(annotation: ast.expr, context: PythonFileContext, non_import_bindings: set[str]) -> bool:
+    if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+        try:
+            annotation = ast.parse(annotation.value.strip(), mode="eval").body
+        except SyntaxError:
+            return False
+    if isinstance(annotation, ast.Subscript):
+        if isinstance(annotation.slice, ast.Tuple):
+            return False
+        annotation = annotation.value
+    root = _root_name(annotation)
+    return root not in non_import_bindings and context.module_imports.resolves(
+        annotation, sources=_TYPING_SOURCES, symbol="Final"
+    )
+
+
 def _bindings(statement: ast.stmt) -> tuple[tuple[str, ast.expr], ...]:
     match statement:
         case ast.Assign(targets=targets, value=value):
@@ -195,14 +288,30 @@ def _mutable_literal_kind(value: ast.expr, *, shadowed_builtins: set[str]) -> st
             return None
         case ast.Call(func=ast.Name(id=kind)) if kind in {"set", "dict", "list"} and kind not in shadowed_builtins:
             return kind
+        case ast.Call(func=ast.Attribute(value=ast.Name(id="dict"), attr="fromkeys"), args=args, keywords=[]) if (
+            "dict" not in shadowed_builtins
+            and len(args) in {1, 2}
+            and not any(isinstance(argument, ast.Starred) for argument in args)
+        ):
+            return None if _empty_literal(args[0]) else "dict"
         case _:
             return None
 
 
+def _empty_literal(value: ast.expr) -> bool:
+    match value:
+        case (
+            ast.List(elts=[]) | ast.Tuple(elts=[]) | ast.Set(elts=[]) | ast.Dict(keys=[]) | ast.Constant(value="" | b"")
+        ):
+            return True
+        case _:
+            return False
+
+
 def _mutated_names(tree: ast.Module) -> frozenset[str]:
     mutated: set[str] = set()
     module_bindings: dict[str, int] = {}
-    for statement in tree.body:
+    for statement in _module_statements(tree.body):
         if isinstance(statement, ast.Assign) and len(statement.targets) > 1:
             # Skip every chained alias because mutation or escape through one name changes them all.
             mutated.update(target.id for target in statement.targets if isinstance(target, ast.Name))
@@ -424,8 +533,9 @@ def _scope_global_names(body: list[ast.stmt]) -> set[str]:
 
 
 class _BoundNameCollector(ast.NodeVisitor):
-    def __init__(self) -> None:
+    def __init__(self, *, include_imports: bool) -> None:
         self.names: set[str] = set()
+        self._include_imports: bool = include_imports
 
     def _record_target(self, target: ast.expr) -> None:
         match target:
@@ -503,11 +613,13 @@ class _BoundNameCollector(ast.NodeVisitor):
 
     @override
     def visit_Import(self, node: ast.Import) -> None:
-        self.names.update(alias.asname or alias.name.split(".", maxsplit=1)[0] for alias in node.names)
+        if self._include_imports:
+            self.names.update(alias.asname or alias.name.split(".", maxsplit=1)[0] for alias in node.names)
 
     @override
     def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
-        self.names.update(alias.asname or alias.name for alias in node.names)
+        if self._include_imports:
+            self.names.update(alias.asname or alias.name for alias in node.names)
 
     @override
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
@@ -544,8 +656,8 @@ class _BoundNameCollector(ast.NodeVisitor):
         self.generic_visit(node)
 
 
-def _scope_bound_names(body: list[ast.stmt]) -> set[str]:
-    collector = _BoundNameCollector()
+def _scope_bound_names(body: list[ast.stmt], *, include_imports: bool = True) -> set[str]:
+    collector = _BoundNameCollector(include_imports=include_imports)
     for statement in body:
         collector.visit(statement)
     return collector.names
@@ -615,10 +727,15 @@ def _literal_container_root_names(value: ast.expr) -> tuple[str, ...]:
 
 
 def _message(name: str, kind: str) -> str:
-    replacement = {"list": "tuple", "set": "frozenset", "dict": "an immutable mapping"}[kind]
+    if kind == "dict":
+        return (
+            f"uppercase module dictionary `{name}` should declare constant intent with Final[dict[K, V]]; "
+            "Final prevents reassignment in type-checked code but does not freeze dictionary contents."
+        )
+    replacement = {"list": "tuple", "set": "frozenset"}[kind]
     return (
         f"uppercase module collection `{name}` is a mutable {kind} — consider {replacement} to prevent top-level "
-        "membership or key changes; preserve concrete APIs and recursively freeze nested values when required."
+        "membership changes; preserve concrete APIs and recursively freeze nested values when required."
     )
 
 

{sarj_python_lint-1.16.3 → sarj_python_lint-1.18.0}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -101,7 +101,8 @@ class PreferMatchTypeDispatch(Rule):
         limitations=(
             "General dispatch requires three or more adjacent, unguarded `isinstance` branches over the same simple name. Two arms are checked only for an exact `ast.Name.id` / `ast.Attribute.attr` projection followed by a None-returning fallback.",
             "A terminating sibling prefix may precede a two-arm if/elif tail whose bodies can fall through. Preserve nested checks inside case bodies rather than moving them into case guards.",
-            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "The checked types must be unshadowed builtins, undecorated module-local classes without an explicit or known locally inherited custom metaclass, or proven stdlib ast classes; unresolved imports, runtime type groups, repeated type references, generated files, and non-terminating sibling checks are excluded.",
+            "Local ancestry must resolve to stable undeclared-metaclass classes or proven builtin/stdlib ast bases. External bases, runtime base aliases, and parameterized base expressions remain excluded because their metaclass or __class_getitem__ effects are unproven.",
             "Nested attribute-validation guards are excluded: converting them to keyword class patterns can turn attribute errors into match fallthrough, and an imported isinstance operand may be a runtime tuple rather than a class.",
             "A terminal-looking context-manager body does not prove a sibling branch terminates: exceptions can be suppressed. An unconditional return or raise after the context manager remains eligible.",
             "Declared support for Python before 3.10 suppresses this recommendation when proven by the nearest project metadata or exact installed-distribution ownership. Missing or ambiguous target metadata retains advisory behavior; it does not prove a modern target.",
@@ -239,20 +240,20 @@ class PreferMatchTypeDispatch(Rule):
             return []
         imports = context.imports
         all_nodes = tuple(context.nodes(ast.AST))
-        unsafe_bindings = _unsafe_local_bound_names(tree, all_nodes) | frozenset(
+        unsafe_bindings = _unsafe_local_bound_names(tree, all_nodes, imports) | frozenset(
             qualified
             for node in all_nodes
             if isinstance(node, ast.Attribute)
             and isinstance(node.ctx, (ast.Store, ast.Del))
             and (qualified := imports.resolved_qualified_name(node)) is not None
-            and qualified.startswith("ast.")
+            and qualified.startswith(("ast.", "builtins."))
         )
         has_wildcard_import = any(
             isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names) for node in all_nodes
         )
         if not imports.builtin_is_unshadowed("isinstance") or "isinstance" in unsafe_bindings or has_wildcard_import:
             return []
-        local_classes = _unshadowed_module_classes(tree, all_nodes)
+        local_classes = _unshadowed_module_classes(tree, all_nodes, imports, unsafe_bindings)
         findings = _ladder_findings(
             all_nodes,
             path,
@@ -287,14 +288,10 @@ class PreferMatchTypeDispatch(Rule):
         return findings
 
 
-def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    classes = [
-        statement.name
-        for statement in tree.body
-        if isinstance(statement, ast.ClassDef)
-        and not statement.decorator_list
-        and not any(keyword.arg in {"metaclass", None} for keyword in statement.keywords)
-    ]
+def _unshadowed_module_classes(
+    tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> frozenset[str]:
+    declarations = [statement for statement in tree.body if isinstance(statement, ast.ClassDef)]
     rebound: set[str] = set()
     for node in all_nodes:
         match node:
@@ -310,17 +307,83 @@ def _unshadowed_module_classes(tree: ast.Module, all_nodes: tuple[ast.AST, ...])
             case _:
                 pass
     _add_module_import_bindings(tree, rebound)
-    return frozenset(name for name in classes if classes.count(name) == 1 and name not in rebound)
+    names = [declaration.name for declaration in declarations]
+    stable = [
+        declaration
+        for declaration in declarations
+        if names.count(declaration.name) == 1 and declaration.name not in rebound
+    ]
+    nominal = _nominal_class_ancestry(stable, imports, unsafe_bindings)
+    return frozenset(
+        declaration.name
+        for declaration in stable
+        if declaration.name in nominal
+        and not any(keyword.arg in {"metaclass", None} for keyword in declaration.keywords)
+    )
 
 
-def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...]) -> frozenset[str]:
-    module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
-    names = {
-        alias.asname or alias.name.partition(".")[0]
-        for statement in all_nodes
-        if isinstance(statement, (ast.Import, ast.ImportFrom)) and id(statement) not in module_imports
-        for alias in statement.names
-    }
+def _nominal_class_ancestry(
+    declarations: list[ast.ClassDef], imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> frozenset[str]:
+    proven: frozenset[str] = frozenset()
+    while True:
+        nominal = frozenset(
+            declaration.name
+            for declaration in declarations
+            if not declaration.decorator_list
+            and not _unproven_metaclass_header(declaration, imports, unsafe_bindings)
+            and all(_nominal_base(base, imports, proven, unsafe_bindings) for base in declaration.bases)
+        )
+        if nominal <= proven:
+            return proven
+        proven |= nominal
+
+
+def _nominal_base(
+    expression: ast.expr, imports: ImportIndex, local_classes: frozenset[str], unsafe_bindings: frozenset[str]
+) -> bool:
+    if isinstance(expression, ast.Subscript):
+        return False
+    return _type_reference(expression, imports, local_classes, unsafe_bindings) is not None or (
+        _builtin_class_reference(expression, imports, unsafe_bindings) is not None
+    )
+
+
+def _unproven_metaclass_header(
+    declaration: ast.ClassDef, imports: ImportIndex, unsafe_bindings: frozenset[str]
+) -> bool:
+    for keyword in declaration.keywords:
+        if keyword.arg is None:
+            return True
+        if keyword.arg != "metaclass":
+            continue
+        if _builtin_class_reference(keyword.value, imports, unsafe_bindings) == "type":
+            continue
+        return True
+    return False
+
+
+def _builtin_class_reference(expression: ast.expr, imports: ImportIndex, unsafe_bindings: frozenset[str]) -> str | None:
+    root = expression
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if not isinstance(root, ast.Name) or root.id in unsafe_bindings:
+        return None
+    if (
+        isinstance(expression, ast.Name)
+        and expression.id in _BUILTIN_TYPES
+        and imports.builtin_is_unshadowed(expression.id)
+        and f"builtins.{expression.id}" not in unsafe_bindings
+    ):
+        return expression.id
+    symbol = imports.resolved_symbol(expression, sources=frozenset({"builtins"}))
+    if symbol in _BUILTIN_TYPES and f"builtins.{symbol}" not in unsafe_bindings:
+        return symbol
+    return None
+
+
+def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex) -> frozenset[str]:
+    names = _unsafe_import_bound_names(tree, all_nodes, imports)
     names.update(
         candidate.name
         for candidate in all_nodes
@@ -334,6 +397,31 @@ def _unsafe_local_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...])
     return frozenset(names)
 
 
+def _unsafe_import_bound_names(tree: ast.Module, all_nodes: tuple[ast.AST, ...], imports: ImportIndex) -> set[str]:
+    module_imports = {id(statement) for statement in tree.body if isinstance(statement, (ast.Import, ast.ImportFrom))}
+    names: set[str] = set()
+    for statement in all_nodes:
+        if not isinstance(statement, (ast.Import, ast.ImportFrom)):
+            continue
+        relative = isinstance(statement, ast.ImportFrom) and statement.level > 0
+        if id(statement) in module_imports and not relative:
+            continue
+        for alias in statement.names:
+            if not _preserves_indexed_import(statement, alias, imports):
+                names.add(alias.asname or alias.name.partition(".")[0])
+    return names
+
+
+def _preserves_indexed_import(statement: ast.Import | ast.ImportFrom, alias: ast.alias, imports: ImportIndex) -> bool:
+    local = alias.asname or alias.name.partition(".")[0]
+    target = imports.bindings.get(local)
+    if target is None:
+        return False
+    if isinstance(statement, ast.ImportFrom):
+        return not statement.level and target.module == statement.module and target.symbol == alias.name
+    return target.module == alias.name and target.symbol is None
+
+
 def _ladder_findings(
     all_nodes: tuple[ast.AST, ...],
     path: Path,
@@ -632,6 +720,7 @@ def _type_reference(
             expression.id in _BUILTIN_TYPES
             and imports.builtin_is_unshadowed(expression.id)
             and expression.id not in unsafe_bindings
+            and f"builtins.{expression.id}" not in unsafe_bindings
         ):
             return expression.id
         if expression.id in local_classes and expression.id not in unsafe_bindings:

{sarj_python_lint-1.16.3 → sarj_python_lint-1.18.0}/src/sarj_python_lint/rules/prefer_module_level_constant.py

@@ -99,20 +99,23 @@ class PreferModuleLevelConstant(Rule):
     code: str = "SARJ039"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="Hoist repeatedly read static values when an immutable module representation preserves behavior.",
+        summary="Hoist repeatedly read static values when a module constant preserves behavior.",
         rationale=(
             "Rebuilding a substantial static collection repeats allocation, while calling `re.compile` with a "
-            "constant pattern repeats a regex-cache lookup. In reusable code, an immutable module value makes "
-            "the static lifetime explicit without exposing shared mutable state."
+            "constant pattern repeats a regex-cache lookup. Native immutable collections or Final dictionary bindings "
+            "make the static lifetime explicit for proven read-only use."
         ),
         remediation=(
-            "Define the value once at module scope as a tuple, frozenset, immutable mapping, or compiled pattern, "
-            "then reference it from the function. Preserve ordering and concrete-type behavior used by callers."
+            "Define the value once at module scope as a tuple, frozenset, Final[dict[K, V]], or compiled pattern, "
+            "then reference it from the function. Final prevents reassignment in type-checked code but does not freeze "
+            "dictionary contents; use MappingProxyType when runtime write protection is required. Preserve ordering "
+            "and concrete-type behavior used by callers."
         ),
         category=RuleCategory.PERFORMANCE,
         limitations=(
             "Test, test-support, and generated files are excluded.",
             "Collections require at least eight deeply immutable elements, or three when allocated inside a loop; only representation-insensitive reads are accepted.",
+            "Final dictionaries retain mutable contents at runtime; unknown calls, mutation, and escaping references are excluded from hoisting candidates.",
             "Regex findings require a proven stdlib `re.compile` binding and exclude `re.DEBUG`; the rule cannot prove that a function is hot, so findings remain advisory.",
         ),
         examples=(
@@ -144,6 +147,36 @@ class PreferModuleLevelConstant(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="static-lookup-built-per-call",
+                scenario="keyed-values",
+                title="Static lookup dictionary rebuilt per call",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "service.py",
+                        "def handle(key):\n    labels = {'a': 1, 'b': 2, 'c': 3, 'd': 4, 'e': 5, 'f': 6, 'g': 7, 'h': 8}\n    return labels.get(key)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="final-module-lookup",
+                scenario="keyed-values",
+                title="Final lookup dictionary defined once",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "service.py",
+                        "from typing import Final\n\nLABELS: Final[dict[str, int]] = {'a': 1, 'b': 2, 'c': 3, 'd': 4, 'e': 5, 'f': 6, 'g': 7, 'h': 8}\n\ndef handle(key):\n    return LABELS.get(key)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("service.py"),
+                expected_count=0,
+                public=True,
+            ),
         ),
     )
     description: str = documentation.summary
@@ -600,6 +633,12 @@ def _is_excluded_test_path(path: Path) -> bool:
 def _message(name: str, candidate: _Candidate) -> str:
     if candidate.kind == _REGEX_KIND:
         return f"`{name}` repeats a regex-cache lookup on every call — hoist it to module scope."
+    if candidate.kind == "dict":
+        return (
+            f"`{name}` is a constant-only dictionary rebuilt on every call — hoist it to module scope as "
+            "Final[dict[K, V]] for read-only lookup use. Final prevents reassignment in type-checked code but does not "
+            "freeze dictionary contents; use MappingProxyType when runtime write protection is required."
+        )
     return (
         f"`{name}` is a constant-only {candidate.kind} rebuilt on every call — hoist it "
         "to module scope in immutable form (tuple, frozenset, or an immutable mapping) "