sarj-python-lint 1.12.0__tar.gz → 1.14.0__tar.gz

{sarj_python_lint-1.12.0 → sarj_python_lint-1.14.0}/PKG-INFO

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

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

{sarj_python_lint-1.12.0 → sarj_python_lint-1.14.0}/src/sarj_python_lint/rules/_registry.py

@@ -98,6 +98,7 @@ from sarj_python_lint.rules.no_whole_request_response_payload_in_log import (
 from sarj_python_lint.rules.opaque_parametrize_case_needs_id import OpaqueParametrizeCaseNeedsId
 from sarj_python_lint.rules.over_mocked_test import OverMockedTest
 from sarj_python_lint.rules.phase_label_comment import TestPhaseLabelComment
+from sarj_python_lint.rules.prefer_autospec_for_callable_mock import PreferAutospecForCallableMock
 from sarj_python_lint.rules.prefer_class_row import PreferClassRow
 from sarj_python_lint.rules.prefer_collection_comprehension import PreferCollectionComprehension
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
@@ -248,6 +249,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         PreferInjectedDependencyOverMonkeypatch.id: PreferInjectedDependencyOverMonkeypatch,
         PreferMonkeypatchForProcessStateInTest.id: PreferMonkeypatchForProcessStateInTest,
         MockWithoutSpec.id: MockWithoutSpec,
+        PreferAutospecForCallableMock.id: PreferAutospecForCallableMock,
         OpaqueParametrizeCaseNeedsId.id: OpaqueParametrizeCaseNeedsId,
         PytestFixtureReturnsBareTuple.id: PytestFixtureReturnsBareTuple,
         StoreGetDelegatesToBulkRead.id: StoreGetDelegatesToBulkRead,

sarj_python_lint-1.14.0/src/sarj_python_lint/rules/prefer_autospec_for_callable_mock.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+import ast
+from collections import Counter
+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,
+    is_suppressed,
+)
+from sarj_python_lint.rules._ast_index import walk
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_MOCK_SOURCES = frozenset({"unittest.mock"})
+_CONSTRUCTORS = frozenset({"Mock", "MagicMock", "AsyncMock"})
+_CONSTRUCTOR_OPTIONS = frozenset({"spec", "spec_set", "return_value", "name", "unsafe", "autospec"})
+_SAFE_ATTRIBUTES = frozenset(
+    {
+        "assert_called",
+        "assert_called_once",
+        "assert_called_with",
+        "assert_called_once_with",
+        "assert_any_call",
+        "assert_has_calls",
+        "assert_not_called",
+        "assert_awaited",
+        "assert_awaited_once",
+        "assert_awaited_with",
+        "assert_awaited_once_with",
+        "assert_any_await",
+        "assert_has_awaits",
+        "assert_not_awaited",
+        "called",
+        "call_count",
+        "call_args",
+        "call_args_list",
+        "mock_calls",
+        "await_count",
+        "await_args",
+        "await_args_list",
+        "return_value",
+    }
+)
+_REFLECTION = frozenset({"globals", "locals", "vars", "eval", "exec", "setattr", "delattr"})
+_REFLECTION_TARGETS = frozenset(f"builtins.{name}" for name in _REFLECTION)
+_SCOPES = (
+    ast.Module,
+    ast.FunctionDef,
+    ast.AsyncFunctionDef,
+    ast.ClassDef,
+    ast.Lambda,
+    ast.ListComp,
+    ast.SetComp,
+    ast.DictComp,
+    ast.GeneratorExp,
+)
+_BAD = (
+    "from unittest.mock import Mock\n"
+    "def send(*, recipient: str) -> None:\n    pass\n"
+    "def test_send():\n    double = Mock(spec=send)\n    double(recipient='sample')\n"
+)
+_GOOD = _BAD.replace("Mock", "create_autospec").replace("spec=send", "send, spec_set=True")
+
+
+@final
+class PreferAutospecForCallableMock(Rule):
+    id = "prefer-autospec-for-callable-mock"
+    code = "SARJ474"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Prefer autospec for specced function mocks called with explicit keywords.",
+        rationale=(
+            "Mock, MagicMock and AsyncMock with spec or spec_set allow incompatible arguments during invocation. "
+            "Tests that assert only results or call counts can therefore accept a misspelled keyword or stale call shape."
+        ),
+        remediation=(
+            "Use create_autospec(function, spec_set=True), preserving configured results. "
+            "An async function produces an awaitable mock whose signature is checked when awaited. "
+            "Retain a reasoned local exception for a deliberately permissive double."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only authored test files, proven unittest.mock constructors, earlier undecorated non-generic module-local function specs without **kwargs, and unconditional simple mock assignments are analyzed.",
+            "Requires a stable binding and at least one direct call with explicit keywords in the same scope. Escapes, aliases, rebinding, dynamic argument unpacking, wildcard imports and reflective namespace mutation are excluded.",
+            "Imported functions, class or descriptor specs, wrapping, side effects and uncertain configuration are excluded. AsyncMock requires an async function spec so autospec preserves awaiting. Import and function shadow checks, including exception/pattern captures and importer-root walrus/global writes, are conservative across the file. Proven builtins reflection aliases are excluded.",
+            "Exact call-shape assertions such as assert_called_once_with can already validate a spec's signature; this advisory warning asks for validation during invocation. Autospec does not enforce argument value types.",
+            "Passing autospec=True to a Mock constructor merely configures an attribute; it does not activate autospeccing. Use create_autospec instead.",
+            "The initial bounded private-platform survey found zero direct matches within this scope; this is a preventive contract warning, not evidence of a current platform incident. No autofix or blocking promotion is proposed.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="specced-function-direct-call",
+                title="A function spec leaves invocation permissive",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/test_delivery.py", _BAD),),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="autospecced-function-direct-call",
+                title="Autospec checks the function call shape",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("tests/test_delivery.py", _GOOD),),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if not is_test_path(context.path) or context.generated or "Mock" not in context.source:
+            return []
+        tree = context.tree
+        if tree is None or _ambiguous_namespace(context):
+            return []
+        specs = _stable_specs(tree)
+        if not specs:
+            return []
+        findings: list[Diagnostic] = []
+        scopes = [tree, *context.nodes(ast.FunctionDef, ast.AsyncFunctionDef)]
+        for scope in scopes:
+            scope_nodes = tuple(walk(scope))
+            bindings = _binding_counts(scope_nodes)
+            for statement in scope.body:
+                candidate = _mock_binding(statement, specs, context)
+                if candidate is None:
+                    continue
+                name, call = candidate
+                if bindings[name] != 1 or not _closed_fixed_calls(name, call, scope, scope_nodes, context.parents):
+                    continue
+                if 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,
+                        message="A function spec does not check arguments during invocation; use create_autospec(function, spec_set=True) for this callable mock.",
+                        severity=Severity.WARNING,
+                    )
+                )
+        return findings
+
+
+def _stable_specs(tree: ast.Module) -> dict[str, ast.FunctionDef | ast.AsyncFunctionDef]:
+    bindings = _binding_counts(walk(tree))
+    return {
+        node.name: node
+        for node in tree.body
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and not node.decorator_list
+        and not node.type_params
+        and node.args.kwarg is None
+        and bindings[node.name] == 1
+    }
+
+
+def _binding_counts(nodes: Iterable[ast.AST]) -> Counter[str]:
+    counts: Counter[str] = Counter()
+    for node in nodes:
+        match node:
+            case (
+                ast.Name(id=name, ctx=(ast.Store() | ast.Del()))
+                | ast.arg(arg=name)
+                | ast.FunctionDef(name=name)
+                | ast.AsyncFunctionDef(name=name)
+                | ast.ClassDef(name=name)
+                | ast.ExceptHandler(name=str(name))
+                | ast.MatchAs(name=str(name))
+                | ast.MatchStar(name=str(name))
+                | ast.MatchMapping(rest=str(name))
+            ):
+                counts[name] += 1
+            case ast.alias(name=name, asname=alias):
+                counts[alias or name.partition(".")[0]] += 1
+            case ast.Global(names=names) | ast.Nonlocal(names=names):
+                counts.update(names)
+            case _:
+                pass
+    return counts
+
+
+def _mock_binding(
+    statement: ast.stmt, specs: Mapping[str, ast.FunctionDef | ast.AsyncFunctionDef], context: PythonFileContext
+) -> tuple[str, ast.Call] | None:
+    match statement:
+        case (
+            ast.Assign(targets=[ast.Name(id=name)], value=ast.Call() as call)
+            | ast.AnnAssign(target=ast.Name(id=name), value=ast.Call() as call)
+        ):
+            pass
+        case _:
+            return None
+    constructor = context.imports.resolved_symbol(call.func, sources=_MOCK_SOURCES)
+    if call.args or constructor not in _CONSTRUCTORS:
+        return None
+    if any(keyword.arg not in _CONSTRUCTOR_OPTIONS for keyword in call.keywords):
+        return None
+    contracts = [keyword.value for keyword in call.keywords if keyword.arg in {"spec", "spec_set"}]
+    if len(contracts) != 1 or not isinstance(contracts[0], ast.Name) or contracts[0].id not in specs:
+        return None
+    spec = specs[contracts[0].id]
+    if spec.lineno >= call.lineno or (constructor == "AsyncMock" and not isinstance(spec, ast.AsyncFunctionDef)):
+        return None
+    return name, call
+
+
+def _closed_fixed_calls(
+    name: str,
+    constructor: ast.Call,
+    scope: ast.Module | ast.FunctionDef | ast.AsyncFunctionDef,
+    nodes: tuple[ast.AST, ...],
+    parents: Mapping[ast.AST, ast.AST],
+) -> bool:
+    called = False
+    for node in nodes:
+        if not isinstance(node, ast.Name) or node.id != name or not isinstance(node.ctx, ast.Load):
+            continue
+        if node.lineno <= constructor.lineno or _scope_of(node, parents) is not scope:
+            return False
+        parent = parents[node]
+        if isinstance(parent, ast.Call) and parent.func is node:
+            if not _fixed_arguments(parent):
+                return False
+            called = called or bool(parent.keywords)
+        elif _safe_mock_attribute(parent):
+            continue
+        else:
+            return False
+    return called
+
+
+def _fixed_arguments(call: ast.Call) -> bool:
+    return not any(isinstance(argument, ast.Starred) for argument in call.args) and all(
+        keyword.arg is not None for keyword in call.keywords
+    )
+
+
+def _safe_mock_attribute(node: ast.AST) -> bool:
+    if not isinstance(node, ast.Attribute) or node.attr not in _SAFE_ATTRIBUTES:
+        return False
+    return isinstance(node.ctx, ast.Load) or (node.attr == "return_value" and isinstance(node.ctx, ast.Store))
+
+
+def _scope_of(node: ast.AST, parents: Mapping[ast.AST, ast.AST]) -> ast.AST:
+    while node in parents:
+        node = parents[node]
+        if isinstance(node, _SCOPES):
+            return node
+    return node
+
+
+def _ambiguous_namespace(context: PythonFileContext) -> bool:
+    if _ambiguous_constructor_bindings(context):
+        return True
+    for node in context.nodes(ast.ImportFrom, ast.Call, ast.Attribute):
+        if isinstance(node, ast.ImportFrom) and any(alias.name == "*" for alias in node.names):
+            return True
+        if isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name) and node.func.id in _REFLECTION:
+                return True
+            if context.imports.resolved_qualified_name(node.func) in _REFLECTION_TARGETS:
+                return True
+        if (
+            isinstance(node, ast.Attribute)
+            and isinstance(node.ctx, (ast.Store, ast.Del))
+            and context.imports.resolved_symbol(node, sources=_MOCK_SOURCES) in _CONSTRUCTORS
+        ):
+            return True
+    return False
+
+
+def _ambiguous_constructor_bindings(context: PythonFileContext) -> bool:
+    constructor_roots = _constructor_roots(context)
+    for node in context.nodes(
+        ast.ExceptHandler, ast.MatchAs, ast.MatchStar, ast.MatchMapping, ast.NamedExpr, ast.Global
+    ):
+        match node:
+            case (
+                ast.ExceptHandler(name=name)
+                | ast.MatchAs(name=name)
+                | ast.MatchStar(name=name)
+                | ast.MatchMapping(rest=name)
+                | ast.NamedExpr(target=ast.Name(id=name))
+            ):
+                if name in constructor_roots:
+                    return True
+            case ast.Global(names=names):
+                if constructor_roots.intersection(names):
+                    return True
+    return False
+
+
+def _constructor_roots(context: PythonFileContext) -> set[str]:
+    constructor_roots: set[str] = set()
+    for call in context.nodes(ast.Call):
+        if context.imports.resolved_symbol(call.func, sources=_MOCK_SOURCES) not in _CONSTRUCTORS:
+            continue
+        root = call.func
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if isinstance(root, ast.Name):
+            constructor_roots.add(root.id)
+    return constructor_roots

{sarj_python_lint-1.12.0 → sarj_python_lint-1.14.0}/src/sarj_python_lint/rules/unused_test_factory_option.py

@@ -38,14 +38,15 @@ class UnusedTestFactoryOption(Rule):
     code = "SARJ443"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="A private test factory exposes a literal option that visible callers never vary.",
+        summary="A private test factory exposes an option that visible callers never vary.",
         rationale="Unused customization obscures the values that actually distinguish test scenarios.",
         remediation="Keep the value in the factory's construction instead of exposing an unused option; retain it if external callers need it.",
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only module-level private _make_ and _build_ helpers with straight-line local assignments ending in a construction return are considered; control flow and standalone side effects are excluded.",
-            "Only literal defaults with direct, unambiguous calls in this file are reported. Explicit options require at least two calls with the same effective literal value. Decorators, rebinding, callable escapes, reflection, and argument unpacking exclude the helper.",
+            "Literal defaults and stable earlier module-local function defaults are considered. Callable options are reported only when every direct caller omits them; explicit literal options require at least two calls with the same effective value.",
+            "Decorators, rebinding, shadowing, callable escapes, reflection, argument unpacking, and ambiguous provider mutation or patch targets exclude the affected helper or callable option.",
             "Cross-module callers cannot be proven absent. Shared helpers require an exact suppression; this advisory never autofixes signatures or changes default evaluation timing.",
         ),
         examples=(
@@ -77,6 +78,36 @@ class UnusedTestFactoryOption(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="unused-callable-option",
+                scenario="callable-default",
+                title="Use an unexercised local dependency directly",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _read():\n    return 'value'\n\ndef _make_widget(*, read=_read):\n    return Widget(read=read)\n\n_make_widget()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="exercised-callable-option",
+                scenario="callable-default",
+                title="Keep a dependency that a caller replaces",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _read():\n    return 'value'\n\ndef _make_widget(*, read=_read):\n    return Widget(read=read)\n\n_make_widget(read=other)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=0,
+                public=True,
+            ),
         ),
     )
     description = documentation.summary
@@ -173,6 +204,27 @@ def _factory_findings(
                 ),
             )
         )
+    for argument, default in _factory_options(function):
+        if (
+            argument.arg in supplied
+            or not isinstance(default, ast.Name)
+            or not _is_stable_local_callable(tree, function, default.id, node_index=node_index)
+            or is_suppressed(lines, argument.lineno, code)
+        ):
+            continue
+        findings.append(
+            Diagnostic(
+                path=path,
+                line=argument.lineno,
+                col=argument.col_offset + 1,
+                code=code,
+                severity=Severity.WARNING,
+                message=(
+                    f"No direct caller in this file supplies `{function.name}.{argument.arg}`; use the stable local "
+                    f"callable `{default.id}` in the factory instead of exposing an unused option. Retain it if external callers need it."
+                ),
+            )
+        )
     return findings
 
 
@@ -258,18 +310,49 @@ def _factory_argument_is_invariant(argument: ast.arg, default: ast.Constant, bou
     )
 
 
-def _literal_factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.Constant]]:
-    options: list[tuple[ast.arg, ast.Constant]] = []
+def _factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.expr]]:
     positional = [*function.args.posonlyargs, *function.args.args]
     defaults = [
         *zip(positional[len(positional) - len(function.args.defaults) :], function.args.defaults, strict=True),
         *zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True),
     ]
     used = {node.id for node in nodes(function, ast.Name) if isinstance(node.ctx, ast.Load)}
-    for argument, default in defaults:
-        if argument.arg not in used or not isinstance(default, ast.Constant):
-            continue
-        if default.value is not None and not isinstance(default.value, (str, bytes, int, float)):
-            continue
-        options.append((argument, default))
-    return options
+    return [(argument, default) for argument, default in defaults if argument.arg in used and default is not None]
+
+
+def _literal_factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.Constant]]:
+    return [
+        (argument, default)
+        for argument, default in _factory_options(function)
+        if isinstance(default, ast.Constant)
+        and (default.value is None or isinstance(default.value, (str, bytes, int, float)))
+    ]
+
+
+def _is_stable_local_callable(
+    tree: ast.Module,
+    factory: ast.FunctionDef,
+    name: str,
+    *,
+    node_index: NodeIndex | None = None,
+) -> bool:
+    if not any(
+        isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and node.name == name
+        and node.lineno < factory.lineno
+        and not node.decorator_list
+        for node in tree.body
+    ) or not _has_unambiguous_factory_name(tree, name, node_index=node_index):
+        return False
+    return not (
+        any(node.id == name and not isinstance(node.ctx, ast.Load) for node in nodes(tree, ast.Name, index=node_index))
+        or any(
+            not isinstance(node.ctx, ast.Load) and any(child.id == name for child in nodes(node.value, ast.Name))
+            for node in nodes(tree, ast.Attribute, index=node_index)
+        )
+        or any(
+            isinstance(node.value, str)
+            and (node.value.rsplit(".", 1)[-1] == name or factory.name in node.value.split("."))
+            for node in nodes(tree, ast.Constant, index=node_index)
+        )
+    )