sarj-python-lint 1.36.0__tar.gz → 1.37.0__tar.gz

{sarj_python_lint-1.36.0 → sarj_python_lint-1.37.0}/PKG-INFO

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

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

{sarj_python_lint-1.36.0 → sarj_python_lint-1.37.0}/src/sarj_python_lint/rule_base.py

@@ -94,6 +94,7 @@ class Rule(ABC):
     id: str
     code: str
     description: str
+    enabled_by_default: ClassVar[bool] = True
     documentation: ClassVar[RuleDocumentation | None] = None
     _analysis_session: AnalysisSession | None = None
 

sarj_python_lint-1.37.0/src/sarj_python_lint/rules/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from sarj_python_lint.rules._registry import DEFAULT_REGISTRY as DEFAULT_REGISTRY, REGISTRY as REGISTRY

{sarj_python_lint-1.36.0 → sarj_python_lint-1.37.0}/src/sarj_python_lint/rules/_project_index.py

@@ -566,20 +566,22 @@ class ProjectIndexSet:
             if isinstance(owner, ast.ClassDef) and _class_has_typed_dependency(candidate, owner, target)
         )
 
+    @cached_property
+    def _mock_specs(self) -> Mapping[SymbolRef, frozenset[Path]]:
+        specs: dict[SymbolRef, set[Path]] = {}
+        for candidate in self._units.values():
+            if candidate.tree is None:
+                continue
+            for call in walk_ast(candidate.tree):
+                if isinstance(call, ast.Call):
+                    for target in _mock_spec_targets(candidate, call):
+                        specs.setdefault(target, set()).add(candidate.path)
+        return MappingProxyType({target: frozenset(paths) for target, paths in specs.items()})
+
     def test_mock_specs(self, unit: SourceUnit, name: str) -> frozenset[Path]:
         if unit.module is None:
             return frozenset()
-        target = SymbolRef(unit.module, name)
-        return frozenset(
-            candidate.path
-            for candidate in self._units.values()
-            if candidate.tree is not None
-            and any(
-                _is_mock_spec_for(candidate, call, target)
-                for call in walk_ast(candidate.tree)
-                if isinstance(call, ast.Call)
-            )
-        )
+        return self._mock_specs.get(SymbolRef(unit.module, name), frozenset())
 
     def class_inherits_from(self, unit: SourceUnit, name: str, qualified_bases: frozenset[str]) -> bool:
         if unit.module is None:
@@ -1350,14 +1352,15 @@ def _class_has_typed_dependency(unit: SourceUnit, owner: ast.ClassDef, target: S
     return False
 
 
-def _is_mock_spec_for(unit: SourceUnit, call: ast.Call, target: SymbolRef) -> bool:
+def _mock_spec_targets(unit: SourceUnit, call: ast.Call) -> Iterator[SymbolRef]:
     mock_name = _mock_function_name(unit, call.func)
     if mock_name is None:
-        return False
-    return any(
-        keyword.arg in {"spec", "spec_set"} and _direct_base_symbol(unit, keyword.value) == target
-        for keyword in call.keywords
-    ) or (mock_name == "create_autospec" and bool(call.args) and _direct_base_symbol(unit, call.args[0]) == target)
+        return
+    for keyword in call.keywords:
+        if keyword.arg in {"spec", "spec_set"} and (target := _direct_base_symbol(unit, keyword.value)) is not None:
+            yield target
+    if mock_name == "create_autospec" and call.args and (target := _direct_base_symbol(unit, call.args[0])) is not None:
+        yield target
 
 
 def _mock_function_name(unit: SourceUnit, function: ast.expr) -> str | None:

{sarj_python_lint-1.36.0 → sarj_python_lint-1.37.0}/src/sarj_python_lint/rules/_registry.py

@@ -215,10 +215,12 @@ from sarj_python_lint.rules.no_impossible_pydantic_field_bounds import NoImpossi
 from sarj_python_lint.rules.no_unknown_pydantic_validator_field import NoUnknownPydanticValidatorField
 from sarj_python_lint.rules.redundant_test_constructor_forwarder import RedundantTestConstructorForwarder
 from sarj_python_lint.rules.repeated_unimplemented_test_contract import RepeatedUnimplementedTestContract
+from sarj_python_lint.rules.test_without_explicit_oracle import NoExplicitTestOracle
 
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        NoExplicitTestOracle.id: NoExplicitTestOracle,
         NoConflictingPydanticAliasValidation.id: NoConflictingPydanticAliasValidation,
         NoUnknownPydanticValidatorField.id: NoUnknownPydanticValidatorField,
         NoImpossiblePydanticFieldBounds.id: NoImpossiblePydanticFieldBounds,
@@ -367,3 +369,8 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RepeatedUnimplementedTestContract.id: RepeatedUnimplementedTestContract,
     }
 )
+
+
+DEFAULT_REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
+    {name: rule for name, rule in REGISTRY.items() if rule.enabled_by_default}
+)

sarj_python_lint-1.37.0/src/sarj_python_lint/rules/test_without_explicit_oracle.py

@@ -0,0 +1,244 @@
+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
+from sarj_python_lint.rules._pytest import uses_benchmark_fixture
+from sarj_python_lint.rules._test_assertions import names_verification, reads_as_verification
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+type _Function = ast.FunctionDef | ast.AsyncFunctionDef
+_NON_UNIT_MARKS = frozenset({"benchmark", "lto", "lto_judge", "skip", "skipif", "xfail"})
+
+
+@final
+class NoExplicitTestOracle(Rule):
+    id = "test-without-explicit-oracle"
+    code = "SARJ495"
+    enabled_by_default = False
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="A collected test has no visible assertion or exception oracle.",
+        rationale=(
+            "A test can execute a side effect without observing whether the intended effect occurred. "
+            "The absence of an explicit oracle is a review candidate, not proof that a smoke or no-throw contract is weak."
+        ),
+        remediation=(
+            "Identify the intended contract. Reuse adequate existing coverage, observe the returned value, state, "
+            "or emitted effect, or retain the test when successful execution is itself the contract. Do not add "
+            "a tautological assertion or delete a test solely to silence this advisory."
+        ),
+        category=RuleCategory.TESTING,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "This opt-in advisory is excluded from default Python checks; select it explicitly or use code-standards observe.",
+            "Only default-collected test_* functions and methods of undecorated or pytest-marked, constructor-free, base-free Test* classes are inspected.",
+            "Assertions, explicit raises, verification-named calls, import aliases, and local helpers containing or forwarding an oracle are accepted conservatively.",
+            "Unknown decorators, test opt-outs, benchmark/LLM/skipped tests, and callable fixture parameters are left unreported; external helper behavior is not inferred.",
+            "An intentional no-throw test may match. Findings describe syntax and require contract review; they never authorize automatic deletion or error-level promotion.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="unobserved-effect",
+                title="Observe whether the requested side effect occurred",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("tests/test_delivery.py", "def test_delivery():\n    deliver('hello')\n"),),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="observed-effect",
+                title="The assertion distinguishes a missing delivery",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_delivery.py",
+                        "def test_delivery(sender):\n    deliver('hello', sender)\n    assert sender.messages == ['hello']\n",
+                    ),
+                ),
+                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.path.name == "conftest.py" or context.generated:
+            return []
+        tree = context.tree
+        if tree is None or _opts_out(tree.body) or not _scope_marks(tree.body, context.imports):
+            return []
+        helpers = _oracle_helpers(tree, context.imports)
+        return [
+            Diagnostic(
+                path=context.path,
+                line=function.lineno,
+                col=function.col_offset + 1,
+                code=self.code,
+                severity=Severity.WARNING,
+                message=(
+                    f"`{function.name}` has no visible assertion or exception oracle. Review the contract: "
+                    "observe the outcome, reuse existing coverage, or retain an intentional smoke/no-throw test."
+                ),
+            )
+            for function in _collected_tests(tree, context.imports)
+            if not uses_benchmark_fixture(function)
+            and not _has_oracle(function, helpers, context.imports)
+            and not _calls_fixture(function)
+        ]
+
+
+def _scope_nodes(function: _Function) -> Iterator[ast.AST]:
+    pending: list[ast.AST] = list(reversed(function.body))
+    while pending:
+        node = pending.pop()
+        yield node
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+            pending.extend(reversed(list(ast.iter_child_nodes(node))))
+
+
+def _has_oracle(function: _Function, helpers: frozenset[str], imports: ImportIndex) -> bool:
+    for node in _scope_nodes(function):
+        if isinstance(node, (ast.Assert, ast.Raise)):
+            return True
+        if isinstance(node, ast.Call):
+            if names_verification(node.func, helpers):
+                return True
+            if isinstance(node.func, ast.Attribute) and node.func.attr in helpers:
+                return True
+            qualified = imports.resolved_qualified_name(node.func)
+            if qualified is not None and reads_as_verification(qualified.rsplit(".", 1)[-1]):
+                return True
+    return False
+
+
+def _oracle_helpers(tree: ast.Module, imports: ImportIndex) -> frozenset[str]:
+    functions = [node for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))]
+    helpers: frozenset[str] = frozenset()
+    while True:
+        updated = helpers | frozenset(
+            function.name for function in functions if _has_oracle(function, helpers, imports)
+        )
+        if updated == helpers:
+            return helpers
+        helpers = updated
+
+
+def _opts_out(statements: Sequence[ast.stmt]) -> bool:
+    return any(
+        isinstance(target, ast.Name)
+        and target.id == "__test__"
+        and (not isinstance(value, ast.Constant) or value.value is not True)
+        for target, value in _assignments(statements)
+    )
+
+
+def _assignments(statements: Sequence[ast.stmt]) -> Iterator[tuple[ast.expr, ast.expr]]:
+    for statement in statements:
+        if isinstance(statement, ast.Assign):
+            for target in statement.targets:
+                yield target, statement.value
+        elif isinstance(statement, ast.AnnAssign) and statement.value is not None:
+            yield statement.target, statement.value
+
+
+def _scope_marks(statements: Sequence[ast.stmt], imports: ImportIndex) -> bool:
+    for target, value in _assignments(statements):
+        if isinstance(target, ast.Name) and target.id == "pytestmark":
+            marks = value.elts if isinstance(value, (ast.List, ast.Tuple)) else [value]
+            if not _safe_marks(marks, imports):
+                return False
+    return True
+
+
+def _disabled_tests(statements: Sequence[ast.stmt]) -> frozenset[str]:
+    return frozenset(
+        ast.unparse(target.value)
+        for target, value in _assignments(statements)
+        if (
+            isinstance(target, ast.Attribute)
+            and target.attr == "__test__"
+            and (not isinstance(value, ast.Constant) or value.value is not True)
+        )
+    )
+
+
+def _safe_marks(decorators: Sequence[ast.expr], imports: ImportIndex) -> bool:
+    for decorator in decorators:
+        target = decorator.func if isinstance(decorator, ast.Call) else decorator
+        qualified = imports.resolved_qualified_name(target)
+        if qualified is None or not qualified.startswith("pytest.mark."):
+            return False
+        if qualified.rsplit(".", 1)[-1] in _NON_UNIT_MARKS:
+            return False
+    return True
+
+
+def _collected_tests(tree: ast.Module, imports: ImportIndex) -> Iterator[_Function]:
+    disabled = _disabled_tests(tree.body)
+    for statement in tree.body:
+        if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _test_function(statement, disabled, imports):
+                yield statement
+        elif isinstance(statement, ast.ClassDef) and statement.name not in disabled and _test_class(statement, imports):
+            yield from _class_tests(statement, disabled, imports)
+
+
+def _class_tests(node: ast.ClassDef, disabled: frozenset[str], imports: ImportIndex) -> Iterator[_Function]:
+    class_disabled = _disabled_tests(node.body) | frozenset(
+        name.removeprefix(f"{node.name}.") for name in disabled if name.startswith(f"{node.name}.")
+    )
+    for child in node.body:
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)) and _test_function(
+            child, class_disabled, imports
+        ):
+            yield child
+
+
+def _test_function(node: _Function, disabled: frozenset[str], imports: ImportIndex) -> bool:
+    return node.name.startswith("test_") and node.name not in disabled and _safe_marks(node.decorator_list, imports)
+
+
+def _test_class(node: ast.ClassDef, imports: ImportIndex) -> bool:
+    if not node.name.startswith("Test") or node.bases or node.keywords or _opts_out(node.body):
+        return False
+    if any(
+        isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)) and child.name in {"__init__", "__new__"}
+        for child in node.body
+    ):
+        return False
+    return _safe_marks(node.decorator_list, imports) and _scope_marks(node.body, imports)
+
+
+def _calls_fixture(function: _Function) -> bool:
+    parameters = {
+        argument.arg for argument in (*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs)
+    }
+    return any(
+        isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in parameters
+        for node in _scope_nodes(function)
+    )

sarj_python_lint-1.36.0/src/sarj_python_lint/rules/__init__.py

@@ -1,3 +0,0 @@
-from __future__ import annotations
-
-from sarj_python_lint.rules._registry import REGISTRY as REGISTRY