sarj-python-lint 0.67.11__tar.gz → 0.67.13__tar.gz

{sarj_python_lint-0.67.11 → sarj_python_lint-0.67.13}/.gitignore

@@ -37,3 +37,4 @@ Thumbs.db
 !.claude/settings.json
 .worktrees/
 .sarj-private-refs.toml
+.sarj-standards-rollout.toml

{sarj_python_lint-0.67.11 → sarj_python_lint-0.67.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.67.11
+Version: 0.67.13
 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.67.11 → sarj_python_lint-0.67.13}/pyproject.toml

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

{sarj_python_lint-0.67.11 → sarj_python_lint-0.67.13}/src/sarj_python_lint/rules/_fastapi.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import ast
 from collections import Counter
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, NamedTuple
+from typing import TYPE_CHECKING, Literal, NamedTuple
 
 
 if TYPE_CHECKING:
@@ -41,6 +41,7 @@ class Route:
     receiver: str
     method: str
     path: str | None
+    receiver_kind: Literal["FastAPI", "APIRouter"]
     inherited_hidden: bool = False
 
     @property
@@ -114,6 +115,7 @@ class FastapiIndex:
         self.type_aliases: dict[str, ast.expr] = {}
         self.receivers: set[tuple[int, str]] = set()
         self.receiver_origins: dict[tuple[int, str], tuple[int, str]] = {}
+        self.receiver_kinds: dict[tuple[int, str], Literal["FastAPI", "APIRouter"]] = {}
         self.hidden_receivers: set[tuple[int, str]] = set()
         self.decorators: dict[tuple[int, str], tuple[str, str]] = {}
         self.bound_names: set[tuple[int, str]] = set()
@@ -228,10 +230,20 @@ class FastapiIndex:
                 if key in self.receivers or key in self.decorators:
                     continue
                 source = self._receiver_key(scope, _binding_name(value))
-                if self._is_constructor_call(value) or source is not None:
+                constructor_kind = self._constructor_kind(value)
+                if constructor_kind is not None:
                     self.receivers.add(key)
-                    self.receiver_origins[key] = key if source is None else self.receiver_origins[source]
-                    if self._constructor_is_hidden(value) or (source is not None and source in self.hidden_receivers):
+                    self.receiver_origins[key] = key
+                    self.receiver_kinds[key] = constructor_kind
+                    if self._constructor_is_hidden(value):
+                        self.hidden_receivers.add(key)
+                    changed = True
+                    continue
+                if source is not None:
+                    self.receivers.add(key)
+                    self.receiver_origins[key] = self.receiver_origins[source]
+                    self.receiver_kinds[key] = self.receiver_kinds[source]
+                    if source in self.hidden_receivers:
                         self.hidden_receivers.add(key)
                     changed = True
                     continue
@@ -276,16 +288,26 @@ class FastapiIndex:
         return isinstance(value, ast.Constant) and value.value is False
 
     def _is_constructor_call(self, node: ast.expr) -> bool:
+        return self._constructor_kind(node) is not None
+
+    def _constructor_kind(self, node: ast.expr) -> Literal["FastAPI", "APIRouter"] | None:
         if not isinstance(node, ast.Call):
-            return False
+            return None
         if isinstance(node.func, ast.Name):
-            return node.func.id in self.constructors
-        return (
+            canonical = self.symbols.get(node.func.id)
+            if canonical == "FastAPI":
+                return "FastAPI"
+            if canonical == "APIRouter":
+                return "APIRouter"
+            return None
+        if (
             isinstance(node.func, ast.Attribute)
             and isinstance(node.func.value, ast.Name)
             and node.func.value.id in self.modules
             and node.func.attr in {"FastAPI", "APIRouter"}
-        )
+        ):
+            return "FastAPI" if node.func.attr == "FastAPI" else "APIRouter"
+        return None
 
     def routes(self, function: ast.FunctionDef | ast.AsyncFunctionDef) -> tuple[Route, ...]:
         routes: list[Route] = []
@@ -321,6 +343,7 @@ class FastapiIndex:
                     receiver=f"{origin_scope}:{origin_name}",
                     method=route_method,
                     path=path,
+                    receiver_kind=self.receiver_kinds[receiver_key],
                     inherited_hidden=receiver_key in self.hidden_receivers,
                 )
                 for route_method in route_methods

{sarj_python_lint-0.67.11 → sarj_python_lint-0.67.13}/src/sarj_python_lint/rules/_registry.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 from types import MappingProxyType
 from typing import TYPE_CHECKING
 
+from sarj_python_lint.rules.created_at_order_requires_tiebreaker import (
+    CreatedAtOrderRequiresTiebreaker,
+)
 from sarj_python_lint.rules.defect_xfail_requires_strict import DefectXfailRequiresStrict
 from sarj_python_lint.rules.docstring_args_restate_signature import (
     DocstringArgsRestateSignature,
@@ -58,6 +61,9 @@ from sarj_python_lint.rules.no_stdlib_logging import NoStdlibLogging
 from sarj_python_lint.rules.no_string_concat_in_loop import NoStringConcatInLoop
 from sarj_python_lint.rules.no_tautological_expect import NoTautologicalExpect
 from sarj_python_lint.rules.no_typed_doc_sections import NoTypedDocSections
+from sarj_python_lint.rules.no_unique_violation_message_match import (
+    NoUniqueViolationMessageMatch,
+)
 from sarj_python_lint.rules.opaque_parametrize_case_needs_id import OpaqueParametrizeCaseNeedsId
 from sarj_python_lint.rules.over_mocked_test import OverMockedTest
 from sarj_python_lint.rules.phase_label_comment import TestPhaseLabelComment
@@ -125,6 +131,7 @@ if TYPE_CHECKING:
 
 REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
     {
+        CreatedAtOrderRequiresTiebreaker.id: CreatedAtOrderRequiresTiebreaker,
         NoStringConcatInLoop.id: NoStringConcatInLoop,
         PreferClassRow.id: PreferClassRow,
         PreferStrEnum.id: PreferStrEnum,
@@ -196,6 +203,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoLongComment.id: NoLongComment,
         NoTypedDocSections.id: NoTypedDocSections,
         PreferNominalIdTypes.id: PreferNominalIdTypes,
+        NoUniqueViolationMessageMatch.id: NoUniqueViolationMessageMatch,
     }
 )
 

sarj_python_lint-0.67.13/src/sarj_python_lint/rules/created_at_order_requires_tiebreaker.py

@@ -0,0 +1,193 @@
+"""SARJ407 — Store queries ordered by `created_at` need a later tie-break key.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_created_at_order_requires_tiebreaker.py
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+import re
+from typing import TYPE_CHECKING, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    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._sql import is_store_module, sql_string_value, strip_sql_noise
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_QUERY_SHAPE = re.compile(r"\bSELECT\b[\s\S]*?\bFROM\b", re.IGNORECASE)
+_ORDER_BY = re.compile(r"\bORDER\s+BY\b", re.IGNORECASE)
+_CLAUSE_BOUNDARY = re.compile(
+    r"\b(?:LIMIT|OFFSET|FETCH|FOR|UNION|INTERSECT|EXCEPT|RETURNING|WINDOW|QUALIFY|"
+    r"GROUP\s+BY|HAVING|ORDER\s+BY)\b",
+    re.IGNORECASE,
+)
+_CREATED_AT_ITEM = re.compile(
+    r"(?:(?:[A-Za-z_][A-Za-z0-9_$]*\s*\.\s*)*)created_at"
+    r"(?:\s+(?:ASC|DESC))?(?:\s+NULLS\s+(?:FIRST|LAST))?\s*\Z",
+    re.IGNORECASE,
+)
+
+
+@final
+class CreatedAtOrderRequiresTiebreaker(Rule):
+    id = "created-at-order-requires-tiebreaker"
+    code = "SARJ407"
+    documentation = RuleDocumentation(
+        summary="Store queries ordered by `created_at` should include a later tie-break key.",
+        rationale=(
+            "Timestamps are not unique, so rows with the same `created_at` value have no stable relative order. "
+            "That can make pagination and repeated reads skip, repeat, or reorder rows."
+        ),
+        remediation="Add a stable key after `created_at`, such as `ORDER BY created_at DESC, id DESC`.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only fully reconstructable SQL string literals in recognized production store modules are analyzed.",
+            (
+                "The rule reports an exact, optionally qualified `created_at` column only when it is the final "
+                "same-depth `ORDER BY` item; any later same-depth ordering item is accepted."
+            ),
+            (
+                "Dynamic string construction, formatted strings, quoted identifiers, expressions containing "
+                "`created_at`, and non-SELECT fragments are excluded."
+            ),
+            "The intended stable key cannot be inferred safely, so the rule does not offer an autofix.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="created-at-is-the-only-order-key",
+                title="A store query orders only by a timestamp",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/task_store.py",
+                        'QUERY = "SELECT id, created_at FROM task ORDER BY created_at DESC LIMIT 50"\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/task_store.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="created-at-is-followed-by-id",
+                title="A stable key breaks equal-timestamp ties",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/task_store.py",
+                        'QUERY = "SELECT id, created_at FROM task ORDER BY created_at DESC, id DESC LIMIT 50"\n',
+                    ),
+                ),
+                focus_path=PurePosixPath("app/task_store.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_store_module(path) or is_generated(path, source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        diagnostics: list[Diagnostic] = []
+        consumed: set[int] = set()
+        for node in nodes(tree, ast.Constant, ast.BinOp, ast.JoinedStr):
+            if id(node) in consumed:
+                continue
+            if isinstance(node, (ast.BinOp, ast.JoinedStr)):
+                consumed.update(id(child) for child in walk(node))
+            if not _is_fully_static_string(node):
+                continue
+            text = sql_string_value(node)
+            if text is None:
+                continue
+            sql = strip_sql_noise(text)
+            if _QUERY_SHAPE.search(sql) is None or not _created_at_ends_order_clause(sql):
+                continue
+            diagnostics.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    severity=Severity.WARNING,
+                    message=(
+                        "Store query leaves `created_at` as its final ordering item; add a stable tie-break key "
+                        "after it, such as `id` (for example, `ORDER BY created_at DESC, id DESC`)."
+                    ),
+                )
+            )
+        diagnostics.sort(key=lambda diagnostic: (diagnostic.line, diagnostic.col))
+        return diagnostics
+
+
+def _is_fully_static_string(node: ast.expr) -> bool:
+    if isinstance(node, ast.Constant):
+        return isinstance(node.value, str)
+    return (
+        isinstance(node, ast.BinOp)
+        and isinstance(node.op, ast.Add)
+        and _is_fully_static_string(node.left)
+        and _is_fully_static_string(node.right)
+    )
+
+
+def _created_at_ends_order_clause(sql: str) -> bool:
+    depths = _depths(sql)
+    for order in _ORDER_BY.finditer(sql):
+        clause_depth = depths[order.start()]
+        item_start = order.end()
+        clause_end = len(sql)
+        index = item_start
+        while index < len(sql):
+            if (
+                depths[index] < clause_depth
+                or sql[index] == ";"
+                or (sql[index] == ")" and depths[index] == clause_depth)
+            ):
+                clause_end = index
+                break
+            if depths[index] == clause_depth:
+                if sql[index] == ",":
+                    item_start = index + 1
+                elif _CLAUSE_BOUNDARY.match(sql, index) is not None:
+                    clause_end = index
+                    break
+            index += 1
+        if _CREATED_AT_ITEM.fullmatch(sql[item_start:clause_end].strip()) is not None:
+            return True
+    return False
+
+
+def _depths(sql: str) -> list[int]:
+    depths: list[int] = []
+    depth = 0
+    for character in sql:
+        depths.append(depth)
+        if character == "(":
+            depth += 1
+        elif character == ")" and depth:
+            depth -= 1
+    return depths

sarj_python_lint-0.67.13/src/sarj_python_lint/rules/no_unique_violation_message_match.py

@@ -0,0 +1,175 @@
+"""SARJ404 — Classify unique violations by structured constraint identity.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_no_unique_violation_message_match.py
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    parse_or_none,
+)
+from sarj_python_lint.rules._imports import ImportIndex
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_DRIVERS = frozenset({"psycopg", "psycopg2"})
+
+
+@final
+class NoUniqueViolationMessageMatch(Rule):
+    id = "no-unique-violation-message-match"
+    code = "SARJ404"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        summary="Do not identify a database unique constraint by substring-matching an exception message.",
+        rationale=(
+            "Database error text is not a stable interface and can change with driver or server versions; "
+            "psycopg exposes the violated constraint as structured diagnostic data."
+        ),
+        remediation="Compare `exc.diag.constraint_name` with the expected constraint name.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "The rule recognizes psycopg and psycopg2 `UniqueViolation` handlers with direct `in` or `not in` checks against `str(exc)`.",
+            "Aliases of the stringified exception and other message operations remain outside its scope.",
+            "Tests and generated files are excluded.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="message-matched-constraint",
+                title="Unique constraint selected from error text",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/store.py",
+                        "from psycopg import errors\n\ntry:\n    save()\nexcept errors.UniqueViolation as exc:\n    if 'user_email_key' in str(exc):\n        raise DuplicateEmail from exc\n    raise\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/store.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="structured-constraint-check",
+                title="Unique constraint selected from structured diagnostics",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/store.py",
+                        "from psycopg import errors\n\ntry:\n    save()\nexcept errors.UniqueViolation as exc:\n    if exc.diag.constraint_name == 'user_email_key':\n        raise DuplicateEmail from exc\n    raise\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/store.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path) or is_generated(path, source) or "UniqueViolation" not in source:
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        imports = ImportIndex.from_tree(tree)
+        if not imports.builtin_is_unshadowed("str"):
+            return []
+        findings: list[ast.Call] = []
+        for handler in (node for node in ast.walk(tree) if isinstance(node, ast.ExceptHandler)):
+            if handler.name is None or not _catches_unique_violation(handler.type, tree):
+                continue
+            for statement in handler.body:
+                _collect_message_matches(statement, handler.name, findings)
+        findings.sort(key=lambda node: (node.lineno, node.col_offset))
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=(
+                    "UniqueViolation is classified by substring-matching its message; compare "
+                    "`exc.diag.constraint_name` with the expected constraint instead."
+                ),
+                severity=Severity.WARNING,
+            )
+            for node in findings
+        ]
+
+
+def _catches_unique_violation(node: ast.expr | None, tree: ast.Module) -> bool:
+    if node is None:
+        return False
+    candidates = node.elts if isinstance(node, ast.Tuple) else (node,)
+    return any(
+        _qualified_import(candidate, tree) in {"psycopg.errors.UniqueViolation", "psycopg2.errors.UniqueViolation"}
+        for candidate in candidates
+    )
+
+
+def _qualified_import(node: ast.expr, tree: ast.Module) -> str | None:
+    parts: list[str] = []
+    current = node
+    while isinstance(current, ast.Attribute):
+        parts.append(current.attr)
+        current = current.value
+    if not isinstance(current, ast.Name):
+        return None
+    parts.reverse()
+    for statement in tree.body:
+        if isinstance(statement, ast.Import):
+            for alias in statement.names:
+                local = alias.asname or alias.name.split(".")[0]
+                if local == current.id:
+                    base = alias.name if alias.asname else alias.name.split(".")[0]
+                    return ".".join((base, *parts))
+        elif isinstance(statement, ast.ImportFrom) and statement.level == 0 and statement.module:
+            for alias in statement.names:
+                if (alias.asname or alias.name) != current.id:
+                    continue
+                return ".".join((statement.module, alias.name, *parts))
+    return None
+
+
+def _collect_message_matches(node: ast.AST, exception_name: str, findings: list[ast.Call]) -> None:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+        return
+    if isinstance(node, ast.Compare) and any(isinstance(operator, (ast.In, ast.NotIn)) for operator in node.ops):
+        findings.extend(
+            operand
+            for operand in (node.left, *node.comparators)
+            if isinstance(operand, ast.Call) and _is_str_exception_call(operand, exception_name)
+        )
+    for child in ast.iter_child_nodes(node):
+        _collect_message_matches(child, exception_name, findings)
+
+
+def _is_str_exception_call(node: ast.expr, exception_name: str) -> bool:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "str"
+        and len(node.args) == 1
+        and not node.keywords
+        and isinstance(node.args[0], ast.Name)
+        and node.args[0].id == exception_name
+    )