sarj-python-lint 1.36.1__tar.gz → 1.38.0__tar.gz

{sarj_python_lint-1.36.1 → sarj_python_lint-1.38.0}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.36.1"
+version = "1.38.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.1 → sarj_python_lint-1.38.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.38.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.1 → sarj_python_lint-1.38.0}/src/sarj_python_lint/rules/_registry.py

@@ -32,6 +32,7 @@ from sarj_python_lint.rules.no_analytical_aggregation_in_postgres_store import (
     NoAnalyticalAggregationInPostgresStore,
 )
 from sarj_python_lint.rules.no_any_mapping_types import NoAnyMappingTypes
+from sarj_python_lint.rules.no_async_function_cache import NoAsyncFunctionCache
 from sarj_python_lint.rules.no_before_validator_input_mutation import NoBeforeValidatorInputMutation
 from sarj_python_lint.rules.no_broad_keyword_capture import NoBroadKeywordCapture
 from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
@@ -215,10 +216,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,
@@ -239,6 +242,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoSwallowedAsyncioCancellation.id: NoSwallowedAsyncioCancellation,
         RequireExplicitPsycopgTransaction.id: RequireExplicitPsycopgTransaction,
         AsyncMockCallWithoutAwaitAssertion.id: AsyncMockCallWithoutAwaitAssertion,
+        NoAsyncFunctionCache.id: NoAsyncFunctionCache,
         ComplexPostgresQueryRequiresArchitectureReview.id: ComplexPostgresQueryRequiresArchitectureReview,
         ExcessiveCommentary.id: ExcessiveCommentary,
         PreferWalrusAwaitedNoneGuard.id: PreferWalrusAwaitedNoneGuard,
@@ -367,3 +371,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.38.0/src/sarj_python_lint/rules/no_async_function_cache.py

@@ -0,0 +1,179 @@
+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,
+    is_suppressed,
+)
+from sarj_python_lint.rules._ast_index import children
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_FUNCTOOLS = frozenset({"functools"})
+_COROUTINE_CACHES = frozenset({"cache", "cached_property", "lru_cache"})
+_LRU_CACHE_POSITIONAL_ARGUMENTS = 2
+
+
+@final
+class NoAsyncFunctionCache(Rule):
+    id = "no-async-function-cache"
+    code = "SARJ507"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Standard library cache decorates a coroutine function and retains single-use coroutine objects.",
+        rationale=(
+            "`functools.cache`, `lru_cache`, and `cached_property` store the coroutine object returned by an async "
+            "function rather than its awaited value. A subsequent cache hit can raise `RuntimeError: cannot reuse "
+            "already awaited coroutine`."
+        ),
+        remediation="Remove the standard library cache or use an async-aware cache that stores completed results.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only a proven functools import used as the innermost decorator on a coroutine function is reported.",
+            "Async generators, transformed functions, ambiguous or rebound imports, and generated files are excluded.",
+            "Wildcard imports and names rebound by relative imports or imports outside the module body are excluded conservatively.",
+            "lru_cache with disabled, dynamic, or unpacked maxsize arguments is excluded; an omitted size or literal positive integer or None is required.",
+            "Indirect wrapping calls and runtime monkeypatches are not resolved. Test code is checked because coroutine reuse fails there too.",
+            "No automatic rewrite is offered because cache lifetime, cancellation, and concurrency require an explicit design decision.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="cached-coroutine-function",
+                title="A standard cache retains an exhausted coroutine",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/cache.py",
+                        "from functools import cache\n\n@cache\nasync def load() -> int:\n    return 1\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/cache.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="fresh-coroutine-function",
+                title="Each call creates a fresh coroutine",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/cache.py", "async def load() -> int:\n    return 1\n"),),
+                focus_path=PurePosixPath("app/cache.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if "async" not in context.source or context.generated or context.tree is None:
+            return []
+        shadowed = _nested_import_names(context)
+        if "*" in shadowed:
+            return []
+        diagnostics: list[Diagnostic] = []
+        for function in context.nodes(ast.AsyncFunctionDef):
+            if not function.decorator_list:
+                continue
+            decorator = function.decorator_list[-1]
+            if (
+                not _is_coroutine_cache(decorator, context.imports, shadowed)
+                or _has_own_yield(function)
+                or is_suppressed(context.source_lines, decorator.lineno, self.code)
+            ):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=context.path,
+                    line=decorator.lineno,
+                    col=decorator.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "Standard library cache retains a single-use coroutine; remove it or use an async-aware "
+                        "cache that stores awaited results."
+                    ),
+                    severity=Severity.WARNING,
+                ),
+            )
+        return diagnostics
+
+
+def _nested_import_names(context: PythonFileContext) -> frozenset[str]:
+    return frozenset(
+        alias.asname or alias.name.partition(".")[0]
+        for node in context.nodes(ast.Import, ast.ImportFrom)
+        for alias in node.names
+        if context.parents[node] is not context.tree
+        or (isinstance(node, ast.ImportFrom) and node.level > 0)
+        or alias.name == "*"
+    )
+
+
+def _is_coroutine_cache(decorator: ast.expr, imports: ImportIndex, shadowed: frozenset[str]) -> bool:
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    root = target
+    while isinstance(root, ast.Attribute):
+        root = root.value
+    if isinstance(root, ast.Name) and root.id in shadowed:
+        return False
+    symbol = imports.resolved_symbol(target, sources=_FUNCTOOLS)
+    if symbol not in _COROUTINE_CACHES:
+        return False
+    if not isinstance(decorator, ast.Call):
+        return True
+    if symbol != "lru_cache" or any(keyword.arg is None for keyword in decorator.keywords):
+        return False
+    if len(decorator.args) > _LRU_CACHE_POSITIONAL_ARGUMENTS or any(
+        isinstance(argument, ast.Starred) for argument in decorator.args
+    ):
+        return False
+    sizes = [keyword.value for keyword in decorator.keywords if keyword.arg == "maxsize"]
+    if decorator.args:
+        sizes.append(decorator.args[0])
+    if not sizes:
+        return True
+    if len(sizes) != 1:
+        return False
+    match sizes[0]:
+        case ast.Constant(value=None):
+            return True
+        case ast.Constant(value=int() as size) | ast.UnaryOp(op=ast.UAdd(), operand=ast.Constant(value=int() as size)):
+            return size > 0
+        case _:
+            return False
+
+
+def _has_own_yield(function: ast.AsyncFunctionDef) -> bool:
+    pending: list[ast.AST] = list(function.body)
+    while pending:
+        match pending.pop():
+            case ast.Yield() | ast.YieldFrom():
+                return True
+            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.Lambda() as definition:
+                pending.extend(definition.args.defaults)
+                pending.extend(default for default in definition.args.kw_defaults if default is not None)
+                if not isinstance(definition, ast.Lambda):
+                    pending.extend(definition.decorator_list)
+            case ast.ClassDef() as definition:
+                pending.extend(definition.bases)
+                pending.extend(keyword.value for keyword in definition.keywords)
+                pending.extend(definition.decorator_list)
+            case node:
+                pending.extend(children(node))
+    return False

sarj_python_lint-1.38.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.1/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