sarj-python-lint 1.16.0__tar.gz → 1.16.2__tar.gz

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/PKG-INFO

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

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

sarj_python_lint-1.16.2/src/sarj_python_lint/rules/discourage_nullable_constructor_parameters.py

@@ -0,0 +1,171 @@
+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,
+)
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_REJECTED = (
+    "class Service:\n"
+    "    def __init__(self, store: Store | None = None) -> None:\n"
+    "        if store is None:\n"
+    "            raise ValueError('store is required')\n"
+    "        self.store = store\n"
+)
+
+
+@final
+class DiscourageNullableConstructorParameters(Rule):
+    id = "discourage-nullable-constructor-parameters"
+    code = "SARJ468"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Make constructor inputs required when their None default is immediately rejected.",
+        rationale=(
+            "A constructor that immediately rejects its None default advertises omission even though it cannot "
+            "construct an instance from that default. Static typing permits the omitted call."
+        ),
+        remediation=(
+            "Make the rejected input required and non-nullable. Keep deliberate optional state nullable; "
+            "no wrapper, interface, or alternate constructor is needed."
+        ),
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Requires a PEP604 nullable parameter with a literal None default and immediate explicit rejection in an undecorated synchronous __init__ body.",
+            "Only a first executable `if parameter is None: raise ...` or `assert parameter is not None` is checked; docstrings and simple assignments preparing a raised error are allowed. Compound guards, later validation, fallbacks, and required nullable inputs are excluded.",
+            "An assertion expresses rejection in normal assertions-enabled execution; Python -O can remove it. No autofix changes a public constructor signature or error type.",
+            "Tests, generated code, decorated classes, and constructors with decorators are excluded. Nullable state that is stored or handled is valid.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="rejected-constructor-default",
+                title="The constructor immediately rejects its advertised default",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/service.py", _REJECTED),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="required-constructor-input",
+                title="The signature requires the input that construction needs",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/service.py", _REJECTED.replace("Store | None = None", "Store")),),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.generated or context.tree is None or is_test_path(context.path):
+            return []
+        findings: list[Diagnostic] = []
+        for owner in context.nodes(ast.ClassDef):
+            if owner.decorator_list:
+                continue
+            for method in owner.body:
+                if not isinstance(method, ast.FunctionDef) or method.name != "__init__" or method.decorator_list:
+                    continue
+                parameter = _rejected_default(method)
+                if parameter is None:
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=parameter.lineno,
+                        col=parameter.col_offset + 1,
+                        code=self.code,
+                        severity=Severity.WARNING,
+                        message=f"Constructor input `{parameter.arg}` defaults to None but immediately rejects it; make this input required and non-nullable instead of adding an abstraction.",
+                    )
+                )
+        return findings
+
+
+def _rejected_default(method: ast.FunctionDef) -> ast.arg | None:
+    rejected = _immediately_rejected_parameter(method)
+    if rejected is None:
+        return None
+    positional = (*method.args.posonlyargs, *method.args.args)
+    defaulted = positional[-len(method.args.defaults) :] if method.args.defaults else ()
+    defaults = (
+        *zip(defaulted, method.args.defaults, strict=True),
+        *zip(method.args.kwonlyargs, method.args.kw_defaults, strict=True),
+    )
+    for parameter, default in defaults:
+        if parameter.arg != rejected or (positional and parameter is positional[0]):
+            continue
+        if (
+            not isinstance(default, ast.Constant)
+            or default.value is not None
+            or parameter.annotation is None
+            or not _is_nullable_union(parameter.annotation)
+        ):
+            continue
+        return parameter
+    return None
+
+
+def _immediately_rejected_parameter(method: ast.FunctionDef) -> str | None:
+    body = method.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        body = body[1:]
+    if not body:
+        return None
+    first = body[0]
+    if (
+        isinstance(first, ast.If)
+        and isinstance(first.body[-1], ast.Raise)
+        and all(isinstance(statement, (ast.Assign, ast.AnnAssign)) for statement in first.body[:-1])
+    ):
+        condition, operator = first.test, ast.Is
+    elif isinstance(first, ast.Assert):
+        condition, operator = first.test, ast.IsNot
+    else:
+        return None
+    if not isinstance(condition, ast.Compare) or len(condition.ops) != 1 or not isinstance(condition.ops[0], operator):
+        return None
+    left, right = condition.left, condition.comparators[0]
+    for name, absent in ((left, right), (right, left)):
+        if isinstance(name, ast.Name) and isinstance(absent, ast.Constant) and absent.value is None:
+            return name.id
+    return None
+
+
+def _is_nullable_union(annotation: ast.expr) -> bool:
+    if not isinstance(annotation, ast.BinOp) or not isinstance(annotation.op, ast.BitOr):
+        return False
+    return _is_none_union_member(annotation.left) or _is_none_union_member(annotation.right)
+
+
+def _is_none_union_member(annotation: ast.expr) -> bool:
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        return _is_none_union_member(annotation.left) or _is_none_union_member(annotation.right)
+    return isinstance(annotation, ast.Constant) and annotation.value is None

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/src/sarj_python_lint/rules/no_broad_keyword_capture.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import ast
+from dataclasses import replace
 from pathlib import PurePosixPath
+from types import MappingProxyType
 from typing import TYPE_CHECKING, ClassVar, final
 
 from sarj_python_lint.rule_base import (
@@ -18,6 +20,7 @@ from sarj_python_lint.rule_base import (
 )
 from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics, scope_bound_names
 from sarj_python_lint.rules._ast_index import walk
+from sarj_python_lint.rules.no_hidden_constructor_fallback import LocalBindingCollector, scope_bindings
 
 
 if TYPE_CHECKING:
@@ -62,7 +65,7 @@ class NoBroadKeywordCapture(Rule):
             "Reports missing, Any- or object-valued keyword captures whether discarded, read or forwarded.",
             "Precise or unresolved decorated signature-declaration families and functions with unresolved decorator effects are excluded; known classmethod/staticmethod/abstractmethod/final/override declarations remain eligible.",
             "Homogeneous keyword types constrain values but allow arbitrary names; ParamSpec preserves only its target's existing contract.",
-            "Generated/vendor source and stubs are excluded. Unresolved imports, wildcard imports and shadowed annotation provenance are conservative.",
+            "Generated/vendor source and stubs are excluded. Unresolved imports, wildcard imports, conflicting imports, actual global or definition-time writes and shadowed annotation provenance are conservative. Identical imports and read-only global declarations remain eligible.",
             "Cross-file aliases, external stubs, generated signatures and runtime reflection are not resolved; transparent annotation metadata and ambiguous decorated declaration families can cause conservative false negatives.",
             "No autofix can infer the intended contract. Dynamic payload/formatting APIs can intentionally need an exact-code exception.",
         ),
@@ -165,7 +168,8 @@ class NoBroadKeywordCapture(Rule):
         tree = context.tree
         if tree is None:
             return []
-        semantics = AnnotationSemantics.from_tree(tree)
+        semantics = _stable_annotation_semantics(context, tree)
+        mutated_members = _mutated_annotation_members(context, semantics)
         overloads: set[ast.FunctionDef | ast.AsyncFunctionDef] | None = None
         findings: list[Diagnostic] = []
         for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
@@ -174,12 +178,12 @@ class NoBroadKeywordCapture(Rule):
                 continue
             if not _is_broad(argument.annotation, semantics):
                 continue
-            if _uncertain_annotation(argument.annotation, function, context, semantics):
+            if _uncertain_annotation(argument.annotation, function, context, semantics, mutated_members):
                 continue
-            if _unknown_decorator(function, context, semantics):
+            if _unknown_decorator(function, context, semantics, mutated_members):
                 continue
             if overloads is None:
-                overloads = _overload_implementations(context, semantics)
+                overloads = _overload_implementations(context, semantics, mutated_members)
             if function in overloads:
                 continue
             if is_suppressed(context.source_lines, argument.lineno, self.code) or is_suppressed(
@@ -202,6 +206,90 @@ class NoBroadKeywordCapture(Rule):
         return sorted(findings, key=lambda finding: (finding.line, finding.col))
 
 
+def _stable_annotation_semantics(context: PythonFileContext, tree: ast.Module) -> AnnotationSemantics:
+    semantics = AnnotationSemantics.from_tree(tree)
+    unstable = _conflicting_annotation_imports(context, semantics) | _annotation_binding_writes(context)
+    if not unstable:
+        return semantics
+    imports = replace(
+        semantics.imports,
+        bindings=MappingProxyType(
+            {name: target for name, target in semantics.imports.bindings.items() if name not in unstable}
+        ),
+        shadowed_names=semantics.imports.shadowed_names | unstable,
+    )
+    return replace(
+        semantics,
+        imports=imports,
+        aliases=MappingProxyType({name: value for name, value in semantics.aliases.items() if name not in unstable}),
+    )
+
+
+def _conflicting_annotation_imports(context: PythonFileContext, semantics: AnnotationSemantics) -> set[str]:
+    conflicts: set[str] = set()
+    for statement in context.nodes(ast.Import, ast.ImportFrom):
+        if not isinstance(_lexical_scope(statement, context), ast.Module):
+            continue
+        for alias in statement.names:
+            name = alias.asname or alias.name.partition(".")[0]
+            binding = semantics.imports.bindings.get(name)
+            if binding is not None and _import_reference(statement, alias) != (binding.module, binding.symbol):
+                conflicts.add(name)
+    return conflicts
+
+
+def _import_reference(statement: ast.Import | ast.ImportFrom, alias: ast.alias) -> tuple[str, str | None] | None:
+    if isinstance(statement, ast.ImportFrom):
+        return (statement.module, alias.name) if not statement.level and statement.module is not None else None
+    return (alias.name if alias.asname else alias.name.partition(".")[0], None)
+
+
+def _annotation_binding_writes(context: PythonFileContext) -> set[str]:
+    writes: set[str] = set()
+    for owner in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda):
+        if isinstance(_lexical_scope(owner, context), ast.Module):
+            header = LocalBindingCollector()
+            header.visit(owner)
+            if not isinstance(owner, ast.Lambda):
+                header.names.discard(owner.name)
+            writes.update(header.names)
+        if not isinstance(owner, ast.Lambda):
+            body = LocalBindingCollector()
+            for statement in owner.body:
+                body.visit(statement)
+            writes.update(body.names & body.globals)
+    return writes
+
+
+def _mutated_annotation_members(context: PythonFileContext, semantics: AnnotationSemantics) -> frozenset[str]:
+    members: set[str] = set()
+    for node in context.nodes(ast.Attribute):
+        if not isinstance(node.ctx, (ast.Store, ast.Del)) or _shadowed_annotation(node, node, context, semantics):
+            continue
+        qualified = semantics.imports.resolved_qualified_name(node)
+        if qualified is not None:
+            members.add(qualified)
+    return frozenset(members)
+
+
+def _uses_mutated_member(annotation: ast.expr, semantics: AnnotationSemantics, mutated_members: frozenset[str]) -> bool:
+    if not mutated_members:
+        return False
+    pending = [annotation]
+    seen: set[str] = set()
+    while pending:
+        parsed = semantics.parse(pending.pop())
+        if parsed is None:
+            continue
+        for node in walk(parsed):
+            if isinstance(node, ast.Attribute) and semantics.imports.resolved_qualified_name(node) in mutated_members:
+                return True
+            if isinstance(node, ast.Name) and node.id in semantics.aliases and node.id not in seen:
+                seen.add(node.id)
+                pending.append(semantics.aliases[node.id])
+    return False
+
+
 def _is_broad(annotation: ast.expr | None, semantics: AnnotationSemantics) -> bool:
     if annotation is None:
         return True
@@ -215,29 +303,35 @@ def _is_broad(annotation: ast.expr | None, semantics: AnnotationSemantics) -> bo
 
 def _shadowed_annotation(
     annotation: ast.expr | None,
-    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    function: ast.AST,
     context: PythonFileContext,
     semantics: AnnotationSemantics,
 ) -> bool:
     names = _uses_names(annotation, semantics)
-    if names & _type_parameter_names(function):
+    if isinstance(function, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and names & _type_parameter_names(
+        function
+    ):
         return True
     parent = context.parents.get(function)
     while parent is not None:
-        if isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and names & _scope_bindings(
-            parent
-        ):
+        if isinstance(
+            parent, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+        ) and names & _scope_bindings(parent):
             return True
         parent = context.parents.get(parent)
     return False
 
 
-def _scope_bindings(owner: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> set[str]:
-    bound = scope_bound_names(owner.body) | _type_parameter_names(owner)
-    if isinstance(owner, (ast.FunctionDef, ast.AsyncFunctionDef)):
-        args = owner.args
-        bound.update(arg.arg for arg in [*args.posonlyargs, *args.args, *args.kwonlyargs])
-        bound.update(arg.arg for arg in (args.vararg, args.kwarg) if arg is not None)
+def _scope_bindings(owner: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Lambda) -> set[str]:
+    if isinstance(owner, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+        bound = set(scope_bindings(owner))
+    else:
+        collector = LocalBindingCollector()
+        for statement in owner.body:
+            collector.visit(statement)
+        bound = collector.names - collector.globals
+    if not isinstance(owner, ast.Lambda):
+        bound.update(_type_parameter_names(owner))
     return bound
 
 
@@ -250,10 +344,11 @@ def _uncertain_annotation(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     context: PythonFileContext,
     semantics: AnnotationSemantics,
+    mutated_members: frozenset[str],
 ) -> bool:
     if annotation is None:
         return False
-    if _has_wildcard_import(context):
+    if _has_wildcard_import(context) or _uses_mutated_member(annotation, semantics, mutated_members):
         return True
     if context.tree is not None:
         unknown = scope_bound_names(context.tree.body) - set(semantics.imports.bindings) - set(semantics.aliases)
@@ -280,8 +375,9 @@ def _known_decorator(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     context: PythonFileContext,
     semantics: AnnotationSemantics,
+    mutated_members: frozenset[str],
 ) -> str | None:
-    if _has_wildcard_import(context):
+    if _has_wildcard_import(context) or _uses_mutated_member(decorator, semantics, mutated_members):
         return None
     if _shadowed_annotation(decorator, function, context, semantics):
         return None
@@ -297,9 +393,10 @@ def _unknown_decorator(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     context: PythonFileContext,
     semantics: AnnotationSemantics,
+    mutated_members: frozenset[str],
 ) -> bool:
     return any(
-        _known_decorator(decorator, function, context, semantics) not in _KNOWN_DECORATORS
+        _known_decorator(decorator, function, context, semantics, mutated_members) not in _KNOWN_DECORATORS
         for decorator in function.decorator_list
     )
 
@@ -307,6 +404,7 @@ def _unknown_decorator(
 def _overload_implementations(
     context: PythonFileContext,
     semantics: AnnotationSemantics,
+    mutated_members: frozenset[str],
 ) -> set[ast.FunctionDef | ast.AsyncFunctionDef]:
     families: dict[tuple[ast.AST | None, str], list[ast.FunctionDef | ast.AsyncFunctionDef]] = {}
     implementations: set[ast.FunctionDef | ast.AsyncFunctionDef] = set()
@@ -315,7 +413,7 @@ def _overload_implementations(
         scope = _lexical_scope(node, context)
         if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             key = scope, node.name
-            if _signature_declaration(node, context, semantics):
+            if _signature_declaration(node, context, semantics, mutated_members):
                 families.setdefault(key, []).append(node)
             else:
                 family = families.pop(key, [])
@@ -356,6 +454,10 @@ def _signature_declaration(
     function: ast.FunctionDef | ast.AsyncFunctionDef,
     context: PythonFileContext,
     semantics: AnnotationSemantics,
+    mutated_members: frozenset[str],
 ) -> bool:
-    decorators = {_known_decorator(decorator, function, context, semantics) for decorator in function.decorator_list}
+    decorators = {
+        _known_decorator(decorator, function, context, semantics, mutated_members)
+        for decorator in function.decorator_list
+    }
     return bool(decorators & _OVERLOAD_DECORATORS) or not decorators <= _KNOWN_DECORATORS

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/src/sarj_python_lint/rules/no_database_programmability.py

@@ -41,7 +41,7 @@ class NoDatabaseProgrammability(Rule):
         default_level=Severity.ERROR,
         summary="Keep stored SQL functions and triggers out of embedded SQL.",
         rationale="SQL hidden in Python can bypass migration-only architecture rules. Procedural fault fixtures require extra database objects and cleanup when a declarative constraint suffices.",
-        remediation="Use declarative constraints or explicit transactional application behavior, including in test fixtures. Use an exact SARJ470 suppression for an approved compatibility exception.",
+        remediation="Prefer declarative constraints or explicit transactional application behavior where equivalent, including in test fixtures. Preserve transaction atomicity and database-enforced integrity; use an exact SARJ470 suppression for an approved database-owned invariant or compatibility exception.",
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
@@ -92,7 +92,7 @@ class NoDatabaseProgrammability(Rule):
                     col=node.col_offset + 1,
                     code=self.code,
                     severity=Severity.ERROR,
-                    message="Stored SQL functions and triggers are prohibited by project architecture, including in test fixtures; use a declarative constraint or explicit transactional application code.",
+                    message="Project architecture prefers declarative constraints or explicit transactional application behavior, including in test fixtures. Preserve atomicity and database-enforced integrity; use an exact SARJ470 suppression for an approved database-owned invariant or compatibility exception.",
                 )
             )
         return sorted(diagnostics, key=lambda item: (item.line, item.col))

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/src/sarj_python_lint/rules/no_injected_module_loader.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+from itertools import chain
 from pathlib import PurePosixPath
 from typing import TYPE_CHECKING, ClassVar, final, override
 
@@ -45,13 +46,14 @@ class NoInjectedModuleLoader(Rule):
     code = "SARJ471"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="Keep Python module loaders out of application parameter defaults.",
-        rationale="Exposing Python's import machinery as an injectable dependency expands the callable contract and hides the concrete imported API behind a generic loader.",
-        remediation="Use a normal or lazy import inside the implementation; pass the concrete configuration, object, or domain factory when callers need a real dependency boundary.",
+        summary="Avoid a generic module-loader parameter used only to import one fixed module.",
+        rationale="When every direct use imports the same literal module, a generic importer can be unnecessary customization rather than a domain dependency. Dynamic plugin/import APIs legitimately need import hooks.",
+        remediation="Consider owning the fixed import inside the implementation when import-hook substitution is unnecessary. Preserve intentional import hooks and plugin APIs; do not add wrapper factories or Protocols just to silence this advisory.",
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Flags defaults resolving to importlib.import_module, importlib.__import__, or builtins.__import__, including stable module-level import and single-assignment aliases and unshadowed __import__.",
+            "Every body reference to the parameter must be a direct call with one identical literal module name. Dynamic names, multiple module names, forwarding, returned/captured hooks, rebinding, unpacking and unused defaults are excluded.",
             "Tests, test support, and generated code are excluded. Required loader parameters, application loaders, wrapper lambdas, alias chains, comprehensions, and imports local to enclosing scopes are not inferred.",
             "Conservatively skips shadowed or rebound names, wildcard-import files, reassigned loader attributes, conflicting conditional or relative imports, and exception or pattern captures of importer roots, symbols or assignment aliases. Identical repeated importer imports remain valid. A relevant-name capture in an unrelated local scope can cause a false negative because capture checks are file-wide.",
             "Assignment aliases require one module binding and precede use by line and column. Defaults use their enclosing evaluation scope: earlier statements in the nearest executing class body can shadow loaders; methods and nested classes do not close over class attributes. Enclosing function body bindings remain conservative exclusions, but a function's parameters do not shadow its own defaults. Relevant global declarations and walrus writes exclude sensitive importer names. Compound class statements can cause conservative omissions. Dynamic namespace mutation is not inferred. No autofix: changing arguments or import placement can alter API and initialization behavior.",
@@ -110,7 +112,8 @@ class NoInjectedModuleLoader(Rule):
                     and (aliases[default.id].lineno, aliases[default.id].col_offset)
                     < (function.lineno, function.col_offset)
                 )
-                if not (direct or aliased) or _shadowed(default, function, context):
+                module_name = _fixed_module_name(context, function, argument.arg)
+                if not (direct or aliased) or _shadowed(default, function, context) or module_name is None:
                     continue
                 findings.append(
                     Diagnostic(
@@ -118,13 +121,43 @@ class NoInjectedModuleLoader(Rule):
                         line=argument.lineno,
                         col=argument.col_offset + 1,
                         code=self.code,
-                        message=f"Parameter `{argument.arg}` exposes Python's module loader; import directly or pass a concrete domain dependency.",
+                        message=(
+                            f"Parameter `{argument.arg}` exposes a generic module loader but only imports "
+                            f"`{module_name}`; consider an internal import unless this import hook is intentional."
+                        ),
                         severity=Severity.WARNING,
                     )
                 )
         return sorted(findings, key=lambda finding: (finding.line, finding.col))
 
 
+def _fixed_module_name(
+    context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda, name: str
+) -> str | None:
+    body = [function.body] if isinstance(function, ast.Lambda) else function.body
+    module_names: set[str] = set()
+    for reference in chain.from_iterable(ast.walk(statement) for statement in body):
+        if not isinstance(reference, ast.Name) or reference.id != name:
+            continue
+        call = context.parents.get(reference)
+        if not isinstance(reference.ctx, ast.Load) or not isinstance(call, ast.Call) or call.func is not reference:
+            return None
+        if (
+            call.keywords
+            or len(call.args) != 1
+            or not isinstance(call.args[0], ast.Constant)
+            or not isinstance(call.args[0].value, str)
+        ):
+            return None
+        parent = context.parents.get(call)
+        while parent is not None and parent is not function:
+            if isinstance(parent, _LEXICAL_SCOPES):
+                return None
+            parent = context.parents.get(parent)
+        module_names.add(call.args[0].value)
+    return next(iter(module_names)) if len(module_names) == 1 else None
+
+
 def _ambiguous_loader_bindings(context: PythonFileContext, aliases: Mapping[str, ast.stmt]) -> bool:
     if any(alias.name == "*" for node in context.nodes(ast.ImportFrom) for alias in node.names):
         return True

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/src/sarj_python_lint/rules/no_nullable_dependency_fallback.py

@@ -66,7 +66,7 @@ class NoNullableDependencyFallback(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Warns for None-defaulted function parameters with a fallback used as a callable or a proven application-settings fallback; genuine absent state is allowed.",
-            "Constructors remain owned by SARJ095 and SARJ468. Decorated functions, tests, generated code, nested scope captures, non-callable object fallbacks, and interprocedural forwarding are excluded.",
+            "Constructor settings fallbacks remain owned by SARJ095; constructor nullability alone is not a defect. Decorated functions, tests, generated code, nested scope captures, non-callable object fallbacks, and interprocedural forwarding are excluded.",
             "Callable use through a local assignment, annotation or None guard requires at most one body binding for that name and a call after the binding statement completes. Rebinding, deletion, imports, definitions, pattern or exception captures, global/nonlocal declarations and nested-scope bindings conservatively exclude that inference; direct inline calls remain independent. Settings provenance also excludes enclosing bindings and names written by a function declaring them global, while read-only global declarations remain valid.",
             "No autofix: removing explicit None acceptance changes the callable contract, and moving a fallback can change initialization timing or error handling.",
         ),

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/src/sarj_python_lint/rules/no_unused_underscored_keyword_parameter.py

@@ -39,7 +39,8 @@ class NoUnusedUnderscoredKeywordParameter(Rule):
         ),
         remediation=(
             "Remove the unused keyword-only parameter and update callers together. If an external contract requires "
-            "the input, preserve its required spelling and use a narrow, reasoned unused-argument suppression."
+            "the input, preserve its required spelling and use a narrow, reasoned unused-argument suppression. "
+            "Do not erase a precise callback signature with **kwargs or add dummy reads to silence this warning."
         ),
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
@@ -48,7 +49,7 @@ class NoUnusedUnderscoredKeywordParameter(Rule):
             "Decorated functions other than unshadowed builtin staticmethod/classmethod, inherited methods, and intentional stubs are excluded.",
             "Any reference within the body counts as use, including nested scopes; shadowing and reassignment can produce false negatives.",
             "Functions accessing locals, vars, eval, or exec through recognized builtin bindings are excluded.",
-            "Call sites, lambda parameters, unknown dynamic reflection, and cross-module callback contracts are not resolved.",
+            "Callables referenced as values are excluded because their external keyword contract is unknown. Lambda parameters, unknown dynamic reflection, and cross-module callback contracts are not resolved.",
             "Generated and vendored files are excluded; test source is checked.",
         ),
         examples=(
@@ -103,7 +104,12 @@ def _unused_parameters(
     context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef
 ) -> tuple[ast.arg, ...]:
     candidates = [argument for argument in function.args.kwonlyargs if argument.arg.startswith("_")]
-    if not candidates or _has_contract(context, function) or _is_stub(function):
+    if (
+        not candidates
+        or _has_contract(context, function)
+        or _is_stub(function)
+        or _escapes_as_callback(context, function)
+    ):
         return ()
     body = list(chain.from_iterable(ast.walk(statement) for statement in function.body))
     if _reads_dynamic_locals(context, function, body):
@@ -174,3 +180,15 @@ def _reads_dynamic_locals(
         )
         for node in body
     )
+
+
+def _escapes_as_callback(context: PythonFileContext, function: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    for reference in context.nodes(ast.Name, ast.Attribute):
+        if (isinstance(reference, ast.Name) and reference.id != function.name) or (
+            isinstance(reference, ast.Attribute) and reference.attr != function.name
+        ):
+            continue
+        parent = context.parents.get(reference)
+        if isinstance(reference.ctx, ast.Load) and not (isinstance(parent, ast.Call) and parent.func is reference):
+            return True
+    return False

{sarj_python_lint-1.16.0 → sarj_python_lint-1.16.2}/src/sarj_python_lint/rules/no_unused_value_marker.py

@@ -46,6 +46,7 @@ class NoUnusedValueMarker(Rule):
             "Plain and annotated assignments whose standalone target is `_` are reported, including chained assignments.",
             "Formal-parameter references are reported too, including positional, keyword-only, and variadic parameters.",
             "Unpacking placeholders, loop targets, wildcard imports, and underscore-prefixed names are excluded.",
+            "A binding read in the same enclosing scope is not a discard. Reads in nested scopes conservatively preserve it, even when shadowing cannot be resolved.",
             "Generated and vendored files are excluded.",
         ),
         examples=(
@@ -148,7 +149,9 @@ class NoUnusedValueMarker(Rule):
         markers = [
             node
             for node in context.nodes(ast.AST)
-            if isinstance(node, (ast.Assign, ast.AnnAssign)) and _is_unused_value_marker(node)
+            if isinstance(node, (ast.Assign, ast.AnnAssign))
+            and _is_unused_value_marker(node)
+            and not _scope_reads_marker(context, node)
         ]
         if not markers:
             return []
@@ -173,3 +176,14 @@ def _is_unused_value_marker(node: ast.Assign | ast.AnnAssign) -> bool:
     if isinstance(node, ast.AnnAssign):
         return node.value is not None and isinstance(node.target, ast.Name) and node.target.id == "_"
     return any(isinstance(target, ast.Name) and target.id == "_" for target in node.targets)
+
+
+def _scope_reads_marker(context: PythonFileContext, marker: ast.Assign | ast.AnnAssign) -> bool:
+    scope: ast.AST = marker
+    while (parent := context.parents.get(scope)) is not None:
+        scope = parent
+        if isinstance(scope, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef | ast.Module):
+            break
+    return any(
+        isinstance(node, ast.Name) and node.id == "_" and isinstance(node.ctx, ast.Load) for node in ast.walk(scope)
+    )