sarj-python-lint 0.85.0__tar.gz → 0.86.0__tar.gz

{sarj_python_lint-0.85.0 → sarj_python_lint-0.86.0}/PKG-INFO

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

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

{sarj_python_lint-0.85.0 → sarj_python_lint-0.86.0}/src/sarj_python_lint/__main__.py

@@ -142,6 +142,10 @@ _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
         "SARJ088": frozenset({"SARJ050", "SARJ085", "SARJ420"}),
         "SARJ092": frozenset({"SARJ086", "SARJ087", "SARJ420"}),
         "SARJ093": frozenset({"SARJ034"}),
+        # Visible FastAPI operations have a route-aware contract diagnostic.
+        # Keep the annotation diagnostics when SARJ094 is absent, including
+        # when a concrete response_model makes the route contract complete.
+        "SARJ094": frozenset({"SARJ008", "SARJ447"}),
         "SARJ099": frozenset({"SARJ420"}),
         # Any-valued mappings are the stronger correctness failure. SARJ008
         # still owns every fixed dictionary return when selected alone, while
@@ -166,13 +170,17 @@ def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = Non
         "SARJ420" in codes and not codes.isdisjoint(_DOCSTRING_PRECEDENCE_CODES)
     )
     docstring_owners = _docstring_owner_locations(source) if source is not None and needs_docstring_owners else {}
-    needs_signature_owners = ("SARJ093" in codes and "SARJ034" in codes) or ("SARJ447" in codes and "SARJ008" in codes)
+    needs_signature_owners = (
+        ("SARJ093" in codes and "SARJ034" in codes)
+        or ("SARJ447" in codes and "SARJ008" in codes)
+        or ("SARJ094" in codes and not codes.isdisjoint(_DIAGNOSTIC_PRECEDENCE["SARJ094"]))
+    )
     signature_owners = (
         _function_signature_owner_locations(source) if source is not None and needs_signature_owners else {}
     )
 
     def owner_location(diagnostic: Diagnostic) -> _OwnerLocation:
-        if diagnostic.code in {"SARJ008", "SARJ034", "SARJ093", "SARJ447"}:
+        if diagnostic.code in {"SARJ008", "SARJ034", "SARJ093", "SARJ094", "SARJ447"}:
             line, column = signature_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
         else:
             line, column = docstring_owners.get(diagnostic.line, (diagnostic.line, diagnostic.col))
@@ -180,6 +188,8 @@ def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = Non
 
     present: dict[tuple[Path, int, int], dict[str, set[Severity]]] = {}
     for diagnostic in diags:
+        if diagnostic.code == "SARJ094" and not diagnostic.message.startswith("[return]"):
+            continue
         location = owner_location(diagnostic)
         by_code = present.setdefault((diagnostic.path, location.line, location.column), {})
         by_code.setdefault(diagnostic.code, set()).add(diagnostic.severity)
@@ -213,23 +223,45 @@ def _suppressed_diagnostics(
 
 
 def _suppressed_codes(codes: dict[str, set[Severity]]) -> set[tuple[str, Severity]]:
-    suppressed = {
-        (generic, generic_severity)
-        for specific, generics in _DIAGNOSTIC_PRECEDENCE.items()
-        if specific in codes
-        for generic in generics
-        for generic_severity in codes.get(generic, set())
-        if generic_severity is Severity.WARNING or Severity.ERROR in codes[specific]
-    }
+    suppressed = _precedence_suppressions(codes)
+    # SARJ094 is deliberately staged as a warning while teams calibrate the
+    # FastAPI contract policy. Its route-aware return finding still owns the
+    # overlapping annotation failure: emitting the blocking SARJ447 twin would
+    # defeat warning staging and give two remediations for one return contract.
+    if "SARJ094" in codes:
+        suppressed.update(_route_contract_suppressions(codes))
     # The promoted signature-restatement rules now block. Keep their errors and
     # drop only the lower-severity typed-docstring twin at the same owner.
-    if Severity.WARNING in codes.get("SARJ092", set()) and any(
-        Severity.ERROR in codes.get(generic, set()) for generic in ("SARJ086", "SARJ087")
-    ):
+    if _typed_docstring_warning_is_superseded(codes):
         suppressed.add(("SARJ092", Severity.WARNING))
     return suppressed
 
 
+def _precedence_suppressions(codes: dict[str, set[Severity]]) -> set[tuple[str, Severity]]:
+    suppressed: set[tuple[str, Severity]] = set()
+    for specific, generics in _DIAGNOSTIC_PRECEDENCE.items():
+        if specific not in codes:
+            continue
+        specific_severities = codes[specific]
+        for generic in generics:
+            for generic_severity in codes.get(generic, set()):
+                if generic_severity is Severity.WARNING or Severity.ERROR in specific_severities:
+                    suppressed.add((generic, generic_severity))
+    return suppressed
+
+
+def _route_contract_suppressions(codes: dict[str, set[Severity]]) -> set[tuple[str, Severity]]:
+    return {
+        (generic, severity) for generic in _DIAGNOSTIC_PRECEDENCE["SARJ094"] for severity in codes.get(generic, set())
+    }
+
+
+def _typed_docstring_warning_is_superseded(codes: dict[str, set[Severity]]) -> bool:
+    if Severity.WARNING not in codes.get("SARJ092", set()):
+        return False
+    return any(Severity.ERROR in codes.get(generic, set()) for generic in ("SARJ086", "SARJ087"))
+
+
 def _function_signature_owner_locations(source: str) -> dict[int, _OwnerLocation]:
     try:
         tree = ast.parse(source)

sarj_python_lint-0.86.0/src/sarj_python_lint/rules/_annotation_semantics.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Self
+
+from sarj_python_lint.rules._imports import ImportIndex
+
+
+_TYPING_SOURCES = frozenset({"typing", "typing_extensions"})
+_TRANSPARENT_WRAPPERS = frozenset({"Annotated", "ClassVar", "Final", "NotRequired", "Optional", "ReadOnly", "Required"})
+
+
+@dataclass(frozen=True, slots=True)
+class AnnotationSemantics:
+    imports: ImportIndex
+    aliases: MappingProxyType[str, ast.expr]
+
+    @classmethod
+    def from_tree(cls, tree: ast.Module, *, module_scope_only: bool = True) -> Self:
+        imports = ImportIndex.from_tree(tree, module_scope_only=module_scope_only)
+        candidates: dict[str, ast.expr] = {}
+        ambiguous: set[str] = set()
+        for statement in tree.body:
+            name: str | None = None
+            value: ast.expr | None = None
+            match statement:
+                case ast.TypeAlias(name=ast.Name(id=alias), value=alias_value, type_params=[]):
+                    name, value = alias, alias_value
+                case ast.AnnAssign(target=ast.Name(id=alias), annotation=annotation, value=alias_value) if (
+                    alias_value is not None
+                    and imports.resolves(annotation, sources=_TYPING_SOURCES, symbol="TypeAlias")
+                ):
+                    name, value = alias, alias_value
+                case _:
+                    pass
+            if name is None or value is None:
+                continue
+            if name in candidates:
+                ambiguous.add(name)
+            else:
+                candidates[name] = value
+        if not candidates:
+            return cls(imports, MappingProxyType({}))
+        rebound = _module_rebindings(tree)
+        aliases = {name: value for name, value in candidates.items() if name not in ambiguous and name not in rebound}
+        return cls(imports, MappingProxyType(aliases))
+
+    def parse(self, annotation: ast.expr | None) -> ast.expr | None:
+        if not isinstance(annotation, ast.Constant) or not isinstance(annotation.value, str):
+            return annotation
+        try:
+            parsed = ast.parse(annotation.value.strip(), mode="eval").body
+        except SyntaxError:
+            return None
+        ast.copy_location(parsed, annotation)
+        return parsed
+
+    def resolve_alias(self, annotation: ast.expr | None, *, seen: frozenset[str] = frozenset()) -> ast.expr | None:
+        resolved = self.parse(annotation)
+        while isinstance(resolved, ast.Name) and resolved.id in self.aliases and resolved.id not in seen:
+            seen |= {resolved.id}
+            resolved = self.parse(self.aliases[resolved.id])
+        return resolved
+
+    def transparent_members(
+        self, annotation: ast.expr | None, *, seen: frozenset[str] = frozenset()
+    ) -> tuple[ast.expr, ...]:
+        resolved = self.parse(annotation)
+        if resolved is None:
+            return ()
+        if isinstance(resolved, ast.Name) and resolved.id in self.aliases:
+            return self._alias_members(resolved.id, seen=seen)
+        if isinstance(resolved, ast.BinOp) and isinstance(resolved.op, ast.BitOr):
+            return self.transparent_members(resolved.left, seen=seen) + self.transparent_members(
+                resolved.right, seen=seen
+            )
+        if isinstance(resolved, ast.Subscript):
+            return self._subscript_members(resolved, seen=seen)
+        return (resolved,)
+
+    def _alias_members(self, name: str, *, seen: frozenset[str]) -> tuple[ast.expr, ...]:
+        if name in seen:
+            return ()
+        return self.transparent_members(self.aliases[name], seen=seen | {name})
+
+    def _subscript_members(self, node: ast.Subscript, *, seen: frozenset[str]) -> tuple[ast.expr, ...]:
+        wrapper = self.imports.resolved_symbol(node.value, sources=_TYPING_SOURCES)
+        if wrapper == "Union":
+            members = node.slice.elts if isinstance(node.slice, ast.Tuple) else [node.slice]
+            return self._flatten_members(members, seen=seen)
+        if wrapper not in _TRANSPARENT_WRAPPERS:
+            return (node,)
+        inner = node.slice.elts[0] if isinstance(node.slice, ast.Tuple) else node.slice
+        return self.transparent_members(inner, seen=seen)
+
+    def _flatten_members(self, nodes: list[ast.expr], *, seen: frozenset[str]) -> tuple[ast.expr, ...]:
+        members: list[ast.expr] = []
+        for node in nodes:
+            members.extend(self.transparent_members(node, seen=seen))
+        return tuple(members)
+
+
+def _module_rebindings(tree: ast.Module) -> set[str]:
+    counts: dict[str, int] = {}
+    for statement in tree.body:
+        for name in _bound_names(statement):
+            counts[name] = counts.get(name, 0) + 1
+    return {name for name, count in counts.items() if count > 1}
+
+
+def scope_bound_names(statements: list[ast.stmt]) -> set[str]:
+    return {name for statement in statements for name in _bound_names(statement)}
+
+
+def _bound_names(statement: ast.stmt) -> set[str]:
+    collector = _ScopeBindings()
+    collector.visit(statement)
+    return collector.names
+
+
+def _target_names(node: ast.expr) -> set[str]:
+    if isinstance(node, ast.Name):
+        return {node.id}
+    if isinstance(node, (ast.List, ast.Tuple)):
+        return {name for item in node.elts for name in _target_names(item)}
+    return set()
+
+
+class _ScopeBindings(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.names: set[str] = set()
+
+    def visit_Name(self, node: ast.Name) -> None:
+        if isinstance(node.ctx, (ast.Store, ast.Del)):
+            self.names.add(node.id)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self.names.add(node.name)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self.names.add(node.name)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.names.add(node.name)
+
+    def visit_Lambda(self, node: ast.Lambda) -> None:
+        pass
+
+    def visit_Import(self, node: ast.Import) -> None:
+        self.names.update(alias.asname or alias.name.partition(".")[0] for alias in node.names)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        self.names.update(alias.asname or alias.name for alias in node.names if alias.name != "*")
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
+        if node.name is not None:
+            self.names.add(node.name)
+        self.generic_visit(node)
+
+    def visit_MatchAs(self, node: ast.MatchAs) -> None:
+        if node.name is not None:
+            self.names.add(node.name)
+        self.generic_visit(node)
+
+    def visit_MatchStar(self, node: ast.MatchStar) -> None:
+        if node.name is not None:
+            self.names.add(node.name)
+
+    def visit_MatchMapping(self, node: ast.MatchMapping) -> None:
+        if node.rest is not None:
+            self.names.add(node.rest)
+        self.generic_visit(node)