sarj-python-lint 1.88.0__tar.gz → 1.88.20__tar.gz

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/PKG-INFO

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

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

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/_fastapi.py

@@ -3,6 +3,10 @@ from __future__ import annotations
 import ast
 from collections import Counter
 from dataclasses import dataclass
+from functools import cached_property
+from http import HTTPStatus
+import re
+from types import MappingProxyType
 from typing import TYPE_CHECKING, Literal, NamedTuple
 
 from sarj_python_lint._source import read_python_source
@@ -19,19 +23,24 @@ HTTP_METHODS = frozenset({"get", "post", "put", "patch", "delete", "options", "h
 PARAM_MARKERS = frozenset({"Path", "Query", "Header", "Cookie", "Body", "Form", "File", "Depends", "Security"})
 SCHEMA_MARKERS = PARAM_MARKERS - {"Depends", "Security"}
 INJECTION_TYPES = frozenset({"Request", "Response", "WebSocket", "HTTPConnection", "BackgroundTasks", "SecurityScopes"})
-RESPONSE_TYPES = frozenset(
+_RESPONSE_DEFAULT_STATUSES = MappingProxyType(
     {
-        "Response",
-        "JSONResponse",
-        "HTMLResponse",
-        "PlainTextResponse",
-        "RedirectResponse",
-        "StreamingResponse",
-        "FileResponse",
-        "ORJSONResponse",
-        "UJSONResponse",
+        "Response": HTTPStatus.OK,
+        "JSONResponse": HTTPStatus.OK,
+        "HTMLResponse": HTTPStatus.OK,
+        "PlainTextResponse": HTTPStatus.OK,
+        "RedirectResponse": HTTPStatus.TEMPORARY_REDIRECT,
+        "StreamingResponse": HTTPStatus.OK,
+        "FileResponse": HTTPStatus.OK,
+        "ORJSONResponse": HTTPStatus.OK,
+        "UJSONResponse": HTTPStatus.OK,
     }
 )
+RESPONSE_TYPES = frozenset(_RESPONSE_DEFAULT_STATUSES)
+_STARLETTE_RESPONSE_TYPES = RESPONSE_TYPES - {"ORJSONResponse", "UJSONResponse"}
+_JSON_RESPONSE_TYPES = frozenset({"JSONResponse", "ORJSONResponse", "UJSONResponse"})
+NO_BODY_STATUSES = frozenset({204, 205, 304})
+_STATUS_MEMBER = re.compile(r"HTTP_(\d{3})_[A-Z0-9_]+")
 _DEPENDENCY_MARKERS = frozenset({"Depends", "Security"})
 _CONSTRUCTOR_SOURCES = frozenset({"fastapi", "fastapi.applications", "fastapi.routing"})
 _MAX_IMPORTED_MODULE_BYTES = 500_000
@@ -50,6 +59,7 @@ class Route:
     inherited_responses: ast.expr | None = None
     inherited_response_class: ast.expr | None = None
     inherited_prefix: ast.expr | None = None
+    inherited_has_unpack: bool = False
 
     @property
     def keywords(self) -> dict[str, ast.expr]:
@@ -154,6 +164,7 @@ class FastapiIndex:
         self.receiver_kinds: dict[_ReceiverKey, Literal["FastAPI", "APIRouter"]] = {}
         self.hidden_receivers: set[_ReceiverKey] = set()
         self.receiver_defaults: dict[_ReceiverKey, dict[str, ast.expr]] = {}
+        self.unpacked_receivers: set[_ReceiverKey] = set()
         self.decorators: dict[_ReceiverKey, _DecoratorBinding] = {}
         self.bound_names: set[_ReceiverKey] = set()
         self._node_scopes: dict[int, int] = {}
@@ -394,6 +405,8 @@ class FastapiIndex:
                 for keyword in value.keywords
                 if keyword.arg in {"responses", "default_response_class", "prefix"}
             }
+            if any(keyword.arg is None for keyword in value.keywords):
+                self.unpacked_receivers.add(key)
         if self._constructor_is_hidden(value):
             self.hidden_receivers.add(key)
 
@@ -497,6 +510,7 @@ class FastapiIndex:
                 inherited_responses=defaults.get("responses"),
                 inherited_response_class=defaults.get("default_response_class"),
                 inherited_prefix=defaults.get("prefix"),
+                inherited_has_unpack=origin in self.unpacked_receivers,
             )
             for route_method in route_methods
         )
@@ -541,6 +555,167 @@ class FastapiIndex:
             case _:
                 return ""
 
+    def status_code(self, node: ast.expr | None) -> int | None:
+        if isinstance(node, ast.Constant) and isinstance(node.value, int):
+            return node.value
+        if not isinstance(node, (ast.Name, ast.Attribute)) or self._is_shadowed_in_enclosing_scope(node):
+            return None
+        qualified = self.imports.resolved_qualified_name(node) or ""
+        module, _, member = qualified.rpartition(".")
+        if (
+            module == "starlette.status"
+            and module not in self._unstable_native_providers
+            and (match := _STATUS_MEMBER.fullmatch(member))
+        ):
+            return int(match.group(1))
+        if not isinstance(node, ast.Attribute):
+            return None
+        owner = self._status_provider(node.value)
+        if owner in self._unstable_native_providers:
+            return None
+        if owner == "starlette.status" and (match := _STATUS_MEMBER.fullmatch(node.attr)):
+            return int(match.group(1))
+        if owner == "http.HTTPStatus":
+            status = HTTPStatus.__members__.get(node.attr)
+            return status.value if status is not None else None
+        return None
+
+    def operation_status_code(self, route: Route) -> int | None:
+        node = route.keywords.get("status_code")
+        if node is None and route.has_unpack:
+            return None
+        if node is None or (isinstance(node, ast.Constant) and node.value is None):
+            if not self.response_classes_are_stable:
+                return None
+            if route.has_unpack and "response_class" not in route.keywords:
+                return None
+            response_class = route.keywords.get("response_class") or route.inherited_response_class
+            if response_class is None:
+                return None if route.inherited_has_unpack else HTTPStatus.OK
+            response_name = self.response_class_name(response_class)
+            return _RESPONSE_DEFAULT_STATUSES.get(response_name) if response_name is not None else None
+        return self.status_code(node)
+
+    def response_class_name(self, node: ast.expr) -> str | None:
+        if not self.response_classes_are_stable:
+            return None
+        return self._native_response_name(self._response_import(node))
+
+    def can_infer_json_response(self, route: Route) -> bool:
+        if route.has_unpack:
+            return False
+        status = self.operation_status_code(route)
+        if status is None or status in NO_BODY_STATUSES:
+            return False
+        response_class = route.keywords.get("response_class") or route.inherited_response_class
+        if response_class is None:
+            return not route.inherited_has_unpack and self.response_classes_are_stable
+        return self.response_class_name(response_class) in _JSON_RESPONSE_TYPES
+
+    @property
+    def response_classes_are_stable(self) -> bool:
+        return "responses" not in self._unstable_native_providers
+
+    @staticmethod
+    def _native_response_name(qualified: str | None) -> str | None:
+        if qualified is None:
+            return None
+        module, _, name = qualified.rpartition(".")
+        if module == "fastapi" and name == "Response":
+            return name
+        if module == "fastapi.responses" and name in RESPONSE_TYPES:
+            return name
+        if module == "starlette.responses" and name in _STARLETTE_RESPONSE_TYPES:
+            return name
+        return None
+
+    def _response_import(self, node: ast.expr) -> str | None:
+        if not isinstance(node, (ast.Name, ast.Attribute)) or self._is_shadowed_in_enclosing_scope(node):
+            return None
+        qualified = self.imports.resolved_qualified_name(node)
+        if isinstance(node, ast.Name) and qualified is None:
+            binding = self.imports.bindings.get(node.id)
+            return binding.module if binding is not None and binding.symbol is None else None
+        if isinstance(node, ast.Attribute) and qualified is None:
+            module = self.imports.resolved_qualified_name(node.value)
+            return f"{module}.{node.attr}" if module is not None else None
+        return qualified
+
+    def _status_provider(self, node: ast.expr) -> str | None:
+        if not isinstance(node, (ast.Name, ast.Attribute)) or self._is_shadowed_in_enclosing_scope(node):
+            return None
+        qualified = self.imports.resolved_qualified_name(node)
+        if isinstance(node, ast.Name) and qualified is None:
+            binding = self.imports.bindings.get(node.id)
+            qualified = (
+                binding.module
+                if binding is not None and binding.symbol is None and binding.module != "fastapi.status"
+                else None
+            )
+        # FastAPI exports Starlette's status module rather than a status submodule.
+        if qualified == "fastapi.status":
+            return "starlette.status"
+        return qualified if qualified in {"starlette.status", "http.HTTPStatus"} else None
+
+    @cached_property
+    def _unstable_native_providers(self) -> frozenset[str]:
+        providers: set[str] = set()
+        route_calls: set[int] = set()
+        for node in walk_ast(self.tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                route_calls.update(id(route.decorator) for route in self.routes(node))
+                continue
+            values = self._provider_values(node)
+            if not values:
+                continue
+            for value in values:
+                if (provider := self._status_provider(value)) is not None:
+                    providers.add(provider)
+            for value in self._response_provider_values(node, values, route_calls):
+                qualified = self._response_import(value)
+                if qualified in {"fastapi.responses", "starlette.responses"} or self._native_response_name(qualified):
+                    providers.add("responses")
+        return frozenset(providers)
+
+    @staticmethod
+    def _provider_values(node: ast.AST) -> tuple[ast.expr, ...]:
+        match node:
+            case ast.Attribute(value=value, ctx=ast.Store() | ast.Del()):
+                return node, value
+            case ast.Assign(value=value) | ast.AnnAssign(value=ast.expr() as value) | ast.NamedExpr(value=value):
+                return (value,)
+            case ast.Return(value=ast.expr() as value):
+                return (value,)
+            case ast.Call(args=args, keywords=keywords):
+                return (*args, *(keyword.value for keyword in keywords))
+            case _:
+                return ()
+
+    def _response_provider_values(
+        self, node: ast.AST, values: tuple[ast.expr, ...], route_calls: set[int]
+    ) -> tuple[ast.expr, ...]:
+        if not isinstance(node, ast.Call):
+            return values
+        trusted_keyword = self._trusted_response_keyword(node, route_calls)
+        return (*node.args, *(keyword.value for keyword in node.keywords if keyword.arg != trusted_keyword))
+
+    def _trusted_response_keyword(self, node: ast.Call, route_calls: set[int]) -> str | None:
+        trusted_keyword = "response_class" if id(node) in route_calls else None
+        if (
+            any(keyword.arg == "default_response_class" for keyword in node.keywords)
+            and self.constructor_kind(node) is not None
+        ):
+            return "default_response_class"
+        if not isinstance(node.func, ast.Attribute) or node.func.attr not in {"include_router", "add_api_route"}:
+            return trusted_keyword
+        scope = self._node_scopes.get(id(node), 0)
+        receiver = _binding_name(node.func.value)
+        if receiver.startswith("self."):
+            scope = self._node_classes.get(id(node)) or scope
+        if self._receiver_key(scope, receiver) is None:
+            return trusted_keyword
+        return "default_response_class" if node.func.attr == "include_router" else "response_class"
+
     @staticmethod
     def _root_name(node: ast.Attribute) -> str:
         value: ast.expr = node

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/_opaque_contracts.py

@@ -192,7 +192,7 @@ class OpaqueContractFacts:
 
     def _find_checked(self, function: _Function) -> frozenset[ast.arg]:
         found = set(self.native.namespace(function).parameters())
-        terminal_rejection = _rejects(function.body)
+        terminal_rejection = self._rejects(function.body)
         for node in direct_nodes(function):
             if not self.reachable(node, function):
                 continue
@@ -206,8 +206,85 @@ class OpaqueContractFacts:
                 found.update(self._statement_parameters(node, terminal_rejection=terminal_rejection))
         found.update(self._identity_parameters(function))
         found.update(self._key_parameters(function))
+        found.update(self._model_iteration_parameters(function))
         return frozenset(found)
 
+    def _model_iteration_parameters(self, function: _Function) -> set[ast.arg]:
+        found: set[ast.arg] = set()
+        for parameter in (*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs):
+            if not self._opaque_iterable(parameter):
+                continue
+            loops = self._parameter_iterations(parameter, function)
+            if loops and all(self._validated_iteration(loop, function) for loop in loops):
+                found.add(parameter)
+        return found
+
+    def _opaque_iterable(self, parameter: ast.arg) -> bool:
+        if parameter.annotation is None:
+            return False
+        resolved = self.facts.resolve_annotation(parameter.annotation)
+        if resolved is None or not isinstance(resolved.expression, ast.Subscript):
+            return False
+        node = resolved.expression
+        return self.facts.qualified(node.value, resolved.at) in {
+            "collections.abc.Iterable",
+            "typing.Iterable",
+        } and _unknown_slot(node.slice, self.facts, resolved.at)
+
+    def _parameter_iterations(self, parameter: ast.arg, function: _Function) -> list[ast.For] | None:
+        loops: list[ast.For] = []
+        members = set(direct_nodes(function))
+        for read in self.facts.provenance.reads.get(parameter.arg, ()):
+            runtime = self.facts.provenance.runtime_binding(read.id, read)
+            if runtime is not parameter and self.facts.provenance.binding(read.id, read) is not parameter:
+                continue
+            if not self.reachable(read, function):
+                continue
+            owner = self.context.parents.get(read)
+            if (
+                runtime is not parameter
+                or not isinstance(owner, ast.For)
+                or owner not in members
+                or owner.iter is not read
+                or not isinstance(owner.target, ast.Name)
+            ):
+                return None
+            loops.append(owner)
+        return loops
+
+    def _validated_iteration(self, loop: ast.For, function: _Function) -> bool:
+        if not isinstance(loop.target, ast.Name):
+            return False
+        reads = [
+            read
+            for read in self.facts.provenance.reads.get(loop.target.id, ())
+            if (
+                self.facts.provenance.runtime_binding(read.id, read) is loop.target
+                or self.facts.provenance.binding(read.id, read) is loop.target
+            )
+            and self.reachable(read, function)
+        ]
+        members = set(direct_nodes(loop))
+        return bool(reads) and all(
+            self.facts.provenance.runtime_binding(read.id, read) is loop.target
+            and read in members
+            and self._model_element_read(read)
+            for read in reads
+        )
+
+    def _model_element_read(self, read: ast.Name) -> bool:
+        call = self.context.parents.get(read)
+        if isinstance(call, ast.keyword):
+            call = self.context.parents.get(call)
+        if not isinstance(call, ast.Call) or not isinstance(call.func, ast.Attribute):
+            return False
+        arguments = call_arguments(call, ("obj",))
+        if call.func.attr != "model_validate" or arguments is None or arguments.get("obj") is not read:
+            return False
+        contracts = DeclaredContracts(self.context)
+        model = contracts.class_type(call.func.value)
+        return model is not None and contracts.inherits(model, _VALIDATION_BASES)
+
     def _key_parameters(self, function: _Function) -> set[ast.arg]:
         found: set[ast.arg] = set()
         for parameter in (*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs):
@@ -337,7 +414,7 @@ class OpaqueContractFacts:
                 return set()
 
     def _if_parameters(self, node: ast.If) -> set[ast.arg]:
-        if _rejects(node.body):
+        if self._rejects(node.body):
             candidate = node.test
             if isinstance(candidate, ast.BoolOp) and isinstance(candidate.op, ast.Or):
                 candidate = candidate.values[0]
@@ -345,7 +422,7 @@ class OpaqueContractFacts:
                 return {parameter}
             if isinstance(candidate, ast.UnaryOp) and isinstance(candidate.op, ast.Not):
                 return self._predicate(candidate.operand)
-        return self._predicate(node.test) if _rejects(node.orelse) else set()
+        return self._predicate(node.test) if self._rejects(node.orelse) else set()
 
     def _match_parameters(self, node: ast.Match) -> set[ast.arg]:
         if not node.cases:
@@ -355,7 +432,7 @@ class OpaqueContractFacts:
             isinstance(last.pattern, ast.MatchAs)
             and last.pattern.name is None
             and last.guard is None
-            and _rejects(last.body)
+            and self._rejects(last.body)
         ):
             return set()
         parameter = self.parameter(node.subject)
@@ -363,6 +440,21 @@ class OpaqueContractFacts:
             return {parameter}
         return set()
 
+    def _rejects(self, body: list[ast.stmt]) -> bool:
+        if _rejects(body):
+            return True
+        if not body or not isinstance(body[-1], ast.Expr) or not isinstance(body[-1].value, ast.Call):
+            return False
+        source = self._source(body[-1].value.func)
+        if source is None:
+            return False
+        _owner, function = source
+        return (
+            bool(function.body)
+            and isinstance(function.body[-1], ast.Raise)
+            and not any(isinstance(node, ast.Return | ast.Yield | ast.YieldFrom) for node in direct_nodes(function))
+        )
+
     def _predicate(self, expression: ast.expr) -> set[ast.arg]:
         if isinstance(expression, ast.BoolOp):
             return self._predicate(expression.values[0])

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/fastapi_class_router_contract.py

@@ -27,7 +27,6 @@ if TYPE_CHECKING:
     from sarj_python_lint.rules._ast_index import NodeIndex
 
 
-_NO_BODY = frozenset({204, 304})
 _NON_JSON_RESPONSES = frozenset(
     {"FileResponse", "HTMLResponse", "PlainTextResponse", "RedirectResponse", "StreamingResponse"}
 )
@@ -56,7 +55,9 @@ class FastapiClassRouterContract(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Tests, generated code, and hidden routes are excluded. FastAPI application construction and include_router composition are allowed.",
-            "Response-model checks exclude 204/304 responses and explicit stream/file/HTML/text/redirect responses.",
+            "Response-model checks exclude literal or import-proven 204/205/304 statuses and proven non-JSON response classes, including raw Response.",
+            "Unpacked metadata or an explicit unresolved status cannot prove a JSON response; receiver ownership remains checked while response-model inference abstains.",
+            "Response classes require unshadowed native import provenance; direct provider writes/escapes, custom classes, and unresolved defaults disable JSON-model inference.",
         ),
         examples=(
             RuleExample(
@@ -211,12 +212,11 @@ def _response_problem(
     function: ast.FunctionDef | ast.AsyncFunctionDef, route: Route, index: FastapiIndex
 ) -> str | None:
     keywords = route.keywords
-    status = keywords.get("status_code")
-    if isinstance(status, ast.Constant) and status.value in _NO_BODY:
-        return None
     response_class = keywords.get("response_class") or route.inherited_response_class
     if response_class is not None and flat_name(response_class) in _NON_JSON_RESPONSES:
         return None
+    if not index.can_infer_json_response(route):
+        return None
     response_model = keywords.get("response_model")
     if response_model is None or (isinstance(response_model, ast.Constant) and response_model.value is None):
         return "JSON operation requires explicit `response_model=NamedResponse`"

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/fastapi_explicit_openapi_contract.py

@@ -20,6 +20,7 @@ from sarj_python_lint.rule_base import (
 )
 from sarj_python_lint.rules._ast_index import children
 from sarj_python_lint.rules._fastapi import (
+    NO_BODY_STATUSES,
     SCHEMA_MARKERS,
     FastapiIndex,
     Route,
@@ -89,6 +90,9 @@ class FastapiExplicitOpenapiContract(Rule):
         limitations=(
             "Hidden routes, WebSocket handlers, tests, generated files, documentation-source examples, and unrelated decorators are excluded.",
             "Dynamic response mappings are accepted when their contents cannot be resolved statically.",
+            "Response-body/model inference abstains for unresolved status/class metadata, direct native-provider writes/escapes, and opaque unpacked defaults; no-body JSON metadata includes 205.",
+            "Direct-status alias/callee/catch recognition retains its existing limits; broader coverage requires separate reachability and runtime-dispatch evidence.",
+            "Route conflicts require unconditional registrations on the same local router; conditional composition requires trusted route/schema validation.",
             "Operation ID conflicts require unconditional registrations with literal IDs and paths on the same local router; conditional registrations, dynamic IDs, OpenAPI overrides, and cross-router composition require generated-schema validation.",
             "Explicit status and parameter-location findings are organizational policy even when FastAPI inference would generate valid OpenAPI.",
             (
@@ -268,7 +272,7 @@ class FastapiExplicitOpenapiContract(Rule):
                 findings.extend(_check_metadata(route, index))
                 findings.extend(_check_projection(route))
                 findings.extend(_check_response_statuses(route, index))
-        findings.extend(_check_route_conflicts(declared))
+        findings.extend(_check_route_conflicts(declared, context.parents))
         findings.extend(_check_operation_ids(declared, context.parents))
         return [
             Diagnostic(
@@ -548,7 +552,9 @@ def _check_inferred_return(
     if not builds_fixed_record(function, imports=index.imports):
         return []
     for route in _operations(routes):
-        if route.has_unpack:
+        if route.inherited_has_unpack and route.inherited_responses is None:
+            continue
+        if not index.can_infer_json_response(route):
             continue
         response_model = route.keywords.get("response_model")
         status = _status_code(route.keywords.get("status_code"), index) or HTTPStatus.OK
@@ -572,13 +578,22 @@ def _check_return_route(route: Route, contract: _ReturnContract, index: FastapiI
     if contract.erases_schema and not _concrete_response_model(response_model, index):
         problems.add("response annotation erases its OpenAPI schema; define an output model")
     status = _status_code(keywords.get("status_code"), index)
+    proven_status = index.operation_status_code(route)
+    body_status_is_known = proven_status is not None and proven_status not in NO_BODY_STATUSES
     response_class = keywords.get("response_class") or route.inherited_response_class
-    if contract.is_response and status not in _NO_CONTENT_STATUSES and response_class is None:
+    default_class_is_known = not route.inherited_has_unpack and index.response_classes_are_stable
+    if (
+        contract.is_response
+        and status not in _NO_CONTENT_STATUSES
+        and body_status_is_known
+        and response_class is None
+        and default_class_is_known
+    ):
         problems.add("direct Response return requires response_class= for accurate OpenAPI")
     _check_response_body(route, contract, index, problems)
     if response_model is not None and not response_model_none and _schema_erasing(response_model, index):
         problems.add("response_model erases its OpenAPI schema; define an output model")
-    if status in _NO_CONTENT_STATUSES:
+    if status in _NO_CONTENT_STATUSES and status == proven_status:
         if response_model is not None and not response_model_none:
             problems.add(f"status {status} must not declare a response model")
         if not (contract.is_none or contract.is_response):
@@ -589,19 +604,30 @@ def _check_response_body(route: Route, contract: _ReturnContract, index: Fastapi
     response_model = route.keywords.get("response_model")
     response_model_none = response_model is not None and _literal_none(response_model)
     status = _status_code(route.keywords.get("status_code"), index)
+    proven_status = index.operation_status_code(route)
     response_class = route.keywords.get("response_class") or route.inherited_response_class
     response_name = index.response_name(contract.annotation)
     class_name = index.response_name(response_class)
-    response_class_is_unresolved = response_class is not None and not class_name
+    proven_class_name = index.response_class_name(response_class) if response_class is not None else None
+    response_class_is_unresolved = (response_class is not None and (not class_name or proven_class_name is None)) or (
+        response_class is None and (route.inherited_has_unpack or not index.response_classes_are_stable)
+    )
     has_documented_body = (
         _concrete_response_model(response_model, index)
         or any(_documents_response_content(node, status, index) for node in _route_response_nodes(route))
         or class_name in _SELF_DOCUMENTING_RESPONSE_CLASSES
+        or proven_class_name in _SELF_DOCUMENTING_RESPONSE_CLASSES
         or response_class_is_unresolved
     )
-    if response_name not in {"", "Response"} and class_name and response_name != class_name:
+    if (
+        response_name not in {"", "Response"}
+        and class_name
+        and proven_class_name is not None
+        and response_name != class_name
+    ):
         problems.add(f"return type {response_name} conflicts with response_class={class_name}")
-    if contract.is_response and status not in _NO_CONTENT_STATUSES and not has_documented_body:
+    body_status_is_known = proven_status is not None and proven_status not in NO_BODY_STATUSES
+    if contract.is_response and status not in _NO_CONTENT_STATUSES and body_status_is_known and not has_documented_body:
         problems.add("direct Response return requires a concrete response_model or responses content schema")
     elif not contract.is_response and not contract.is_none and response_model_none:
         problems.add("response_model=None suppresses the declared response schema")
@@ -725,14 +751,7 @@ def _check_direct_responses(
     if not direct.statuses:
         return findings
     for route in _operations(routes):
-        responses = _route_response_nodes(route)
-        if any(not isinstance(node, ast.Dict) for node in responses):
-            continue
-        documented = {
-            status for node in responses if isinstance(node, ast.Dict) for status in _response_codes(node, index)
-        }
-        primary = _status_code(route.keywords.get("status_code"), index)
-        missing = sorted(direct.statuses - documented - ({primary} if primary is not None else set()))
+        missing = _undocumented_direct_statuses(route, direct.statuses, index)
         if missing:
             findings.append(
                 _Finding(
@@ -743,6 +762,23 @@ def _check_direct_responses(
     return findings
 
 
+def _undocumented_direct_statuses(route: Route, statuses: set[int], index: FastapiIndex) -> list[int]:
+    if route.has_unpack or (route.inherited_has_unpack and route.inherited_responses is None):
+        return []
+    proven_primary = index.operation_status_code(route)
+    if proven_primary is None:
+        return []
+    responses = _route_response_nodes(route)
+    if any(not isinstance(node, ast.Dict) for node in responses):
+        return []
+    documented = {status for node in responses if isinstance(node, ast.Dict) for status in _response_codes(node, index)}
+    primary = _status_code(route.keywords.get("status_code"), index)
+    primary_statuses = {proven_primary}
+    if primary is not None:
+        primary_statuses.add(primary)
+    return sorted(statuses - documented - primary_statuses)
+
+
 @dataclass(frozen=True, slots=True)
 class _DirectResponseStatuses:
     statuses: set[int]
@@ -794,13 +830,15 @@ def _direct_statuses(
     statuses: list[tuple[ast.Call, int]] = []
     call = current.exc if isinstance(current, ast.Raise) else None
     if isinstance(call, ast.Call) and index.is_http_exception(call.func) and not catches_http_exception:
-        status = _status_code(_keyword(call, "status_code") or (call.args[0] if call.args else None), index)
-        if status is not None:
+        status_node = _keyword(call, "status_code") or (call.args[0] if call.args else None)
+        status = _status_code(status_node, index)
+        if status is not None and index.status_code(status_node) == status:
             statuses.append((call, status))
     returned = current.value if isinstance(current, ast.Return) else None
     if isinstance(returned, ast.Call) and index.is_response(returned.func):
-        status = _status_code(_keyword(returned, "status_code"), index)
-        if status is not None:
+        status_node = _keyword(returned, "status_code")
+        status = _status_code(status_node, index)
+        if status is not None and index.status_code(status_node) == status:
             statuses.append((returned, status))
     return statuses
 
@@ -890,12 +928,12 @@ def _function_scopes(tree: ast.Module) -> dict[int, int]:
     return scopes
 
 
-def _check_route_conflicts(routes: list[tuple[int, Route]]) -> list[_Finding]:
+def _check_route_conflicts(routes: list[tuple[int, Route]], parents: Mapping[ast.AST, ast.AST]) -> list[_Finding]:
     findings: list[_Finding] = []
     seen: dict[tuple[int, str, str, str], Route] = {}
     dynamic: dict[tuple[int, str, str], list[tuple[Route, re.Pattern[str]]]] = {}
     for scope, route in sorted(routes, key=lambda item: item[1].decorator.lineno):
-        if route.path is None or route.method == "*":
+        if route.path is None or route.method == "*" or _conditional_registration(route.decorator, parents):
             continue
         key = scope, route.receiver, route.method, route.path
         if key in seen:

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/prefer_precise_object_contract.py

@@ -54,6 +54,8 @@ class PreferPreciseObjectContract(Rule):
             "Ordinary raw validators retain object inputs tied to builtin isinstance, exact builtin type comparisons or an actual source-resolved TypeGuard/TypeIs through rejecting branches, actual type/refinement assertions, accepting terminal branches with a rejecting fallback, or conditional expressions. Stable projections from containers with unchecked value slots retain their raw root contract when those values are validated. Source-visible local and imported validators may delegate those inputs and raw results; precise result narrowing does not justify a bare object output. Related unchecked mapping projections and transforms retain unknown values; import-proven native parsers and JSONDecoder preserve raw outputs. Universal builtin and stdlib interoperation may retain raw inputs. Independent object parameters, domain constructors and unproven parser names remain checked. Source resolution and dataflow are bounded with cycle guards; rebinding, decorators and namespace mutation invalidate delegated proof.",
             "Native opaque contracts include canonical ast.Constant.value reads and captures, FunctionType invocations, identity-only inputs and sys.getrefcount. Actual exec/eval globals and locals retain unknown values only through bounded native dict construction and alias flow; unrelated dictionaries and source domain factories do not borrow that ownership. Stub property returns on an import-proven runtime_checkable Protocol retain unchecked incoming attributes. Generic callable results, ordinary Protocol methods, application properties and unused parameters remain checked.",
             "Raw input unions may include scalar or None branches; only genuine unchecked container branches seed raw projections. Mapping consumers that inspect only keys retain uninspected value slots. Projected aliases require simple statement dominance, and precise active guards permit typed consumption after validation. Native namespace output reads require a preceding direct function-scope execution and abstain after authored mutations. Benign builtins imports do not hide builtin object contracts; explicit object shadowing and source-visible object mutations remain outside scope.",
+            "An import-proven Iterable of unchecked values retains its raw element contract when every input use is a direct synchronous iteration and every reachable element read directly enters source-proven Pydantic model_validate. Deferred closures, rebinding, other iterator/element uses, unknown model providers and JSON-text parsers do not establish that boundary.",
+            "Rejecting branches may end in a stable source-visible synchronous helper whose body ends with an unconditional raise and contains no return or yield path. Names and NoReturn annotations alone do not establish termination; decorated, mutated, asynchronous, generator and returning helpers remain unknown.",
         ),
         examples=(
             RuleExample(

{sarj_python_lint-1.88.0 → sarj_python_lint-1.88.20}/src/sarj_python_lint/rules/prefer_typed_cli.py

@@ -42,7 +42,7 @@ class PreferTypedCli(Rule):
         category=RuleCategory.MAINTAINABILITY,
         autofix=AutofixPolicy.NONE,
         limitations=(
-            "Checks import-proven sys.argv reads, argparse/optparse parser construction, getopt parsing and Click command construction. sys.argv[0], assignment targets and forwarding through args= to a proven local Typer application are retained.",
+            "Checks import-proven sys.argv reads, argparse/optparse parser construction, getopt parsing and Click command construction. sys.argv[0] and its direct nonempty guard with a literal string fallback, assignment targets and forwarding through args= to a proven local Typer application are retained.",
             "Checks parameters of source-visible functions passed directly to typer.run or registered with a stable local Typer application's command/callback decorator. Missing annotations and bare Any/object, including Annotated wrappers, are reported. Ordinary functions and unrelated command decorators are excluded.",
             "Stable local import and application aliases are followed. Shadowed or mutated imports, wildcard imports, dynamic namespaces and generated/vendor files abstain. Imported command functions, dynamic registrations and composite erased types require separate type checking.",
             "No automatic rewrite: positional/option compatibility and conversion behavior require review. This policy does not claim every argparse or Click program is incorrectly validated.",
@@ -191,6 +191,20 @@ def _retained_argv(node: ast.expr, facts: AnnotationOrigins) -> bool:
         if isinstance(parent.slice, ast.Constant) and type(parent.slice.value) is int and parent.slice.value == 0:
             return True
         parent = facts.context.parents.get(parent)
+    match parent:
+        case ast.IfExp(
+            test=test,
+            body=ast.Subscript(value=arguments, slice=ast.Constant(value=index)),
+            orelse=ast.Constant(value=str()),
+        ):
+            return (
+                test is node
+                and type(index) is int
+                and index == 0
+                and facts.qualified(arguments, arguments) == "sys.argv"
+            )
+        case _:
+            pass
     if not isinstance(parent, ast.keyword) or parent.arg != "args":
         return False
     call = facts.context.parents.get(parent)