sarj-python-lint 1.29.0__tar.gz → 1.30.0__tar.gz

{sarj_python_lint-1.29.0 → sarj_python_lint-1.30.0}/PKG-INFO

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

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

sarj_python_lint-1.30.0/src/sarj_python_lint/rules/_exports.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import ast
+
+from sarj_python_lint.rules._ast_index import walk
+
+
+def mentions_dunder_all(node: ast.AST) -> bool:
+    for child in walk(node):
+        match child:
+            case ast.Name(id="__all__"):
+                return True
+            case ast.alias() if (child.asname or child.name).split(".")[0] == "__all__":
+                return True
+            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef() if child.name == "__all__":
+                return True
+            case ast.arg(arg="__all__") | ast.ExceptHandler(name="__all__"):
+                return True
+            case ast.MatchAs() | ast.MatchStar() if child.name == "__all__":
+                return True
+            case ast.MatchMapping(rest="__all__"):
+                return True
+            case ast.Global() | ast.Nonlocal() if "__all__" in child.names:
+                return True
+            case _:
+                pass
+    return False

{sarj_python_lint-1.29.0 → sarj_python_lint-1.30.0}/src/sarj_python_lint/rules/_namespace_access.py

@@ -16,6 +16,9 @@ _DYNAMIC_MEMBERS = frozenset(
         "__dict__",
         "__globals__",
         "__code__",
+        "__origin__",
+        "__args__",
+        "__parameters__",
         "__setattr__",
         "__delattr__",
         "__getattribute__",

{sarj_python_lint-1.29.0 → sarj_python_lint-1.30.0}/src/sarj_python_lint/rules/_pytest.py

@@ -1,10 +1,26 @@
 from __future__ import annotations
 
 import ast
+from typing import TYPE_CHECKING
 
 from sarj_python_lint.rules._ast_index import walk
 
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+def collected_tests(statements: list[ast.stmt]) -> Iterator[ast.FunctionDef | ast.AsyncFunctionDef]:
+    for statement in statements:
+        match statement:
+            case ast.FunctionDef() | ast.AsyncFunctionDef() if statement.name.startswith("test"):
+                yield statement
+            case ast.ClassDef() if statement.name.startswith("Test"):
+                yield from collected_tests(statement.body)
+            case _:
+                pass
+
+
 # The pytest-benchmark fixture: the test measures time, it does not verify.
 _BENCHMARK = "benchmark"
 

sarj_python_lint-1.30.0/src/sarj_python_lint/rules/_resource_provenance.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from functools import cached_property
+from types import MappingProxyType
+from typing import TYPE_CHECKING, final
+
+from sarj_python_lint.rules._namespace_access import dynamic_namespace_access
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_SCOPES = (
+    ast.Module,
+    ast.FunctionDef,
+    ast.AsyncFunctionDef,
+    ast.ClassDef,
+    ast.Lambda,
+    ast.ListComp,
+    ast.SetComp,
+    ast.DictComp,
+    ast.GeneratorExp,
+)
+_RESOURCE_OWNERS = MappingProxyType(
+    {
+        "contextlib": frozenset({"ExitStack", "AsyncExitStack", "_BaseExitStack"}),
+        "subprocess": frozenset({"Popen", "TimeoutExpired"}),
+    }
+)
+
+
+@final
+class ResourceProvenance:
+    def __init__(self, context: PythonFileContext, *, require_static_namespace: bool = False) -> None:
+        self.context = context
+        self.require_static_namespace = require_static_namespace
+        self.bindings: dict[ast.AST | None, dict[str, list[ast.AST]]] = defaultdict(lambda: defaultdict(list))
+        self.reads: dict[str, list[ast.Name]] = defaultdict(list)
+        self._reads_by_binding: dict[str, dict[ast.AST, list[ast.Name]]] = {}
+        self.escape_cache: dict[tuple[ast.AST, bool], bool] = {}
+        self.async_contract_cache: dict[ast.AsyncFunctionDef, bool] = {}
+        self.import_contract_cache: dict[str, bool] = {}
+        self.wildcard = False
+        self.mutated: set[str] = set()
+        self.external_bindings: set[str] = set()
+        for node in context.nodes(ast.AST):
+            if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+                self.reads[node.id].append(node)
+
+            for name in _bound_names(node):
+                self.bindings[self.scope(node)][name].append(node)
+                self.wildcard |= name == "*"
+            if isinstance(node, ast.Global | ast.Nonlocal):
+                self.external_bindings.update(node.names)
+            if isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Store | ast.Del):
+                root = _root_name(node)
+                if root is not None:
+                    self.mutated.add(root)
+
+    @cached_property
+    def builtin_namespace_untouched(self) -> bool:
+        return not any(
+            (isinstance(node, ast.Import) and any(alias.name == "builtins" for alias in node.names))
+            or (isinstance(node, ast.ImportFrom) and node.module == "builtins")
+            or (isinstance(node, ast.Name) and node.id == "__builtins__")
+            for node in self.context.nodes(ast.Import, ast.ImportFrom, ast.Name)
+        )
+
+    def scope(self, node: ast.AST) -> ast.AST | None:
+        parent = self.context.parents.get(node)
+        while parent is not None and not isinstance(parent, _SCOPES):
+            parent = self.context.parents.get(parent)
+        return parent
+
+    def binding(self, name: str, at: ast.AST) -> ast.AST | None:
+        scope = self.scope(at)
+        while scope is not None:
+            nodes = self.bindings.get(scope, {}).get(name)
+            if nodes:
+                return nodes[0] if len(nodes) == 1 else None
+            scope = self.scope(scope)
+        return None
+
+    def imported(self, node: ast.expr, qualified: str) -> bool:
+        root = _root_name(node)
+        if (
+            self.wildcard
+            or self.dynamic_namespace
+            or root is None
+            or root in self.mutated
+            or not self._owner_namespace_untouched(qualified.partition(".")[0])
+        ):
+            return False
+        binding = self.binding(root, node)
+        for read in self.reads.get(root, ()):
+            parent = self.context.parents.get(read)
+            if isinstance(parent, ast.Attribute | ast.ExceptHandler):
+                continue
+            if not (isinstance(parent, ast.Call) and parent.func is read):
+                return False
+        return (
+            isinstance(binding, ast.alias)
+            and isinstance(self.scope(binding), ast.Module)
+            and self.context.imports.resolved_qualified_name(node) == qualified
+        )
+
+    def _owner_namespace_untouched(self, module: str) -> bool:
+        if module not in _RESOURCE_OWNERS:
+            return True
+        if module not in self.import_contract_cache:
+            self.import_contract_cache[module] = self._inspect_owner_namespace(module)
+        return self.import_contract_cache[module]
+
+    def _inspect_owner_namespace(self, module: str) -> bool:
+        origins: dict[str, set[str]] = defaultdict(set)
+        for node in self.context.nodes(ast.Import, ast.ImportFrom):
+            for name, target in _owner_import_targets(node, module).items():
+                origins[name].add(target)
+        if not self.mutated.isdisjoint(origins):
+            return False
+        owners = frozenset(f"{module}.{name}" for name in _RESOURCE_OWNERS[module])
+        return all(
+            self._safe_import_use(node)
+            for node in self.context.nodes(ast.Name, ast.Attribute)
+            if self._owner_reference(node, origins, owners)
+        )
+
+    def _owner_reference(
+        self, node: ast.Name | ast.Attribute, origins: dict[str, set[str]], owners: frozenset[str]
+    ) -> bool:
+        if not isinstance(node.ctx, ast.Load):
+            return False
+        if isinstance(node, ast.Name):
+            return node.id in origins
+        return any(
+            qualified == owner or qualified.startswith(owner + ".")
+            for qualified in _owner_attribute_targets(node, origins)
+            for owner in owners
+        )
+
+    def _safe_import_use(self, node: ast.Name | ast.Attribute) -> bool:
+        parent = self.context.parents.get(node)
+        return (
+            (isinstance(parent, ast.Attribute) and parent.value is node)
+            or (isinstance(parent, ast.Call) and parent.func is node)
+            or (isinstance(parent, ast.ExceptHandler) and parent.type is node)
+        )
+
+    def constructor(self, name: ast.Name, at: ast.AST) -> ast.Call | None:
+        binding = self.binding(name.id, at)
+        if not isinstance(binding, ast.Name):
+            return None
+        statement = self.context.parents.get(binding)
+        if isinstance(statement, ast.withitem):
+            owner = self.context.parents.get(statement)
+            if (
+                binding is statement.optional_vars
+                and self.contains(owner, at)
+                and isinstance(statement.context_expr, ast.Call)
+            ):
+                return statement.context_expr
+            return None
+        value = self.assignment_value(binding, at)
+        return value if isinstance(value, ast.Call) else None
+
+    def assignment_value(self, binding: ast.Name, at: ast.AST) -> ast.expr | None:
+        statement = self.context.parents.get(binding)
+        if not isinstance(statement, ast.Assign | ast.AnnAssign):
+            return None
+        if isinstance(statement, ast.Assign) and len(statement.targets) != 1:
+            return None
+        if not isinstance(self.context.parents.get(statement), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+            return None
+        return statement.value if statement.lineno < getattr(at, "lineno", 0) else None
+
+    def async_function(self, value: ast.expr, at: ast.AST) -> ast.AsyncFunctionDef | None:
+        if self.dynamic_namespace:
+            return None
+        seen: set[str] = set()
+        while isinstance(value, ast.Name) and value.id not in seen:
+            seen.add(value.id)
+            if value.id in self.mutated:
+                return None
+            binding = self.binding(value.id, at)
+            if isinstance(binding, ast.AsyncFunctionDef):
+                return self._stable_async_definition(binding)
+            if not isinstance(binding, ast.Name):
+                return None
+            resolved = self.assignment_value(binding, at)
+            if resolved is None:
+                return None
+            value, at = resolved, binding
+        return None
+
+    @cached_property
+    def dynamic_namespace(self) -> bool:
+        return self.require_static_namespace and dynamic_namespace_access(
+            self.context.nodes(ast.AST), self.context.imports, self.context.parents
+        )
+
+    def _stable_async_definition(self, function: ast.AsyncFunctionDef) -> ast.AsyncFunctionDef | None:
+        owner = self.context.parents.get(function)
+        if not isinstance(owner, ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+            return None
+        if function.decorator_list or any(isinstance(node, ast.Yield | ast.YieldFrom) for node in ast.walk(function)):
+            return None
+        if function not in self.async_contract_cache:
+            self.async_contract_cache[function] = self._async_aliases_untouched(function)
+        return function if self.async_contract_cache[function] else None
+
+    def _async_aliases_untouched(self, function: ast.AsyncFunctionDef) -> bool:
+        pending: list[ast.AsyncFunctionDef | ast.Name] = [function]
+        seen: set[ast.AST] = set()
+        while pending:
+            binding = pending.pop()
+            if binding in seen:
+                continue
+            seen.add(binding)
+            name = binding.id if isinstance(binding, ast.Name) else binding.name
+            if name in self.mutated or name in self.external_bindings:
+                return False
+            for read in self._binding_reads(name, binding):
+                alias = self._function_alias(read)
+                if alias is not None:
+                    pending.append(alias)
+                elif not self._safe_async_read(read):
+                    return False
+        return True
+
+    def _function_alias(self, read: ast.Name) -> ast.Name | None:
+        parent = self.context.parents.get(read)
+        if not isinstance(parent, ast.Assign | ast.AnnAssign) or parent.value is not read:
+            return None
+        if not isinstance(self.context.parents.get(parent), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+            return None
+        targets = parent.targets if isinstance(parent, ast.Assign) else [parent.target]
+        if len(targets) != 1 or not isinstance(targets[0], ast.Name):
+            return None
+        target = targets[0]
+        return target if self.binding(target.id, target) is target else None
+
+    def _safe_async_read(self, read: ast.Name) -> bool:
+        parent = self.context.parents.get(read)
+        if not isinstance(parent, ast.Call):
+            return False
+        if parent.func is read:
+            return True
+        if not parent.args or parent.args[0] is not read or not isinstance(parent.func, ast.Attribute):
+            return False
+        receiver = parent.func.value
+        if parent.func.attr not in {"callback", "push_async_callback"} or not isinstance(receiver, ast.Name):
+            return False
+        if not self.unescaped(receiver, parent, allow_context=True):
+            return False
+        constructor = self.constructor(receiver, parent)
+        return (
+            constructor is not None
+            and not constructor.args
+            and not constructor.keywords
+            and any(self.imported(constructor.func, f"contextlib.{kind}") for kind in ("ExitStack", "AsyncExitStack"))
+        )
+
+    def _binding_reads(self, name: str, binding: ast.AST) -> list[ast.Name]:
+        if name not in self._reads_by_binding:
+            grouped: dict[ast.AST, list[ast.Name]] = defaultdict(list)
+            for read in self.reads.get(name, ()):
+                if (owner := self.binding(read.id, read)) is not None:
+                    grouped[owner].append(read)
+            self._reads_by_binding[name] = grouped
+        return self._reads_by_binding[name].get(binding, [])
+
+    def unescaped(self, name: ast.Name, at: ast.AST, *, allow_context: bool = False) -> bool:
+        binding = self.binding(name.id, at)
+        if self.dynamic_namespace or binding is None or name.id in self.mutated:
+            return False
+        key = (binding, allow_context)
+        if key not in self.escape_cache:
+            self.escape_cache[key] = all(
+                self._method_or_context_read(read, allow_context=allow_context)
+                for read in self._binding_reads(name.id, binding)
+            )
+        return self.escape_cache[key]
+
+    def _method_or_context_read(self, read: ast.Name, *, allow_context: bool) -> bool:
+        parent = self.context.parents.get(read)
+        if allow_context and isinstance(parent, ast.withitem) and parent.context_expr is read:
+            return True
+        if (
+            not isinstance(parent, ast.Attribute)
+            or parent.value is not read
+            or parent.attr in {"__setattr__", "__delattr__", "__getattribute__"}
+        ):
+            return False
+        call = self.context.parents.get(parent)
+        return isinstance(call, ast.Call) and call.func is parent
+
+    def contains(self, owner: ast.AST | None, node: ast.AST) -> bool:
+        while node in self.context.parents:
+            node = self.context.parents[node]
+            if node is owner:
+                return True
+        return False
+
+
+def _owner_import_targets(node: ast.Import | ast.ImportFrom, module: str) -> dict[str, str]:
+    if isinstance(node, ast.Import):
+        return {alias.asname or alias.name: module for alias in node.names if alias.name == module}
+    if node.module == module:
+        return {
+            alias.asname or alias.name: f"{module}.{alias.name}"
+            for alias in node.names
+            if alias.name in _RESOURCE_OWNERS[module]
+        }
+    return {}
+
+
+def _owner_attribute_targets(node: ast.Attribute, origins: dict[str, set[str]]) -> frozenset[str]:
+    parts: list[str] = []
+    current: ast.expr = node
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if not isinstance(current, ast.Name):
+        return frozenset()
+    suffix = ".".join(reversed(parts))
+    return frozenset(f"{origin}.{suffix}" for origin in origins.get(current.id, ()))
+
+
+def _root_name(node: ast.expr) -> str | None:
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None
+
+
+def _bound_names(node: ast.AST) -> tuple[str, ...]:
+    match node:
+        case ast.Name(id=name, ctx=ast.Store() | ast.Del()) | ast.arg(arg=name):
+            return (name,)
+        case ast.alias():
+            return (node.asname or node.name.partition(".")[0],)
+        case (
+            ast.FunctionDef(name=name)
+            | ast.AsyncFunctionDef(name=name)
+            | ast.ClassDef(name=name)
+            | ast.ExceptHandler(name=str() as name)
+            | ast.MatchAs(name=str() as name)
+            | ast.MatchStar(name=str() as name)
+            | ast.MatchMapping(rest=str() as name)
+        ):
+            return (name,)
+        case ast.Global(names=names) | ast.Nonlocal(names=names):
+            return tuple(names)
+        case _:
+            return ()

{sarj_python_lint-1.29.0 → sarj_python_lint-1.30.0}/src/sarj_python_lint/rules/async_cleanup_registered_synchronously.py

@@ -30,7 +30,7 @@ class AsyncCleanupRegisteredSynchronously(Rule):
     id: str = "async-cleanup-registered-synchronously"
     code: str = "SARJ463"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        default_level=Severity.WARNING,
+        default_level=Severity.ERROR,
         summary="Do not register a proven async cleanup function with ExitStack.callback.",
         rationale="The synchronous callback API discards the returned coroutine without awaiting it, so the cleanup body never runs.",
         remediation="Use AsyncExitStack and register the coroutine function with push_async_callback.",
@@ -40,6 +40,8 @@ class AsyncCleanupRegisteredSynchronously(Rule):
             "Requires a proven contextlib ExitStack or AsyncExitStack constructor and an undecorated, visible async function, optionally through simple function aliases.",
             "Unknown methods/callables, decorated functions, async generators, conditional bindings, transferred stacks, wildcard imports, and generated files are excluded.",
             "Resource aliases and interprocedural mutation are not inferred. No autofix is offered because executing previously dropped cleanup can raise new exceptions.",
+            "Coroutine-function assignment aliases must remain unmutated and unescaped; attribute inspection, containers, returned functions and unknown helper arguments abstain. Direct calls and proven stack registrations remain supported.",
+            "Visible namespace APIs, frame/module introspection, code mutation and bound attribute setters invalidate the file's provenance proof.",
         ),
         examples=(
             RuleExample(
@@ -70,7 +72,7 @@ class AsyncCleanupRegisteredSynchronously(Rule):
     def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
         if "callback" not in context.symbol_source or context.generated or context.tree is None:
             return []
-        provenance = ResourceProvenance(context)
+        provenance = ResourceProvenance(context, require_static_namespace=True)
         findings: list[Diagnostic] = []
         for call in context.nodes(ast.Call):
             if not _wrong_callback(call, provenance) or is_suppressed(context.source_lines, call.lineno, self.code):
@@ -81,7 +83,7 @@ class AsyncCleanupRegisteredSynchronously(Rule):
                     line=call.lineno,
                     col=call.col_offset + 1,
                     code=self.code,
-                    severity=Severity.WARNING,
+                    severity=Severity.ERROR,
                     message="synchronous ExitStack.callback does not await this async cleanup function; use AsyncExitStack.push_async_callback",
                 )
             )

{sarj_python_lint-1.29.0 → sarj_python_lint-1.30.0}/src/sarj_python_lint/rules/async_mock_call_without_await_assertion.py

@@ -20,6 +20,7 @@ from sarj_python_lint.rule_base import (
 )
 from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._pytest import collected_tests
 
 
 if TYPE_CHECKING:
@@ -224,24 +225,13 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
                 severity=Severity.WARNING,
                 message="AsyncMock call assertions do not prove awaiting; keep this assertion and add an await assertion",
             )
-            for test in _collected_tests(tree.body)
+            for test in collected_tests(tree.body)
             if not _is_pytest_fixture(test, imports)
             for call in _uncovered_calls(_test_imports(imports, test), test, writes)
             if not is_suppressed(lines, call.lineno, self.code)
         ]
 
 
-def _collected_tests(statements: list[ast.stmt]) -> Iterator[_TestFunction]:
-    for statement in statements:
-        match statement:
-            case ast.FunctionDef() | ast.AsyncFunctionDef() if statement.name.startswith("test"):
-                yield statement
-            case ast.ClassDef() if statement.name.startswith("Test"):
-                yield from _collected_tests(statement.body)
-            case _:
-                pass
-
-
 def _is_pytest_fixture(test: _TestFunction, imports: ImportIndex) -> bool:
     return any(
         imports.resolved_qualified_name(decorator.func if isinstance(decorator, ast.Call) else decorator)