sarj-python-lint 1.25.3__tar.gz → 1.25.5__tar.gz

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/PKG-INFO

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

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

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/__main__.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import ast
 from collections import Counter
+from contextlib import suppress
 from dataclasses import dataclass
 from fnmatch import fnmatch
 import json
@@ -16,6 +17,7 @@ from sarj_python_lint import __version__
 from sarj_python_lint._analysis_session import AnalysisSession
 from sarj_python_lint._file_context import PythonFileContext
 from sarj_python_lint._filesystem import atomic_write_text
+from sarj_python_lint._source import read_python_source
 from sarj_python_lint.json_boundary import is_object_mapping, parse_json
 from sarj_python_lint.rule_base import Diagnostic, ProjectRule, Rule, Severity, is_suppressed
 from sarj_python_lint.rules import REGISTRY
@@ -110,7 +112,7 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     loaded: dict[Path, str] = {}
     for path in expanded:
         try:
-            loaded[path] = path.read_text(encoding="utf-8", errors="replace")
+            loaded[path] = read_python_source(path)
         except OSError:
             continue
     project_rules = [rule for rule in rules if isinstance(rule, ProjectRule)]
@@ -138,6 +140,7 @@ def check_source(
             if diagnostic.code == "SARJ419" or not is_suppressed(source_lines, diagnostic.line, diagnostic.code)
         ],
         source=source,
+        context=context,
     )
 
 
@@ -187,21 +190,27 @@ class _OwnerLocation(NamedTuple):
     column: int
 
 
-def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = None) -> list[Diagnostic]:
-    diags = _deduplicate_test_composition(diags, source)
+def deduplicate_diagnostics(
+    diags: list[Diagnostic], *, source: str | None = None, context: PythonFileContext | None = None
+) -> list[Diagnostic]:
     codes = frozenset(diagnostic.code for diagnostic in diags)
     needs_docstring_owners = ("SARJ092" in codes and not codes.isdisjoint(_DIAGNOSTIC_PRECEDENCE["SARJ092"])) or (
         "SARJ420" in codes and not codes.isdisjoint(_DOCSTRING_PRECEDENCE_CODES)
     )
-    docstring_owners = _docstring_owner_locations(source) if source is not None and needs_docstring_owners else {}
     needs_signature_owners = (
         ("SARJ093" in codes and "SARJ034" in codes)
         or ("SARJ447" in codes and "SARJ008" in codes)
         or ("SARJ094" in codes and not codes.isdisjoint(_DIAGNOSTIC_PRECEDENCE["SARJ094"]))
     )
-    signature_owners = (
-        _function_signature_owner_locations(source) if source is not None and needs_signature_owners else {}
+    needs_composition_owners = {"SARJ066", "SARJ457"} <= codes
+    tree = (
+        _diagnostic_owner_tree(source, context)
+        if needs_docstring_owners or needs_signature_owners or needs_composition_owners
+        else None
     )
+    diags = _deduplicate_test_composition(diags, tree)
+    docstring_owners = _docstring_owner_locations(tree) if needs_docstring_owners else {}
+    signature_owners = _function_signature_owner_locations(tree) if needs_signature_owners else {}
 
     def owner_location(diagnostic: Diagnostic) -> _OwnerLocation:
         if diagnostic.code in {"SARJ008", "SARJ034", "SARJ093", "SARJ094", "SARJ447"}:
@@ -236,13 +245,19 @@ def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = Non
     ]
 
 
-def _deduplicate_test_composition(diags: list[Diagnostic], source: str | None) -> list[Diagnostic]:
+def _diagnostic_owner_tree(source: str | None, context: PythonFileContext | None) -> ast.Module | None:
+    if source is None:
+        return None
+    if context is not None and context.source == source:
+        return context.tree
+    with suppress(SyntaxError):
+        return ast.parse(source)
+    return None
+
+
+def _deduplicate_test_composition(diags: list[Diagnostic], tree: ast.Module | None) -> list[Diagnostic]:
     codes = {diagnostic.code for diagnostic in diags}
-    if source is None or not {"SARJ066", "SARJ457"} <= codes:
-        return diags
-    try:
-        tree = ast.parse(source)
-    except SyntaxError:
+    if tree is None or not {"SARJ066", "SARJ457"} <= codes:
         return diags
     whole_tests = {
         (diagnostic.path, diagnostic.line): diagnostic.severity for diagnostic in diags if diagnostic.code == "SARJ066"
@@ -312,10 +327,8 @@ def _typed_docstring_warning_is_superseded(codes: dict[str, set[Severity]]) -> b
     return any(Severity.ERROR in codes.get(generic, set()) for generic in ("SARJ086", "SARJ087"))
 
 
-def _function_signature_owner_locations(source: str) -> dict[int, _OwnerLocation]:
-    try:
-        tree = ast.parse(source)
-    except SyntaxError:
+def _function_signature_owner_locations(tree: ast.Module | None) -> dict[int, _OwnerLocation]:
+    if tree is None:
         return {}
     owners: dict[int, _OwnerLocation] = {}
     for node in ast.walk(tree):
@@ -327,11 +340,7 @@ def _function_signature_owner_locations(source: str) -> dict[int, _OwnerLocation
     return owners
 
 
-def _docstring_owner_locations(source: str) -> dict[int, _OwnerLocation]:
-    try:
-        tree = ast.parse(source)
-    except SyntaxError:
-        tree = None
+def _docstring_owner_locations(tree: ast.Module | None) -> dict[int, _OwnerLocation]:
     if tree is None:
         return {}
     owners: dict[int, _OwnerLocation] = {}

sarj_python_lint-1.25.5/src/sarj_python_lint/_source.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+PYTHON_SOURCE_ENCODING: Final = "utf-8-sig"
+
+
+def read_python_source(path: Path) -> str:
+    return path.read_text(encoding=PYTHON_SOURCE_ENCODING, errors="replace")

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/ratchet.py

@@ -9,6 +9,7 @@ import tokenize
 from types import MappingProxyType
 from typing import TYPE_CHECKING, Final, NamedTuple, TypeGuard
 
+from sarj_python_lint._source import PYTHON_SOURCE_ENCODING
 from sarj_python_lint.json_boundary import is_object_mapping, parse_json
 
 
@@ -329,7 +330,7 @@ def _python_files(root: Path, excluded_dir_names: frozenset[str]) -> Iterator[Pa
 
 def _read(path: Path) -> str:
     try:
-        return path.read_text(encoding="utf-8")
+        return path.read_text(encoding=PYTHON_SOURCE_ENCODING)
     except UnicodeDecodeError, OSError:
         return ""
 

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/_fastapi.py

@@ -5,6 +5,7 @@ from collections import Counter
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Literal, NamedTuple
 
+from sarj_python_lint._source import read_python_source
 from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._imports import ImportIndex
 
@@ -839,7 +840,7 @@ def _read_module(path: Path, cache: dict[Path, ast.Module | None]) -> ast.Module
         if path.stat().st_size > _MAX_IMPORTED_MODULE_BYTES:
             tree = None
         else:
-            tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"), filename=str(path))
+            tree = ast.parse(read_python_source(path), filename=str(path))
     except OSError, SyntaxError:
         tree = None
     cache[path] = tree

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/_local_source.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, final
 
+from sarj_python_lint._source import PYTHON_SOURCE_ENCODING
 from sarj_python_lint.rules._imports import ImportIndex
 
 
@@ -113,7 +114,7 @@ def _read_module(path: Path) -> LocalModule | None:
             data = stream.read(_MAX_MODULE_BYTES + 1)
         if len(data) > _MAX_MODULE_BYTES:
             return None
-        source = data.decode("utf-8")
+        source = data.decode(PYTHON_SOURCE_ENCODING)
         tree = ast.parse(source, filename=str(path))
     except OSError, UnicodeError, SyntaxError:
         return None

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/_nominal_project.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, TypeGuard, final
 from packaging.requirements import InvalidRequirement, Requirement
 from packaging.utils import canonicalize_name
 
+from sarj_python_lint._source import PYTHON_SOURCE_ENCODING
 from sarj_python_lint.rules._first_party import distribution_root
 from sarj_python_lint.rules._imports import ImportIndex
 from sarj_python_lint.rules._paths import is_generated
@@ -264,7 +265,7 @@ def _source(path: Path) -> NominalSource | None:
     try:
         if path.is_symlink() or path.stat().st_size > _MAX_BYTES:
             return None
-        text = path.read_text(encoding="utf-8")
+        text = path.read_text(encoding=PYTHON_SOURCE_ENCODING)
         if is_generated(path, text):
             return None
     except OSError, UnicodeError:

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/_project_index.py

@@ -11,6 +11,7 @@ import re
 from types import MappingProxyType
 from typing import TYPE_CHECKING, final
 
+from sarj_python_lint._source import read_python_source
 from sarj_python_lint.rules._ast_index import walk as walk_ast
 from sarj_python_lint.rules._first_party import FirstPartyFacts, project_root
 from sarj_python_lint.rules._paths import is_generated
@@ -532,7 +533,7 @@ def _read_bounded_source(root: Path, path: Path) -> LoadedSource | None:
             return None
         resolved = path.resolve()
         resolved.relative_to(root.resolve())
-        return LoadedSource(resolved, resolved.read_text(encoding="utf-8", errors="replace"))
+        return LoadedSource(resolved, read_python_source(resolved))
     except OSError, ValueError:
         return None
 

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/invalid_pydantic_field_default.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, NamedTuple, final, override
 
+from sarj_python_lint._source import read_python_source
 from sarj_python_lint.rule_base import (
     AutofixPolicy,
     Diagnostic,
@@ -688,7 +689,7 @@ def _read_module(path: Path) -> ast.Module | None:
     try:
         if path.stat().st_size > _MAX_IMPORTED_MODULE_BYTES:
             return None
-        tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"), filename=str(path))
+        tree = ast.parse(read_python_source(path), filename=str(path))
     except OSError, SyntaxError:
         return None
     return tree

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/no_hidden_constructor_fallback.py

@@ -7,6 +7,7 @@ import os
 from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, ClassVar, NamedTuple, final, override
 
+from sarj_python_lint._source import read_python_source
 from sarj_python_lint.rule_base import (
     Diagnostic,
     ExampleFile,
@@ -718,7 +719,7 @@ def _read_module(path: Path, facts: RuntimeConfigFacts) -> ast.Module:
     if cached is not None:
         return cached
     try:
-        tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"), filename=str(path))
+        tree = ast.parse(read_python_source(path), filename=str(path))
     except OSError, SyntaxError:
         tree = ast.Module(body=[], type_ignores=[])
     facts.modules[path] = tree
@@ -781,7 +782,7 @@ def _candidate_calls_class(
     if is_test_path(candidate):
         return False
     try:
-        source = candidate.read_text(encoding="utf-8", errors="replace")
+        source = read_python_source(candidate)
     except OSError:
         return False
     if class_name not in source or is_generated(candidate, source):

{sarj_python_lint-1.25.3 → sarj_python_lint-1.25.5}/src/sarj_python_lint/rules/no_tautological_expect.py

@@ -15,6 +15,7 @@ from sarj_python_lint.rule_base import (
     Severity,
 )
 from sarj_python_lint.rules._ast_index import walk as walk_ast
+from sarj_python_lint.rules._paths import is_test_path
 
 
 if TYPE_CHECKING:
@@ -32,13 +33,14 @@ _FAIL = "fail"
 
 # Enough of the operand to identify it in the message without pasting a screenful.
 _OPERAND_PREVIEW_CHARS = 40
+_UNKNOWN = object()
 
 
 class NoTautologicalExpect(Rule):
     id: str = "no-statically-truthy-assertion"
     code: str = "SARJ057"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        summary="A bare assertion condition is statically truthy.",
+        summary="An assertion condition is statically truthy, including test-local scalar setup.",
         rationale=(
             "A condition that stays truthy whenever evaluation succeeds cannot reject an incorrect result and often "
             "means the intended condition was wrapped in a container or placed in the message slot."
@@ -51,10 +53,40 @@ class NoTautologicalExpect(Rule):
         aliases=("no-tautological-expect",),
         limitations=(
             "Detection covers truthy scalar constants and definitely non-empty list, set, and dict displays.",
+            "Test-local immutable scalar bindings and their aliases are tracked only through straight-line assignments; calls, control flow, mutable values, and global/nonlocal writes invalidate tracking.",
             "Ruff owns asserted strings and tuples, literal comparisons and identity, and unittest-style assertion methods.",
             "Generated files, always-failing assertions, deliberate match-arm success markers, and runtime-value comparisons are excluded.",
         ),
         examples=(
+            RuleExample(
+                example_id="setup-only-oracle",
+                scenario="setup-only",
+                title="A test asserts only on its own fixed setup",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_service.py", "def test_service():\n    status = 'ok'\n    assert status == 'ok'\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="produced-scalar-oracle",
+                scenario="setup-only",
+                title="Assert on a value returned by the application",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_service.py",
+                        "def test_service():\n    status = service_status()\n    assert status == 'ok'\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_service.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="condition-in-message-slot",
                 title="The intended condition became an assertion message",
@@ -96,6 +128,9 @@ class NoTautologicalExpect(Rule):
         if tree is None:
             return []
         exempt = _exempt_nodes(tree, node_index=context.node_index)
+        tautologies = _tautologies(tree, exempt, node_index=context.node_index)
+        if is_test_path(path) and path.name != "conftest.py":
+            tautologies.extend(_bound_tautologies(context))
         diags = [
             Diagnostic(
                 path=path,
@@ -105,12 +140,93 @@ class NoTautologicalExpect(Rule):
                 message=_message(node, reason),
                 severity=Severity.ERROR,
             )
-            for node, reason in _tautologies(tree, exempt, node_index=context.node_index)
+            for node, reason in tautologies
         ]
         diags.sort(key=lambda d: (d.line, d.col))
         return diags
 
 
+def _bound_tautologies(context: PythonFileContext) -> list[_Tautology]:
+    found: list[_Tautology] = []
+    external_writes = context.nodes(ast.Global, ast.Nonlocal)
+    for function in context.nodes(ast.FunctionDef, ast.AsyncFunctionDef):
+        if not function.name.startswith("test_"):
+            continue
+        if any(function.lineno <= node.lineno <= (function.end_lineno or function.lineno) for node in external_writes):
+            continue
+        found.extend(_function_bound_tautologies(function))
+    return found
+
+
+def _function_bound_tautologies(function: ast.FunctionDef | ast.AsyncFunctionDef) -> list[_Tautology]:
+    found: list[_Tautology] = []
+    bindings: dict[str, object] = {}
+    for statement in function.body:
+        if _record_scalar_assignment(statement, bindings):
+            continue
+        if isinstance(statement, ast.Assert):
+            references_setup = any(
+                isinstance(node, ast.Name) and node.id in bindings for node in ast.walk(statement.test)
+            )
+            if references_setup and _scalar_condition(statement.test, bindings) is True:
+                found.append(_Tautology(statement, "the condition follows only from unchanged scalar setup"))
+        bindings.clear()
+    return found
+
+
+def _record_scalar_assignment(statement: ast.stmt, bindings: dict[str, object]) -> bool:
+    match statement:
+        case (
+            ast.Assign(targets=[ast.Name(id=name)], value=value) | ast.AnnAssign(target=ast.Name(id=name), value=value)
+        ) if value is not None:
+            scalar = _scalar_value(value, bindings)
+            if scalar is not _UNKNOWN:
+                bindings[name] = scalar
+                return True
+        case _:
+            pass
+    return False
+
+
+def _scalar_value(node: ast.expr, bindings: dict[str, object]) -> object:
+    if isinstance(node, ast.Name):
+        return bindings.get(node.id, _UNKNOWN)
+    if isinstance(node, ast.Constant):
+        value: object = node.value
+        return value if value is None or isinstance(value, (bool, int, float, str, bytes)) else _UNKNOWN
+    if isinstance(node, ast.UnaryOp):
+        value = _scalar_value(node.operand, bindings)
+        if isinstance(node.op, ast.Not) and value is not _UNKNOWN:
+            return not value
+        if isinstance(value, (int, float)):
+            if isinstance(node.op, ast.USub):
+                return -value
+            if isinstance(node.op, ast.UAdd):
+                return +value
+    return _UNKNOWN
+
+
+def _scalar_condition(node: ast.expr, bindings: dict[str, object]) -> bool | None:
+    if isinstance(node, ast.Compare) and len(node.ops) == 1:
+        left = _scalar_value(node.left, bindings)
+        right = _scalar_value(node.comparators[0], bindings)
+        if left is _UNKNOWN or right is _UNKNOWN:
+            return None
+        match node.ops[0]:
+            case ast.Eq():
+                return left == right
+            case ast.NotEq():
+                return left != right
+            case ast.Is() if left is None or isinstance(left, bool):
+                return left is right
+            case ast.IsNot() if left is None or isinstance(left, bool):
+                return left is not right
+            case _:
+                return None
+    value = _scalar_value(node, bindings)
+    return None if value is _UNKNOWN else bool(value)
+
+
 def _exempt_nodes(tree: ast.Module, *, node_index: NodeIndex | None = None) -> set[ast.AST]:
     exempt: set[ast.AST] = set()
     for node in walk_ast(tree, index=node_index):