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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.7.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.7.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.7.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"