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

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

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

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