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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.6.0
+Version: 0.8.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
@@ -32,7 +32,6 @@ uv tool install sarj-python-lint
   hooks:
     - id: sarj-no-sequential-await
     - id: sarj-inefficient-string-concat-in-loop
-    - id: sarj-prefer-discriminated-union
     - id: sarj-prefer-str-enum
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries

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

@@ -14,7 +14,6 @@ uv tool install sarj-python-lint
   hooks:
     - id: sarj-no-sequential-await
     - id: sarj-inefficient-string-concat-in-loop
-    - id: sarj-prefer-discriminated-union
     - id: sarj-prefer-str-enum
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries

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

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

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

@@ -66,6 +66,18 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
     return diags
 
 
+class _Args(argparse.Namespace):
+    cmd: str | None
+    rule: list[str]
+    files: list[Path]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.cmd = None
+        self.rule = []
+        self.files = []
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="sarj-python-lint",
@@ -85,18 +97,15 @@ 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
+    args = parser.parse_args(argv, namespace=_Args())
 
-    if cmd == "list-rules":
+    if args.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
 
-    rule_ids: list[str] = args.rule
-    files: list[Path] = args.files
-    diags = _check(rule_ids, files)
+    diags = _check(args.rule, args.files)
     for d in diags:
         sys.stdout.write(d.format() + "\n")
     return 1 if diags else 0

{sarj_python_lint-0.6.0 → sarj_python_lint-0.8.0}/src/sarj_python_lint/rules/_registry.py

@@ -24,7 +24,6 @@ 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_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,
@@ -45,7 +44,6 @@ if TYPE_CHECKING:
 REGISTRY: dict[str, type[Rule]] = {
     NoSequentialAwait.id: NoSequentialAwait,
     InefficientStringConcatInLoop.id: InefficientStringConcatInLoop,
-    PreferDiscriminatedUnion.id: PreferDiscriminatedUnion,
     PreferClassRow.id: PreferClassRow,
     PreferStrEnum.id: PreferStrEnum,
     NoFatTryBlocks.id: NoFatTryBlocks,

{sarj_python_lint-0.6.0 → sarj_python_lint-0.8.0}/src/sarj_python_lint/rules/no_aggregation_in_store_query.py

@@ -82,9 +82,9 @@ def _strip_sql_comments(text: str) -> str:
 class NoAggregationInStoreQuery(Rule):
     """DISTINCT / GROUP BY / COUNT in a store query — aggregate in ClickHouse."""
 
-    id = "no-aggregation-in-store-query"
-    code = "SARJ020"
-    description = (
+    id: str = "no-aggregation-in-store-query"
+    code: str = "SARJ020"
+    description: str = (
         "DISTINCT / GROUP BY / COUNT in a Postgres store query — push heavy "
         "aggregation to the columnar mirror (ClickHouse / BigQuery)."
     )

{sarj_python_lint-0.6.0 → sarj_python_lint-0.8.0}/src/sarj_python_lint/rules/no_fat_try_blocks.py

@@ -1,4 +1,4 @@
-"""SARJ007: `try` block whose body has more than 3 top-level statements.
+"""SARJ007: `try` block with more than 3 top-level statements that can raise.
 
 A fat `try` body obscures which statement is actually expected to raise and
 widens the blast radius of the `except` handlers: unrelated failures get
@@ -6,13 +6,20 @@ caught (and often swallowed or mis-reported) by handlers written for a
 different operation. Keep the `try` skinny — isolate the throwing
 statement(s) and move the non-throwing setup and follow-up work outside.
 
-Only the top-level statements of the `try` body are counted; statements
-nested inside an `if` / `with` / loop within the body count as the single
-compound statement that contains them. Nested `try` blocks are checked
-independently. `try*` (PEP 654 except-groups) is held to the same limit.
-
-This is a direct Python port of the org's ESLint restriction
-`TryStatement > BlockStatement[body.length > 3]` in eslint.strict.mjs.
+Two refinements keep the count aligned with that intent and avoid the
+false-positive patterns that dominated real-world suppressions:
+
+* Only top-level statements that *can raise* are counted — a statement counts
+  toward the limit only if its subtree contains a call or `await`. Pure
+  assignments / name-rebinds (`self.x = y`, `a = b.c`) don't obscure a throwing
+  statement and are free. Statements nested inside an `if` / `with` / loop
+  count as the single compound statement that contains them. Nested `try`
+  blocks are checked independently. `try*` (PEP 654) is held to the same limit.
+* `try` blocks that carry an `else` or `finally` clause are exempt. Those
+  clauses are a deliberate success/cleanup contract that couples the body to
+  the handler (a `finally` that tears down a resource, an `else`/`finally` that
+  reads a status the body set) — statements can't be freely hoisted out without
+  changing semantics, so the length check is counterproductive there.
 
 Instead of:
     try:
@@ -52,12 +59,18 @@ if TYPE_CHECKING:
 _MAX_TRY_BODY_STATEMENTS = 3
 
 
+def _can_raise(stmt: ast.stmt) -> bool:
+    """True if the statement's subtree contains a call or `await` — i.e. it can
+    plausibly raise. Pure assignments / rebinds with no call do not count."""
+    return any(isinstance(n, (ast.Call, ast.Await)) for n in ast.walk(stmt))
+
+
 class NoFatTryBlocks(Rule):
-    """Try body longer than 3 statements — isolate the throwing statement(s)."""
+    """Try body with too many throwing statements — isolate the one that raises."""
 
     id: str = "no-fat-try-blocks"
     code: str = "SARJ007"
-    description: str = "Try block body exceeds 3 statements — keep try blocks skinny."
+    description: str = "Try block has too many throwing statements — keep try blocks skinny."
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
@@ -69,7 +82,12 @@ class NoFatTryBlocks(Rule):
         for node in ast.walk(tree):
             if not isinstance(node, (ast.Try, ast.TryStar)):
                 continue
-            if len(node.body) <= _MAX_TRY_BODY_STATEMENTS:
+            # An `else`/`finally` clause is a deliberate success/cleanup contract
+            # that couples the body to the handler — don't fight it on length.
+            if node.orelse or node.finalbody:
+                continue
+            throwing = sum(_can_raise(stmt) for stmt in node.body)
+            if throwing <= _MAX_TRY_BODY_STATEMENTS:
                 continue
             diags.append(
                 Diagnostic(
@@ -78,7 +96,7 @@ class NoFatTryBlocks(Rule):
                     col=node.col_offset + 1,
                     code=self.code,
                     message=(
-                        f"try block has {len(node.body)} statements "
+                        f"try block has {throwing} statements that can raise "
                         f"(max {_MAX_TRY_BODY_STATEMENTS}) — try blocks should "
                         "isolate the throwing statement(s); move non-throwing "
                         "work outside the try."

{sarj_python_lint-0.6.0 → sarj_python_lint-0.8.0}/src/sarj_python_lint/rules/no_query_with_many_joins.py

@@ -61,9 +61,9 @@ def _strip_sql_comments(text: str) -> str:
 class NoQueryWithManyJoins(Rule):
     """A SQL query with 3+ JOINs is too entangled — split it or denormalize."""
 
-    id = "no-query-with-many-joins"
-    code = "SARJ019"
-    description = (
+    id: str = "no-query-with-many-joins"
+    code: str = "SARJ019"
+    description: str = (
         "SQL query with 3 or more JOINs — split the query or denormalize instead of fanning across many tables."
     )
 

{sarj_python_lint-0.6.0 → sarj_python_lint-0.8.0}/src/sarj_python_lint/rules/no_select_star.py

@@ -67,9 +67,9 @@ def _has_real_select_star(sql: str) -> bool:
 class NoSelectStar(Rule):
     """`SELECT *` in a store query — list the columns explicitly."""
 
-    id = "no-select-star"
-    code = "SARJ021"
-    description = (
+    id: str = "no-select-star"
+    code: str = "SARJ021"
+    description: str = (
         "SELECT * in a store query — name the columns; * over-fetches and breaks "
         "class_row mapping when the schema changes."
     )

sarj_python_lint-0.8.0/src/sarj_python_lint/rules/no_sequential_await.py

@@ -0,0 +1,196 @@
+"""SARJ001: detect the `for x in xs: await f(x)` gather antipattern.
+
+Sequential `await` in a for-loop serializes I/O that could be parallelized
+with `asyncio.gather([f(x) for x in xs])`. The performance gap is often 10-100x
+for network-bound work (HTTP, DB queries, LLM calls).
+
+Deliberately narrow, to flag the textbook antipattern and almost nothing else —
+an over-broad version drowned real signal under suppressions. The rule fires
+only for:
+
+* a `for` loop whose body is **straight-line** (no `if`/`try`/`with`/`return`/
+  `break`/`continue`/`raise`/nested loop — those signal conditional or ordered
+  logic, not a parallel map) and awaits a call that **uses the loop variable**
+  (so each iteration is a distinct, independent call); or
+* a comprehension / generator expression with an `await` in its element or a
+  per-element `if` (those have no ordered side effects).
+
+It does NOT fire for: `while` loops (pagination, polling, queue drains — length
+unknown, inherently sequential), a loop's once-evaluated iterable
+(`for x in await fetch()`), `async for`, test modules (intentional ordering),
+or a `for` body containing control flow. Those were the false-positive sources.
+
+References:
+- https://docs.python.org/3/library/asyncio-task.html#running-tasks-concurrently
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+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)
+
+
+class NoSequentialAwait(Rule):
+    """Sequential await calls in a loop that could be parallelized."""
+
+    id: str = "no-sequential-await"
+    code: str = "SARJ001"
+    description: str = "Sequential `await` in a for-loop — prefer asyncio.gather."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if _is_test_path(path):
+            return []
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        visitor = _SequentialAwaitVisitor()
+        visitor.visit(tree)
+        diags = [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=("Sequential `await` inside `for` — prefer `asyncio.gather([f(x) for x in xs])`."),
+            )
+            for node in visitor.hits
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+# A loop's *iterable* is evaluated once in the enclosing scope, NOT per element:
+# `for x in await fetch()` / `{x for x in await fetch()}` await once. Iterables
+# are visited *before* the loop is pushed, so an await there attributes to an
+# enclosing loop (if any), not this one.
+_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
+
+# Top-level body statements that signal conditional or ordered logic rather than
+# a straight-line parallel map. A `for` whose body contains any of these is not
+# treated as the gather antipattern.
+_CONTROL_FLOW = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.With,
+    ast.AsyncWith,
+    ast.Try,
+    ast.Match,
+    ast.Return,
+    ast.Break,
+    ast.Continue,
+    ast.Raise,
+)
+
+
+def _names(node: ast.AST) -> set[str]:
+    return {n.id for n in ast.walk(node) if isinstance(n, ast.Name)}
+
+
+def _is_gather_antipattern(node: ast.For) -> bool:
+    """True for `for x in xs: <straight-line body awaiting a call that uses x>`."""
+    if any(isinstance(stmt, _CONTROL_FLOW) for stmt in node.body):
+        return False
+    targets = _names(node.target)
+    for stmt in node.body:
+        for inner in ast.walk(stmt):
+            if isinstance(inner, ast.Await) and _names(inner) & targets:
+                return True
+    return False
+
+
+class _SequentialAwaitVisitor(ast.NodeVisitor):
+    """Single O(n) pass: flag the first per-iteration `await` of each loop.
+
+    Maintains a stack of enclosing loops within the current function. The stack
+    resets at function boundaries so a loop in an outer function never claims an
+    `await` in a nested one. Each loop is flagged at most once. A loop's
+    once-evaluated iterable is excluded (see module comment).
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._loops: list[ast.AST] = []
+        self._flagged: set[int] = set()
+        self.hits: list[ast.Await] = []
+
+    def _flag_if_in_loop(self, node: ast.Await) -> None:
+        if self._loops:
+            loop = self._loops[-1]
+            if id(loop) not in self._flagged:
+                self._flagged.add(id(loop))
+                self.hits.append(node)
+
+    def visit_For(self, node: ast.For) -> None:
+        # `<iter>` runs once in the enclosing scope; visit it before entering.
+        self.visit(node.iter)
+        # Only a straight-line per-element-await body is the gather antipattern;
+        # control-flow bodies (conditional/ordered) are not pushed, so awaits in
+        # them are not flagged for this loop.
+        antipattern = _is_gather_antipattern(node)
+        if antipattern:
+            self._loops.append(node)
+        self.visit(node.target)
+        for stmt in (*node.body, *node.orelse):
+            self.visit(stmt)
+        if antipattern:
+            self._loops.pop()
+
+    def _visit_comprehension(self, node: ast.AST, elements: tuple[ast.expr, ...]) -> None:
+        gens: list[ast.comprehension] = node.generators  # pyright: ignore[reportAttributeAccessIssue]
+        # Outermost iterable is evaluated once in the enclosing scope.
+        self.visit(gens[0].iter)
+        self._loops.append(node)
+        for elt in elements:
+            self.visit(elt)
+        self.visit(gens[0].target)
+        for cond in gens[0].ifs:
+            self.visit(cond)
+        # Later generators iterate per element of the preceding one.
+        for gen in gens[1:]:
+            self.visit(gen.iter)
+            self.visit(gen.target)
+            for cond in gen.ifs:
+                self.visit(cond)
+        self._loops.pop()
+
+    def visit_ListComp(self, node: ast.ListComp) -> None:
+        self._visit_comprehension(node, (node.elt,))
+
+    def visit_SetComp(self, node: ast.SetComp) -> None:
+        self._visit_comprehension(node, (node.elt,))
+
+    def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
+        self._visit_comprehension(node, (node.elt,))
+
+    def visit_DictComp(self, node: ast.DictComp) -> None:
+        self._visit_comprehension(node, (node.key, node.value))
+
+    @override
+    def generic_visit(self, node: ast.AST) -> None:
+        if isinstance(node, _SCOPES):
+            saved = self._loops
+            self._loops = []
+            super().generic_visit(node)
+            self._loops = saved
+        elif isinstance(node, ast.Await):
+            self._flag_if_in_loop(node)
+            super().generic_visit(node)
+        else:
+            super().generic_visit(node)

{sarj_python_lint-0.6.0 → sarj_python_lint-0.8.0}/src/sarj_python_lint/rules/store_insert_requires_on_conflict.py

@@ -61,9 +61,9 @@ def _strip_sql_comments(text: str) -> str:
 class StoreInsertRequiresOnConflict(Rule):
     """Embedded INSERT in store code without ON CONFLICT — store writes must be upserts."""
 
-    id = "store-insert-requires-on-conflict"
-    code = "SARJ018"
-    description = "Embedded SQL INSERT in store code without ON CONFLICT — store writes must be idempotent upserts."
+    id: str = "store-insert-requires-on-conflict"
+    code: str = "SARJ018"
+    description: str = "Embedded SQL INSERT in store code without ON CONFLICT — store writes must be idempotent upserts."
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:

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

@@ -1,94 +0,0 @@
-"""SARJ001: detect `for x in xs: await f(x)` patterns.
-
-Sequential `await` in a for-loop serializes I/O that could be parallelized
-with `asyncio.gather([f(x) for x in xs])`. The performance gap is often 10-100x
-for network-bound work (HTTP, DB queries, LLM calls).
-
-References:
-- https://docs.python.org/3/library/asyncio-task.html#running-tasks-concurrently
-"""
-
-from __future__ import annotations
-
-import ast
-from typing import TYPE_CHECKING, override
-
-from sarj_python_lint.rule_base import Diagnostic, Rule
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-class NoSequentialAwait(Rule):
-    """Sequential await calls in a loop that could be parallelized."""
-
-    id: str = "no-sequential-await"
-    code: str = "SARJ001"
-    description: str = "Sequential `await` in a for-loop — prefer asyncio.gather."
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        try:
-            tree = ast.parse(source, filename=str(path))
-        except SyntaxError:
-            return []
-        visitor = _SequentialAwaitVisitor()
-        visitor.visit(tree)
-        diags = [
-            Diagnostic(
-                path=path,
-                line=node.lineno,
-                col=node.col_offset + 1,
-                code=self.code,
-                message=(
-                    "Sequential `await` inside `for` — prefer "
-                    "`asyncio.gather([f(x) for x in xs])`."
-                ),
-            )
-            for node in visitor.hits
-        ]
-        diags.sort(key=lambda d: (d.line, d.col))
-        return diags
-
-
-# Loop-like constructs whose body runs once per element: `await` inside one of
-# them serializes the iterations. `async for` is deliberately absent — it is the
-# parallel-iteration construct, not the antipattern.
-_LOOPS = (ast.For, ast.While, ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
-_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
-
-
-class _SequentialAwaitVisitor(ast.NodeVisitor):
-    """Single O(n) pass: flag the first `await` of each enclosing loop.
-
-    Maintains a stack of enclosing loops within the current function. The stack
-    resets at function boundaries so a loop in an outer function never claims an
-    `await` in a nested one. Each loop is flagged at most once.
-    """
-
-    def __init__(self) -> None:
-        self._loops: list[ast.AST] = []
-        self._flagged: set[int] = set()
-        self.hits: list[ast.Await] = []
-
-    @override
-    def generic_visit(self, node: ast.AST) -> None:
-        if isinstance(node, _SCOPES):
-            saved = self._loops
-            self._loops = []
-            super().generic_visit(node)
-            self._loops = saved
-        elif isinstance(node, _LOOPS):
-            self._loops.append(node)
-            super().generic_visit(node)
-            self._loops.pop()
-        elif isinstance(node, ast.Await):
-            if self._loops:
-                loop = self._loops[-1]
-                if id(loop) not in self._flagged:
-                    self._flagged.add(id(loop))
-                    self.hits.append(node)
-            super().generic_visit(node)
-        else:
-            super().generic_visit(node)

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

@@ -1,391 +0,0 @@
-"""SARJ005: flag poor-man's-result shapes — prefer a discriminated union.
-
-Three triggers:
-
-1. **success-bool model** — a pydantic BaseModel with a bool status field plus
-   Optional siblings:
-
-       class Result(BaseModel):
-           success: bool
-           data: Optional[Data] = None
-           error: Optional[str] = None
-
-   allows illegal states (success=True with data=None, or success=False with
-   data set). Use a discriminated union:
-
-       class Success(BaseModel): data: Data
-       class Failure(BaseModel): error: str
-       Result = Union[Success, Failure]
-
-2. **bool-tuple result** — a function whose return annotation is a two-element
-   `tuple[bool, X]` / `tuple[X, bool]` (also `Tuple[...]` and `X | None`
-   payloads): the classic `(ok, value)` poor-man's-result. Model
-   success/failure as a discriminated union (e.g. `Ok[T] | Err`) instead of a
-   bool-tuple — the bool and the payload can disagree.
-
-3. **nullable cluster with a discriminator** — a pydantic BaseModel or
-   dataclass with 3+ `X | None` / `Optional[X]` fields AND a str / StrEnum /
-   Literal field named like a discriminator (`status`, `state`, `type`,
-   `kind`, `result`, `outcome`):
-
-       class Call(BaseModel):
-           status: str
-           started_at: datetime | None = None
-           ended_at: datetime | None = None
-           error: str | None = None
-
-   Split into per-state models in a discriminated union (the CallState
-   pattern: `PendingCall | ActiveCall | CompletedCall | FailedCall`) so each
-   state carries exactly the fields that are valid for it.
-
-   Query/filter inputs and PATCH-style partial-update DTOs legitimately hold
-   many optional fields, so class names matching those conventions
-   (`*Input` / `*Params` / `*Filter` / `*Query` / `Update*` / `Patch*` /
-   `Upsert*`) are excluded from this trigger.
-
-   A single-value `Literal` tag (e.g. `type: Literal["complete"]`) marks a model
-   that is already an arm of a discriminated union, so it is excluded too — a
-   multi-value `Literal[...]` is still treated as a poor-man's discriminator.
-
-References:
-- https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
-- https://en.wikipedia.org/wiki/Tagged_union
-"""
-
-from __future__ import annotations
-
-import ast
-from typing import TYPE_CHECKING, override
-
-from sarj_python_lint.rule_base import Diagnostic, Rule
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-STATUS_FIELDS = {"success", "ok", "is_success", "succeeded", "successful", "failed", "failure"}
-IGNORED_OPTIONAL_FIELDS = {
-    "metadata",
-    "meta",
-    "debug",
-    "debug_logs",
-    "extra",
-    "log",
-    "logs",
-    "traceback",
-    "request_id",
-    "trace_id",
-}
-DISCRIMINATOR_FIELD_NAMES = {"status", "state", "type", "kind", "result", "outcome"}
-NULLABLE_CLUSTER_THRESHOLD = 3
-# A bool status field plus this many Optional siblings trips the original trigger.
-OPTIONAL_SIBLINGS_THRESHOLD = 2
-# An (ok, value) bool-tuple has exactly two elements.
-_BOOL_TUPLE_LEN = 2
-# Query/filter inputs and partial-update DTOs are all-optional by design.
-DTO_CLASS_NAME_SUFFIXES = ("Input", "Params", "Filter", "Query")
-DTO_CLASS_NAME_PREFIXES = ("Update", "Patch", "Upsert")
-
-
-class PreferDiscriminatedUnion(Rule):
-    """Bool-status models, bool-tuple results, status+Optionals — prefer a discriminated union."""
-
-    id: str = "prefer-discriminated-union"
-    code: str = "SARJ005"
-    description: str = (
-        "success:bool + Optionals, tuple[bool, X] results, or status + nullable "
-        "cluster — use a discriminated union."
-    )
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        try:
-            tree = ast.parse(source, filename=str(path))
-        except SyntaxError:
-            return []
-        diags: list[Diagnostic] = []
-        str_enum_names = _collect_str_enum_names(tree)
-        for node in ast.walk(tree):
-            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-                diag = self._check_bool_tuple_return(path, node)
-                if diag is not None:
-                    diags.append(diag)
-                continue
-            if not isinstance(node, ast.ClassDef):
-                continue
-            diag = self._check_class(path, node, str_enum_names)
-            if diag is not None:
-                diags.append(diag)
-        return diags
-
-    def _check_bool_tuple_return(
-        self, path: Path, node: ast.FunctionDef | ast.AsyncFunctionDef
-    ) -> Diagnostic | None:
-        if not _is_bool_tuple(node.returns):
-            return None
-        returns_text = ast.unparse(node.returns) if node.returns else ""
-        return Diagnostic(
-            path=path,
-            line=node.lineno,
-            col=node.col_offset + 1,
-            code=self.code,
-            message=(
-                f"`{node.name}` returns `{returns_text}` — a (ok, value) bool-tuple. "
-                "Model success/failure as a discriminated union "
-                "(e.g. `Ok[T] | Err`), not a bool-tuple."
-            ),
-        )
-
-    def _check_class(
-        self, path: Path, node: ast.ClassDef, str_enum_names: set[str]
-    ) -> Diagnostic | None:
-        is_model = _inherits_basemodel(node)
-        is_dc = _is_dataclass(node)
-        if not (is_model or is_dc):
-            return None
-        has_status_bool = False
-        has_literal_tag = False
-        optional_fields: list[str] = []
-        discriminator_fields: list[str] = []
-        for stmt in node.body:
-            if not isinstance(stmt, ast.AnnAssign):
-                continue
-            if not isinstance(stmt.target, ast.Name):
-                continue
-            name = stmt.target.id
-            if name in STATUS_FIELDS and _is_bool_annotation(stmt.annotation):
-                has_status_bool = True
-            if name in DISCRIMINATOR_FIELD_NAMES and _is_discriminator_type(
-                stmt.annotation, str_enum_names
-            ):
-                discriminator_fields.append(name)
-                if _is_single_value_literal(stmt.annotation):
-                    has_literal_tag = True
-            if _is_optional(stmt.annotation) and name not in IGNORED_OPTIONAL_FIELDS:
-                optional_fields.append(name)
-        # Original trigger: bool status field + Optional siblings (BaseModel only).
-        if is_model and has_status_bool and len(optional_fields) >= OPTIONAL_SIBLINGS_THRESHOLD:
-            return Diagnostic(
-                path=path,
-                line=node.lineno,
-                col=node.col_offset + 1,
-                code=self.code,
-                message=(
-                    f"`{node.name}` has a bool status field plus "
-                    f"Optional fields ({', '.join(optional_fields)}). "
-                    "Model as `Union[Success, Failure]` to make illegal "
-                    "states unrepresentable."
-                ),
-            )
-        # Nullable-cluster trigger: discriminator-ish field + 3 or more nullables.
-        # A single-value `Literal` tag (e.g. `type: Literal["complete"]`) marks a
-        # model that is already a discriminated-union arm, not a poor-man's result.
-        if (
-            discriminator_fields
-            and len(optional_fields) >= NULLABLE_CLUSTER_THRESHOLD
-            and not _is_dto_class_name(node.name)
-            and not has_literal_tag
-        ):
-            return Diagnostic(
-                path=path,
-                line=node.lineno,
-                col=node.col_offset + 1,
-                code=self.code,
-                message=(
-                    f"`{node.name}` has a discriminator-ish field "
-                    f"(`{discriminator_fields[0]}`) plus {len(optional_fields)} nullable "
-                    f"fields ({', '.join(optional_fields)}). Split into per-state models "
-                    "in a discriminated union (the CallState pattern: "
-                    "`PendingCall | ActiveCall | CompletedCall | FailedCall`)."
-                ),
-            )
-        return None
-
-
-def _is_dto_class_name(name: str) -> bool:
-    """Query/filter input and partial-update DTO names are all-optional by design."""
-    return name.endswith(DTO_CLASS_NAME_SUFFIXES) or name.startswith(DTO_CLASS_NAME_PREFIXES)
-
-
-def _is_single_value_literal(node: ast.AST | None) -> bool:
-    """Detect a single-constant `Literal[X]` annotation.
-
-    A one-element `Literal` (e.g. `type: Literal["complete"]`) is the canonical
-    tag of a discriminated-union arm, so a model carrying one is already modelled
-    correctly. A multi-value `Literal[...]` is still a poor-man's discriminator.
-    """
-    if node is None:
-        return False
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        try:
-            parsed = ast.parse(node.value, mode="eval")
-        except SyntaxError:
-            return False
-        return _is_single_value_literal(parsed.body)
-    if not isinstance(node, ast.Subscript):
-        return False
-    if _get_name_flat(node.value).rsplit(".", 1)[-1] != "Literal":
-        return False
-    slice_node = node.slice
-    if isinstance(slice_node, ast.Tuple):
-        return len(slice_node.elts) == 1
-    return True
-
-
-def _inherits_basemodel(node: ast.ClassDef) -> bool:
-    for base in node.bases:
-        if isinstance(base, ast.Name) and base.id == "BaseModel":
-            return True
-        if isinstance(base, ast.Attribute) and base.attr == "BaseModel":
-            return True
-    return False
-
-
-def _is_dataclass(node: ast.ClassDef) -> bool:
-    """Detect `@dataclass`, `@dataclasses.dataclass`, and called forms."""
-    for deco in node.decorator_list:
-        target = deco.func if isinstance(deco, ast.Call) else deco
-        name = _get_name_flat(target)
-        if name == "dataclass" or name.endswith(".dataclass"):
-            return True
-    return False
-
-
-def _collect_str_enum_names(tree: ast.Module) -> set[str]:
-    """Names of classes in this module that look like string enums.
-
-    Matches `class X(StrEnum)`, `class X(enum.StrEnum)`, and the
-    pre-3.11 `class X(str, Enum)` spelling.
-    """
-    names: set[str] = set()
-    for node in ast.walk(tree):
-        if not isinstance(node, ast.ClassDef):
-            continue
-        base_names = {_get_name_flat(base).rsplit(".", 1)[-1] for base in node.bases}
-        if "StrEnum" in base_names or {"str", "Enum"} <= base_names:
-            names.add(node.name)
-    return names
-
-
-def _is_bool_tuple(node: ast.AST | None) -> bool:
-    """Detect a two-element `tuple[bool, X]` / `tuple[X, bool]` annotation."""
-    if node is None:
-        return False
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        try:
-            parsed = ast.parse(node.value, mode="eval")
-        except SyntaxError:
-            return False
-        return _is_bool_tuple(parsed.body)
-    if not isinstance(node, ast.Subscript):
-        return False
-    name = _get_name_flat(node.value).rsplit(".", 1)[-1]
-    if name not in {"tuple", "Tuple"}:
-        return False
-    slice_node = node.slice
-    if not isinstance(slice_node, ast.Tuple) or len(slice_node.elts) != _BOOL_TUPLE_LEN:
-        return False
-    elts = slice_node.elts
-    # `tuple[bool, ...]` is a homogeneous variadic tuple, not an (ok, value) pair.
-    if any(isinstance(e, ast.Constant) and e.value is Ellipsis for e in elts):
-        return False
-    return any(_is_bool(e) for e in elts)
-
-
-def _is_bool(node: ast.AST) -> bool:
-    if isinstance(node, ast.Name):
-        return node.id == "bool"
-    if isinstance(node, ast.Attribute):
-        return node.attr == "bool"
-    return False
-
-
-def _is_bool_annotation(node: ast.AST | None) -> bool:
-    """True if the annotation is `bool` (optionally unioned, e.g. `bool | None`).
-
-    A parsed-node check, so `success: BoolishFlag` no longer trips the substring
-    `"bool" in ast.unparse(...)` heuristic.
-    """
-    if node is None:
-        return False
-    if _is_bool(node):
-        return True
-    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
-        return _is_bool_annotation(node.left) or _is_bool_annotation(node.right)
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        try:
-            parsed = ast.parse(node.value, mode="eval")
-        except SyntaxError:
-            return False
-        return _is_bool_annotation(parsed.body)
-    return False
-
-
-def _is_discriminator_type(node: ast.AST | None, str_enum_names: set[str]) -> bool:
-    """Detect a str / StrEnum / Literal annotation (optionally unioned with None)."""
-    if node is None:
-        return False
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        try:
-            parsed = ast.parse(node.value, mode="eval")
-        except SyntaxError:
-            return False
-        return _is_discriminator_type(parsed.body, str_enum_names)
-    if isinstance(node, ast.Name):
-        return node.id == "str" or node.id in str_enum_names
-    if isinstance(node, ast.Attribute):
-        return node.attr in str_enum_names
-    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
-        return _is_discriminator_type(node.left, str_enum_names) or _is_discriminator_type(
-            node.right, str_enum_names
-        )
-    if isinstance(node, ast.Subscript):
-        name = _get_name_flat(node.value).rsplit(".", 1)[-1]
-        if name == "Literal":
-            return True
-        if name == "Optional":
-            return _is_discriminator_type(node.slice, str_enum_names)
-    return False
-
-
-def _get_name_flat(node: ast.AST) -> str:
-    if isinstance(node, ast.Name):
-        return node.id
-    if isinstance(node, ast.Attribute):
-        val = _get_name_flat(node.value)
-        if val:
-            return f"{val}.{node.attr}"
-    return ""
-
-
-def _is_optional(node: ast.AST | None) -> bool:
-    """Detect if an annotation represents an Optional type or Union with None."""
-    if node is None:
-        return False
-
-    # If it's a string literal (forward ref), parse it and check the inner AST
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        try:
-            parsed = ast.parse(node.value, mode="eval")
-            return _is_optional(parsed.body)
-        except SyntaxError:
-            pass
-
-    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
-        return _is_optional(node.left) or _is_optional(node.right)
-
-    if isinstance(node, ast.Subscript):
-        name = _get_name_flat(node.value)
-        if name == "Optional" or name.endswith(".Optional"):
-            return True
-        if name == "Union" or name.endswith(".Union"):
-            slice_node = node.slice
-            if isinstance(slice_node, ast.Tuple):
-                return any(_is_optional(elt) for elt in slice_node.elts)
-            return _is_optional(slice_node)
-
-    if isinstance(node, ast.Constant) and node.value is None:
-        return True
-
-    return isinstance(node, ast.Name) and node.id == "None"