sarj-python-lint 0.81.18__tar.gz → 0.82.0__tar.gz

{sarj_python_lint-0.81.18 → sarj_python_lint-0.82.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 0.81.18
+Version: 0.82.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-0.81.18 → sarj_python_lint-0.82.0}/pyproject.toml

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

{sarj_python_lint-0.81.18 → sarj_python_lint-0.82.0}/src/sarj_python_lint/rules/complex_postgres_query_requires_architecture_review.py

@@ -18,8 +18,9 @@ from sarj_python_lint.rule_base import (
     parse_or_none,
 )
 from sarj_python_lint.rules._ast_index import nodes, walk
-from sarj_python_lint.rules._paths import is_generated
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip_sql_noise
+from sarj_python_lint.rules.no_analytical_aggregation_in_postgres_store import analytical_signal
 
 
 if TYPE_CHECKING:
@@ -29,7 +30,6 @@ if TYPE_CHECKING:
 
 
 _QUERY_SHAPE = re.compile(r"\bSELECT\b[\s\S]*?\bFROM\b", re.IGNORECASE)
-_DERIVED_RELATION_GATE = re.compile(r"\b(?:FROM|JOIN)\s*\(", re.IGNORECASE)
 _POSTGRES_IMPORT_PREFIXES = (
     "asyncpg",
     "psycopg",
@@ -37,13 +37,7 @@ _POSTGRES_IMPORT_PREFIXES = (
     "psycopg_pool",
     "sqlalchemy.dialects.postgresql",
 )
-_COMPETING_IMPORT_PREFIXES = (
-    "aiosqlite",
-    "clickhouse_connect",
-    "clickhouse_driver",
-    "google.cloud.bigquery",
-    "sqlite3",
-)
+_AMBIGUOUS_RELATIONAL_IMPORT_PREFIXES = ("aiosqlite", "sqlite3")
 _QUERY_SINKS = frozenset({"execute", "executemany", "fetch", "fetchrow", "fetchval", "prepare"})
 _QUERY_KEYWORDS = frozenset({"command", "operation", "query", "statement"})
 _QUERY_RECEIVER_TOKENS = frozenset(
@@ -61,6 +55,12 @@ _BIGQUERY_SQL = re.compile(
 )
 _COMPOSABLE_HOLE = re.compile(r"(?<!\{)\{(?:[A-Za-z_]\w*|\d*)\}(?!\})")
 _SQL_HOLE = "__sarj_sql_hole__"
+_JOIN_LIMIT = 4
+_STAGE_LIMIT = 6
+_COMBINED_JOIN_LIMIT = 3
+_COMBINED_STAGE_LIMIT = 4
+_WIDE_PROJECTION_LIMIT = 25
+_WIDE_PROJECTION_JOIN_LIMIT = 2
 
 
 class _ConstructorImport(NamedTuple):
@@ -308,7 +308,7 @@ 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 _parse_signal(sql: str) -> str | None:
+def _parse_signal(sql: str, *, include_extended_shapes: bool) -> 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
 
@@ -318,16 +318,31 @@ def _parse_signal(sql: str) -> str | None:
     except SqlglotError:
         return None
     for statement in statements:
-        if statement is not None and (signal := _architecture_signal(statement)) is not None:
+        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) -> str | None:
+def _architecture_signal(statement: exp.Expr, *, include_extended_shapes: bool) -> 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):
         return None
+    maximum_joins = max(
+        (
+            sum(isinstance(join, exp.Join) and "pivots" in join.args for join in _expression_args(select, "joins"))
+            for select in statement.find_all(exp.Select)
+        ),
+        default=0,
+    )
+    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
     for select in _root_selects(statement):
         for join in _expression_args(select, "joins"):
             if not isinstance(join, exp.Join):
@@ -339,6 +354,15 @@ def _architecture_signal(statement: exp.Expr) -> str | None:
             continue
         if (derived := _derived_query(_expression_arg(from_clause, "this"))) is not None and _has_complex_body(derived):
             return "Complex FROM-derived query"
+    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):
+        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:
+            return f"Joined query block has {len(projections)} projected expressions"
     return None
 
 
@@ -389,29 +413,64 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
     id: str = "complex-postgres-query-requires-architecture-review"
     code: str = "SARJ437"
     documentation = RuleDocumentation(
-        summary="Complex anonymous PostgreSQL relation stages merit readability review.",
+        summary="Complex executable PostgreSQL query shapes require architecture review.",
         rationale=(
-            "Anonymous derived relations with nested or transformational bodies can obscure query stages and make "
-            "bounds, ordering, and locking semantics harder to review. Syntax alone does not establish runtime cost "
-            "or justify materialization or offload."
+            "Join-heavy, deeply staged, or wide joined reads can obscure cardinality, bounds, ordering, and locking "
+            "semantics and can signal repeated read-time reconstruction. Syntax alone does not establish runtime "
+            "cost, a bad data model, or the right datastore."
         ),
         remediation=(
-            "First verify bounds, ordering, and lock semantics. Use a semantics-preserving CTE when naming improves "
-            "reviewability; it is not a performance optimization. Consider a view only for a reusable stable "
-            "interface, a materialized view only for measured repeated reads with an explicit freshness contract, "
-            "and a columnar store only for measured analytical workloads with an explicit synchronization contract."
+            "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."
         ),
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only statically recoverable SQL passed to execute, executemany, fetch, fetchrow, fetchval, or prepare in recognized PostgreSQL store modules is analyzed.",
+            "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.",
             "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 derived relation is reported only when it contains nesting, a window, grouping, HAVING, or a set operation.",
-            "Scalar, EXISTS, IN, and LATERAL subqueries are excluded; execution plans and production cardinality remain authoritative.",
-            "A CTE is suggested only as a naming refactor; the rule does not infer optimizer behavior, materialization, performance, or datastore placement.",
+            "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.",
+            "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.",
         ),
         examples=(
+            RuleExample(
+                example_id="multi-join-root-discovery",
+                title="A read repeatedly discovers a derived root through multiple joins",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/call_store.py",
+                        'import psycopg\ncursor.execute("SELECT call.id FROM simulated_batch '
+                        "JOIN batch_call ON batch_call.batch_id = simulated_batch.batch_id "
+                        "JOIN call ON call.batch_call_id = batch_call.id "
+                        "JOIN campaign_call ON campaign_call.call_id = call.id "
+                        'JOIN campaign ON campaign.id = campaign_call.campaign_id WHERE simulated_batch.batch_id = %s")\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/call_store.py"),
+                expected_count=1,
+                public=True,
+                scenario="multi-join-review",
+            ),
+            RuleExample(
+                example_id="stored-root-lookup",
+                title="A read uses a root resolved and stored by its owning write workflow",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/call_store.py",
+                        'import psycopg\ncursor.execute("SELECT root_call_id FROM canary_run WHERE id = %s")\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/call_store.py"),
+                expected_count=0,
+                public=True,
+                scenario="multi-join-review",
+            ),
             RuleExample(
                 example_id="ranked-queue-claim",
                 title="A queue claim hides ranking inside nested derived relations",
@@ -453,14 +512,14 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if not is_store_module(path) or is_generated(path, source):
+        if is_test_path(path) or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:
             return []
         imports = _import_names(tree)
         if not _has_import_prefix(imports, _POSTGRES_IMPORT_PREFIXES) or _has_import_prefix(
-            imports, _COMPETING_IMPORT_PREFIXES
+            imports, _AMBIGUOUS_RELATIONAL_IMPORT_PREFIXES
         ):
             return []
 
@@ -481,13 +540,24 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
             sql_without_noise = strip_sql_noise(text_value)
             if (
                 _QUERY_SHAPE.search(sql_without_noise) is None
-                or _DERIVED_RELATION_GATE.search(sql_without_noise) is None
                 or _CLICKHOUSE_SQL.search(sql_without_noise)
                 or _BIGQUERY_SQL.search(sql_without_noise)
+                or (is_store_module(path) and analytical_signal(sql_without_noise) is not None)
             ):
                 continue
-            if (signal := _parse_signal(text_value)) is None:
+            if (signal := _parse_signal(text_value, include_extended_shapes=is_store_module(path))) is None:
                 continue
+            coordination = re.search(
+                r"\b(?:FOR\s+(?:NO\s+KEY\s+)?UPDATE|FOR\s+SHARE|SKIP\s+LOCKED)\b", text_value, re.IGNORECASE
+            )
+            guidance = (
+                " preserve the atomic statement; review bounds, ordering, and locks, then document its cardinality, "
+                "supporting indexes, and production-like plan."
+                if coordination is not None
+                else " review bounds, ordering, and locks; review cardinality and a production-like query plan, then "
+                "review whether repeated read-time reconstruction should become a stable derived fact maintained at "
+                "write-time, or otherwise simplify the query or read model when warranted."
+            )
             diagnostics.append(
                 Diagnostic(
                     path=path,
@@ -496,8 +566,9 @@ class ComplexPostgresQueryRequiresArchitectureReview(Rule):
                     code=self.code,
                     severity=Severity.WARNING,
                     message=(
-                        f"{signal} hides a relational stage — review bounds, ordering, and locks; name it with a "
-                        "semantics-preserving CTE if clearer. Reviewability warning only; no cost or offload claim."
+                        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."
                     ),
                 )
             )

{sarj_python_lint-0.81.18 → sarj_python_lint-0.82.0}/src/sarj_python_lint/rules/no_analytical_aggregation_in_postgres_store.py

@@ -25,6 +25,8 @@ from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from sqlglot import exp
+
 
 _QUERY_SHAPE = re.compile(r"\bSELECT\b[\s\S]*?\bFROM\b", re.IGNORECASE)
 _POSTGRES_OWNER = re.compile(
@@ -49,6 +51,11 @@ _COMMON_AGGREGATE = re.compile(
     r"\b(?:COUNT|SUM|AVG|MIN|MAX|ARRAY_AGG|STRING_AGG|JSONB?_AGG|BOOL_AND|BOOL_OR|EVERY)\s*\(",
     re.IGNORECASE,
 )
+_LOCKING_READ = re.compile(r"\b(?:FOR\s+(?:NO\s+KEY\s+)?UPDATE|FOR\s+SHARE|SKIP\s+LOCKED)\b", re.IGNORECASE)
+_PLACEHOLDER = re.compile(r"%(?:\([^)]+\))?s")
+_GROUP_KEYS_LIMIT = 2
+_GROUP_AGGREGATES_LIMIT = 2
+_SINGLE_GROUP_AGGREGATES_LIMIT = 3
 _STRONG_ANALYTICAL: tuple[tuple[str, re.Pattern[str]], ...] = (
     ("STDDEV", re.compile(r"\bSTDDEV(?:_POP|_SAMP)?\s*\(", re.IGNORECASE)),
     ("VARIANCE", re.compile(r"\b(?:VARIANCE|VAR_POP|VAR_SAMP)\s*\(", re.IGNORECASE)),
@@ -71,15 +78,66 @@ def _docstring_node_ids(tree: ast.AST) -> set[int]:
     return result
 
 
-def _analytical_signal(sql: str) -> str | None:
+def analytical_signal(sql: str) -> str | None:
+    if _LOCKING_READ.search(sql) is not None:
+        return None
     for label, pattern in _STRONG_ANALYTICAL:
         if pattern.search(sql):
             return label
     if _TIME_BUCKET.search(sql) and _GROUP_BY.search(sql) and _COMMON_AGGREGATE.search(sql):
         return "time-bucketed GROUP BY"
+    return _grouped_reporting_signal(sql)
+
+
+def _grouped_reporting_signal(sql: str) -> str | None:
+    import sqlglot  # ruff: ignore[import-outside-top-level] -- parse only aggregate-shaped SQL after cheap gates
+    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- paired with lazy parser import
+    from sqlglot.errors import SqlglotError  # ruff: ignore[import-outside-top-level] -- paired with lazy parser import
+
+    if _GROUP_BY.search(sql) is None or _COMMON_AGGREGATE.search(sql) is None:
+        return None
+    try:
+        statements = sqlglot.parse(_PLACEHOLDER.sub("?", sql), read="postgres")
+    except SqlglotError:
+        return None
+    for statement in statements:
+        if not isinstance(statement, exp.Query):
+            continue
+        for select in statement.find_all(exp.Select):
+            if _is_identity_bounded(select):
+                continue
+            group = select.args.get("group")
+            group_count = len(group.expressions) if isinstance(group, exp.Group) else 0
+            aggregate_count = sum(1 for aggregate in select.find_all(exp.AggFunc) if aggregate.parent_select is select)
+            if (
+                group_count >= _GROUP_KEYS_LIMIT and aggregate_count >= _GROUP_AGGREGATES_LIMIT
+            ) or aggregate_count >= _SINGLE_GROUP_AGGREGATES_LIMIT:
+                return "grouped reporting shape"
     return None
 
 
+def _is_identity_bounded(select: object) -> bool:
+    from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- shared with lazy parser path
+
+    if not isinstance(select, exp.Select):
+        return False
+    where = select.args.get("where")
+    if not isinstance(where, exp.Where):
+        return False
+    equality = _expression_arg(where, "this")
+    if not isinstance(equality, exp.EQ):
+        return False
+    left = _expression_arg(equality, "this")
+    right = _expression_arg(equality, "expression")
+    return (isinstance(left, exp.Column) and left.name.casefold() == "id" and not isinstance(right, exp.Column)) or (
+        isinstance(right, exp.Column) and right.name.casefold() == "id" and not isinstance(left, exp.Column)
+    )
+
+
+def _expression_arg(node: exp.Expr, key: str) -> exp.Expr | None:
+    return next((child for child in node.iter_expressions() if child.arg_key == key), None)
+
+
 @final
 class NoAnalyticalAggregationInPostgresStore(Rule):
     id: str = "no-analytical-aggregation-in-postgres-store"
@@ -100,7 +158,7 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
         aliases=("no-aggregation-in-store-query",),
         limitations=(
             "Only SQL string literals in recognized store modules with positive PostgreSQL ownership evidence are analyzed.",
-            "Only statistical aggregates and time-bucketed grouped rollups are reported; ordinary operational aggregates are intentionally excluded.",
+            "Statistical aggregates, time-bucketed rollups, and broad grouped reporting shapes are reported; locked coordination reads and identity-bounded aggregates are excluded.",
             "ClickHouse- and BigQuery-specific query syntax is excluded per query, including in mixed-backend modules.",
         ),
         examples=(
@@ -166,7 +224,7 @@ class NoAnalyticalAggregationInPostgresStore(Rule):
                 or _BIGQUERY_SQL.search(sql)
             ):
                 continue
-            signal = _analytical_signal(sql)
+            signal = analytical_signal(sql)
             if signal is None:
                 continue
             diagnostics.append(