sarj-python-lint 1.15.2__tar.gz → 1.16.1__tar.gz

{sarj_python_lint-1.15.2 → sarj_python_lint-1.16.1}/PKG-INFO

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

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

{sarj_python_lint-1.15.2 → sarj_python_lint-1.16.1}/src/sarj_python_lint/rules/_registry.py

@@ -33,6 +33,7 @@ from sarj_python_lint.rules.no_analytical_aggregation_in_postgres_store import (
     NoAnalyticalAggregationInPostgresStore,
 )
 from sarj_python_lint.rules.no_any_mapping_types import NoAnyMappingTypes
+from sarj_python_lint.rules.no_broad_keyword_capture import NoBroadKeywordCapture
 from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
 from sarj_python_lint.rules.no_conftest_test_module_import import NoConftestTestModuleImport
 from sarj_python_lint.rules.no_copied_inherited_docstring import NoCopiedInheritedDocstring
@@ -297,6 +298,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoDuplicateDunderAllEntry.id: NoDuplicateDunderAllEntry,
         NoDunderAll.id: NoDunderAll,
         NoDeleteStatement.id: NoDeleteStatement,
+        NoBroadKeywordCapture.id: NoBroadKeywordCapture,
         NoCopiedInheritedDocstring.id: NoCopiedInheritedDocstring,
         RedundantClassDocstring.id: RedundantClassDocstring,
         RedundantModuleDocstring.id: RedundantModuleDocstring,

sarj_python_lint-1.16.1/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.1/src/sarj_python_lint/rules/no_broad_keyword_capture.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics, scope_bound_names
+from sarj_python_lint.rules._ast_index import walk
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_MIN_OVERLOAD_DECLARATIONS = 2
+_OVERLOAD_DECORATORS = frozenset({"typing.overload", "typing_extensions.overload"})
+_KNOWN_DECORATORS = _OVERLOAD_DECORATORS | {
+    "builtins.classmethod",
+    "builtins.staticmethod",
+    "abc.abstractmethod",
+    "typing.final",
+    "typing.override",
+    "typing_extensions.final",
+    "typing_extensions.override",
+}
+
+
+@final
+class NoBroadKeywordCapture(Rule):
+    id = "no-broad-keyword-capture"
+    code = "SARJ477"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Prefer precise keyword interfaces over missing, Any- or object-valued captures.",
+        rationale=(
+            "Replacing a fixed typed interface with broad **kwargs can erase required keyword names and per-key "
+            "value types, making test doubles accept calls the real implementation rejects. object remains a safe "
+            "typed top type, and deliberately open data interfaces can be valid; this warning requests interface "
+            "review rather than proving every broad capture is defective."
+        ),
+        remediation=(
+            "Keep explicit typed parameters at fixed interfaces. Preserve required keyword names with named unused "
+            "local bindings. Use ParamSpec for forwarding, Unpack[TypedDict] for named schemas, or a precise "
+            "homogeneous value type. Document genuinely open interfaces with an exact-code reasoned suppression."
+        ),
+        category=RuleCategory.MAINTAINABILITY,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "This is an advisory interface policy, not proof of incorrect behavior or a universal ban on the object type.",
+            "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.",
+            "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.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="discarded-session-keywords",
+                title="An ignored catch-all weakens a fake's contract",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/fakes/session.py",
+                        "class Session:\n    async def start(self, **_kwargs: object) -> None:\n        self.start_count += 1\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/fakes/session.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="typed-unused-keywords",
+                title="Preserve named typed keywords with a named unused binding",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/fakes/session.py",
+                        "class Session:\n    async def start(self, *, room: Room, agent: Agent) -> None:\n        _unused_inputs = room, agent\n        self.start_count += 1\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/fakes/session.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="broad-forwarding-arguments",
+                title="Forwarding broad arguments still loses the callable contract",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "def wrapper(*args: object, **kwargs: object):\n    return target(*args, **kwargs)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=1,
+                public=True,
+                scenario="forwarding",
+            ),
+            RuleExample(
+                example_id="typed-forwarding-arguments",
+                title="ParamSpec preserves the forwarded callable contract",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/adapter.py",
+                        "from collections.abc import Callable\ndef wrapper[**P, R](target: Callable[P, R], *args: P.args, **kwargs: P.kwargs) -> R:\n    return target(*args, **kwargs)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/adapter.py"),
+                expected_count=0,
+                public=True,
+                scenario="forwarding",
+            ),
+            RuleExample(
+                example_id="open-template-fields",
+                title="A deliberately open formatting interface still requests policy review",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/templates.py",
+                        "def render(template: str, **values: object) -> str:\n    return template.format(**values)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/templates.py"),
+                expected_count=1,
+                public=True,
+                scenario="dynamic-boundary",
+            ),
+            RuleExample(
+                example_id="documented-open-template-fields",
+                title="Document why template fields require an open object-valued interface",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/templates.py",
+                        "def render(template: str, **values: object) -> str:  # sarj-noqa: SARJ477 — template supplies dynamic field names and object formatting\n    return template.format(**values)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/templates.py"),
+                expected_count=0,
+                public=True,
+                scenario="dynamic-boundary",
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "*" not in context.source or context.generated or context.path.suffix == ".pyi":
+            return []
+        tree = context.tree
+        if tree is None:
+            return []
+        semantics = AnnotationSemantics.from_tree(tree)
+        overloads: set[ast.FunctionDef | ast.AsyncFunctionDef] | None = None
+        findings: list[Diagnostic] = []
+        for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+            argument = function.args.kwarg
+            if argument is None:
+                continue
+            if not _is_broad(argument.annotation, semantics):
+                continue
+            if _uncertain_annotation(argument.annotation, function, context, semantics):
+                continue
+            if _unknown_decorator(function, context, semantics):
+                continue
+            if overloads is None:
+                overloads = _overload_implementations(context, semantics)
+            if function in overloads:
+                continue
+            if is_suppressed(context.source_lines, argument.lineno, self.code) or is_suppressed(
+                context.source_lines, function.lineno, self.code
+            ):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=context.path,
+                    line=argument.lineno,
+                    col=argument.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message=(
+                        f"keyword capture `{argument.arg}` has no declared names or narrow value type; "
+                        "prefer an explicit typed interface or document a deliberately open contract."
+                    ),
+                )
+            )
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _is_broad(annotation: ast.expr | None, semantics: AnnotationSemantics) -> bool:
+    if annotation is None:
+        return True
+    return any(
+        (isinstance(member, ast.Name) and member.id == "object" and semantics.imports.builtin_is_unshadowed("object"))
+        or semantics.imports.resolved_qualified_name(member)
+        in {"typing.Any", "typing_extensions.Any", "builtins.object"}
+        for member in semantics.transparent_members(annotation)
+    )
+
+
+def _shadowed_annotation(
+    annotation: ast.expr | None,
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    context: PythonFileContext,
+    semantics: AnnotationSemantics,
+) -> bool:
+    names = _uses_names(annotation, semantics)
+    if 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
+        ):
+            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)
+    return bound
+
+
+def _has_wildcard_import(context: PythonFileContext) -> bool:
+    return any(alias.name == "*" for node in context.nodes(ast.ImportFrom) for alias in node.names)
+
+
+def _uncertain_annotation(
+    annotation: ast.expr | None,
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    context: PythonFileContext,
+    semantics: AnnotationSemantics,
+) -> bool:
+    if annotation is None:
+        return False
+    if _has_wildcard_import(context):
+        return True
+    if context.tree is not None:
+        unknown = scope_bound_names(context.tree.body) - set(semantics.imports.bindings) - set(semantics.aliases)
+        if _uses_names(annotation, semantics) & unknown:
+            return True
+    return _shadowed_annotation(annotation, function, context, semantics)
+
+
+def _type_parameter_names(owner: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> set[str]:
+    return {
+        parameter.name
+        for parameter in owner.type_params
+        if isinstance(parameter, (ast.TypeVar, ast.TypeVarTuple, ast.ParamSpec))
+    }
+
+
+def _uses_names(expression: ast.expr | None, semantics: AnnotationSemantics) -> set[str]:
+    parsed = semantics.parse(expression)
+    return {node.id for node in walk(parsed) if isinstance(node, ast.Name)} if parsed is not None else set()
+
+
+def _known_decorator(
+    decorator: ast.expr,
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    context: PythonFileContext,
+    semantics: AnnotationSemantics,
+) -> str | None:
+    if _has_wildcard_import(context):
+        return None
+    if _shadowed_annotation(decorator, function, context, semantics):
+        return None
+    if isinstance(decorator, ast.Name) and decorator.id in {"classmethod", "staticmethod"}:
+        if context.tree is not None and decorator.id in scope_bound_names(context.tree.body):
+            return None
+        if semantics.imports.builtin_is_unshadowed(decorator.id):
+            return "builtins." + decorator.id
+    return semantics.imports.resolved_qualified_name(decorator)
+
+
+def _unknown_decorator(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    context: PythonFileContext,
+    semantics: AnnotationSemantics,
+) -> bool:
+    return any(
+        _known_decorator(decorator, function, context, semantics) not in _KNOWN_DECORATORS
+        for decorator in function.decorator_list
+    )
+
+
+def _overload_implementations(
+    context: PythonFileContext,
+    semantics: AnnotationSemantics,
+) -> set[ast.FunctionDef | ast.AsyncFunctionDef]:
+    families: dict[tuple[ast.AST | None, str], list[ast.FunctionDef | ast.AsyncFunctionDef]] = {}
+    implementations: set[ast.FunctionDef | ast.AsyncFunctionDef] = set()
+    events = context.nodes(ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Name, ast.Import, ast.ImportFrom)
+    for node in sorted(events, key=lambda item: (item.lineno, item.col_offset)):
+        scope = _lexical_scope(node, context)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            key = scope, node.name
+            if _signature_declaration(node, context, semantics):
+                families.setdefault(key, []).append(node)
+            else:
+                family = families.pop(key, [])
+                if _precise_family(family, semantics):
+                    implementations.add(node)
+        else:
+            for name in _rebound_names(node):
+                families.pop((scope, name), None)
+    return implementations
+
+
+def _lexical_scope(node: ast.AST, context: PythonFileContext) -> ast.AST | None:
+    parent = context.parents.get(node)
+    while parent is not None and not isinstance(
+        parent, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+    ):
+        parent = context.parents.get(parent)
+    return parent
+
+
+def _precise_family(family: list[ast.FunctionDef | ast.AsyncFunctionDef], semantics: AnnotationSemantics) -> bool:
+    return len(family) >= _MIN_OVERLOAD_DECLARATIONS and all(
+        f.args.kwarg is None or not _is_broad(f.args.kwarg.annotation, semantics) for f in family
+    )
+
+
+def _rebound_names(node: ast.AST) -> set[str]:
+    if isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+        return {node.id}
+    if isinstance(node, ast.ClassDef):
+        return {node.name}
+    if isinstance(node, (ast.Import, ast.ImportFrom)):
+        return scope_bound_names([node])
+    return set()
+
+
+def _signature_declaration(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    context: PythonFileContext,
+    semantics: AnnotationSemantics,
+) -> bool:
+    decorators = {_known_decorator(decorator, function, context, semantics) for decorator in function.decorator_list}
+    return bool(decorators & _OVERLOAD_DECORATORS) or not decorators <= _KNOWN_DECORATORS

{sarj_python_lint-1.15.2 → sarj_python_lint-1.16.1}/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.15.2 → sarj_python_lint-1.16.1}/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