sarj-python-lint 0.21.0__tar.gz → 0.23.0__tar.gz

{sarj_python_lint-0.21.0 → sarj_python_lint-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.21.0
+Version: 0.23.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards
@@ -196,6 +196,92 @@ sarj-python-lint check --rule mock-without-spec --update-baseline test-quality-b
 sarj-python-lint check --rule mock-without-spec --baseline test-quality-baseline.json python/
 ```
 
+### Multi-tenant scoping (0.22.0)
+
+```yaml
+    - id: sarj-no-optional-tenant-predicate        # SARJ056
+```
+
+`SARJ056` fires when every WHERE-fragment mentioning a tenant column
+(`organization_id` and friends) sits inside a conditional, so the predicate
+disappears — and the query still runs — whenever the filter is empty:
+
+```python
+where_conditions = []
+if args.organization_ids:                                    # ← optional
+    where_conditions.append(SQL("organization_id = ANY(%s::uuid[])"))
+...
+where_clause = SQL(" AND ").join(where_conditions) if where_conditions else SQL("1=1")
+```
+
+The safe idiom seeds the list, so scoping always applies and the rule stays
+quiet:
+
+```python
+conditions: list[Composable] = [SQL("organization_id = %s")]
+```
+
+A function with **no** tenant predicate at all never fires — an intentionally
+cross-tenant admin query is out of scope; only *attempted-but-optional* scoping
+is a finding. Where a caller genuinely wants the all-tenant query, that
+intent belongs in an explicit method (or an inline `sarj-noqa`) rather than in
+an omitted filter.
+
+Measured before shipping: **0 findings across 26,345 files** of pydantic, trio,
+attrs, Airflow and Home Assistant — single-tenant codebases have no tenant
+column, so the rule is silent by construction — and 0 in noura-be, ai, kpi-hub
+and demo-gateway. In bulbul it finds 10 sites, all genuine fail-open
+compositions, two of which were reachable cross-tenant reads at the time of
+writing (`POST /v1/calls/list` and `POST /v1/calls/batch/list`, both of which
+composed `WHERE 1=1` for a user whose `organization_id` was NULL).
+
+### Assertions that can never fail (0.23.0)
+
+```yaml
+    - id: sarj-no-tautological-expect              # SARJ057
+```
+
+`SARJ057` fires when an assertion's operands are all literals, so its outcome is
+fixed before the code runs. `SARJ043` already catches the test with *no*
+assertion; this is the test whose assertion is decorative.
+
+The placeholder spelling (`assert True`) is the obvious half. The expensive half
+is the assertion whose real condition slid out of the condition slot, because it
+was a working assertion when it was typed:
+
+```python
+assert {                                              # ← braces, not parentheses
+    "referencing a non existing `via_device` " in caplog.text
+}                                                     # one-element SET, always truthy
+
+assert [f"No logs found on hdfs for ti={ti}"]         # the `== messages` was lost
+assert True, cover_result_json[0]["success"][...]     # slid into the MESSAGE slot
+```
+
+**The narrowness is the rule.** The obvious generalisation — "flag a comparison
+of a thing with itself" — measures ~95% false positives: `assert i == i`,
+`assert x is x`, `expect(hash([o])).toEqual(hash([o]))` are reflexivity,
+determinism and memoization tests, and for a type with custom `__eq__`/`__hash__`
+they can genuinely fail. So an identifier, attribute or call operand is never
+enough; both sides must be literals, and textually identical ones. `assert True`
+as the sole statement of an `except` handler is exempt — it asserts *which branch
+ran* — as is anything inside a pytest-benchmark test.
+
+Measured before shipping: **4 findings across 28,608 files** — 26,346 of
+pydantic, trio, attrs, Airflow and Home Assistant plus 2,262 first-party files
+in bulbul, noura-be, kpi-hub, ai and demo-gateway. All 4 are true positives
+(Home Assistant `tests/helpers/test_device_registry.py:3711` and `:3777`,
+`tests/components/emulated_hue/test_hue_api.py:1078`, Airflow
+`providers/apache/hdfs/.../log/test_hdfs_task_handler.py:170`); 0 false
+positives. The two `except ...: assert True` markers that a carve-out-free
+version does flag — `pydantic-core/tests/benchmarks/test_micro_benchmarks.py:716`
+and `core/tests/components/mqtt/test_client.py:1353` — were verified silent.
+
+The TypeScript half of the same rule ships as `@sarj/no-tautological-expect` in
+`@sarj/eslint-plugin` ≥ 2.14.0; until now there was no TS counterpart at all,
+which is how `expect(true).toBe(true); // placeholder` survived in a suite named
+for the behaviour it was supposed to check.
+
 ## CLI
 
 ```bash

{sarj_python_lint-0.21.0 → sarj_python_lint-0.23.0}/README.md

@@ -178,6 +178,92 @@ sarj-python-lint check --rule mock-without-spec --update-baseline test-quality-b
 sarj-python-lint check --rule mock-without-spec --baseline test-quality-baseline.json python/
 ```
 
+### Multi-tenant scoping (0.22.0)
+
+```yaml
+    - id: sarj-no-optional-tenant-predicate        # SARJ056
+```
+
+`SARJ056` fires when every WHERE-fragment mentioning a tenant column
+(`organization_id` and friends) sits inside a conditional, so the predicate
+disappears — and the query still runs — whenever the filter is empty:
+
+```python
+where_conditions = []
+if args.organization_ids:                                    # ← optional
+    where_conditions.append(SQL("organization_id = ANY(%s::uuid[])"))
+...
+where_clause = SQL(" AND ").join(where_conditions) if where_conditions else SQL("1=1")
+```
+
+The safe idiom seeds the list, so scoping always applies and the rule stays
+quiet:
+
+```python
+conditions: list[Composable] = [SQL("organization_id = %s")]
+```
+
+A function with **no** tenant predicate at all never fires — an intentionally
+cross-tenant admin query is out of scope; only *attempted-but-optional* scoping
+is a finding. Where a caller genuinely wants the all-tenant query, that
+intent belongs in an explicit method (or an inline `sarj-noqa`) rather than in
+an omitted filter.
+
+Measured before shipping: **0 findings across 26,345 files** of pydantic, trio,
+attrs, Airflow and Home Assistant — single-tenant codebases have no tenant
+column, so the rule is silent by construction — and 0 in noura-be, ai, kpi-hub
+and demo-gateway. In bulbul it finds 10 sites, all genuine fail-open
+compositions, two of which were reachable cross-tenant reads at the time of
+writing (`POST /v1/calls/list` and `POST /v1/calls/batch/list`, both of which
+composed `WHERE 1=1` for a user whose `organization_id` was NULL).
+
+### Assertions that can never fail (0.23.0)
+
+```yaml
+    - id: sarj-no-tautological-expect              # SARJ057
+```
+
+`SARJ057` fires when an assertion's operands are all literals, so its outcome is
+fixed before the code runs. `SARJ043` already catches the test with *no*
+assertion; this is the test whose assertion is decorative.
+
+The placeholder spelling (`assert True`) is the obvious half. The expensive half
+is the assertion whose real condition slid out of the condition slot, because it
+was a working assertion when it was typed:
+
+```python
+assert {                                              # ← braces, not parentheses
+    "referencing a non existing `via_device` " in caplog.text
+}                                                     # one-element SET, always truthy
+
+assert [f"No logs found on hdfs for ti={ti}"]         # the `== messages` was lost
+assert True, cover_result_json[0]["success"][...]     # slid into the MESSAGE slot
+```
+
+**The narrowness is the rule.** The obvious generalisation — "flag a comparison
+of a thing with itself" — measures ~95% false positives: `assert i == i`,
+`assert x is x`, `expect(hash([o])).toEqual(hash([o]))` are reflexivity,
+determinism and memoization tests, and for a type with custom `__eq__`/`__hash__`
+they can genuinely fail. So an identifier, attribute or call operand is never
+enough; both sides must be literals, and textually identical ones. `assert True`
+as the sole statement of an `except` handler is exempt — it asserts *which branch
+ran* — as is anything inside a pytest-benchmark test.
+
+Measured before shipping: **4 findings across 28,608 files** — 26,346 of
+pydantic, trio, attrs, Airflow and Home Assistant plus 2,262 first-party files
+in bulbul, noura-be, kpi-hub, ai and demo-gateway. All 4 are true positives
+(Home Assistant `tests/helpers/test_device_registry.py:3711` and `:3777`,
+`tests/components/emulated_hue/test_hue_api.py:1078`, Airflow
+`providers/apache/hdfs/.../log/test_hdfs_task_handler.py:170`); 0 false
+positives. The two `except ...: assert True` markers that a carve-out-free
+version does flag — `pydantic-core/tests/benchmarks/test_micro_benchmarks.py:716`
+and `core/tests/components/mqtt/test_client.py:1353` — were verified silent.
+
+The TypeScript half of the same rule ships as `@sarj/no-tautological-expect` in
+`@sarj/eslint-plugin` ≥ 2.14.0; until now there was no TS counterpart at all,
+which is how `expect(true).toBe(true); // placeholder` survived in a suite named
+for the behaviour it was supposed to check.
+
 ## CLI
 
 ```bash

{sarj_python_lint-0.21.0 → sarj_python_lint-0.23.0}/pyproject.toml

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

sarj_python_lint-0.23.0/src/sarj_python_lint/rules/_pytest.py

@@ -0,0 +1,61 @@
+"""Shared pytest-shape predicates for the assertion-quality rules.
+
+A pytest-benchmark test measures wall-clock time; verifying is not its job, and
+every rule that judges a test's assertions needs the same carve-out for it —
+SARJ043 (`zero-assertion-test`) because a benchmark asserts nothing, SARJ057
+(`no-tautological-expect`) because the idiomatic way to benchmark a *failing*
+path is `try: ...; assert False; except Err: assert True` inside the timed
+callable. Keeping the predicate in one module is what stops the two copies from
+drifting apart.
+"""
+
+from __future__ import annotations
+
+import ast
+
+
+# The pytest-benchmark fixture: the test measures time, it does not verify.
+_BENCHMARK = "benchmark"
+
+
+def uses_benchmark_fixture(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """Report whether `node` both declares and uses the pytest-benchmark fixture.
+
+    `def test_x(benchmark)` then `benchmark(fn, arg)` or `@benchmark` on a nested
+    function. The fixture times the callable; a benchmark that asserted on the
+    result would be measuring the assertion. Requiring the name to be *used*, not
+    just declared, keeps an unrelated parameter that happens to be called
+    `benchmark` from silencing the rule.
+
+    Returns:
+        True when the function is a pytest-benchmark test.
+
+    """
+    args = node.args
+    declared = any(arg.arg == _BENCHMARK for arg in (*args.posonlyargs, *args.args, *args.kwonlyargs))
+    return declared and any(isinstance(child, ast.Name) and child.id == _BENCHMARK for child in ast.walk(node))
+
+
+def has_benchmark_marker(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """Report whether `node` carries `@pytest.mark.benchmark`, called or bare.
+
+    The marker form is the other half of pytest-benchmark's surface: a test can
+    take the fixture, wear the marker, or both.
+
+    Returns:
+        True when a `pytest.mark.benchmark` decorator is present.
+
+    """
+    return any(_decorator_attr(dec) == _BENCHMARK for dec in node.decorator_list)
+
+
+def _decorator_attr(dec: ast.expr) -> str | None:
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    if not isinstance(target, ast.Attribute):
+        return None
+    # Only `*.mark.<name>`, so a `@benchmark.something` helper is not mistaken
+    # for a pytest marker.
+    parent = target.value
+    if isinstance(parent, ast.Attribute) and parent.attr == "mark":
+        return target.attr
+    return None

{sarj_python_lint-0.21.0 → sarj_python_lint-0.23.0}/src/sarj_python_lint/rules/_registry.py

@@ -26,6 +26,9 @@ from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_gen_random_uuid_in_sql import NoGenRandomUuidInSql
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
+from sarj_python_lint.rules.no_optional_tenant_predicate import (
+    NoOptionalTenantPredicate,
+)
 from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
 from sarj_python_lint.rules.no_raw_sql_in_tests import NoRawSqlInTests
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
@@ -36,6 +39,7 @@ from sarj_python_lint.rules.no_sentinel_return_on_except import NoSentinelReturn
 from sarj_python_lint.rules.no_sequential_await import NoSequentialAwait
 from sarj_python_lint.rules.no_sleep_in_test_body import NoSleepInTestBody
 from sarj_python_lint.rules.no_stdlib_logging import NoStdlibLogging
+from sarj_python_lint.rules.no_tautological_expect import NoTautologicalExpect
 from sarj_python_lint.rules.no_unreachable_after_terminal import (
     NoUnreachableAfterTerminal,
 )
@@ -83,6 +87,19 @@ if TYPE_CHECKING:
 #   SARJ027, SARJ029, SARJ030 (dropped in 0.11.1 as too noisy),
 #   SARJ033 httpx-client-requires-timeout, SARJ035 no-import-time-settings
 #   (dropped by user veto after the 0.13.x mined-rules review),
+#   SARJ055 no-filler-success-adverb (built and corpus-validated, then dropped
+#   — but not for the reason first recorded. The headline "4.7% of Airflow's
+#   info/debug logs" is a composition artifact: 237 of those 248 hits are in
+#   `providers/` (contributed vendor operators, heavily copy-pasted — the
+#   template "%s completed successfully." appears 22 times verbatim). Airflow's
+#   maintainer-owned `airflow-core/` sits at 1.15% and Home Assistant at 1.24%,
+#   so the real external baseline is ~1.2%, not 4.7%. The rule was re-measured
+#   and dropped on a stronger basis: the narrow variant — fire only when the
+#   adverb is the sole content beyond a bare verb — has 12 external hits and
+#   ZERO internal ones across all six repos, so it would govern nothing we
+#   write. The broad rule remains opt-in house style, not a defect check.
+#   (Noted for any future revisit: noura-be measures 7.92%, a genuine outlier
+#   against every corpus; that, not the narrow variant, is the case to make.),
 #   SARJ037 no-trivial-single-use-helper (prototyped and dropped for FP rate;
 #   see the 0.13.1 inlining commit for the corpus analysis).
 REGISTRY: dict[str, type[Rule]] = {
@@ -132,6 +149,8 @@ REGISTRY: dict[str, type[Rule]] = {
     NoStdlibLogging.id: NoStdlibLogging,
     NoGenRandomUuidInSql.id: NoGenRandomUuidInSql,
     NoFileLevelEscapeHatchNoqa.id: NoFileLevelEscapeHatchNoqa,
+    NoOptionalTenantPredicate.id: NoOptionalTenantPredicate,
+    NoTautologicalExpect.id: NoTautologicalExpect,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.23.0/src/sarj_python_lint/rules/no_optional_tenant_predicate.py

@@ -0,0 +1,192 @@
+"""SARJ056: a tenant predicate that only appears inside a conditional branch.
+
+Multi-tenant stores compose a WHERE clause by accumulating fragments in a list::
+
+    where_conditions: list[Composable] = []
+    if args.organization_ids:
+        where_conditions.append(SQL("organization_id = ANY(%s::uuid[])"))
+    if args.status:
+        where_conditions.append(SQL("status = ANY(%s)"))
+    where_clause = SQL(" AND ").join(where_conditions) if where_conditions else SQL("1=1")
+
+When the tenant fragment is the *only* thing standing between a caller and every
+other tenant's rows, guarding it with `if` makes the scoping **fail open**: the
+query still executes, just without the predicate. A caller that passes an empty
+or missing organization list silently reads the whole table.
+
+This is not hypothetical. In bulbul, `PsqlCallStore._build_filter_conditions`
+had exactly this shape, and `POST /v1/calls/list` reached it with
+`organization_ids=[]` for any user whose `organization_id` was NULL — composing
+`SELECT ... FROM call WHERE 1=1`, i.e. every tenant's calls.
+
+The rule fires when, within a single function, *every* WHERE-fragment that
+mentions a tenant column is nested inside a conditional. The safe idiom seeds
+the fragment list with the tenant predicate unconditionally::
+
+    conditions: list[Composable] = [SQL("organization_id = %s")]   # always applied
+
+so that form never fires. A function with no tenant fragment at all does not
+fire either — an intentionally cross-tenant admin query is not this rule's
+business; only *attempted-but-optional* scoping is.
+
+Scope note: only fragments participating in list composition (a list literal, or
+an argument to `.append()` / `.extend()`) are considered, so an unrelated inline
+`WHERE organization_id = %s` elsewhere in the same function neither triggers nor
+masks a finding.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._paths import is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# Columns that scope a row to a tenant. `org_id` is included because bulbul's
+# older stores use it; `tenant_id`/`account_id`/`workspace_id` are the common
+# names the same pattern takes in other multi-tenant codebases.
+_TENANT_COLUMNS = ("organization_id", "org_id", "tenant_id", "account_id", "workspace_id")
+
+# A fragment is a predicate (not a bare column name in a SELECT list) when the
+# tenant column is followed by a comparison. `= %s`, `= ANY(...)`, `IN (...)`,
+# `= {}` (psycopg SQL.format) and `<>` all count.
+_TENANT_PREDICATE_RE = re.compile(
+    r"\b(?:\w+\.)?(?:" + "|".join(_TENANT_COLUMNS) + r")\b\s*(?:=|<>|!=|\bIN\b|\bIS\b)",
+    re.IGNORECASE,
+)
+
+_CONDITIONAL_NODES = (ast.If, ast.IfExp)
+
+
+class NoOptionalTenantPredicate(Rule):
+    """Tenant scoping that disappears when a filter is absent."""
+
+    id: str = "no-optional-tenant-predicate"
+    code: str = "SARJ056"
+    description: str = (
+        "A tenant predicate reachable only inside a conditional makes tenant scoping fail open — "
+        "the query still runs, unscoped, when the filter is absent."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path):
+            return []
+        # A file with no tenant column anywhere cannot produce a finding, and
+        # that is the overwhelming majority of files. Skipping the AST walk
+        # here keeps the rule off the critical path of every unrelated file.
+        if not any(column in source for column in _TENANT_COLUMNS):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        diags: list[Diagnostic] = []
+        for func in _iter_functions(tree):
+            fragments = _tenant_fragments(func)
+            if not fragments:
+                continue
+            if any(not conditional for _, conditional in fragments):
+                # At least one unconditional tenant predicate — scoping always applies.
+                continue
+            node = fragments[0][0]
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"tenant predicate in `{func.name}` is only added inside a conditional, so the "
+                        "query runs unscoped when the filter is empty or missing. Seed the condition "
+                        "list with the tenant predicate unconditionally, or require the tenant id."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _iter_functions(tree: ast.Module) -> list[ast.FunctionDef | ast.AsyncFunctionDef]:
+    """Collect every function and method in the module.
+
+    Returns:
+        All `FunctionDef`/`AsyncFunctionDef` nodes, outermost first.
+
+    """
+    return [n for n in ast.walk(tree) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+
+
+def _tenant_fragments(func: ast.FunctionDef | ast.AsyncFunctionDef) -> list[tuple[ast.expr, bool]]:
+    """Find WHERE-fragments in `func` that carry a tenant predicate.
+
+    Only fragments taking part in list composition count: elements of a list
+    literal, or arguments to `.append()` / `.extend()`. Each is paired with
+    whether it sits inside a conditional *within this function*.
+
+    One recursive pass carries the "am I under an `If`/`IfExp`?" flag down the
+    tree, so the cost is linear in the function's node count.
+
+    Returns:
+        `(node, is_conditional)` pairs in source order.
+
+    """
+    found: list[tuple[ast.expr, bool]] = []
+
+    def visit(node: ast.AST, *, conditional: bool) -> None:
+        # An `IfExp` fragment guards the predicate inside itself:
+        # `c.append(SQL("organization_id = %s") if org else SQL("TRUE"))`.
+        found.extend(
+            (fragment, conditional or isinstance(fragment, ast.IfExp))
+            for fragment in _composition_fragments(node)
+            if _mentions_tenant_predicate(fragment)
+        )
+        nested = conditional or isinstance(node, _CONDITIONAL_NODES)
+        for child in ast.iter_child_nodes(node):
+            visit(child, conditional=nested)
+
+    for child in ast.iter_child_nodes(func):
+        visit(child, conditional=False)
+    found.sort(key=lambda pair: (pair[0].lineno, pair[0].col_offset))
+    return found
+
+
+def _composition_fragments(node: ast.AST) -> list[ast.expr]:
+    """Yield the expressions `node` itself accumulates into a WHERE-fragment list.
+
+    Shallow by design — the caller recurses — so each node is inspected once.
+
+    Returns:
+        List-literal elements, or `.append()`/`.extend()` arguments.
+
+    """
+    if isinstance(node, ast.List):
+        return list(node.elts)
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr in {"append", "extend"}:
+        return list(node.args)
+    return []
+
+
+def _mentions_tenant_predicate(node: ast.expr) -> bool:
+    """Report whether `node`'s subtree contains a tenant-column predicate string.
+
+    Walking the subtree catches `SQL("organization_id = %s")` and the
+    `SQL("...").format(...)` form alike.
+
+    Returns:
+        True when a tenant predicate literal appears in the subtree.
+
+    """
+    return any(
+        isinstance(child, ast.Constant)
+        and isinstance(child.value, str)
+        and _TENANT_PREDICATE_RE.search(child.value) is not None
+        for child in ast.walk(node)
+    )

sarj_python_lint-0.23.0/src/sarj_python_lint/rules/no_tautological_expect.py

@@ -0,0 +1,374 @@
+"""SARJ057: an assertion whose outcome is decided by the literal it was handed.
+
+`assert True`, `assert ["..."]`, `self.assertEqual(1, 1)` — the condition
+contains no value the code under test produced, so the assertion passes before
+the program runs. It is not a weak test, it is a *non*-test: deleting the
+function under test entirely would not change the result.
+
+Two shapes dominate, and neither looks wrong at a glance:
+
+* **the placeholder that was never replaced** — `expect(true).toBe(true)` in
+  TypeScript, `assert True` in Python, left behind when a test file was
+  scaffolded and the body never written;
+* **the assertion whose real condition slid out of the condition slot.** This is
+  the dangerous one, because it was a working assertion when it was typed. Home
+  Assistant has the same six-line condition twice in
+  `tests/helpers/test_device_registry.py` (:3711, :3777), wrapped in braces
+  rather than parentheses::
+
+      assert {
+          "calls `device_registry.async_get_or_create` "
+          "referencing a non existing `via_device` " in caplog.text
+      }
+
+  The braces make it a one-element **set display**, which is truthy whatever the
+  `in` test inside it evaluates to. Airflow has the list-literal spelling in
+  `providers/apache/hdfs/.../log/test_hdfs_task_handler.py:170`,
+  `assert [f"No logs found on hdfs for ti={ti}"]`, where the `== messages` was
+  lost. And Home Assistant's `emulated_hue/test_hue_api.py:1078` shows the third
+  variant, where the value slid into the assertion-*message* slot:
+  `assert True, cover_result_json[0]["success"][...]` — a `KeyError` there would
+  still be raised, so it half-works, which is why it survived review.
+
+Fires on exactly four shapes, all of them syntactically decidable:
+
+1. `assert <always-truthy literal>` — `True`, a nonzero number, a non-empty
+   string, or a non-empty list/set/dict/tuple **display**;
+2. `assert <literal> == <textually identical literal>` (and `is`);
+3. `assertTrue(<truthy literal>)` / `assertFalse(<falsy literal>)`;
+4. `assertEqual(<literal>, <textually identical literal>)` (and `assertIs`).
+
+**The narrowness is the rule.** The obvious generalisation — "flag a comparison
+of a thing with itself" — was measured and is ~95% false positives.
+`assert i == i`, `assert x is x`, `expect(hash([o])).toEqual(hash([o]))` are
+*reflexivity, determinism and memoization* tests: for a type with a custom
+`__eq__` or `__hash__`, `x == x` is precisely the property under test and can
+genuinely fail. So an operand that is an identifier, an attribute or a call is
+never enough; both sides must be literals, and textually identical ones.
+
+Deliberately NOT flagged:
+
+* **`assert True` as the sole statement of an `except` handler** — the
+  deliberate "reaching here is the acceptable outcome" marker, the mirror image
+  of the `assert False` that precedes it in the `try`. It reads as a tautology
+  in isolation and is a real assertion in context: it asserts *which branch ran*.
+  Both known Python false positives are this shape —
+  `pydantic-core/tests/benchmarks/test_micro_benchmarks.py:716` and
+  `core/tests/components/mqtt/test_client.py:1353`;
+* **anything inside a pytest-benchmark test**, whether it takes the `benchmark`
+  fixture or wears `@pytest.mark.benchmark` — the same carve-out SARJ043 needs,
+  shared through `_pytest.py`. The try/`assert False`/except/`assert True`
+  sandwich above is the idiomatic way to time a *failing* validation path;
+* `assert False` — the standard unreachable-branch marker, and an assertion that
+  always fails is a loud problem, not a silent one;
+* an empty container (`assert []`), which is always *falsy* — that is a failing
+  assertion, again loud;
+* a container display with a `*splat` or `**unpack` element (`assert [*items]`),
+  whose emptiness depends on the runtime value;
+* an f-string, whose truth depends on the interpolated values.
+
+Measured before shipping: **4 findings across 28,608 files** — 26,346 of
+pydantic, trio, attrs, Airflow and Home Assistant plus 2,262 first-party files
+in bulbul, noura-be, kpi-hub, ai and demo-gateway. All 4 are the true positives
+named above; 0 false positives. The `except`/benchmark carve-outs are
+load-bearing rather than defensive: with `_exempt_nodes` neutered the sweep
+gains exactly the two known false positives and nothing else.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._pytest import has_benchmark_marker, uses_benchmark_fixture
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+# unittest methods whose single argument fixes the outcome on its own.
+_TRUTHY_ARG_METHODS = frozenset({"assertTrue"})
+_FALSY_ARG_METHODS = frozenset({"assertFalse"})
+
+# unittest methods that compare two operands for sameness.
+_EQUALITY_METHODS = frozenset({"assertEqual", "assertEquals", "assertIs"})
+
+# unittest's failure-text parameter — present or not, the outcome is the same.
+_UNITTEST_MSG_KWARG = "msg"
+
+# `assertEqual(first, second)` and friends: the two operands compared.
+_EQUALITY_ARITY = 2
+
+# Comparison operators whose two-identical-literals form is a tautology. `<=`
+# and `>=` are too, but nobody writes them by accident; `!=`/`is not` on
+# identical literals always *fails*, which is loud rather than silent.
+_SAMENESS_OPS = (ast.Eq, ast.Is)
+
+# Enough of the operand to identify it in the message without pasting a screenful.
+_OPERAND_PREVIEW_CHARS = 40
+
+_CONTAINER_KINDS: dict[type[ast.expr], str] = {
+    ast.List: "list",
+    ast.Set: "set",
+    ast.Dict: "dict",
+    ast.Tuple: "tuple",
+}
+
+
+class NoTautologicalExpect(Rule):
+    """An assertion on a literal can never fail — it tests the literal, not the code."""
+
+    id: str = "no-tautological-expect"
+    code: str = "SARJ057"
+    description: str = "Assertion whose operands are all literals — its outcome is fixed before the code runs."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        """Flag assertions whose truth is decided by their own literals.
+
+        Returns:
+            One diagnostic per never-failing assertion, sorted by position.
+
+        """
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        exempt = _exempt_nodes(tree)
+        diags = [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=_message(node, reason),
+            )
+            for node, reason in _tautologies(tree, exempt)
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _exempt_nodes(tree: ast.Module) -> set[ast.AST]:
+    """Collect the nodes the carve-outs put out of reach.
+
+    Every node under a pytest-benchmark test, plus the lone `assert` that forms
+    an `except` handler's whole body — the "this exception is the acceptable
+    outcome" marker, which is a statement about control flow rather than about a
+    literal.
+
+    Returns:
+        The nodes this rule must not report.
+
+    """
+    exempt: set[ast.AST] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, _FUNC_NODES) and (uses_benchmark_fixture(node) or has_benchmark_marker(node)):
+            exempt.update(ast.walk(node))
+        elif isinstance(node, ast.ExceptHandler) and len(node.body) == 1 and isinstance(node.body[0], ast.Assert):
+            exempt.add(node.body[0])
+    return exempt
+
+
+def _tautologies(tree: ast.Module, exempt: set[ast.AST]) -> list[tuple[ast.Assert | ast.Call, str]]:
+    """Find every assertion in `tree` whose outcome its own literals decide.
+
+    Returns:
+        Pairs of offending node and the phrase describing why it cannot fail.
+
+    """
+    found: list[tuple[ast.Assert | ast.Call, str]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Assert, ast.Call)) or node in exempt:
+            continue
+        reason = _fixed_truth_reason(node.test) if isinstance(node, ast.Assert) else _unittest_reason(node)
+        if reason is not None:
+            found.append((node, reason))
+    return found
+
+
+def _unittest_reason(node: ast.Call) -> str | None:
+    """Describe why a `unittest` assertion call cannot fail, if it cannot.
+
+    Returns:
+        The reason phrase, or None when the call is not a fixed-outcome assertion.
+
+    """
+    name = _called_method(node)
+    # `msg=` is unittest's failure text and changes nothing about the outcome;
+    # any other keyword means this is not the method we think it is.
+    if name is None or any(kw.arg != _UNITTEST_MSG_KWARG for kw in node.keywords):
+        return None
+    args = node.args
+    if name in _EQUALITY_METHODS and len(args) >= _EQUALITY_ARITY and _is_same_literal(args[0], args[1]):
+        return f"`{_preview(args[0])}` is compared with an identical literal"
+    if len(args) < 1:
+        return None
+    if name in _TRUTHY_ARG_METHODS:
+        return _fixed_truth_reason(args[0])
+    if name in _FALSY_ARG_METHODS and _is_always_falsy_literal(args[0]):
+        return f"`{_preview(args[0])}` is a literal that is always falsy"
+    return None
+
+
+def _fixed_truth_reason(test: ast.expr) -> str | None:
+    """Describe why `test` is always truthy, if it is.
+
+    Returns:
+        The reason phrase, or None when the value depends on the code.
+
+    """
+    if _constant_truth(test) is True:
+        return f"`{_preview(test)}` is a constant truthy value"
+    kind = _nonempty_container_kind(test)
+    if kind is not None:
+        return f"a non-empty {kind} display is truthy whatever it contains"
+    if _is_identical_literal_comparison(test):
+        return f"`{_preview(test)}` compares a literal with an identical literal"
+    return None
+
+
+def _constant_truth(node: ast.expr) -> bool | None:
+    """Evaluate the truthiness of a scalar constant, `-1` and `+0` included.
+
+    Returns:
+        The constant's truth value, or None when `node` is not a scalar constant.
+
+    """
+    if isinstance(node, ast.Constant):
+        return bool(node.value)
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd)):
+        return _constant_truth(node.operand)
+    return None
+
+
+def _nonempty_container_kind(node: ast.expr) -> str | None:
+    """Name the container display kind when `node` is a provably non-empty one.
+
+    A `*splat`/`**unpack` element makes emptiness a runtime question, so those
+    are excluded — `assert [*items]` really can fail.
+
+    Returns:
+        "list"/"set"/"dict"/"tuple", or None.
+
+    """
+    if isinstance(node, ast.Dict):
+        if not node.keys or any(key is None for key in node.keys):
+            return None
+        return _CONTAINER_KINDS[ast.Dict]
+    if not isinstance(node, (ast.List, ast.Set, ast.Tuple)):
+        return None
+    if not node.elts or any(isinstance(elt, ast.Starred) for elt in node.elts):
+        return None
+    return _CONTAINER_KINDS[type(node)]
+
+
+def _is_identical_literal_comparison(node: ast.expr) -> bool:
+    """Report whether `node` compares one literal with a textually identical one.
+
+    Single-operator comparisons only, and only `==`/`is`. Both operands must be
+    literals: `assert i == i` and `assert x is x` are reflexivity tests on a
+    real object and are the false positives this rule exists to avoid.
+
+    Returns:
+        True for `1 == 1`, `"a" is "a"`; False for `i == i`, `f(x) == f(x)`.
+
+    """
+    if not isinstance(node, ast.Compare) or len(node.ops) != 1:
+        return False
+    if not isinstance(node.ops[0], _SAMENESS_OPS):
+        return False
+    return _is_same_literal(node.left, node.comparators[0])
+
+
+def _is_same_literal(left: ast.expr, right: ast.expr) -> bool:
+    """Report whether both operands are literals with identical syntax.
+
+    Returns:
+        True when both are literals and unparse to the same source.
+
+    """
+    return _is_literal(left) and _is_literal(right) and ast.dump(left) == ast.dump(right)
+
+
+def _is_literal(node: ast.expr) -> bool:
+    """Report whether `node` is a literal built entirely from constants.
+
+    An identifier, attribute, call or f-string is not — its value comes from
+    somewhere the syntax cannot see, which is exactly what makes an assertion on
+    it a real assertion.
+
+    Returns:
+        True for constants, negated numeric constants, and displays of literals.
+
+    """
+    if isinstance(node, ast.Constant):
+        return True
+    if isinstance(node, ast.UnaryOp):
+        # `-1` is a negation of a constant, not a constant; without this,
+        # `assertEqual(-1, -1)` would slip through.
+        return isinstance(node.op, (ast.USub, ast.UAdd)) and _is_literal(node.operand)
+    if isinstance(node, (ast.List, ast.Set, ast.Tuple)):
+        return all(_is_literal(elt) for elt in node.elts)
+    if isinstance(node, ast.Dict):
+        return all(key is not None and _is_literal(key) for key in node.keys) and all(
+            _is_literal(value) for value in node.values
+        )
+    return False
+
+
+def _is_always_falsy_literal(node: ast.expr) -> bool:
+    """Report whether `node` is a literal that is always falsy.
+
+    Returns:
+        True for `False`, `0`, `""`, `None` and empty displays.
+
+    """
+    if _constant_truth(node) is False:
+        return True
+    if isinstance(node, (ast.List, ast.Tuple)):
+        return not node.elts
+    if isinstance(node, ast.Dict):
+        return not node.keys
+    return False
+
+
+def _called_method(node: ast.Call) -> str | None:
+    func = node.func
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    if isinstance(func, ast.Name):
+        return func.id
+    return None
+
+
+def _preview(node: ast.expr) -> str:
+    """Render `node` back to source, truncated so the message stays one line.
+
+    Returns:
+        The unparsed operand, elided past `_OPERAND_PREVIEW_CHARS`.
+
+    """
+    text = " ".join(ast.unparse(node).split())
+    if len(text) > _OPERAND_PREVIEW_CHARS:
+        return f"{text[:_OPERAND_PREVIEW_CHARS]}…"
+    return text
+
+
+def _message(node: ast.Assert | ast.Call, reason: str) -> str:
+    """Compose the diagnostic, adding the message-slot hint where it applies.
+
+    Returns:
+        The full diagnostic message.
+
+    """
+    slid_into_message_slot = isinstance(node, ast.Assert) and node.msg is not None
+    hint = (
+        " The expression you meant to assert on is sitting in the assertion-message slot — move it into the condition."
+        if slid_into_message_slot
+        else " Assert on a value the code produced, or delete the test."
+    )
+    return f"This assertion can never fail: {reason}.{hint}"

{sarj_python_lint-0.21.0 → sarj_python_lint-0.23.0}/src/sarj_python_lint/rules/zero_assertion_test.py

@@ -114,6 +114,7 @@ from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 from sarj_python_lint.rules._paths import is_test_path
+from sarj_python_lint.rules._pytest import uses_benchmark_fixture
 
 
 if TYPE_CHECKING:
@@ -132,9 +133,6 @@ _RAISES_NAMES = frozenset({"raises", "warns", "fail"})
 
 _TEST_PREFIX = "test_"
 
-# The pytest-benchmark fixture: the test measures time, it does not verify.
-_BENCHMARK = "benchmark"
-
 # Fluent verification DSLs reached through an attribute rather than a call name.
 _FLUENT_ATTRS = frozenset({"expect"})
 
@@ -203,7 +201,7 @@ def _unverifying_tests(tree: ast.Module) -> list[ast.FunctionDef | ast.AsyncFunc
     verifying_helpers = _verifying_local_names(defined_here)
     hits: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
     for node in _collectible_tests(tree):
-        if _is_skipped(node) or _is_fixture(node) or _is_placeholder(node) or _uses_benchmark_fixture(node):
+        if _is_skipped(node) or _is_fixture(node) or _is_placeholder(node) or uses_benchmark_fixture(node):
             continue
         if _verifies_something(node) or _delegates_verification(node, defined_here, verifying_helpers):
             continue
@@ -292,15 +290,6 @@ def _is_inert(stmt: ast.stmt) -> bool:
     return isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant)
 
 
-def _uses_benchmark_fixture(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
-    # pytest-benchmark: `def test_x(benchmark)` then `benchmark(fn, arg)` or
-    # `@benchmark` on a nested function. The fixture times the callable; a
-    # benchmark that asserted on the result would be measuring the assertion.
-    args = node.args
-    declared = any(arg.arg == _BENCHMARK for arg in (*args.posonlyargs, *args.args, *args.kwonlyargs))
-    return declared and any(isinstance(child, ast.Name) and child.id == _BENCHMARK for child in ast.walk(node))
-
-
 def _verifies_something(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     # Search the whole subtree, nested functions included: the common
     # `async def _run(): assert ...` + `asyncio.run(_run())` wrapper keeps its