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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.10.1
+Version: 0.11.1
 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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.10.1"
+version = "0.11.1"
 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.1}/src/sarj_python_lint/rules/_registry.py

@@ -9,15 +9,20 @@ 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_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 +30,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 +59,10 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferStrEnum.id: PreferStrEnum,
     NoFatTryBlocks.id: NoFatTryBlocks,
     NoIsinstanceUnionChain.id: NoIsinstanceUnionChain,
+    NoOffsetPagination.id: NoOffsetPagination,
+    PreferNamedtupleOverTupleReturn.id: PreferNamedtupleOverTupleReturn,
+    NoCorsWildcardWithCredentials.id: NoCorsWildcardWithCredentials,
+    NoSleepInTestBody.id: NoSleepInTestBody,
     PydanticAtBoundaries.id: PydanticAtBoundaries,
     NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,
     NoUnreachableAfterTerminal.id: NoUnreachableAfterTerminal,

sarj_python_lint-0.11.1/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.1/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.1/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.1/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)