sarj-python-lint 0.5.0__tar.gz → 0.6.0__tar.gz

{sarj_python_lint-0.5.0 → sarj_python_lint-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.5.0
+Version: 0.6.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
@@ -37,6 +37,10 @@ uv tool install sarj-python-lint
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries
     - id: sarj-prefer-class-row
+    - id: sarj-prefer-timedelta-for-durations
+    - id: sarj-prefer-struct-over-namedtuple
+    - id: sarj-no-comment-cruft
+    - id: sarj-no-fstring-in-log
 ```
 
 ## CLI

{sarj_python_lint-0.5.0 → sarj_python_lint-0.6.0}/README.md

@@ -19,6 +19,10 @@ uv tool install sarj-python-lint
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries
     - id: sarj-prefer-class-row
+    - id: sarj-prefer-timedelta-for-durations
+    - id: sarj-prefer-struct-over-namedtuple
+    - id: sarj-no-comment-cruft
+    - id: sarj-no-fstring-in-log
 ```
 
 ## CLI

{sarj_python_lint-0.5.0 → sarj_python_lint-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.5.0"
+version = "0.6.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -27,7 +27,6 @@ Issues = "https://github.com/sarj-ai/standards/issues"
 [dependency-groups]
 dev = [
   "pytest>=9.0",
-  "pytest-benchmark>=5.2",
   "ruff>=0.15",
   "basedpyright>=1.39",
 ]
@@ -53,3 +52,7 @@ exclude = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+# Dogfooding: linted/formatted by this repo's own published config (root-synced).
+[tool.ruff]
+extend = "../../.ruff-strict.toml"

{sarj_python_lint-0.5.0 → sarj_python_lint-0.6.0}/src/sarj_python_lint/__main__.py

@@ -2,8 +2,8 @@
 from __future__ import annotations
 
 import argparse
-import sys
 from pathlib import Path
+import sys
 
 from sarj_python_lint import __version__
 from sarj_python_lint.rule_base import Diagnostic, is_suppressed
@@ -16,6 +16,10 @@ SKIP_DIR_NAMES = {
     ".turbo", ".yarn", ".pnpm-store",
 }
 
+# Skip files larger than this — they are almost always generated/vendored, not
+# hand-written source worth linting.
+_MAX_FILE_BYTES = 500_000
+
 
 def _expand_paths(paths: list[Path]) -> list[Path]:
     out: list[Path] = []
@@ -31,7 +35,7 @@ def _expand_paths(paths: list[Path]) -> list[Path]:
             if any(part in SKIP_DIR_NAMES for part in child.parts):
                 continue
             try:
-                if child.stat().st_size > 500_000:
+                if child.stat().st_size > _MAX_FILE_BYTES:
                     continue
             except OSError:
                 continue
@@ -82,14 +86,17 @@ def main(argv: list[str] | None = None) -> int:
     sub.add_parser("list-rules", help="List available rule IDs.")
 
     args = parser.parse_args(argv)
+    cmd: str | None = args.cmd
 
-    if args.cmd == "list-rules":
+    if cmd == "list-rules":
         for rid, cls in sorted(REGISTRY.items()):
             inst = cls()
             sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
         return 0
 
-    diags = _check(args.rule, args.files)
+    rule_ids: list[str] = args.rule
+    files: list[Path] = args.files
+    diags = _check(rule_ids, files)
     for d in diags:
         sys.stdout.write(d.format() + "\n")
     return 1 if diags else 0

{sarj_python_lint-0.5.0 → sarj_python_lint-0.6.0}/src/sarj_python_lint/rule_base.py

@@ -2,24 +2,31 @@
 
 from __future__ import annotations
 
-import re
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from pathlib import Path
+import re
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
 
 # Suppression syntax. Two forms supported:
 #   # sarj-noqa: SARJ001 — reason
 #   # sarj-noqa: SARJ001, SARJ002 — reason
-# We deliberately do NOT use `# noqa` because ruff aggressively cleans
-# unrecognized noqa codes (RUF100/RUF102) even with `external` set, which
-# silently breaks suppressions across runs. Distinct prefix = no conflict.
+# We deliberately do NOT reuse ruff's own suppression comment because ruff
+# aggressively cleans unrecognized codes (RUF100/RUF102) even with `external`
+# set, which silently breaks suppressions across runs. A distinct prefix
+# (sarj-noqa) shares no syntax with ruff, so the two never collide.
 _SARJ_NOQA_RE = re.compile(
     r"#\s*sarj-noqa(?::\s*([A-Za-z0-9_, ]+))?",
     re.IGNORECASE,
 )
 
 
-def is_suppressed(source_lines: list[str], line: int, code: str) -> bool:
+def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
     """Return True if the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
 
     `line` is 1-based to match Diagnostic.line.

sarj_python_lint-0.6.0/src/sarj_python_lint/rules/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from sarj_python_lint.rules._registry import REGISTRY
+
+
+__all__ = ["REGISTRY"]

sarj_python_lint-0.6.0/src/sarj_python_lint/rules/_logging.py

@@ -0,0 +1,35 @@
+"""Shared logging-receiver detection for SARJ012/SARJ017.
+
+A single resolver for "does this receiver expression evaluate to a logger?",
+used by both the secret-in-log and f-string-in-log rules so they recognise the
+same factory/builder forms.
+"""
+
+from __future__ import annotations
+
+import ast
+
+
+_LOGGER_NAMES = frozenset({"logger", "log", "logging", "loguru", "_logger", "_log"})
+
+_LOGGER_FACTORIES = frozenset({"getlogger", "getchild"})
+
+
+def is_logger_expr(expr: ast.expr) -> bool:
+    """True if `expr` evaluates to a logger.
+
+    Resolves the whole receiver chain so adapter/builder/factory calls are
+    caught: `logger.bind(...).info(...)`, `logger.opt(lazy=True).debug(...)`,
+    `logging.getLogger(__name__).info(...)`, `self.logger.error(...)`.
+    """
+    if isinstance(expr, ast.Name):
+        return expr.id.lower() in _LOGGER_NAMES
+    if isinstance(expr, ast.Attribute):
+        if expr.attr.lower() in _LOGGER_NAMES or expr.attr.lower() in _LOGGER_FACTORIES:
+            return True
+        return is_logger_expr(expr.value)
+    if isinstance(expr, ast.Call):
+        if isinstance(expr.func, ast.Attribute) and expr.func.attr.lower() in _LOGGER_FACTORIES:
+            return True
+        return is_logger_expr(expr.func)
+    return False

sarj_python_lint-0.5.0/src/sarj_python_lint/rules/__init__.py → sarj_python_lint-0.6.0/src/sarj_python_lint/rules/_registry.py

@@ -1,12 +1,20 @@
 from __future__ import annotations
 
-from sarj_python_lint.rule_base import Rule
+from typing import TYPE_CHECKING
+
 from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
 )
+from sarj_python_lint.rules.no_aggregation_in_store_query import (
+    NoAggregationInStoreQuery,
+)
+from sarj_python_lint.rules.no_comment_cruft import NoCommentCruft
 from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
+from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
+from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
+from sarj_python_lint.rules.no_select_star import NoSelectStar
 from sarj_python_lint.rules.no_sentinel_return_on_except import NoSentinelReturnOnExcept
 from sarj_python_lint.rules.no_sequential_await import NoSequentialAwait
 from sarj_python_lint.rules.no_unreachable_after_terminal import (
@@ -18,7 +26,20 @@ from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
 )
 from sarj_python_lint.rules.prefer_discriminated_union import PreferDiscriminatedUnion
 from sarj_python_lint.rules.prefer_str_enum import PreferStrEnum
+from sarj_python_lint.rules.prefer_struct_over_namedtuple import (
+    PreferStructOverNamedtuple,
+)
+from sarj_python_lint.rules.prefer_timedelta_for_durations import (
+    PreferTimedeltaForDurations,
+)
 from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
+from sarj_python_lint.rules.store_insert_requires_on_conflict import (
+    StoreInsertRequiresOnConflict,
+)
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint.rule_base import Rule
 
 
 REGISTRY: dict[str, type[Rule]] = {
@@ -34,6 +55,14 @@ REGISTRY: dict[str, type[Rule]] = {
     NoUnreachableAfterTerminal.id: NoUnreachableAfterTerminal,
     PreferConstantTimeSecretCompare.id: PreferConstantTimeSecretCompare,
     NoSecretInLog.id: NoSecretInLog,
+    PreferTimedeltaForDurations.id: PreferTimedeltaForDurations,
+    PreferStructOverNamedtuple.id: PreferStructOverNamedtuple,
+    NoCommentCruft.id: NoCommentCruft,
+    NoFstringInLog.id: NoFstringInLog,
+    StoreInsertRequiresOnConflict.id: StoreInsertRequiresOnConflict,
+    NoQueryWithManyJoins.id: NoQueryWithManyJoins,
+    NoAggregationInStoreQuery.id: NoAggregationInStoreQuery,
+    NoSelectStar.id: NoSelectStar,
 }
 
 __all__ = ["REGISTRY"]

{sarj_python_lint-0.5.0 → sarj_python_lint-0.6.0}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -12,48 +12,67 @@ References:
 from __future__ import annotations
 
 import ast
-from pathlib import Path
+from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule
 
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
 class InefficientStringConcatInLoop(Rule):
     """O(n²) string concatenation in a loop."""
 
-    id = "inefficient-string-concat-in-loop"
-    code = "SARJ002"
-    description = "`s += '...'` in a loop is O(n²); append to a list and join."
+    id: str = "inefficient-string-concat-in-loop"
+    code: str = "SARJ002"
+    description: str = "`s += '...'` in a loop is O(n²); append to a list and join."
 
+    @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
         try:
             tree = ast.parse(source, filename=str(path))
         except SyntaxError:
             return []
-        diags: list[Diagnostic] = []
-        for loop in ast.walk(tree):
-            if not isinstance(loop, (ast.For, ast.While)):
-                continue
-            for node in ast.walk(loop):
-                if not isinstance(node, ast.AugAssign):
-                    continue
-                if not isinstance(node.op, ast.Add):
-                    continue
-                # Heuristic: the RHS is a string-like value
-                if not _looks_like_string(node.value):
-                    continue
-                diags.append(
-                    Diagnostic(
-                        path=path,
-                        line=node.lineno,
-                        col=node.col_offset + 1,
-                        code=self.code,
-                        message=(
-                            "`+=` string concat in a loop is O(n²). "
-                            "Append to a list and `''.join(...)`."
-                        ),
-                    )
-                )
-        return diags
+        visitor = _ConcatVisitor()
+        visitor.visit(tree)
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=(
+                    "`+=` string concat in a loop is O(n²). "
+                    "Append to a list and `''.join(...)`."
+                ),
+            )
+            for node in visitor.hits
+        ]
+
+
+class _ConcatVisitor(ast.NodeVisitor):
+    """Single O(n) pass flagging each in-loop string `+=` exactly once."""
+
+    def __init__(self) -> None:
+        self._loop_depth: int = 0
+        self.hits: list[ast.AugAssign] = []
+
+    @override
+    def generic_visit(self, node: ast.AST) -> None:
+        if isinstance(node, (ast.For, ast.While)):
+            self._loop_depth += 1
+            super().generic_visit(node)
+            self._loop_depth -= 1
+            return
+        if (
+            self._loop_depth
+            and isinstance(node, ast.AugAssign)
+            and isinstance(node.op, ast.Add)
+            and _looks_like_string(node.value)
+        ):
+            self.hits.append(node)
+        super().generic_visit(node)
 
 
 def _looks_like_string(node: ast.AST) -> bool:

sarj_python_lint-0.6.0/src/sarj_python_lint/rules/no_aggregation_in_store_query.py

@@ -0,0 +1,134 @@
+"""SARJ020: no DISTINCT / GROUP BY / COUNT in a store query — aggregate elsewhere.
+
+Heavy aggregation (`COUNT`, `GROUP BY`, `DISTINCT`) does not belong in the
+transactional Postgres store layer: it scans, sorts, and hashes large row sets
+on the primary, competing with the latency-critical OLTP path. The house
+direction is to push aggregate/analytical reads to the columnar mirror
+(ClickHouse / BigQuery), where they are cheap, and keep Postgres queries to
+point lookups and small bounded reads.
+
+This rule walks SQL string literals embedded in `.py` (`*_store.py`) and flags
+any query (a string containing `FROM`) that uses `COUNT(`, `GROUP BY`, or
+`DISTINCT`. `--` and `/* */` comments are stripped first.
+
+    # flagged
+    "SELECT status, COUNT(*) FROM call GROUP BY status"
+    "SELECT DISTINCT org_id FROM call"
+
+    # preferred
+    point/bounded reads in Postgres; aggregate in ClickHouse/BigQuery.
+
+If an aggregate genuinely must run on Postgres (e.g. a tiny bounded admin
+count), suppress with `# sarj-noqa: SARJ020 — <reason>`.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_LINE_COMMENT = re.compile(r"--.*?$", re.MULTILINE)
+_BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.DOTALL)
+# A real SQL query shape — not just the word "from", so prose/LLM-prompt strings
+# (e.g. "distinct from unexpected exceptions") are not mistaken for queries.
+_QUERY_SHAPE = re.compile(
+    r"\bSELECT\b[\s\S]*?\bFROM\b|\bUPDATE\b[\s\S]*?\bSET\b|\bDELETE\b\s+FROM\b",
+    re.IGNORECASE,
+)
+
+# ClickHouse IS the place for aggregation. A file that talks to ClickHouse (the
+# columnar mirror) is exempt — only Postgres store queries are in scope.
+_CLICKHOUSE_FILE = re.compile(
+    r"\bclickhouse_connect\b|\bclickhouse_driver\b|^\s*import\s+clickhouse\b",
+    re.MULTILINE,
+)
+# Belt-and-braces: a single query using ClickHouse-only functions is ClickHouse.
+_CLICKHOUSE_SQL = re.compile(
+    r"\barg(?:Max|Min)\b|\b_peerdb|\bJSONExtract|\buniqExact\b|\bgroupArray\b"
+    r"|\barrayJoin\b|\bquantile\w*\(",
+)
+
+_AGGREGATIONS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("COUNT(", re.compile(r"\bCOUNT\s*\(", re.IGNORECASE)),
+    ("GROUP BY", re.compile(r"\bGROUP\s+BY\b", re.IGNORECASE)),
+    ("DISTINCT", re.compile(r"\bDISTINCT\b", re.IGNORECASE)),
+)
+
+
+def _string_value(node: ast.expr) -> str | None:
+    """Reconstruct a (possibly `+`-concatenated) string literal, else None."""
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        left = _string_value(node.left)
+        right = _string_value(node.right)
+        if left is not None and right is not None:
+            return left + right
+    return None
+
+
+def _strip_sql_comments(text: str) -> str:
+    return _BLOCK_COMMENT.sub(" ", _LINE_COMMENT.sub("", text))
+
+
+class NoAggregationInStoreQuery(Rule):
+    """DISTINCT / GROUP BY / COUNT in a store query — aggregate in ClickHouse."""
+
+    id = "no-aggregation-in-store-query"
+    code = "SARJ020"
+    description = (
+        "DISTINCT / GROUP BY / COUNT in a Postgres store query — push heavy "
+        "aggregation to the columnar mirror (ClickHouse / BigQuery)."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if _CLICKHOUSE_FILE.search(source):
+            return []
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+
+        diags: list[Diagnostic] = []
+        consumed: set[int] = set()
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Constant | ast.BinOp):
+                continue
+            if id(node) in consumed:
+                continue
+            text = _string_value(node)
+            if text is None:
+                continue
+            consumed.update(id(sub) for sub in ast.walk(node))
+
+            sql = _strip_sql_comments(text)
+            if _QUERY_SHAPE.search(sql) is None or _CLICKHOUSE_SQL.search(sql):
+                continue
+            found = [label for label, pat in _AGGREGATIONS if pat.search(sql)]
+            if not found:
+                continue
+
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"Store query uses {', '.join(found)} — push heavy "
+                        "aggregation to ClickHouse / BigQuery, keep Postgres to "
+                        "point/bounded reads. Suppress with `# sarj-noqa: SARJ020`."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags