sarj-python-lint 0.82.2__tar.gz → 0.82.4__tar.gz

{sarj_python_lint-0.82.2 → sarj_python_lint-0.82.4}/PKG-INFO

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

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

{sarj_python_lint-0.82.2 → sarj_python_lint-0.82.4}/src/sarj_python_lint/rules/_registry.py

@@ -93,6 +93,9 @@ from sarj_python_lint.rules.prefer_fstring_over_concat import PreferFstringOverC
 from sarj_python_lint.rules.prefer_immutable_module_constant import (
     PreferImmutableModuleConstant,
 )
+from sarj_python_lint.rules.prefer_injected_dependency_over_monkeypatch import (
+    PreferInjectedDependencyOverMonkeypatch,
+)
 from sarj_python_lint.rules.prefer_library_fake import PreferLibraryFake
 from sarj_python_lint.rules.prefer_match_assert_never import PreferMatchAssertNever
 from sarj_python_lint.rules.prefer_match_type_dispatch import PreferMatchTypeDispatch
@@ -200,6 +203,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequirePydanticForExternalJson.id: RequirePydanticForExternalJson,
         PreferModuleLevelConstant.id: PreferModuleLevelConstant,
         PreferImmutableModuleConstant.id: PreferImmutableModuleConstant,
+        PreferInjectedDependencyOverMonkeypatch.id: PreferInjectedDependencyOverMonkeypatch,
         MockWithoutSpec.id: MockWithoutSpec,
         OpaqueParametrizeCaseNeedsId.id: OpaqueParametrizeCaseNeedsId,
         PytestFixtureReturnsBareTuple.id: PytestFixtureReturnsBareTuple,

{sarj_python_lint-0.82.2 → sarj_python_lint-0.82.4}/src/sarj_python_lint/rules/no_excessive_cognitive_complexity.py

@@ -166,7 +166,7 @@ class NoExcessiveCognitiveComplexity(Rule):
     documentation = RuleDocumentation(
         summary=f"Error on cognitive complexity above {_ERROR_COMPLEXITY}; scores up to 20 pass.",
         rationale="Nested control flow increases the context a reader must retain while following a function.",
-        remediation="Examples are fictional and written for this documentation; domain types are omitted. The library example replaces nested eligibility checks with early returns while preserving evaluation order. Refactor one function at a time, starting with its largest contributors. Use guard clauses, named predicates, or cohesive helpers; use lookup tables only for equivalent pure dispatch. Preserve APIs, side effects, evaluation order, and exception behavior. Run relevant tests before and after; remeasure the original and extracted functions. Do not hide branches in dense expressions or add indirection just to lower a score.",
+        remediation="Examples are fictional and written for this documentation; domain types are omitted. The library example replaces nested eligibility checks with early returns while preserving evaluation order. Refactor one function at a time, starting with its largest contributors. First simplify control flow and reduce nesting within the function. Extract a helper only when it clarifies a cohesive responsibility or enables meaningful reuse; do not split code solely to lower the score. Use lookup tables only for equivalent pure dispatch. Preserve APIs, side effects, evaluation order, and exception behavior. Run relevant tests before and after; remeasure the original and extracted functions. Do not hide branches in dense expressions or add indirection just to lower a score.",
         category=RuleCategory.MAINTAINABILITY,
         limitations=(
             "Sarj metric, not exact Sonar compatibility: functions and lambdas are independent; calls, recursion, function annotations, parameter defaults, and decorators are not scored.",
@@ -255,7 +255,7 @@ class NoExcessiveCognitiveComplexity(Rule):
                     line=function.lineno,
                     col=function.col_offset + 1,
                     code=self.code,
-                    message=f"Cognitive complexity {score} exceeds {_ERROR_COMPLEXITY}. Largest contributors: {detail}. Start with the largest contributors: flatten nesting or extract a clearly named operation without hiding branches in dense expressions. Preserve behavior and public APIs, run relevant tests before and after, then remeasure.",
+                    message=f"Cognitive complexity {score} exceeds {_ERROR_COMPLEXITY}. Largest contributors: {detail}. Start with the largest contributors: simplify control flow and flatten nesting. Extract a helper only when it clarifies a cohesive responsibility or enables meaningful reuse, never solely to lower the score. Do not hide branches in dense expressions. Preserve behavior and public APIs, run relevant tests before and after, then remeasure.",
                     severity=Severity.ERROR,
                 )
             )

sarj_python_lint-0.82.4/src/sarj_python_lint/rules/prefer_injected_dependency_over_monkeypatch.py

@@ -0,0 +1,281 @@
+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,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+
+_ATTRIBUTE_MUTATIONS = frozenset({"delattr", "setattr"})
+_MONKEYPATCH = "monkeypatch"
+_PYTEST = frozenset({"pytest"})
+_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+
+
+class PreferInjectedDependencyOverMonkeypatch(Rule):
+    id: str = "prefer-injected-dependency-over-monkeypatch"
+    code: str = "SARJ445"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Tests should inject dependencies instead of replacing attributes through pytest monkeypatch.",
+        rationale=(
+            "Attribute patching hides collaborators and configuration behind ambient module or object state, coupling "
+            "tests to lookup locations instead of an explicit boundary. Pytest monkeypatch remains appropriate for "
+            "reversible process state such as environment variables and the working directory."
+        ),
+        remediation=(
+            "Pass the collaborator, settings, clock, sleeper, random source, client, or factory explicitly; prefer a "
+            "real in-process dependency, framework override, or purpose-built ABC/Protocol fake. If a runtime "
+            "boundary is inherently global, or intercepting its lookup is the behavior under test, suppress SARJ445 "
+            "at that call with the concrete reason an owned injection seam would invalidate the test."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only maintained test paths are analyzed; generated files and production helpers are excluded.",
+            "The rule recognizes pytest's conventional monkeypatch fixture name and parameters annotated as pytest.MonkeyPatch.",
+            "Environment, mapping, import-path, and working-directory mutations are intentionally allowed.",
+            "A nested function that captures a monkeypatch handle from an outer scope is not inferred.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="patched-first-party-collaborator",
+                title="Test replaces an application collaborator",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_checkout.py",
+                        "def test_checkout(monkeypatch):\n"
+                        "    monkeypatch.setattr(checkout, 'charge_card', lambda _card: True)\n"
+                        "    assert checkout.run() == 'paid'\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_checkout.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="injected-recording-collaborator",
+                title="Test injects a purpose-built collaborator",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_checkout.py",
+                        "def test_checkout(recording_gateway):\n"
+                        "    service = CheckoutService(payment_gateway=recording_gateway)\n"
+                        "    assert service.run() == 'paid'\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_checkout.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description: str = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_test_path(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree, module_scope_only=True)
+        diagnostics = [
+            Diagnostic(
+                path=path,
+                line=call.lineno,
+                col=call.col_offset + 1,
+                code=self.code,
+                message=(
+                    f"`monkeypatch.{_operation(call)}` replaces an attribute through ambient state. Inject the "
+                    "dependency or configuration, use a framework override, or provide a purpose-built fake. "
+                    "If global lookup or interception is the behavior under test, suppress SARJ445 locally and explain "
+                    "why injection would invalidate the test."
+                ),
+                severity=Severity.WARNING,
+            )
+            for function in _functions(tree)
+            for call in _attribute_mutations(function, imports)
+        ]
+        diagnostics.sort(key=lambda diagnostic: (diagnostic.line, diagnostic.col))
+        return diagnostics
+
+
+def _operation(call: ast.Call) -> str:
+    func = call.func
+    if not isinstance(func, ast.Attribute):  # pragma: no cover - guarded by _attribute_mutations
+        msg = "attribute mutation call must use an attribute function"
+        raise TypeError(msg)
+    return func.attr
+
+
+def _functions(tree: ast.Module) -> Iterator[ast.FunctionDef | ast.AsyncFunctionDef]:
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield node
+
+
+def _attribute_mutations(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    imports: ImportIndex,
+) -> list[ast.Call]:
+    parameters = _parameter_handles(function, imports)
+    if not parameters:
+        return []
+    nodes = tuple(_lexical_body_nodes(function))
+    handles = set(parameters)
+    handles |= _direct_aliases(nodes, handles, parameters)
+    return [
+        node
+        for node in nodes
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr in _ATTRIBUTE_MUTATIONS
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id in handles
+        and not _parameter_rebound_before(node, node.func.value.id, nodes, parameters)
+    ]
+
+
+def _parameter_handles(
+    function: ast.FunctionDef | ast.AsyncFunctionDef,
+    imports: ImportIndex,
+) -> set[str]:
+    args = function.args
+    parameters = (*args.posonlyargs, *args.args, *args.kwonlyargs)
+    return {
+        parameter.arg
+        for parameter in parameters
+        if parameter.arg == _MONKEYPATCH or _is_monkeypatch_annotation(parameter.annotation, imports)
+    }
+
+
+def _is_monkeypatch_annotation(annotation: ast.expr | None, imports: ImportIndex) -> bool:
+    if annotation is None:
+        return False
+    if imports.resolves(annotation, sources=_PYTEST, symbol="MonkeyPatch"):
+        return True
+    if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+        return _is_monkeypatch_annotation(annotation.left, imports) or _is_monkeypatch_annotation(
+            annotation.right, imports
+        )
+    if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+        return annotation.value in {"MonkeyPatch", "pytest.MonkeyPatch"}
+    return False
+
+
+def _parameter_rebound_before(
+    use: ast.AST,
+    handle: str,
+    nodes: tuple[ast.AST, ...],
+    parameters: set[str],
+) -> bool:
+    if handle not in parameters:
+        return False
+    use_position = _position(use)
+    return any(handle in _bound_targets(node) and _position(node) < use_position for node in nodes)
+
+
+def _position(node: ast.AST) -> tuple[int, int]:
+    if isinstance(node, ast.withitem):
+        return _position(node.context_expr)
+    return (getattr(node, "lineno", 0), getattr(node, "col_offset", 0))
+
+
+def _direct_aliases(nodes: tuple[ast.AST, ...], handles: set[str], parameters: set[str]) -> set[str]:
+    binding_counts: dict[str, int] = {}
+    for node in nodes:
+        for name in _bound_targets(node):
+            binding_counts[name] = binding_counts.get(name, 0) + 1
+    aliases: set[str] = set()
+    changed = True
+    while changed:
+        changed = False
+        known = handles | aliases
+        for node in nodes:
+            binding = _alias_binding(node, known)
+            if binding is None:
+                continue
+            candidate, source = binding
+            source_was_rebound = _parameter_rebound_before(node, source, nodes, parameters)
+            if not source_was_rebound and binding_counts.get(candidate) == 1 and candidate not in known:
+                aliases.add(candidate)
+                changed = True
+    return aliases
+
+
+def _bound_targets(node: ast.AST) -> set[str]:
+    match node:
+        case ast.Assign(targets=targets) | ast.Delete(targets=targets):
+            return {name for target in targets for name in _target_names(target)}
+        case (
+            ast.AnnAssign(target=target)
+            | ast.AugAssign(target=target)
+            | ast.NamedExpr(target=target)
+            | ast.For(target=target)
+            | ast.AsyncFor(target=target)
+        ):
+            return _target_names(target)
+        case ast.withitem(optional_vars=target) if target is not None:
+            return _target_names(target)
+        case _:
+            return set()
+
+
+def _alias_binding(node: ast.AST, handles: set[str]) -> tuple[str, str] | None:
+    if isinstance(node, (ast.Assign, ast.AnnAssign)):
+        value = node.value
+        targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+        if isinstance(value, ast.Name) and value.id in handles and len(targets) == 1:
+            names = _target_names(targets[0])
+            return (next(iter(names)), value.id) if len(names) == 1 else None
+    if isinstance(node, ast.withitem) and node.optional_vars is not None:
+        expression = node.context_expr
+        if (
+            isinstance(expression, ast.Call)
+            and isinstance(expression.func, ast.Attribute)
+            and expression.func.attr == "context"
+            and isinstance(expression.func.value, ast.Name)
+            and expression.func.value.id in handles
+        ):
+            names = _target_names(node.optional_vars)
+            return (next(iter(names)), expression.func.value.id) if len(names) == 1 else None
+    return None
+
+
+def _target_names(node: ast.expr) -> set[str]:
+    if isinstance(node, ast.Name):
+        return {node.id}
+    if isinstance(node, (ast.List, ast.Tuple)):
+        return {name for element in node.elts for name in _target_names(element)}
+    return set()
+
+
+def _lexical_body_nodes(function: ast.FunctionDef | ast.AsyncFunctionDef) -> Iterator[ast.AST]:
+    pending: list[ast.AST] = list(reversed(function.body))
+    while pending:
+        node = pending.pop()
+        yield node
+        if isinstance(node, _SCOPES):
+            continue
+        pending.extend(reversed(list(ast.iter_child_nodes(node))))