sarj-python-lint 0.10.1__tar.gz → 0.11.0__tar.gz

{sarj_python_lint-0.10.1 → sarj_python_lint-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.10.1
+Version: 0.11.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

{sarj_python_lint-0.10.1 → sarj_python_lint-0.11.0}/pyproject.toml

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

{sarj_python_lint-0.10.1 → sarj_python_lint-0.11.0}/src/sarj_python_lint/rules/_registry.py

@@ -5,19 +5,27 @@ from typing import TYPE_CHECKING
 from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
 )
+from sarj_python_lint.rules.json_response_not_parsed import JsonResponseNotParsed
+from sarj_python_lint.rules.len_as_truthiness import LenAsTruthiness
 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_cors_wildcard_with_credentials import (
+    NoCorsWildcardWithCredentials,
+)
 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_manual_log_prefix import NoManualLogPrefix
+from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
 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_sleep_in_test_body import NoSleepInTestBody
 from sarj_python_lint.rules.no_unreachable_after_terminal import (
     NoUnreachableAfterTerminal,
 )
@@ -25,6 +33,9 @@ from sarj_python_lint.rules.prefer_class_row import PreferClassRow
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
     PreferConstantTimeSecretCompare,
 )
+from sarj_python_lint.rules.prefer_namedtuple_over_tuple_return import (
+    PreferNamedtupleOverTupleReturn,
+)
 from sarj_python_lint.rules.prefer_str_enum import PreferStrEnum
 from sarj_python_lint.rules.prefer_struct_over_namedtuple import (
     PreferStructOverNamedtuple,
@@ -51,6 +62,13 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferStrEnum.id: PreferStrEnum,
     NoFatTryBlocks.id: NoFatTryBlocks,
     NoIsinstanceUnionChain.id: NoIsinstanceUnionChain,
+    NoOffsetPagination.id: NoOffsetPagination,
+    PreferNamedtupleOverTupleReturn.id: PreferNamedtupleOverTupleReturn,
+    LenAsTruthiness.id: LenAsTruthiness,
+    NoCorsWildcardWithCredentials.id: NoCorsWildcardWithCredentials,
+    NoManualLogPrefix.id: NoManualLogPrefix,
+    JsonResponseNotParsed.id: JsonResponseNotParsed,
+    NoSleepInTestBody.id: NoSleepInTestBody,
     PydanticAtBoundaries.id: PydanticAtBoundaries,
     NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,
     NoUnreachableAfterTerminal.id: NoUnreachableAfterTerminal,

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/json_response_not_parsed.py

@@ -0,0 +1,110 @@
+"""SARJ030: flag an external JSON payload consumed untyped.
+
+A `.json()` call (no args) or a `json.loads(...)` / `json.load(...)` result used
+*directly* — subscripted (`["k"]`), `.get(...)`-ed, or attribute-chained — reaches
+into an external payload's shape without ever parsing it into a pydantic model.
+When the vendor changes that shape the access breaks silently at runtime instead
+of at a validated boundary.
+
+    resp.json()["access_token"]        # fires
+    resp.json().get("data")            # fires
+    (await client.get(u)).json()["k"]  # fires
+    json.loads(body)["id"]             # fires
+
+Parse the payload first: `Token.model_validate(resp.json())`, then read typed
+attributes off the model.
+
+This is an access-shape signal, distinct from the annotation-based SARJ008 /
+ANN401 (`dict[str, Any]` parameters): those catch an untyped *type*, this catches
+an untyped *use* of a live external response with no annotation at all.
+
+Deliberately NOT flagged (keeps false positives at zero):
+- assign-then-subscript (`d = resp.json(); d["k"]`) — only DIRECT chaining off the
+  `.json()` / `json.loads()` call is tracked; a bound name could be anything,
+- a `.json(...)` call WITH arguments — that receiver is not the payload accessor,
+- the payload passed to a parser (`Model.model_validate(resp.json())`) rather than
+  subscripted — that IS the parse we want,
+- a plain dict/list literal subscript (`{"a": 1}["a"]`),
+- a bare `.json` attribute that is never called, and `json.dumps(...)`.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class JsonResponseNotParsed(Rule):
+    """External JSON payload consumed untyped instead of parsed into a model."""
+
+    id: str = "json-response-not-parsed"
+    code: str = "SARJ030"
+    description: str = (
+        "A `.json()` / `json.loads()` result is subscripted, `.get()`-ed, or "
+        "attribute-chained directly — parse it into a pydantic model first."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            value = _direct_accessed_value(node)
+            if value is None or not _is_json_payload_call(value):
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "External JSON payload consumed untyped — parse the "
+                        "`.json()` / `json.loads()` result into a pydantic model "
+                        "before subscripting or attribute access."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _direct_accessed_value(node: ast.AST) -> ast.expr | None:
+    """The receiver being read off, if `node` reaches directly into a value.
+
+    Covers the three access shapes — `<value>[...]` (Subscript), `<value>.attr`
+    (Attribute, which also covers `<value>.get(...)` since `.get` is an
+    attribute), and nothing else. Returns the `<value>` expression, or None.
+    """
+    if isinstance(node, ast.Subscript):
+        return node.value
+    if isinstance(node, ast.Attribute):
+        return node.value
+    return None
+
+
+def _is_json_payload_call(node: ast.expr) -> bool:
+    """True for a JSON-payload-producing call: `<x>.json()` with NO args, or
+    `json.loads(...)` / `json.load(...)`.
+
+    A `.json(...)` call with any positional or keyword argument is not the payload
+    accessor and is skipped.
+    """
+    if not isinstance(node, ast.Call):
+        return False
+    func = node.func
+    if not isinstance(func, ast.Attribute):
+        return False
+    if func.attr == "json":
+        return not node.args and not node.keywords
+    if func.attr in {"loads", "load"}:
+        return isinstance(func.value, ast.Name) and func.value.id == "json"
+    return False

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/len_as_truthiness.py

@@ -0,0 +1,126 @@
+"""SARJ027: flag `len(x) <cmp> 0|1` comparisons that are just a truthiness test.
+
+Six zero-boundary forms of `len(x)` compared against `0` or `1` are exactly
+equivalent to testing the container's truthiness — an empty container is falsy,
+a non-empty one is truthy:
+
+    len(x) == 0   ->  not x
+    len(x) < 1    ->  not x
+    len(x) <= 0   ->  not x
+    len(x) != 0   ->  x
+    len(x) > 0    ->  x
+    len(x) >= 1   ->  x
+
+`len(x)` allocates nothing but reads as size arithmetic; the truthiness form is
+shorter and states the intent. pylint shipped this as C1802/C1803 but neither
+check was ever ported to ruff, so it is genuinely uncovered.
+
+Deliberately NOT flagged — these are real size checks, not truthiness:
+- exact-count / other-boundary comparisons (`len(x) == 1`, `>= 2`, `> 1`, `< 2`,
+  `== 3`, ...); only the six zero-boundary forms above collapse to truthiness,
+- a right-hand constant other than `0`/`1` (or a bool literal `True`/`False`),
+- anything that is not literally `len(<one expr>)` on the left — a different
+  builtin (`count(x) == 0`), `len` with 0/2+ args, or `len` called via attribute,
+- chained comparisons (`0 < len(x) < 5`) — more than one operator,
+- `x == []` / `x == {}` — a different check (it excludes `None`; see the
+  separate empty-collection-literal rule).
+
+The yoda form `0 == len(x)` is intentionally not handled (rare; would widen the
+signal for little gain).
+
+References:
+- https://pylint.readthedocs.io/en/latest/user_guide/messages/refactor/use-implicit-booleaness-not-len.html
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# (comparison-operator type, right-hand int constant) pairs that are equivalent to a
+# plain truthiness test, mapped to the truthy suggestion ("x") or falsy one ("not x").
+_TRUTHINESS_FORMS: dict[tuple[type[ast.cmpop], int], str] = {
+    (ast.Eq, 0): "not x",
+    (ast.Lt, 1): "not x",
+    (ast.LtE, 0): "not x",
+    (ast.NotEq, 0): "x",
+    (ast.Gt, 0): "x",
+    (ast.GtE, 1): "x",
+}
+
+
+class LenAsTruthiness(Rule):
+    """`len(x) <cmp> 0|1` zero-boundary comparisons — prefer a plain truthiness test."""
+
+    id: str = "len-as-truthiness"
+    code: str = "SARJ027"
+    description: str = (
+        "len(x) compared against 0/1 at a zero boundary is a truthiness test — "
+        "use `x` / `not x` instead of `len(x)`."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Compare):
+                continue
+            suggestion = _truthiness_suggestion(node)
+            if suggestion is None:
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"len(...) compared against a zero boundary is a truthiness "
+                        f"test — use `{suggestion}` instead of `len(...)`."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _truthiness_suggestion(node: ast.Compare) -> str | None:
+    """The `x`/`not x` suggestion if `node` is a zero-boundary `len(...)` compare, else None."""
+    if len(node.ops) != 1 or len(node.comparators) != 1:
+        return None
+    if not _is_len_call(node.left):
+        return None
+    const = _int_constant(node.comparators[0])
+    if const is None:
+        return None
+    return _TRUTHINESS_FORMS.get((type(node.ops[0]), const))
+
+
+def _is_len_call(expr: ast.expr) -> bool:
+    """True iff `expr` is literally `len(<single positional expr>)`."""
+    if not isinstance(expr, ast.Call):
+        return False
+    if not (isinstance(expr.func, ast.Name) and expr.func.id == "len"):
+        return False
+    if len(expr.args) != 1 or expr.keywords:
+        return False
+    return not isinstance(expr.args[0], ast.Starred)
+
+
+def _int_constant(expr: ast.expr) -> int | None:
+    """The int value of a plain integer literal, else None. Bool literals are excluded."""
+    if not isinstance(expr, ast.Constant):
+        return None
+    if type(expr.value) is not int:
+        return None
+    return expr.value

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/no_cors_wildcard_with_credentials.py

@@ -0,0 +1,89 @@
+"""SARJ028: detect Starlette/FastAPI CORS that echoes any Origin with credentials.
+
+`CORSMiddleware(allow_credentials=True, allow_origins=[..., "*", ...])` tells the
+browser to reflect the request's `Origin` back in
+`Access-Control-Allow-Origin` AND to send `Access-Control-Allow-Credentials:
+true`. Together these let *any* website read authenticated (cookie/session)
+responses — a cross-origin credential-theft surface.
+
+The rule fires on an `ast.Call` that has BOTH `allow_credentials=True`
+(literal) AND an `allow_origins` value whose subtree contains a `"*"` string
+literal anywhere — so it catches the bare `["*"]` form as well as the
+`allowed if flag else ["*"]` conditional branch. The keyword pair is unique to
+Starlette's CORSMiddleware, so matching the callee name is unnecessary (though it
+would be a valid further tightening).
+
+References:
+- https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#credentialed_requests_and_wildcards
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class NoCorsWildcardWithCredentials(Rule):
+    """CORS that reflects any Origin while allowing credentials."""
+
+    id: str = "no-cors-wildcard-with-credentials"
+    code: str = "SARJ028"
+    description: str = (
+        'CORS `allow_credentials=True` with `"*"` in `allow_origins` lets any '
+        "site read authenticated responses."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            keywords = {kw.arg: kw.value for kw in node.keywords if kw.arg is not None}
+            credentials = keywords.get("allow_credentials")
+            origins = keywords.get("allow_origins")
+            if credentials is None or origins is None:
+                continue
+            if not _is_true_literal(credentials):
+                continue
+            if not _contains_star_literal(origins):
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        'CORS reflects any Origin (`"*"` in `allow_origins`) while '
+                        "`allow_credentials=True` — any site can read authenticated "
+                        "responses. Enumerate explicit trusted origins instead."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _is_true_literal(node: ast.expr) -> bool:
+    """True only for the literal `True` (not `1`, not a truthy expression)."""
+    return isinstance(node, ast.Constant) and node.value is True
+
+
+def _contains_star_literal(node: ast.expr) -> bool:
+    """True if a `"*"` string `Constant` appears anywhere in `node`'s subtree.
+
+    Walking the whole subtree catches both `["*"]` and the `allowed if flag else
+    ["*"]` conditional branch. A dynamic `allow_origins=some_var` has no `"*"`
+    literal, so it does not fire.
+    """
+    return any(isinstance(child, ast.Constant) and child.value == "*" for child in ast.walk(node))

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/no_manual_log_prefix.py

@@ -0,0 +1,146 @@
+"""SARJ029: flag a manual `"[Component] ..."` bracket tag in a logging message.
+
+The house logging style is structured: identify the emitting component with a
+bound field so aggregators can filter on it, rather than baking the label into
+the message text where it can only be grepped:
+
+    # flagged
+    logger.info("[STT] transcription finished")
+
+    # preferred
+    logger.bind(component="STT").info("transcription finished")
+
+A leading `[Tag]` in the literal message duplicates context that belongs in
+structured metadata and fragments template grouping. This is distinct from
+SARJ017 (no-fstring-in-log) / ruff G004, which fire only on *interpolating*
+f-strings; the messages caught here are plain string literals.
+
+To keep false positives near zero the rule requires BOTH a logger-like receiver
+(resolved through builder/factory chains via `is_logger_expr`) AND a logging
+method name, and only inspects the message argument (arg 1 for
+`logger.log(LEVEL, msg)`, arg 0 otherwise).
+
+The bracket tag must be a *component* label, not incidental data. The match
+pattern allows only letters, spaces, underscores and hyphens inside the
+brackets and requires at least one letter, so data-shaped brackets never match:
+`[Errno 2]` (digit), `[1, 2]` (digit/comma), `['a', 'b']` (quotes/comma),
+`[12:34]` (colon) are all excluded, while `[STT]`, `[TTS Pronunciation]` and
+`[AgentDispatch]` match. Empirically this matches 0 data brackets across the
+bulbul (273 hits) and noura (24 hits) corpora.
+
+Suppress an intentional case with `# sarj-noqa: SARJ029 — <reason>`.
+"""
+
+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._logging import is_logger_expr
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_LOG_METHODS = frozenset(
+    {
+        "debug",
+        "info",
+        "warning",
+        "warn",
+        "error",
+        "exception",
+        "critical",
+        "fatal",
+        "trace",
+        "success",
+        "log",
+    }
+)
+
+_PREFIX_RE = re.compile(r"^\[[A-Za-z_ -]*[A-Za-z][A-Za-z_ -]*\]")
+
+_LOG_LEVEL_AND_MESSAGE_ARGC = 2
+
+
+class NoManualLogPrefix(Rule):
+    """Manual `[Component]` prefix in a logging message — bind it as structured context."""
+
+    id: str = "no-manual-log-prefix"
+    code: str = "SARJ029"
+    description: str = (
+        "manual '[Component]' prefix in a logging message — bind the component as "
+        "structured context (logger.bind(component=...)) so aggregators filter on a "
+        "field instead of grepping baked-in text."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call) or not _is_logging_call(node):
+                continue
+            message = _message_arg(node)
+            if message is None:
+                continue
+            leading = _leading_static_str(message)
+            if leading is None or not _PREFIX_RE.match(leading):
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "manual '[Component]' prefix in a logging message — bind it as "
+                        "structured context (logger.bind(component=...)) instead."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _is_logging_call(node: ast.Call) -> bool:
+    func = node.func
+    if not isinstance(func, ast.Attribute) or func.attr not in _LOG_METHODS:
+        return False
+    return is_logger_expr(func.value)
+
+
+def _message_arg(node: ast.Call) -> ast.expr | None:
+    """The message argument: index 1 for `logger.log(LEVEL, msg)`, else index 0.
+
+    A `.log` call carrying fewer than two positionals has no message argument (the
+    lone positional is the level), so there is nothing to inspect.
+    """
+    if isinstance(node.func, ast.Attribute) and node.func.attr == "log":
+        return node.args[1] if len(node.args) >= _LOG_LEVEL_AND_MESSAGE_ARGC else None
+    return node.args[0] if node.args else None
+
+
+def _leading_static_str(node: ast.expr) -> str | None:
+    """The leading static string of a message expr, or None if there isn't one.
+
+    Handles a bare string literal, the leading literal chunk of an f-string, and
+    the left operand of a `+`-concatenation (recursively), so a baked-in prefix
+    is found even when the value is later interpolated or concatenated.
+    """
+    match node:
+        case ast.Constant(value=str() as value):
+            return value
+        case ast.JoinedStr(values=[ast.Constant(value=str() as value), *_]):
+            return value
+        case ast.JoinedStr():
+            return None
+        case ast.BinOp(op=ast.Add(), left=left):
+            return _leading_static_str(left)
+        case _:
+            return None

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/no_offset_pagination.py

@@ -0,0 +1,98 @@
+"""SARJ025: no `OFFSET` pagination in a store query — use a keyset cursor.
+
+`LIMIT n OFFSET m` makes the database scan and discard every one of the `m`
+skipped rows before returning page contents, so page N costs O(N): deep pages get
+linearly slower and, under concurrent inserts, rows shift between pages (an item
+can be shown twice or skipped). Keyset / cursor pagination
+(`WHERE id > :cursor ORDER BY id LIMIT n`) is O(page) and stable. This mirrors the
+SQL-migration linter's `no-limit-offset` (SARJ107), but for the SQL embedded in
+Python store queries — where application pagination actually lives.
+
+The rule walks SQL string literals embedded in `.py`, neutralizes string-literal
+values and `--` / `/* */` comments first (so an `'offset'` value or a prose
+`"offset out of range"` message is never mistaken for the keyword), and flags an
+`OFFSET` keyword immediately followed by a value/param token (`%s`, `%(name)s`,
+`:name`, `@name`, `$1`, or a digit) — the real pagination construct. Requiring the
+value token excludes the English word and BigQuery's `UNNEST(...) WITH OFFSET AS
+col` array indexing (which has no value after `OFFSET`).
+
+    # flagged
+    "SELECT id, status FROM call ORDER BY created_at LIMIT %s OFFSET %s"
+    " LIMIT %s OFFSET %s"          # a paginated-query fragment
+
+    # preferred
+    "SELECT id, status FROM call WHERE id > %s ORDER BY id LIMIT %s"
+
+Suppress a deliberate case (e.g. a bounded admin export) with
+`# sarj-noqa: SARJ025 — <reason>`.
+"""
+
+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._sql import sql_string_value, strip_sql_noise
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# `OFFSET` followed by a value/param token — the real pagination construct. This
+# excludes the English word ("no base offset"), `'offset'` dict keys, and BigQuery
+# `UNNEST(...) WITH OFFSET AS col` (array indexing, no value token after OFFSET).
+_OFFSET_PAGINATION = re.compile(
+    r"\bOFFSET\s+(?:%s|%\(\w+\)s|:\w+|@\w+|\$\d+|\d+)", re.IGNORECASE
+)
+
+
+class NoOffsetPagination(Rule):
+    """`OFFSET` pagination in a store query — use a keyset cursor instead."""
+
+    id: str = "no-offset-pagination"
+    code: str = "SARJ025"
+    description: str = (
+        "OFFSET pagination is O(N) and unstable under concurrent writes — use a "
+        "keyset cursor (WHERE id > :cursor ORDER BY id LIMIT n)."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            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 = sql_string_value(node)
+            if text is None:
+                continue
+            consumed.update(id(sub) for sub in ast.walk(node))
+
+            sql = strip_sql_noise(text)
+            if _OFFSET_PAGINATION.search(sql) is None:
+                continue
+
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "Store query uses OFFSET pagination (O(N), unstable under "
+                        "concurrent writes) — use a keyset cursor (WHERE id > :cursor "
+                        "ORDER BY id LIMIT n). Suppress with `# sarj-noqa: SARJ025`."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/no_sleep_in_test_body.py

@@ -0,0 +1,146 @@
+"""SARJ031: a nonzero `sleep()` directly in a `test_*` body is a flaky-test smell.
+
+`asyncio.sleep(0.01)` / `time.sleep(1)` placed straight in a test function body is
+the canonical flaky-test pattern: under CI load the fixed delay is nondeterministic
+(too short → the awaited work has not finished; the test flakes), and it slows the
+suite for no benefit. The fix is to synchronize on the actual signal — await the
+awaitable, wait on an `Event`, or poll a condition with a timeout.
+
+This is test-scoped and genuinely uncovered: ruff ASYNC251 only flags blocking
+`time.sleep` inside an `async def`, and nothing flags `asyncio.sleep(nonzero)`.
+
+Fires only on the exact shape:
+
+* a call `asyncio.sleep(<arg>)` or `time.sleep(<arg>)` (receiver is the bare name
+  `asyncio` or `time`),
+* where `<arg>` is a **nonzero numeric literal** (`int`/`float` `ast.Constant`) —
+  `sleep(0)` is a cooperative yield, not a timing hack, and a non-literal
+  `sleep(delay)` is a deliberate configured wait, so both are skipped, and
+* whose **nearest enclosing function is a `test_*`-named** `def`/`async def`.
+
+Critical false-positive guard: the sleep must sit DIRECTLY in the test body, with
+no intervening nested `def`/`async def`/`lambda`. A sleep inside a nested helper /
+fake coroutine declared within the test (`_hang`, `_slow`, `mock_*`) deliberately
+simulates latency to exercise cancellation/timeout paths — that is the intended
+use, not a flaky sync, and it must not fire. Because the check keys off the
+*nearest* enclosing function, such a nested helper (not `test_*`-named) is excluded
+automatically.
+
+Applies only in test files (stem `test_*.py`, `*_test.py`, `conftest.py`, or a path
+under a `tests`/`test` directory).
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_SLEEP_RECEIVERS = frozenset({"asyncio", "time"})
+_FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+def _is_test_path(path: Path) -> bool:
+    name = path.name
+    if name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    return any(part in {"tests", "test"} for part in path.parts)
+
+
+def _is_nonzero_numeric_literal(node: ast.expr) -> bool:
+    return (
+        isinstance(node, ast.Constant)
+        and isinstance(node.value, (int, float))
+        and not isinstance(node.value, bool)
+        and node.value != 0
+    )
+
+
+def _is_sleep_call(node: ast.Call) -> bool:
+    func = node.func
+    return (
+        isinstance(func, ast.Attribute)
+        and func.attr == "sleep"
+        and isinstance(func.value, ast.Name)
+        and func.value.id in _SLEEP_RECEIVERS
+        and len(node.args) >= 1
+        and _is_nonzero_numeric_literal(node.args[0])
+    )
+
+
+class NoSleepInTestBody(Rule):
+    """Nonzero `sleep()` directly in a `test_*` body — flaky timing sync."""
+
+    id: str = "no-sleep-in-test-body"
+    code: str = "SARJ031"
+    description: str = "Nonzero `sleep()` in a test body — synchronize on the signal, don't sleep."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not _is_test_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        visitor = _SleepInTestBodyVisitor()
+        visitor.visit(tree)
+        diags = [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=(
+                    "nonzero `sleep()` directly in a test body flakes under CI load — "
+                    "await the awaitable, wait on an `Event`, or poll the condition instead."
+                ),
+            )
+            for node in visitor.hits
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+class _SleepInTestBodyVisitor(ast.NodeVisitor):
+    """Flag sleep calls whose NEAREST enclosing function is a `test_*` def.
+
+    Maintains a stack of enclosing-function names (`None` for a lambda, which has
+    no name and can never be a test). Only the top of the stack — the nearest
+    enclosing function — is consulted, so a sleep inside a nested helper/fake
+    coroutine declared within a test is attributed to that helper, not the test,
+    and does not fire.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._func_names: list[str | None] = []
+        self.hits: list[ast.Call] = []
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        self._func_names.append(node.name)
+        self.generic_visit(node)
+        self._func_names.pop()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_Lambda(self, node: ast.Lambda) -> None:
+        self._func_names.append(None)
+        self.generic_visit(node)
+        self._func_names.pop()
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if self._func_names and _is_sleep_call(node):
+            nearest = self._func_names[-1]
+            if nearest is not None and nearest.startswith("test_"):
+                self.hits.append(node)
+        self.generic_visit(node)

sarj_python_lint-0.11.0/src/sarj_python_lint/rules/prefer_namedtuple_over_tuple_return.py

@@ -0,0 +1,156 @@
+"""SARJ026: flag public functions returning a bare positional `tuple[A, B, ...]`.
+
+A multi-field value returned across a boundary — from a public function (name not
+starting `_`) — must be a `NamedTuple` (or a frozen pydantic model when it needs
+validation), never a positional `tuple[A, B]` the caller has to unpack by position.
+A bare `tuple[bytes, dict, str | None]` return forces every caller to remember which
+slot is which; a typo swaps two fields silently. A named result gives each field a
+name and lets pyright catch a wrong-order access.
+
+    # flagged
+    def download_to_memory(...) -> tuple[bytes, dict[str, str], str | None]:
+        ...
+
+    # preferred
+    class Download(NamedTuple):
+        body: bytes
+        headers: dict[str, str]
+        content_type: str | None
+
+    def download_to_memory(...) -> Download:
+        ...
+
+The three tuple uses CLAUDE.md permits are deliberately NOT flagged:
+- `tuple[X, ...]` — an immutable homogeneous sequence (Ellipsis form),
+- `tuple[X, X]` — structurally homogeneous (every element identical, e.g.
+  `tuple[int, int]`), a pair of the same thing rather than distinct fields,
+- `tuple[Literal["both"], A, B]` — a discriminated-union tag (first element a
+  `Literal[...]`).
+
+Also NOT flagged: private (`_`-prefixed) functions, single-element `tuple[X]`,
+a bare unsubscripted `tuple`, and any non-tuple / unannotated return.
+
+Suppress a deliberate positional return with `# sarj-noqa: SARJ026 — <reason>`.
+
+References:
+- https://docs.python.org/3/library/typing.html#typing.NamedTuple
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TUPLE_NAMES = frozenset({"tuple", "Tuple"})
+_LITERAL_NAMES = frozenset({"Literal"})
+
+_MIN_ELEMENTS = 2
+
+_MSG = (
+    "public function returns a bare positional tuple[...] — callers must unpack by "
+    "position; prefer a NamedTuple (or a frozen pydantic model for boundary values)."
+)
+
+
+class PreferNamedtupleOverTupleReturn(Rule):
+    """Public function returning a bare positional `tuple[A, B, ...]` — prefer a NamedTuple."""
+
+    id: str = "prefer-namedtuple-over-tuple-return"
+    code: str = "SARJ026"
+    description: str = (
+        "public function returning a bare positional tuple[A, B, ...] — prefer a "
+        "NamedTuple or frozen pydantic model so callers don't unpack by position."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if node.name.startswith("_"):
+                continue
+            if node.returns is None:
+                continue
+            if not _is_bare_positional_tuple(node.returns):
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=_MSG,
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _is_bare_positional_tuple(annotation: ast.expr) -> bool:
+    """True if `annotation` is `tuple[A, B, ...]` with >=2 heterogeneous elements.
+
+    Exempts the three permitted forms: `tuple[X, ...]` (Ellipsis), structurally
+    homogeneous `tuple[X, X]`, and the `tuple[Literal[...], ...]` discriminated tag.
+    """
+    if not isinstance(annotation, ast.Subscript):
+        return False
+    if _name_of(annotation.value) not in _TUPLE_NAMES:
+        return False
+    if not isinstance(annotation.slice, ast.Tuple):
+        return False
+    elements = annotation.slice.elts
+    if len(elements) < _MIN_ELEMENTS:
+        return False
+    if any(_is_ellipsis(el) for el in elements):
+        return False
+    if _all_equal(elements):
+        return False
+    return not _is_literal(elements[0])
+
+
+def _all_equal(elements: list[ast.expr]) -> bool:
+    """True if every element is structurally identical (a homogeneous pair/tuple)."""
+    first = elements[0]
+    return all(_ast_equal(el, first) for el in elements[1:])
+
+
+def _is_ellipsis(node: ast.expr) -> bool:
+    return isinstance(node, ast.Constant) and node.value is Ellipsis
+
+
+def _is_literal(node: ast.expr) -> bool:
+    """True if `node` is a `Literal[...]` subscript (discriminated-union tag)."""
+    return isinstance(node, ast.Subscript) and _name_of(node.value) in _LITERAL_NAMES
+
+
+def _name_of(node: ast.expr) -> str | None:
+    """Trailing name of a reference: `tuple` / `typing.Tuple` -> the trailing id."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def _ast_equal(a: object, b: object) -> bool:
+    """Structural equality equivalent to `ast.dump(a) == ast.dump(b)` without the dump."""
+    if isinstance(a, ast.AST):
+        if type(a) is not type(b):
+            return False
+        return all(_ast_equal(getattr(a, field, None), getattr(b, field, None)) for field in a._fields)
+    if isinstance(a, list):
+        if not isinstance(b, list) or len(a) != len(b):
+            return False
+        return all(map(_ast_equal, a, b, strict=True))
+    return type(a) is type(b) and repr(a) == repr(b)