sarj-python-lint 1.6.1__tar.gz → 1.7.0__tar.gz

{sarj_python_lint-1.6.1 → sarj_python_lint-1.7.0}/PKG-INFO

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

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

{sarj_python_lint-1.6.1 → sarj_python_lint-1.7.0}/src/sarj_python_lint/rules/_registry.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from types import MappingProxyType
 from typing import TYPE_CHECKING
 
+from sarj_python_lint.rules.async_cleanup_registered_synchronously import AsyncCleanupRegisteredSynchronously
 from sarj_python_lint.rules.async_mock_call_without_await_assertion import AsyncMockCallWithoutAwaitAssertion
 from sarj_python_lint.rules.complex_postgres_query_requires_architecture_review import (
     ComplexPostgresQueryRequiresArchitectureReview,
@@ -171,6 +172,7 @@ from sarj_python_lint.rules.store_get_delegates_to_bulk_read import StoreGetDele
 from sarj_python_lint.rules.store_insert_requires_on_conflict import (
     StoreInsertRequiresOnConflict,
 )
+from sarj_python_lint.rules.subprocess_kill_without_reap import SubprocessKillWithoutReap
 from sarj_python_lint.rules.timestamp_order_requires_tiebreaker import TimestampOrderRequiresTiebreaker
 from sarj_python_lint.rules.trailing_value_narration import TrailingValueNarration
 from sarj_python_lint.rules.typed_error_reasons import TypedErrorReasons
@@ -186,6 +188,8 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        AsyncCleanupRegisteredSynchronously.id: AsyncCleanupRegisteredSynchronously,
+        SubprocessKillWithoutReap.id: SubprocessKillWithoutReap,
         NoSwallowedAsyncioCancellation.id: NoSwallowedAsyncioCancellation,
         RequireExplicitPsycopgTransaction.id: RequireExplicitPsycopgTransaction,
         AsyncMockCallWithoutAwaitAssertion.id: AsyncMockCallWithoutAwaitAssertion,

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

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+from typing import TYPE_CHECKING, final
+
+
+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,
+)
+
+
+@final
+class ResourceProvenance:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+        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.escape_cache: dict[tuple[ast.AST, bool], bool] = {}
+        self.wildcard = False
+        self.mutated: 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.Attribute) and isinstance(node.ctx, ast.Store | ast.Del):
+                root = _root_name(node)
+                if root is not None:
+                    self.mutated.add(root)
+
+    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 root is None or root in self.mutated:
+            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 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:
+        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):
+                owner = self.context.parents.get(binding)
+                if not isinstance(owner, ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+                    return None
+                if binding.decorator_list or any(
+                    isinstance(node, ast.Yield | ast.YieldFrom) for node in ast.walk(binding)
+                ):
+                    return None
+                return 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
+
+    def unescaped(self, name: ast.Name, at: ast.AST, *, allow_context: bool = False) -> bool:
+        binding = self.binding(name.id, at)
+        if 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.reads.get(name.id, ())
+                if self.binding(read.id, read) is 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:
+            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 _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.7.0/src/sarj_python_lint/rules/async_cleanup_registered_synchronously.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_BAD = "from contextlib import AsyncExitStack\nasync def close():\n    await release()\nasync def run():\n    async with AsyncExitStack() as stack:\n        stack.callback(close)\n"
+
+
+class AsyncCleanupRegisteredSynchronously(Rule):
+    id: str = "async-cleanup-registered-synchronously"
+    code: str = "SARJ463"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        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.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "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.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="dropped-cleanup",
+                title="Synchronous callbacks do not await cleanup",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/resources.py", _BAD),),
+                focus_path=PurePosixPath("app/resources.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="awaited-cleanup",
+                title="Register cleanup with the async API",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python("app/resources.py", _BAD.replace("stack.callback", "stack.push_async_callback")),
+                ),
+                focus_path=PurePosixPath("app/resources.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "callback" not in context.source or context.generated or context.tree is None:
+            return []
+        provenance = ResourceProvenance(context)
+        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):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=context.path,
+                    line=call.lineno,
+                    col=call.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message="synchronous ExitStack.callback does not await this async cleanup function; use AsyncExitStack.push_async_callback",
+                )
+            )
+        return findings
+
+
+def _wrong_callback(call: ast.Call, provenance: ResourceProvenance) -> bool:
+    if not isinstance(call.func, ast.Attribute) or call.func.attr != "callback" or not call.args:
+        return False
+    receiver = call.func.value
+    if not isinstance(receiver, ast.Name) or not provenance.unescaped(receiver, call, allow_context=True):
+        return False
+    constructor = provenance.constructor(receiver, call)
+    if constructor is None or constructor.args or constructor.keywords:
+        return False
+    known = any(provenance.imported(constructor.func, f"contextlib.{name}") for name in ("ExitStack", "AsyncExitStack"))
+    return known and provenance.async_function(call.args[0], call) is not None

{sarj_python_lint-1.6.1 → sarj_python_lint-1.7.0}/src/sarj_python_lint/rules/prefer_regex_fullmatch.py

@@ -36,13 +36,13 @@ class PreferRegexFullmatch(Rule):
     code: str = "SARJ460"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="An anchored regex match rejects invalid values without requiring a full-string match.",
+        summary="An anchored regex validation predicate does not require a full-string match.",
         rationale="The regex `$` anchor can match before a final newline, so an anchored match can accept a value that was not fully validated.",
         remediation="Use `re.fullmatch` or the compiled pattern's `fullmatch` method for whole-value validation; review whether a terminal newline is intentionally allowed.",
         category=RuleCategory.CORRECTNESS,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only direct negative match or `is None` conditions whose sole rejection statement raises are checked; extraction, search, compound conditions, and return-based validators are excluded.",
+            "Checks direct negative match/is-None rejection guards and returns of bool(match), not match, or match is/is-not None. Match-object returns, extraction, search, and compound conditions are excluded.",
             "Patterns must be valid string or bytes literals bounded by `^` or `\\A` and an unescaped outer `$`; top-level alternation, inline extension groups other than noncapturing groups, and flags other than literal zero are excluded.",
             "Only imported standard-library re functions and unique, unconditional module or same-function compile bindings are resolved. Rebinding, import shadowing, escaped regex objects or modules, explicit match positions, tests, and generated files are excluded.",
             "Binding checks are deliberately file-wide, so unrelated same-named locals can suppress findings. Dynamic monkeypatching and interprocedural changes are not inferred.",
@@ -85,8 +85,8 @@ class PreferRegexFullmatch(Rule):
         )
         compiled = _compiled_patterns(context, bindings, mutated)
         findings: list[Diagnostic] = []
-        for guard in context.nodes(ast.If):
-            call = _rejection_call(guard)
+        for guard in context.nodes(ast.If, ast.Return):
+            call = _validation_call(guard, context, bindings)
             if call is None or is_suppressed(context.source_lines, call.lineno, self.code):
                 continue
             pattern = _match_pattern(context, call, bindings, mutated, compiled)
@@ -98,13 +98,30 @@ class PreferRegexFullmatch(Rule):
                     line=call.lineno,
                     col=call.col_offset + 1,
                     code=self.code,
-                    message="anchored match is used to reject invalid values, but `$` can accept a final newline; use fullmatch for whole-value validation and review newline handling.",
+                    message="anchored match is used as a validation predicate, but `$` can accept a final newline; use fullmatch for whole-value validation and review newline handling.",
                     severity=Severity.WARNING,
                 )
             )
         return sorted(findings, key=lambda item: (item.line, item.col))
 
 
+def _validation_call(node: ast.If | ast.Return, context: PythonFileContext, bindings: Counter[str]) -> ast.Call | None:
+    if isinstance(node, ast.If):
+        return _rejection_call(node)
+    match node.value:
+        case (
+            ast.UnaryOp(op=ast.Not(), operand=ast.Call() as call)
+            | ast.Compare(left=ast.Call() as call, ops=[ast.Is() | ast.IsNot()], comparators=[ast.Constant(value=None)])
+        ):
+            return call
+        case ast.Call(func=ast.Name(id="bool"), args=[ast.Call() as call], keywords=[]):
+            if context.imports.builtin_is_unshadowed("bool") and bindings["bool"] == 0:
+                return call
+        case _:
+            pass
+    return None
+
+
 def _rejection_call(guard: ast.If) -> ast.Call | None:
     if len(guard.body) != 1 or not isinstance(guard.body[0], ast.Raise):
         return None

sarj_python_lint-1.7.0/src/sarj_python_lint/rules/subprocess_kill_without_reap.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_BAD = "import subprocess\ndef run(args):\n    process = subprocess.Popen(args)\n    try:\n        process.communicate(timeout=1)\n    except subprocess.TimeoutExpired:\n        process.kill()\n"
+_REAP_METHODS = frozenset({"wait", "communicate", "poll"})
+
+
+class SubprocessKillWithoutReap(Rule):
+    id: str = "subprocess-kill-without-reap"
+    code: str = "SARJ464"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Reap a locally owned subprocess after killing it on timeout.",
+        rationale="Sending a kill signal does not wait for process termination or collect the exit status; deterministic cleanup still requires waiting or communication.",
+        remediation="After kill(), call communicate() when owning captured pipes, or wait() when output is handled separately; an enclosing Popen context manager can also own cleanup.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Requires a unique, dominating local subprocess.Popen assignment and a resolved TimeoutExpired handler ending with a direct kill() after that process's wait or communicate.",
+            "Borrowed processes, custom factories, context-managed ownership, aliases, escaped handles or cleanup callbacks, and any later wait/communicate/poll are excluded conservatively.",
+            "Only direct timeout handlers are checked. Cross-function lifecycle, fields, dynamic mutation, arbitrary exit paths, and generated files are not analyzed. Choosing wait versus communicate requires reviewing output ownership.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="unreaped-child",
+                title="Killing does not complete cleanup",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/processes.py", _BAD),),
+                focus_path=PurePosixPath("app/processes.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="reaped-child",
+                title="Drain and wait after killing",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/processes.py", _BAD + "        process.communicate()\n"),),
+                focus_path=PurePosixPath("app/processes.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "kill" not in context.source or context.generated or context.tree is None:
+            return []
+        provenance = ResourceProvenance(context)
+        findings: list[Diagnostic] = []
+        for handler in context.nodes(ast.ExceptHandler):
+            call = _unreaped_kill(context, provenance, handler)
+            if call is None or is_suppressed(context.source_lines, call.lineno, self.code):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=context.path,
+                    line=call.lineno,
+                    col=call.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message="this Popen timeout handler kills the child without a subsequent reap; call communicate() for owned pipes or wait() when output is handled separately",
+                )
+            )
+        return findings
+
+
+def _unreaped_kill(
+    context: PythonFileContext, provenance: ResourceProvenance, handler: ast.ExceptHandler
+) -> ast.Call | None:
+    if handler.type is None or not provenance.imported(handler.type, "subprocess.TimeoutExpired"):
+        return None
+    last = handler.body[-1]
+    if not isinstance(last, ast.Expr) or not isinstance(last.value, ast.Call):
+        return None
+    call = last.value
+    receiver = _method_receiver(call, frozenset({"kill"}))
+    if receiver is None or call.args or call.keywords or not provenance.unescaped(receiver, call):
+        return None
+    binding = provenance.binding(receiver.id, call)
+    if not isinstance(binding, ast.Name) or provenance.scope(binding) is not provenance.scope(call):
+        return None
+    if not isinstance(context.parents.get(binding), ast.Assign | ast.AnnAssign):
+        return None
+    if not isinstance(provenance.scope(call), ast.FunctionDef | ast.AsyncFunctionDef):
+        return None
+    constructor = provenance.constructor(receiver, call)
+    if constructor is None or not provenance.imported(constructor.func, "subprocess.Popen"):
+        return None
+    owner = context.parents.get(handler)
+    if not isinstance(owner, ast.Try) or not _waits_for_process(owner.body, receiver.id):
+        return None
+    for other in context.nodes(ast.Call):
+        other_receiver = _method_receiver(other, _REAP_METHODS)
+        if (
+            other_receiver is not None
+            and other.lineno > call.lineno
+            and provenance.binding(other_receiver.id, other) is binding
+        ):
+            return None
+    return call
+
+
+def _waits_for_process(body: list[ast.stmt], name: str) -> bool:
+    for statement in body:
+        value = statement.value if isinstance(statement, ast.Expr | ast.Assign | ast.AnnAssign) else None
+        if (
+            isinstance(value, ast.Call)
+            and (receiver := _method_receiver(value, frozenset({"wait", "communicate"}))) is not None
+            and receiver.id == name
+        ):
+            return True
+    return False
+
+
+def _method_receiver(call: ast.Call, methods: frozenset[str]) -> ast.Name | None:
+    function = call.func
+    if isinstance(function, ast.Attribute) and function.attr in methods and isinstance(function.value, ast.Name):
+        return function.value
+    return None