sarj-python-lint 1.46.3__tar.gz → 1.47.0__tar.gz

{sarj_python_lint-1.46.3 → sarj_python_lint-1.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.46.3
+Version: 1.47.0
 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-1.46.3 → sarj_python_lint-1.47.0}/pyproject.toml

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

sarj_python_lint-1.47.0/src/sarj_python_lint/rules/_data_union_discriminator.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+
+from sarj_python_lint.rule_base import Diagnostic, Severity, is_suppressed
+from sarj_python_lint.rules._imports import TYPING_SOURCES
+from sarj_python_lint.rules._pydantic_field_contract import MODEL_SOURCES, unique_members
+from sarj_python_lint.rules._resource_provenance import ResourceProvenance
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_DATACLASS_SOURCES = frozenset({"dataclasses"})
+_MAX_EXPANSION = 128
+_MIN_VARIANTS = 2
+
+type _Tag = str | bytes | int | None
+
+
+@dataclass(frozen=True, slots=True)
+class _Record:
+    fields: dict[str, ast.AnnAssign]
+    required: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _Domain:
+    values: frozenset[_Tag] = frozenset()
+    opaque: bool = False
+    unresolved: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class _Expansion:
+    node: ast.expr
+    aliases: frozenset[str] = frozenset()
+
+
+@dataclass(slots=True)
+class _Budget:
+    remaining: int = _MAX_EXPANSION
+
+
+def data_union_diagnostics(context: PythonFileContext, code: str) -> list[Diagnostic]:
+    if not any(symbol in context.symbol_source for symbol in ("dataclass", "BaseModel", "TypedDict")):
+        return []
+    tree = context.tree
+    if tree is None or context.generated or context.has_wildcard_import:
+        return []
+    if not any(
+        value is not None and _union_expression(value, context)
+        for node in tree.body
+        for value in (_alias_value(node, context),)
+    ):
+        return []
+    analysis = _DataUnions(context, tree)
+    if analysis.provenance.dynamic_namespace:
+        return []
+    return analysis.diagnostics(code)
+
+
+@final
+class _DataUnions:
+    def __init__(self, context: PythonFileContext, tree: ast.Module) -> None:
+        self.context = context
+        self.provenance = ResourceProvenance(context, require_static_namespace=True)
+        bindings = self.provenance.bindings.get(tree, {})
+        self.classes = {
+            node.name: node
+            for node in tree.body
+            if isinstance(node, ast.ClassDef)
+            and len(bindings.get(node.name, ())) == 1
+            and node.name not in self.provenance.mutated
+        }
+        self.aliases: dict[str, ast.expr] = {}
+        self.declarations: dict[str, ast.stmt] = {}
+        for node in tree.body:
+            value = _alias_value(node, context)
+            name = _alias_name(node)
+            if value is not None and name is not None and len(bindings.get(name, ())) == 1:
+                self.aliases[name] = value
+                self.declarations[name] = node
+        self.records: dict[str, _Record | None] = {}
+
+    def diagnostics(self, code: str) -> list[Diagnostic]:
+        findings: list[Diagnostic] = []
+        for name, value in self.aliases.items():
+            node = self.declarations[name]
+            if is_suppressed(self.context.source_lines, node.lineno, code) or not self._untagged_union(value):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=self.context.path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=code,
+                    message=f"Data union `{name}` has no shared disjoint Literal discriminator. "
+                    "Add a common field such as `kind` or `scope` with non-overlapping Literal values "
+                    "on every variant; preserve constructor and serialized contracts when choosing defaults.",
+                    severity=Severity.WARNING,
+                )
+            )
+        return findings
+
+    def _untagged_union(self, value: ast.expr) -> bool:
+        if not _union_expression(value, self.context):
+            return False
+        variants = self._variants(value)
+        if variants is None or len(variants) < _MIN_VARIANTS:
+            return False
+        records: list[_Record] = []
+        for variant in sorted(variants):
+            record = self._record(variant)
+            if record is None:
+                return False
+            records.append(record)
+        return not self._has_discriminator(records, _Budget())
+
+    def _typing_symbol(self, node: ast.expr) -> str | None:
+        if not _untouched(node, self.provenance):
+            return None
+        return self.context.imports.resolved_symbol(node, sources=TYPING_SOURCES)
+
+    def _variants(self, expression: ast.expr) -> set[str] | None:
+        leaves = self._leaves(expression)
+        if leaves is None:
+            return None
+        variants: set[str] = set()
+        for node in leaves:
+            if isinstance(node, ast.Constant) and node.value is None:
+                continue
+            if not isinstance(node, ast.Name) or node.id not in self.classes:
+                return None
+            variants.add(node.id)
+        return variants
+
+    def _leaves(self, expression: ast.expr) -> list[ast.expr] | None:
+        pending = [_Expansion(expression)]
+        leaves: list[ast.expr] = []
+        for _ in range(_MAX_EXPANSION):
+            if not pending:
+                return leaves
+            item = pending.pop()
+            node = _string_expression(item.node)
+            if node is None:
+                return None
+            if isinstance(node, ast.Name) and node.id in self.aliases:
+                if node.id in item.aliases:
+                    return None
+                pending.append(_Expansion(self.aliases[node.id], item.aliases | {node.id}))
+            else:
+                children = self._union_members(node)
+                if children is None:
+                    leaves.append(node)
+                else:
+                    pending.extend(_Expansion(child, item.aliases) for child in children)
+        return None
+
+    def _union_members(self, node: ast.expr) -> tuple[ast.expr, ...] | None:
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+            return node.left, node.right
+        if not isinstance(node, ast.Subscript):
+            return None
+        symbol = self._typing_symbol(node.value)
+        if symbol == "Union" and isinstance(node.slice, ast.Tuple):
+            return tuple(node.slice.elts)
+        if symbol == "Optional":
+            return node.slice, ast.Constant(value=None)
+        if symbol == "Annotated" and isinstance(node.slice, ast.Tuple) and node.slice.elts:
+            return (node.slice.elts[0],)
+        return None
+
+    def _record(self, name: str) -> _Record | None:
+        if name not in self.records:
+            self.records[name] = _record(self.classes[name], self.context, self.provenance)
+        return self.records[name]
+
+    def _has_discriminator(self, records: list[_Record], budget: _Budget) -> bool:
+        if budget.remaining <= 0:
+            return True
+        budget.remaining -= 1
+        common = set(records[0].fields).intersection(*(record.fields for record in records[1:]))
+        common.difference_update({name for name in common if name.startswith("__")})
+        uncertain = False
+        for name in sorted(common):
+            domains = [self._field_domain(record.fields[name], required=record.required) for record in records]
+            uncertain |= _uncertain_domains(domains)
+            groups = _tag_groups(records, domains)
+            if groups and all(len(group) == 1 or self._has_discriminator(group, budget) for group in groups):
+                return True
+        return uncertain
+
+    def _field_domain(self, field: ast.AnnAssign, *, required: bool) -> _Domain:
+        node = field.annotation
+        for _ in range(_MAX_EXPANSION):
+            parsed = _string_expression(node)
+            if parsed is None:
+                return _Domain(opaque=True)
+            node = parsed
+            if not isinstance(node, ast.Subscript):
+                break
+            symbol = self._typing_symbol(node.value)
+            if symbol in {"Required", "NotRequired"}:
+                required = symbol == "Required"
+                node = node.slice
+            elif symbol == "ClassVar":
+                if field.value is None:
+                    return _Domain()
+                node = node.slice
+            elif symbol == "ReadOnly":
+                node = node.slice
+            elif symbol == "Annotated" and isinstance(node.slice, ast.Tuple) and node.slice.elts:
+                node = node.slice.elts[0]
+            else:
+                break
+        return self._literal_domain(node) if required else _Domain()
+
+    def _literal_domain(self, expression: ast.expr) -> _Domain:
+        leaves = self._leaves(expression)
+        if leaves is None:
+            return _Domain(opaque=True)
+        domains = [self._leaf_domain(node) for node in leaves]
+        if any(domain.opaque for domain in domains):
+            return _Domain(opaque=True)
+        if any(domain.unresolved for domain in domains):
+            return _Domain(unresolved=True)
+        if any(not domain.values for domain in domains):
+            return _Domain()
+        return _Domain(frozenset(value for domain in domains for value in domain.values))
+
+    def _leaf_domain(self, node: ast.expr) -> _Domain:
+        if isinstance(node, ast.Constant) and node.value is None:
+            return _Domain(frozenset({None}))
+        if isinstance(node, ast.Name) and (
+            node.id in self.classes or self.context.imports.resolved_qualified_name(node) is not None
+        ):
+            return _Domain(unresolved=True)
+        if not isinstance(node, ast.Subscript):
+            return _Domain()
+        symbol = self._typing_symbol(node.value)
+        if symbol == "Literal":
+            return _literal_values(node)
+        if symbol is not None or (
+            isinstance(node.value, ast.Name)
+            and node.value.id in {"list", "dict", "tuple", "set", "frozenset", "type"}
+            and self.context.imports.builtin_is_unshadowed(node.value.id)
+        ):
+            return _Domain()
+        return _Domain(opaque=True)
+
+
+def _record(node: ast.ClassDef, context: PythonFileContext, provenance: ResourceProvenance) -> _Record | None:
+    required = _record_required(node, context, provenance)
+    if required is None:
+        return None
+    fields: dict[str, ast.AnnAssign] = {}
+    unique = unique_members(node)
+    for member in node.body:
+        if isinstance(member, ast.AnnAssign) and isinstance(member.target, ast.Name):
+            if member.target.id not in unique:
+                return None
+            fields[member.target.id] = member
+        elif isinstance(member, ast.Pass | ast.Expr) and (
+            isinstance(member, ast.Pass)
+            or (isinstance(member.value, ast.Constant) and isinstance(member.value.value, str))
+        ):
+            continue
+        else:
+            return None
+    return _Record(fields, required)
+
+
+def _record_required(node: ast.ClassDef, context: PythonFileContext, provenance: ResourceProvenance) -> bool | None:
+    if node.type_params:
+        return None
+    if any(not _untouched(base, provenance) for base in node.bases):
+        return None
+    if node.decorator_list:
+        return _direct_dataclass(node, context, provenance)
+    if len(node.bases) != 1:
+        return None
+    if context.imports.resolves(node.bases[0], sources=MODEL_SOURCES, symbol="BaseModel"):
+        return True if not node.keywords else None
+    if not context.imports.resolves(node.bases[0], sources=TYPING_SOURCES, symbol="TypedDict"):
+        return None
+    required = True
+    for keyword in node.keywords:
+        if keyword.arg != "total" or not isinstance(keyword.value, ast.Constant):
+            return None
+        if not isinstance(keyword.value.value, bool):
+            return None
+        required = keyword.value.value
+    return required
+
+
+def _direct_dataclass(node: ast.ClassDef, context: PythonFileContext, provenance: ResourceProvenance) -> bool | None:
+    if node.bases or node.keywords or len(node.decorator_list) != 1:
+        return None
+    decorator = node.decorator_list[0]
+    target = decorator.func if isinstance(decorator, ast.Call) else decorator
+    if not _untouched(target, provenance) or not context.imports.resolves(
+        target, sources=_DATACLASS_SOURCES, symbol="dataclass"
+    ):
+        return None
+    return True
+
+
+def _literal_values(node: ast.Subscript) -> _Domain:
+    values: set[_Tag] = set()
+    members = node.slice.elts if isinstance(node.slice, ast.Tuple) else [node.slice]
+    for member in members:
+        match member:
+            case ast.Constant(value=(str() | bytes() | int()) as value):
+                values.add(value)
+            case ast.Constant(value=None):
+                values.add(None)
+            case ast.UnaryOp(op=op, operand=ast.Constant(value=int() as number)) if (
+                isinstance(op, ast.USub | ast.UAdd) and type(number) is int
+            ):
+                values.add(-number if isinstance(op, ast.USub) else number)
+            case _:
+                return _Domain(opaque=True)
+    return _Domain(frozenset(values))
+
+
+def _tag_groups(records: list[_Record], domains: list[_Domain]) -> list[list[_Record]]:
+    if any(not domain.values or domain.opaque for domain in domains):
+        return []
+    groups: dict[_Tag, list[_Record]] = {}
+    for record, domain in zip(records, domains, strict=True):
+        for value in sorted(domain.values, key=repr):
+            groups.setdefault(value, []).append(record)
+    if any(len(group) == len(records) for group in groups.values()):
+        return []
+    return list(groups.values())
+
+
+def _uncertain_domains(domains: list[_Domain]) -> bool:
+    return any(domain.opaque for domain in domains) or (
+        any(domain.values for domain in domains) and any(domain.unresolved for domain in domains)
+    )
+
+
+def _alias_name(node: ast.stmt) -> str | None:
+    match node:
+        case ast.TypeAlias(name=ast.Name(id=name)) | ast.AnnAssign(target=ast.Name(id=name)):
+            return name
+        case ast.Assign(targets=[ast.Name(id=name)]):
+            return name
+        case _:
+            return None
+
+
+def _alias_value(node: ast.stmt, context: PythonFileContext) -> ast.expr | None:
+    match node:
+        case ast.TypeAlias(type_params=[]):
+            return node.value
+        case ast.AnnAssign(target=ast.Name(), annotation=annotation, value=value):
+            return value if context.imports.resolves(annotation, sources=TYPING_SOURCES, symbol="TypeAlias") else None
+        case ast.Assign(targets=[ast.Name()], value=value):
+            return None if isinstance(value, ast.Constant) and isinstance(value.value, str) else value
+        case _:
+            return None
+
+
+def _string_expression(node: ast.expr) -> ast.expr | None:
+    if not isinstance(node, ast.Constant) or not isinstance(node.value, str):
+        return node
+    try:
+        return ast.parse(node.value, mode="eval").body
+    except SyntaxError, UnicodeError, RecursionError:
+        return None
+
+
+def _untouched(node: ast.expr, provenance: ResourceProvenance) -> bool:
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return isinstance(node, ast.Name) and node.id not in provenance.mutated
+
+
+def _union_expression(node: ast.expr, context: PythonFileContext) -> bool:
+    for _ in range(_MAX_EXPANSION):
+        parsed = _string_expression(node)
+        if parsed is None:
+            return False
+        node = parsed
+        if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+            return True
+        if not isinstance(node, ast.Subscript):
+            return False
+        symbol = context.imports.resolved_symbol(node.value, sources=TYPING_SOURCES)
+        if symbol == "Union":
+            return True
+        if symbol == "Optional":
+            node = node.slice
+        elif symbol == "Annotated" and isinstance(node.slice, ast.Tuple) and node.slice.elts:
+            node = node.slice.elts[0]
+        else:
+            return False
+    return False

{sarj_python_lint-1.46.3 → sarj_python_lint-1.47.0}/src/sarj_python_lint/rules/prefer_discriminated_model_union.py

@@ -17,6 +17,7 @@ from sarj_python_lint.rule_base import (
     Severity,
     is_suppressed,
 )
+from sarj_python_lint.rules._data_union_discriminator import data_union_diagnostics
 from sarj_python_lint.rules._paths import is_test_path
 from sarj_python_lint.rules._pydantic_field_contract import (
     DECORATOR_SOURCES,
@@ -87,13 +88,16 @@ class PreferDiscriminatedModelUnion(Rule):
     code = "SARJ510"
     documentation = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="Represent literal-tag-dependent required fields with discriminated model variants.",
+        summary="Give data unions explicit Literal discriminators and express tag-dependent payloads as variants.",
         rationale=(
+            "An explicit shared tag identifies data variants and supports field-based narrowing. "
             "A nullable field remains statically nullable even when an after validator requires it for a literal "
             "tag. A union of models with distinct Literal tags carries that dependency in the type and supports "
             "safe narrowing without repeating runtime guards."
         ),
         remediation=(
+            "Give every data variant a common field with disjoint Literal values. For dataclasses, "
+            "field(default=..., init=False) can preserve existing constructor calls; review serialized contracts. "
             "Consider a discriminated union of model variants. Make the payload non-nullable only in variants "
             "proven to reject None, and preserve every other accepted field combination, defaults, aliases and wire shape. "
             "Independent optional fields can remain optional within each variant."
@@ -101,7 +105,10 @@ class PreferDiscriminatedModelUnion(Rule):
         category=RuleCategory.ARCHITECTURE,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Only stable direct module-level import-proven Pydantic BaseModel subclasses with pure direct after model validators are inspected.",
+            "Declared module-level unions of at least two source-visible direct dataclasses, Pydantic BaseModels or TypedDicts require a shared disjoint Literal field. PEP 604, typing Union, Optional, Annotated, forward references and bounded local aliases are supported; a None branch is allowed.",
+            "The explicit-tag policy is a modeling preference: nominal variants already support isinstance narrowing. Scalar/container unions, inline annotations, generic or inherited variants, behavior classes, unresolved variants and dynamic or ambiguous namespaces are excluded. Imported tag aliases are not resolved; an explicit literal field paired with an unresolved imported or local class domain abstains, as do opaque explicit Literal domains.",
+            "String, bytes, integer, Boolean and None tag values are supported. Boolean/integer equality collisions overlap. A bounded hierarchy of shared literal fields may distinguish nested groups; overlapping tags without a further discriminator still warn. TypedDict tags must be required; dataclass ClassVar tags must have a value. Runtime discriminator configuration and default correctness remain separate contracts. No automatic field addition is safe for every constructor or serializer.",
+            "For nullable-field dependencies, only stable direct module-level import-proven Pydantic BaseModel subclasses with pure direct after model validators are inspected.",
             "Bounded paths may contain finite tag comparisons or literal-container membership, None identity tests, Boolean combinations, nested guards and returns of the same instance. Every rejection region must prove one tag-dependent nullable-field requirement; joint missing-field or independent-tag-axis conditions abstain.",
             "Tags must use imported Literal domains, optionally composed through direct unions, with at least two distinct homogeneous string, integer or Boolean values, optionally including an explicit None state. Mixed primitive families, bool/int equality collisions, open or computed tags abstain. Payloads must explicitly include None in a union, imported Union or Optional.",
             "Every non-null payload member must have a source-proven inhabited built-in scalar or container type; opaque aliases, custom types and None-only or bottom-type unions are excluded.",
@@ -146,19 +153,55 @@ class PreferDiscriminatedModelUnion(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="untagged-data-variants",
+                scenario="explicit-data-discriminator",
+                title="Data variants lack a common explicit tag",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/access.py",
+                        "from dataclasses import dataclass\n"
+                        "@dataclass(frozen=True, slots=True)\nclass TeamAccess:\n    team_id: str\n"
+                        "@dataclass(frozen=True, slots=True)\nclass GlobalAccess:\n    group: str\n"
+                        "type Access = TeamAccess | GlobalAccess\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/access.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="literal-tags-preserve-constructor-calls",
+                scenario="explicit-data-discriminator",
+                title="Explicit tags preserve positional constructor calls with init=False",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/access.py",
+                        "from dataclasses import dataclass, field\nfrom typing import Literal\n"
+                        "@dataclass(frozen=True, slots=True)\nclass TeamAccess:\n"
+                        "    scope: Literal['team'] = field(default='team', init=False)\n    team_id: str\n"
+                        "@dataclass(frozen=True, slots=True)\nclass GlobalAccess:\n"
+                        "    scope: Literal['global'] = field(default='global', init=False)\n    group: str\n"
+                        "type Access = TeamAccess | GlobalAccess\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/access.py"),
+                expected_count=0,
+                public=True,
+            ),
         ),
     )
     description = documentation.summary
 
     @override
     def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
-        if (
-            is_test_path(context.path)
-            or "None" not in context.symbol_source
-            or "model_validator" not in context.symbol_source
-        ):
+        if is_test_path(context.path):
             return []
-        diagnostics: list[Diagnostic] = []
+        diagnostics = data_union_diagnostics(context, self.code)
+        if "None" not in context.symbol_source or "model_validator" not in context.symbol_source:
+            return diagnostics
         provenance = ResourceProvenance(context, require_static_namespace=True)
         for model in direct_models(context, methods=True):
             if not _stable_model(model, context, provenance):