sarj-python-lint 1.7.8__tar.gz → 1.8.2__tar.gz

{sarj_python_lint-1.7.8 → sarj_python_lint-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.7.8
+Version: 1.8.2
 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/
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.16.9
-Requires-Dist: sarj-rule-contracts==0.1.1
+Requires-Dist: sarj-rule-contracts==0.2.0
 Requires-Dist: sqlglot==30.19.0
 Requires-Dist: typer==0.27.2
 Description-Content-Type: text/markdown

{sarj_python_lint-1.7.8 → sarj_python_lint-1.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.7.8"
+version = "1.8.2"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["sarj-rule-contracts==0.1.1", "packaging==26.3", "ruff>=0.16.9", "sqlglot==30.19.0", "typer==0.27.2"]
+dependencies = ["sarj-rule-contracts==0.2.0", "packaging==26.3", "ruff>=0.16.9", "sqlglot==30.19.0", "typer==0.27.2"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

{sarj_python_lint-1.7.8 → sarj_python_lint-1.8.2}/src/sarj_python_lint/rules/async_mock_call_without_await_assertion.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import ast
+from enum import Enum, auto
 from pathlib import PurePosixPath
 from types import MappingProxyType
 from typing import TYPE_CHECKING, ClassVar, Final, final, override
@@ -65,12 +66,18 @@ type _TestFunction = ast.FunctionDef | ast.AsyncFunctionDef
 type _Reference = tuple[str, ...]
 
 
+class _Evidence(Enum):
+    POSITIVE = auto()
+    INSUFFICIENT = auto()
+    UNRESOLVED = auto()
+
+
 @final
 class AsyncMockCallWithoutAwaitAssertion(Rule):
     id = "async-mock-call-without-await-assertion"
     code = "SARJ456"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
-        default_level=Severity.ERROR,
+        default_level=Severity.WARNING,
         summary="Pair positive AsyncMock call assertions with evidence that the mock was awaited.",
         rationale=(
             "Calling an AsyncMock records a call before its coroutine is awaited. A positive call assertion can "
@@ -87,33 +94,50 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
             "Only direct statements in collected test functions and methods are inspected; fixtures, helpers, nested blocks, and generated files are excluded.",
             "Requires a fresh local unittest.mock.AsyncMock constructor with unshadowed imports; aliases, reassignment, reset, and ambiguous configuration are excluded.",
             "Only the mock itself and unchanged immediate children of unspecced, unwrapped mocks are inferred; spec children, return values, and deeper chains are excluded.",
-            "Positive call-count and called-state assertions are covered as well as call-assertion methods. Await-state assertions must prove at least one await; argument equality and exact call/await counts are not compared.",
-            "Boolean conjunctions combine evidence; disjunctions require evidence in every branch. Dynamic counts and call lists are not inferred.",
+            "Positive call evidence includes direct assertion methods and literal integer or boolean call-state checks; unresolved call expectations are excluded.",
+            "Await evidence excludes provably vacuous checks, including zero or nonnegative counts and empty expected await sequences; unresolved expectations are accepted without inferring their values.",
+            "Conjunctions need one accepted await branch; disjunctions need accepted evidence for the same mock in every branch. Argument equality and assertion strength are not compared.",
+            "Compound negation and custom expression semantics remain unresolved; no variable values or fixture graphs are inferred.",
             "Custom assertion helpers and intentional scheduling contracts may require a reasoned local suppression.",
         ),
         examples=(
             RuleExample(
-                example_id="numeric-call-with-vacuous-await-check",
-                title="A nonnegative await count does not prove execution",
+                example_id="call-only-async-mock",
+                title="A call assertion does not prove awaiting",
                 outcome=ExampleOutcome.MATCH,
                 files=(
                     ExampleFile.python(
                         "tests/test_delivery.py",
-                        "from unittest.mock import AsyncMock\n\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    assert send.call_count == 2\n    assert send.await_count >= 0\n",
+                        "from unittest.mock import AsyncMock\n\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once_with('item')\n",
                     ),
                 ),
                 focus_path=PurePosixPath("tests/test_delivery.py"),
                 expected_count=1,
-                public=False,
+                public=True,
             ),
             RuleExample(
-                example_id="call-only-async-mock",
-                title="A call assertion does not prove awaiting",
+                example_id="call-and-await-async-mock",
+                title="Call and await assertions protect different contracts",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_delivery.py",
+                        "from unittest.mock import AsyncMock\n\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once_with('item')\n    send.assert_awaited_once_with('item')\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_delivery.py"),
+                expected_count=0,
+                public=True,
+            ),
+            RuleExample(
+                example_id="vacuous-await-count",
+                scenario="await-expectation-boundaries",
+                title="A nonnegative await count does not prove execution",
                 outcome=ExampleOutcome.MATCH,
                 files=(
                     ExampleFile.python(
                         "tests/test_delivery.py",
-                        "from unittest.mock import AsyncMock\n\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once_with('item')\n",
+                        "from unittest.mock import AsyncMock\n\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    assert send.call_count == 1\n    assert send.await_count >= 0\n",
                     ),
                 ),
                 focus_path=PurePosixPath("tests/test_delivery.py"),
@@ -121,13 +145,14 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
                 public=True,
             ),
             RuleExample(
-                example_id="call-and-await-async-mock",
-                title="Call and await assertions protect different contracts",
+                example_id="dynamic-expected-awaits",
+                scenario="await-expectation-boundaries",
+                title="Unresolved await expectations retain their acceptance",
                 outcome=ExampleOutcome.NO_MATCH,
                 files=(
                     ExampleFile.python(
                         "tests/test_delivery.py",
-                        "from unittest.mock import AsyncMock\n\nasync def test_delivery():\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once_with('item')\n    send.assert_awaited_once_with('item')\n",
+                        "from unittest.mock import AsyncMock\n\nasync def test_delivery(expected):\n    send = AsyncMock()\n    await deliver(send)\n    send.assert_called_once()\n    send.assert_has_awaits(expected)\n",
                     ),
                 ),
                 focus_path=PurePosixPath("tests/test_delivery.py"),
@@ -166,7 +191,7 @@ class AsyncMockCallWithoutAwaitAssertion(Rule):
                 line=call.lineno,
                 col=call.col_offset + 1,
                 code=self.code,
-                severity=Severity.ERROR,
+                severity=Severity.WARNING,
                 message="AsyncMock call assertions do not prove awaiting; keep this assertion and add an await assertion",
             )
             for test in _collected_tests(tree.body)
@@ -231,7 +256,7 @@ def _call_oracles(statement: ast.stmt) -> Iterator[tuple[_Reference, ast.Call |
         ):
             yield _reference(receiver), call
         case ast.Assert(test=condition):
-            for reference in sorted(_positive_states(condition, _CALL_STATE)):
+            for reference in sorted(_asserted_states(condition, _CALL_STATE)):
                 oracle = next(
                     node
                     for node in walk_ast(condition)
@@ -304,49 +329,60 @@ def _await_oracles(statements: list[ast.stmt]) -> set[_Reference]:
             case ast.Expr(value=ast.Call(func=ast.Attribute(value=receiver, attr=method)) as call) if (
                 method in _AWAIT_ASSERTIONS
             ):
-                if method != "assert_has_awaits" or _has_nonempty_calls_argument(call):
+                if method != "assert_has_awaits" or _calls_evidence(call) is not _Evidence.INSUFFICIENT:
                     covered.add(_reference(receiver))
             case ast.Assert(test=condition):
-                covered.update(_positive_states(condition, _AWAIT_STATE))
+                covered.update(_asserted_states(condition, _AWAIT_STATE))
             case _:
                 pass
     return covered
 
 
-def _has_nonempty_calls_argument(call: ast.Call) -> bool:
+def _calls_evidence(call: ast.Call) -> _Evidence:
     if call.args:
-        return _nonempty_sequence(call.args[0])
-    return any(item.arg == "calls" and _nonempty_sequence(item.value) for item in call.keywords)
-
-
-def _positive_states(condition: ast.expr, states: frozenset[str]) -> set[_Reference]:
-    if isinstance(condition, ast.UnaryOp) and isinstance(condition.op, ast.Not):
-        operand = condition.operand
-        if isinstance(operand, ast.Compare) and len(operand.ops) == 1:
-            inverse = _negated_operator(operand.ops[0])
-            if inverse is not None:
-                return _comparison_states(operand.left, inverse, operand.comparators[0], states) | _comparison_states(
-                    operand.comparators[0], _reversed_operator(inverse), operand.left, states
-                )
-        return set()
-    if isinstance(condition, ast.BoolOp):
-        branches = [_positive_states(value, states) for value in condition.values]
-        return (
-            branches[0].union(*branches[1:])
-            if isinstance(condition.op, ast.And)
-            else branches[0].intersection(*branches[1:])
-        )
-    if isinstance(condition, ast.Attribute) and condition.attr in states:
-        return {_reference(condition.value)}
-    if isinstance(condition, ast.Compare):
-        result: set[_Reference] = set()
-        for left, operator, right in zip(
-            (condition.left, *condition.comparators[:-1]), condition.ops, condition.comparators, strict=True
-        ):
-            result.update(_comparison_states(left, operator, right, states))
-            result.update(_comparison_states(right, _reversed_operator(operator), left, states))
-        return result
-    return set()
+        return _sequence_evidence(call.args[0])
+    for keyword in call.keywords:
+        if keyword.arg == "calls":
+            return _sequence_evidence(keyword.value)
+    return _Evidence.UNRESOLVED
+
+
+def _sequence_evidence(node: ast.expr) -> _Evidence:
+    if isinstance(node, (ast.List, ast.Tuple)):
+        if not node.elts:
+            return _Evidence.INSUFFICIENT
+        if any(not isinstance(item, ast.Starred) for item in node.elts):
+            return _Evidence.POSITIVE
+    return _Evidence.UNRESOLVED
+
+
+def _asserted_states(condition: ast.expr, states: frozenset[str]) -> set[_Reference]:
+    match condition:
+        case ast.UnaryOp(op=ast.Not(), operand=ast.UnaryOp(op=ast.Not(), operand=operand)):
+            return _asserted_states(operand, states)
+        case ast.UnaryOp(op=ast.Not(), operand=ast.Compare(left=left, ops=[operator], comparators=[right])):
+            inverse = _negated_operator(operator)
+            return _comparison_states(left, inverse, right, states) if inverse is not None else set()
+        case ast.UnaryOp(op=ast.Not(), operand=ast.Attribute(attr=attribute)) if attribute in states:
+            return set()
+        case ast.BoolOp(op=operator, values=values):
+            branches = [_asserted_states(value, states) for value in values]
+            return (
+                branches[0].union(*branches[1:])
+                if isinstance(operator, ast.And)
+                else branches[0].intersection(*branches[1:])
+            )
+        case ast.Attribute(value=receiver, attr=attribute) if attribute in states:
+            return {_reference(receiver)}
+        case ast.Compare(left=left, ops=operators, comparators=rights):
+            result: set[_Reference] = set()
+            for first, operator, second in zip((left, *rights[:-1]), operators, rights, strict=True):
+                result.update(_comparison_states(first, operator, second, states))
+            return result
+        case _:
+            # Preserve acceptance of unresolved await-state assertions, such as
+            # len(mock.await_args_list) == expected, without value propagation.
+            return _unresolved_await_states(condition, states)
 
 
 def _negated_operator(operator: ast.cmpop) -> ast.cmpop | None:
@@ -364,6 +400,18 @@ def _negated_operator(operator: ast.cmpop) -> ast.cmpop | None:
     return factory() if factory is not None else None
 
 
+def _comparison_states(left: ast.expr, operator: ast.cmpop, right: ast.expr, states: frozenset[str]) -> set[_Reference]:
+    result: set[_Reference] = set()
+    for node, comparison, expected in ((left, operator, right), (right, _reversed_operator(operator), left)):
+        if isinstance(node, ast.Attribute) and node.attr in states:
+            evidence = _state_evidence(node.attr, comparison, expected)
+            if evidence is _Evidence.POSITIVE or (states == _AWAIT_STATE and evidence is _Evidence.UNRESOLVED):
+                result.add(_reference(node.value))
+        else:
+            result.update(_unresolved_await_states(node, states))
+    return result
+
+
 def _reversed_operator(operator: ast.cmpop) -> ast.cmpop:
     match operator:
         case ast.Lt():
@@ -378,32 +426,38 @@ def _reversed_operator(operator: ast.cmpop) -> ast.cmpop:
             return operator
 
 
-def _comparison_states(left: ast.expr, operator: ast.cmpop, right: ast.expr, states: frozenset[str]) -> set[_Reference]:
-    if not isinstance(left, ast.Attribute):
+def _unresolved_await_states(node: ast.expr, states: frozenset[str]) -> set[_Reference]:
+    if states != _AWAIT_STATE:
         return set()
+    return {
+        _reference(child.value) for child in walk_ast(node) if isinstance(child, ast.Attribute) and child.attr in states
+    }
+
+
+def _state_evidence(attribute: str, operator: ast.cmpop, expected: ast.expr) -> _Evidence:
+    positive: bool
     if (
-        states == _AWAIT_STATE
-        and isinstance(left.value, ast.Attribute)
-        and left.value.attr == "await_args"
-        and left.attr in {"args", "kwargs"}
+        attribute in {"call_count", "await_count"}
+        and isinstance(expected, ast.Constant)
+        and isinstance(expected.value, int)
     ):
-        return {_reference(left.value.value)}
-    if left.attr not in states:
-        return set()
-    positive = False
-    if left.attr in {"call_count", "await_count"} and isinstance(right, ast.Constant) and type(right.value) is int:
-        positive = _proves_positive_count(operator, right.value)
-    elif left.attr == "called" and isinstance(right, ast.Constant):
-        positive = (isinstance(operator, (ast.Eq, ast.Is)) and right.value is True) or (
-            isinstance(operator, (ast.NotEq, ast.IsNot)) and right.value is False
+        positive = _proves_positive_count(operator, expected.value)
+    elif attribute == "called" and isinstance(expected, ast.Constant) and isinstance(expected.value, bool):
+        positive = (isinstance(operator, (ast.Eq, ast.Is)) and expected.value) or (
+            isinstance(operator, (ast.NotEq, ast.IsNot)) and not expected.value
         )
-    elif left.attr == "await_args" and isinstance(right, ast.Constant) and right.value is None:
+    elif attribute == "await_args" and isinstance(expected, ast.Constant) and expected.value is None:
         positive = isinstance(operator, (ast.NotEq, ast.IsNot))
-    elif left.attr == "await_args_list":
-        positive = (isinstance(operator, ast.Eq) and _nonempty_sequence(right)) or (
-            isinstance(operator, ast.NotEq) and isinstance(right, ast.List) and not right.elts
+    elif attribute == "await_args_list" and isinstance(operator, (ast.Eq, ast.NotEq)):
+        sequence = _sequence_evidence(expected)
+        if sequence is _Evidence.UNRESOLVED:
+            return sequence
+        positive = (isinstance(operator, ast.Eq) and sequence is _Evidence.POSITIVE) or (
+            isinstance(operator, ast.NotEq) and isinstance(expected, ast.List) and sequence is _Evidence.INSUFFICIENT
         )
-    return {_reference(left.value)} if positive else set()
+    else:
+        return _Evidence.UNRESOLVED
+    return _Evidence.POSITIVE if positive else _Evidence.INSUFFICIENT
 
 
 def _proves_positive_count(operator: ast.cmpop, value: int) -> bool:
@@ -418,10 +472,6 @@ def _proves_positive_count(operator: ast.cmpop, value: int) -> bool:
             return False
 
 
-def _nonempty_sequence(node: ast.expr) -> bool:
-    return isinstance(node, (ast.List, ast.Tuple)) and any(not isinstance(item, ast.Starred) for item in node.elts)
-
-
 def _invalidates_reference(node: ast.AST, reference: _Reference, binding: ast.Name) -> bool:
     match node:
         case ast.Name(id=name, ctx=ast.Store() | ast.Del()):

{sarj_python_lint-1.7.8 → sarj_python_lint-1.8.2}/src/sarj_python_lint/rules/complex_postgres_query_requires_architecture_review.py

@@ -243,26 +243,12 @@ def _expression_args(node: exp.Expr, key: str) -> tuple[exp.Expr, ...]:
     return tuple(child for child in node.iter_expressions() if child.arg_key == key)
 
 
-def _root_selects(query: exp.Query) -> tuple[exp.Select, ...]:
-    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
-
-    if isinstance(query, exp.Select):
-        return (query,)
-    if not isinstance(query, exp.SetOperation):
-        return ()
-    branches: list[exp.Select] = []
-    for key in ("this", "expression"):
-        if isinstance((branch := _expression_arg(query, key)), exp.Query):
-            branches.extend(_root_selects(branch))
-    return tuple(branches)
-
-
 def _derived_query(node: exp.Expr | None) -> exp.Query | None:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
 
-    if isinstance(node, exp.Subquery) and isinstance((query := _expression_arg(node, "this")), exp.Query):
-        return query
-    return None
+    while isinstance(node, (exp.Lateral, exp.Paren, exp.Subquery)):
+        node = _expression_arg(node, "this")
+    return node if isinstance(node, exp.Query) else None
 
 
 @final
@@ -278,18 +264,21 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
             "cost, a bad data model, or the right datastore."
         ),
         remediation=(
-            "Review whether the schema exposes the operational fact directly, together with production-like "
-            "cardinality and EXPLAIN output. Simplify the query or read model when warranted, but do not mechanically "
-            "replace database joins with application joins. Keep atomic coordination in one statement; consider a "
-            "columnar store only for measured repeated analytical reads with an explicit freshness contract."
+            "Prefer ClickHouse for reporting, historical analysis, and broad aggregations, with measured performance "
+            "and an explicit freshness contract. For transactional work, simplify the query or document why "
+            "PostgreSQL is required, with query bounds and production-like EXPLAIN evidence. Review whether the "
+            "schema exposes the operational fact directly; preserve atomic coordination and do not mechanically "
+            "replace database joins with application joins. Do not add reporting-specific indexes without "
+            "evaluating ClickHouse."
         ),
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only statically recoverable SQL passed to execute, executemany, fetch, fetchrow, fetchval, or prepare in non-test modules with explicit PostgreSQL imports is analyzed; extended derived, staged, and wide-shape review requires a recognized store module.",
+            "Only statically recoverable SQL passed to execute, executemany, fetch, fetchrow, fetchval, or prepare in non-test modules with explicit PostgreSQL imports is analyzed, regardless of module filename.",
             "Execution receivers must use a conventional database name; custom wrappers and dynamically obtained receivers abstain.",
             "One direct, unambiguous simple-name binding in the same lexical scope is followed; standalone constants, branches, aliases, attributes, containers, wildcard imports, and cross-scope flow abstain.",
-            "A query is reviewed for a complex derived relation, at least four joins in one query block, at least six nested query stages, three joins plus four stages, or 25 projections plus two joins.",
+            "Review covers derived relations in every SELECT (including LATERAL, CTEs, predicates and writes), four explicit or comma joins, six query stages, three joins plus four stages, or 25 projections plus two joins.",
+            "Derived-relation review requires grouping, HAVING or windowing combined with joins or nested reads; expression density is not a separate trigger.",
             "Projection width alone is accepted, and UNION branches are measured independently; execution plans and production cardinality remain authoritative.",
             "ClickHouse and BigQuery syntax is excluded per query, including in mixed-backend modules.",
             "The rule does not infer optimizer behavior, materialization, performance, data-model quality, or datastore placement.",
@@ -405,9 +394,11 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
                     code=self.code,
                     severity=Severity.WARNING,
                     message=(
-                        f"{signal} requires architecture review;{guidance} "
-                        "Review warning only, not a defect or cost claim; syntax does not prove a bad data model or "
-                        "an offload decision."
+                        f"Complex PostgreSQL query: {signal}. Architecture review required;{guidance} "
+                        "Prefer ClickHouse for reporting, historical analysis, and broad aggregations. "
+                        "For transactional work, simplify the query or document why PostgreSQL is required, "
+                        "with query bounds and EXPLAIN evidence. Do not add reporting-specific indexes without "
+                        "evaluating ClickHouse. Syntax alone does not establish runtime cost or datastore placement."
                     ),
                 )
             )
@@ -494,45 +485,40 @@ def _query_architecture_signal(text_value: str, path: Path) -> str | None:
         or (is_store_module(path) and analytical_signal(sql_without_noise) is not None)
     ):
         return None
-    return _parse_signal(text_value, include_extended_shapes=is_store_module(path))
+    return _parse_signal(text_value)
 
 
-def _parse_signal(sql: str, *, include_extended_shapes: bool) -> str | None:
+def _parse_signal(sql: str) -> str | None:
     import sqlglot  # ruff: ignore[import-outside-top-level] -- parse only SQL that passes cheap ownership and shape gates
     from sqlglot.errors import SqlglotError  # ruff: ignore[import-outside-top-level] -- paired with lazy parser import
 
     normalized = _COMPOSABLE_HOLE.sub(_SQL_HOLE, sql)
     try:
-        statements = sqlglot.parse(normalized, read="postgres")
+        for statement in sqlglot.parse(normalized, read="postgres"):
+            if statement is not None and (signal := _architecture_signal(statement)) is not None:
+                return signal
     except SqlglotError:
         return None
-    for statement in statements:
-        if (
-            statement is not None
-            and (signal := _architecture_signal(statement, include_extended_shapes=include_extended_shapes)) is not None
-        ):
-            return signal
     return None
 
 
-def _architecture_signal(statement: exp.Expr, *, include_extended_shapes: bool) -> str | None:
+def _architecture_signal(statement: exp.Expr) -> str | None:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
 
-    if not isinstance(statement, exp.Query):
+    if not isinstance(statement, (exp.Query, exp.Insert, exp.Update, exp.Delete)):
         return None
     maximum_joins = _maximum_query_joins(statement)
     if maximum_joins >= _JOIN_LIMIT:
-        return f"SELECT block has {maximum_joins} JOINs (4+ explicit JOINs)"
-    if not include_extended_shapes:
-        return None
-    nested_queries = sum(1 for query in statement.walk() if isinstance(query, exp.Query)) - 1
+        return f"SELECT block has {maximum_joins} JOINs (4+ explicit JOINs or comma relations)"
+    nested_queries = sum(1 for query in statement.walk() if isinstance(query, (exp.Select, exp.SetOperation)))
+    nested_queries -= isinstance(statement, (exp.Select, exp.SetOperation))
     if (derived_signal := _derived_architecture_signal(statement)) is not None:
         return derived_signal
     if nested_queries >= _STAGE_LIMIT:
         return f"Query has {nested_queries} CTE/subquery stages"
     if maximum_joins >= _COMBINED_JOIN_LIMIT and nested_queries >= _COMBINED_STAGE_LIMIT:
         return f"Query combines {maximum_joins} JOINs with {nested_queries} CTE/subquery stages"
-    for select in _root_selects(statement):
+    for select in statement.find_all(exp.Select):
         projections = tuple(_expression_args(select, "expressions"))
         joins = tuple(join for join in _expression_args(select, "joins") if isinstance(join, exp.Join))
         if len(projections) >= _WIDE_PROJECTION_LIMIT and len(joins) >= _WIDE_PROJECTION_JOIN_LIMIT:
@@ -540,20 +526,20 @@ def _architecture_signal(statement: exp.Expr, *, include_extended_shapes: bool)
     return None
 
 
-def _derived_architecture_signal(statement: exp.Query) -> str | None:
+def _derived_architecture_signal(statement: exp.Expr) -> str | None:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
 
-    for select in _root_selects(statement):
+    for select in statement.find_all(exp.Select):
         for join in _expression_args(select, "joins"):
             if not isinstance(join, exp.Join):
                 continue
             if (derived := _derived_query(_expression_arg(join, "this"))) is not None and _has_complex_body(derived):
-                return "Complex JOIN-derived query"
+                return "JOIN-derived query combines grouping, HAVING or windowing with joins or nested reads"
         from_clause = _expression_arg(select, "from_")
         if not isinstance(from_clause, exp.From):
             continue
         if (derived := _derived_query(_expression_arg(from_clause, "this"))) is not None and _has_complex_body(derived):
-            return "Complex FROM-derived query"
+            return "FROM-derived query combines grouping, HAVING or windowing with joins or nested reads"
     return None
 
 
@@ -561,28 +547,43 @@ def _has_complex_body(query: exp.Query) -> bool:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
 
     if isinstance(query, exp.SetOperation):
-        return True
+        return any(
+            isinstance(branch := _expression_arg(query, key), exp.Query)
+            and (_has_row_transform(branch) or _has_complex_body(branch))
+            for key in ("this", "expression")
+        )
     if not isinstance(query, exp.Select):
         return False
-    if _expression_arg(query, "group") is not None or _expression_arg(query, "having") is not None:
-        return True
-    if any(window.parent_select is query for window in query.find_all(exp.Window)):
-        return True
-    from_clause = _expression_arg(query, "from_")
-    if isinstance(from_clause, exp.From) and _derived_query(_expression_arg(from_clause, "this")) is not None:
+    if _has_row_transform(query) and (
+        _expression_args(query, "joins") or any(select is not query for select in query.find_all(exp.Select))
+    ):
         return True
-    for join in _expression_args(query, "joins"):
-        if isinstance(join, exp.Join) and _derived_query(_expression_arg(join, "this")) is not None:
+    for relation in query.find_all(exp.From, exp.Join):
+        if relation.parent is not query:
+            continue
+        child = _derived_query(_expression_arg(relation, "this"))
+        if child is not None and (_has_row_transform(child) or _has_complex_body(child)):
             return True
     return False
 
 
-def _maximum_query_joins(statement: exp.Query) -> int:
+def _has_row_transform(query: exp.Query) -> bool:
+    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
+
+    select = _derived_query(query)
+    return isinstance(select, exp.Select) and (
+        _expression_arg(select, "group") is not None
+        or _expression_arg(select, "having") is not None
+        or any(window.parent_select is select for window in select.find_all(exp.Window))
+    )
+
+
+def _maximum_query_joins(statement: exp.Expr) -> int:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- keep parser startup off unrelated lint runs
 
     return max(
         (
-            sum(isinstance(join, exp.Join) and "pivots" in join.args for join in _expression_args(select, "joins"))
+            sum(isinstance(join, exp.Join) for join in _expression_args(select, "joins"))
             for select in statement.find_all(exp.Select)
         ),
         default=0,

{sarj_python_lint-1.7.8 → sarj_python_lint-1.8.2}/src/sarj_python_lint/rules/no_analytical_aggregation_in_postgres_store.py

@@ -159,8 +159,10 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
             "consistent operational aggregates remain valid PostgreSQL work."
         ),
         remediation=(
-            "Review the query bounds and execution plan. Move reporting scans to the repository's "
-            "columnar store, or document why the aggregate must remain transactional."
+            "Review the query bounds and execution plan. Prefer ClickHouse for reporting, historical analysis, "
+            "and broad aggregations, with measured performance and an explicit freshness contract. "
+            "For PostgreSQL, document why the aggregate must remain transactional, with EXPLAIN evidence. "
+            "Do not add reporting-specific indexes without evaluating ClickHouse."
         ),
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
@@ -247,7 +249,9 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
                     severity=Severity.WARNING,
                     message=(
                         f"Possible analytical PostgreSQL query ({signal}); review its bounds and execution plan. "
-                        "Move reporting scans to the columnar store, or document why this aggregate must remain transactional."
+                        "Prefer ClickHouse for reporting, historical analysis, and broad aggregations. "
+                        "For PostgreSQL, document why this aggregate must remain transactional, with EXPLAIN evidence. "
+                        "Do not add reporting-specific indexes without evaluating ClickHouse."
                     ),
                 )
             )