sarj-python-lint 1.95.0__tar.gz → 1.97.0__tar.gz

{sarj_python_lint-1.95.0 → sarj_python_lint-1.97.0}/PKG-INFO

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

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

{sarj_python_lint-1.95.0 → sarj_python_lint-1.97.0}/src/sarj_python_lint/rules/_native_object_contracts.py

@@ -701,9 +701,13 @@ def _stub(statement: ast.stmt) -> bool:
 
 
 def builtin_object(node: ast.expr, facts: MappingShapeFacts, at: ast.AST) -> bool:
-    candidate = facts.qualified(node, at) == "builtins.object" or (
+    return builtin_symbol(node, "object", facts, at)
+
+
+def builtin_symbol(node: ast.expr, name: str, facts: MappingShapeFacts, at: ast.AST) -> bool:
+    candidate = facts.qualified(node, at) == f"builtins.{name}" or (
         isinstance(node, ast.Name)
-        and node.id == "object"
+        and node.id == name
         and not facts.shadowed(node.id, at)
         and facts.provenance.binding(node.id, at) is None
     )
@@ -717,13 +721,11 @@ def builtin_object(node: ast.expr, facts: MappingShapeFacts, at: ast.AST) -> boo
     while isinstance(root, ast.Attribute):
         root = root.value
     if isinstance(root, ast.Name):
-        changed = native.namespace_replaced(root.id) if root.id == "object" else native.namespace_rebound(root.id)
+        changed = native.namespace_replaced(root.id) if root.id == name else native.namespace_rebound(root.id)
         if changed:
             return False
     attribute_mutation = any(
-        isinstance(member.ctx, ast.Store | ast.Del)
-        and member.attr == "object"
-        and _builtins_module(member.value, context)
+        isinstance(member.ctx, ast.Store | ast.Del) and member.attr == name and _builtins_module(member.value, context)
         for member in context.nodes(ast.Attribute)
     )
     return not attribute_mutation and not any(
@@ -731,7 +733,7 @@ def builtin_object(node: ast.expr, facts: MappingShapeFacts, at: ast.AST) -> boo
         and call.func.id in {"setattr", "delattr"}
         and len(call.args) >= _PAIR_ARITY
         and _builtins_module(call.args[0], context)
-        and (not isinstance(call.args[1], ast.Constant) or call.args[1].value == "object")
+        and (not isinstance(call.args[1], ast.Constant) or call.args[1].value == name)
         for call in context.nodes(ast.Call)
     )
 

{sarj_python_lint-1.95.0 → sarj_python_lint-1.97.0}/src/sarj_python_lint/rules/_project_index.py

@@ -12,6 +12,7 @@ from pathlib import Path
 import re
 from types import MappingProxyType
 from typing import TYPE_CHECKING, final
+from weakref import WeakMethod
 
 from sarj_rule_contracts import SourceSnapshot
 
@@ -25,7 +26,7 @@ from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence, Set as AbstractSet
+    from collections.abc import Callable, Iterator, Sequence, Set as AbstractSet
     from typing import Self
 
     from sarj_python_lint._prepared_sources import PreparedSourceInputs
@@ -191,6 +192,13 @@ class _TypeProviderFacts:
     opaque: bool
 
 
+@dataclass(frozen=True)
+class _ImportNamespaceWrites:
+    modules: frozenset[str]
+    dependencies: frozenset[str]
+    incomplete: bool
+
+
 def imports_outside(tree: ast.Module | None, modules: frozenset[str]) -> bool:
     if tree is None:
         return True
@@ -202,6 +210,48 @@ def imports_outside(tree: ast.Module | None, modules: frozenset[str]) -> bool:
     return False
 
 
+@final
+class ImportNamespaceMutations:
+    def __init__(
+        self,
+        load: Callable[[], Callable[[], Mapping[str, _ImportNamespaceWrites]] | None],
+    ) -> None:
+        self._load = load
+        self._facts: Mapping[str, _ImportNamespaceWrites] | None = None
+        self._reachable: dict[str, frozenset[str] | None] = {}
+
+    def for_unit(self, unit: SourceUnit) -> frozenset[str] | None:
+        if unit.module is None:
+            return frozenset()
+        if unit.module in self._reachable:
+            return self._reachable[unit.module]
+        pending = list(_module_prefixes(unit.module))
+        visited: set[str] = set()
+        mutated: set[str] = set()
+        if self._facts is None:
+            load = self._load()
+            if load is None:
+                return None
+            self._facts = load()
+        facts = self._facts
+        while pending:
+            module = pending.pop()
+            if module in visited:
+                continue
+            visited.add(module)
+            fact = facts.get(module)
+            if fact is None:
+                continue
+            if fact.incomplete:
+                self._reachable[unit.module] = None
+                return None
+            mutated.update(fact.modules)
+            pending.extend(fact.dependencies - visited)
+        result = frozenset(mutated)
+        self._reachable[unit.module] = result
+        return result
+
+
 @final
 class ProjectIndexSet:
     # Borrowed ASTs and import mappings must stay unchanged for this index's lifetime.
@@ -225,6 +275,7 @@ class ProjectIndexSet:
         self._type_providers: dict[ast.Module, _TypeProviderFacts] = {}
         self._bound_value_prefixes: dict[str, bool] = {}
         self._value_origins_incomplete = False
+        self.import_namespace_mutations = ImportNamespaceMutations(WeakMethod(self._namespace_write_inventory))
         by_module = {unit.module: unit for unit in units.values() if unit.module is not None}
         self._by_module = MappingProxyType(by_module)
         classes: dict[SymbolRef, ClassSummary] = {}
@@ -380,6 +431,13 @@ class ProjectIndexSet:
     def source_unit(self, module: str) -> SourceUnit | None:
         return self._by_module.get(module)
 
+    def _namespace_write_inventory(self) -> Mapping[str, _ImportNamespaceWrites]:
+        def resolve(origin: SymbolRef) -> tuple[SymbolRef, ...] | None:
+            values = self._canonical_value_symbols(origin)
+            return None if not values and self._value_origins_incomplete else values
+
+        return _import_namespace_write_facts(self._units, self._runtime_origins, resolve)
+
     def nominal_membership_is_dynamic(self, symbol: SymbolRef) -> bool:
         if symbol.module not in self._namespace_mutation:
             unit = self.source_unit(symbol.module)
@@ -767,6 +825,79 @@ def _namespace_closure(
     return MappingProxyType({name: frozenset(targets) for name, targets in values.items()})
 
 
+def _import_namespace_write_facts(
+    units: Mapping[Path, SourceUnit],
+    runtime_origins: Mapping[str, Mapping[str, frozenset[SymbolRef]]],
+    resolve: Callable[[SymbolRef], tuple[SymbolRef, ...] | None],
+) -> Mapping[str, _ImportNamespaceWrites]:
+    facts: dict[str, _ImportNamespaceWrites] = {}
+    for unit in units.values():
+        if unit.module is None or unit.tree is None:
+            continue
+        current = _unit_import_namespace_writes(unit, runtime_origins.get(unit.module, {}), resolve)
+        previous = facts.get(unit.module)
+        if previous is not None:
+            current = _ImportNamespaceWrites(
+                previous.modules | current.modules,
+                previous.dependencies | current.dependencies,
+                previous.incomplete or current.incomplete,
+            )
+        facts[unit.module] = current
+    return MappingProxyType(facts)
+
+
+def _unit_import_namespace_writes(
+    unit: SourceUnit,
+    origins: Mapping[str, frozenset[SymbolRef]],
+    resolve: Callable[[SymbolRef], tuple[SymbolRef, ...] | None],
+) -> _ImportNamespaceWrites:
+    targets: set[str] = set()
+    incomplete = False
+    if unit.tree is not None:
+        for node in walk_ast(unit.tree):
+            reference = _namespace_write_owner(node)
+            if reference is None:
+                continue
+            for origin in _possible_class_symbols(unit, reference, origins):
+                resolved = resolve(origin)
+                if resolved is None:
+                    incomplete = True
+                else:
+                    targets.update(symbol.module or symbol.name for symbol in resolved)
+    return _ImportNamespaceWrites(frozenset(targets), _runtime_dependency_modules(unit), incomplete)
+
+
+def _namespace_write_owner(node: ast.AST) -> ast.Name | ast.Attribute | None:
+    owner: ast.expr | None = None
+    match node:
+        case ast.Attribute(value=value, ctx=ast.Store() | ast.Del()):
+            owner = value
+        case ast.Call(func=ast.Name(id="setattr" | "delattr"), args=[value, _, *_]):
+            owner = value
+        case _:
+            pass
+    return owner if isinstance(owner, ast.Name | ast.Attribute) else None
+
+
+def _runtime_dependency_modules(unit: SourceUnit) -> frozenset[str]:
+    if unit.tree is None:
+        return frozenset()
+    package = (unit.module or "") if unit.path.name == "__init__.py" else (unit.module or "").rpartition(".")[0]
+    dependencies: set[str] = set()
+    for statement in _runtime_import_statements(unit.tree):
+        match statement:
+            case ast.Import(names=aliases):
+                for alias in aliases:
+                    dependencies.update(_module_prefixes(alias.name))
+            case ast.ImportFrom(module=module, level=level, names=aliases):
+                target = _relative_module(package, level, module)
+                if target is None:
+                    continue
+                dependencies.update(_module_prefixes(target))
+                dependencies.update(f"{target}.{alias.name}" for alias in aliases if alias.name != "*")
+    return frozenset(dependencies)
+
+
 def _runtime_import_origins(
     unit: SourceUnit, *, node_index: NodeIndex | None = None
 ) -> dict[str, frozenset[SymbolRef]]:

{sarj_python_lint-1.95.0 → sarj_python_lint-1.97.0}/src/sarj_python_lint/rules/complex_postgres_query_requires_architecture_review.py

@@ -196,7 +196,8 @@ def _visible_constructors(
     scope_chain: list[int] = []
     current = owner
     while True:
-        scope_chain.append(id(current))
+        if current is owner or not isinstance(current, ast.ClassDef):
+            scope_chain.append(id(current))
         parent = parents.get(current)
         if parent is None:
             break
@@ -498,7 +499,7 @@ def _parse_signal(sql: str) -> str | None:
         for statement in parse_postgres(normalized):
             if statement is not None and (signal := _architecture_signal(statement)) is not None:
                 return signal
-    except SqlglotError:
+    except SqlglotError, RecursionError:
         return None
     return None
 
@@ -554,8 +555,17 @@ def _self_join(select: exp.Select, joins: tuple[exp.Join, ...]) -> bool:
     from sqlglot import exp  # ruff: ignore[import-outside-top-level] -- compare only literal relation identities.
 
     from_clause = _expression_arg(select, "from_")
-    root = relation_key(_expression_arg(from_clause, "this")) if isinstance(from_clause, exp.From) else None
-    return root is not None and any(relation_key(_expression_arg(join, "this")) == root for join in joins)
+    relations = [_expression_arg(from_clause, "this")] if isinstance(from_clause, exp.From) else []
+    relations.extend(_expression_arg(join, "this") for join in joins)
+    seen: set[tuple[str, ...]] = set()
+    for relation in relations:
+        key = relation_key(relation)
+        if key is None or any(_SQL_HOLE in name for name in key):
+            continue
+        if key in seen:
+            return True
+        seen.add(key)
+    return False
 
 
 def _derived_architecture_signal(statement: exp.Expr) -> str | None:
@@ -647,7 +657,9 @@ def _record_sql_module_imports(node: ast.Import, owner_id: int, constructors: se
 
 def _query_review_guidance(text_value: str) -> str:
     coordination = re.search(
-        r"\b(?:FOR\s+(?:NO\s+KEY\s+)?UPDATE|FOR\s+SHARE|SKIP\s+LOCKED)\b", text_value, re.IGNORECASE
+        r"\b(?:FOR\s+(?:(?:NO\s+KEY\s+)?UPDATE|(?:KEY\s+)?SHARE)|SKIP\s+LOCKED)\b",
+        strip_sql_noise(text_value),
+        re.IGNORECASE,
     )
     return (
         " preserve the atomic statement; review bounds, ordering, and locks, then document its cardinality, "

{sarj_python_lint-1.95.0 → sarj_python_lint-1.97.0}/src/sarj_python_lint/rules/no_custom_control_flow_exception.py

@@ -61,7 +61,7 @@ class NoCustomControlFlowException(Rule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "This review warning checks stable module-level local Exception/ValueError subclasses whose bodies contain only pass, ellipsis or docstring expressions, including empty local subclasses of those markers. A source-visible direct raise of the class or its constructor is required; imported errors, payload-bearing classes, methods, decorators, generic/ambiguous bases and unused definitions abstain.",
-            "Raising a ValueError-derived marker from an import-proven Pydantic field/model validator or legacy validator preserves that rejection protocol. Unknown external bases and visible escapes of the class to registrations, callbacks or other value consumers abstain; HTTPException and other framework-required exception types remain valid.",
+            "Raising a ValueError-derived marker from an import-proven Pydantic field/model validator or legacy validator preserves that rejection protocol. Unknown external bases and visible mutations or escapes of the class or a local base to registrations, callbacks or other value consumers abstain; HTTPException and other framework-required exception types remain valid.",
             "Expectedness is not inferred from a name, message or prefix. Genuine exceptional markers may also match and require review rather than conversion. Cross-module callers and registrations, indirect raises, dynamically mutated namespaces and class aliases are not inferred.",
             "Tests, generated and vendor code are excluded. No automatic rewrite is safe: a result return must preserve failure handling and transaction/resource unwinding. SARJ435 separately reviews joined-string reason identities.",
         ),
@@ -114,11 +114,10 @@ class NoCustomControlFlowException(Rule):
         if provenance.wildcard or provenance.dynamic_namespace or not provenance.builtin_namespace_untouched:
             return []
         markers = _markers(context, provenance)
+        raised_markers = _direct_raises(markers, context, provenance)
         findings: list[Diagnostic] = []
         for marker in markers.values():
-            if marker.name in provenance.mutated or _escapes(marker, context, provenance):
-                continue
-            if not _direct_raises(marker, context, provenance):
+            if marker not in raised_markers:
                 continue
             if is_suppressed(context.source_lines, marker.lineno, self.code):
                 continue
@@ -152,8 +151,13 @@ def _markers(context: PythonFileContext, provenance: ResourceProvenance) -> dict
             and provenance.binding(base.id, base) is markers.get(base.id)
             and base.id in markers
         )
-        if local or _builtin_base(base, context, provenance):
-            markers[node.name] = node
+        if not (local or _builtin_base(base, context, provenance)):
+            continue
+        if node.name in provenance.mutated or node.name in provenance.external_bindings:
+            continue
+        if _escapes(node, context, provenance):
+            continue
+        markers[node.name] = node
     return markers
 
 
@@ -181,14 +185,24 @@ def _builtin_base(base: ast.expr, context: PythonFileContext, provenance: Resour
     return any(provenance.imported(base, f"builtins.{name}") for name in _BUILTIN_BASES)
 
 
-def _direct_raises(marker: ast.ClassDef, context: PythonFileContext, provenance: ResourceProvenance) -> bool:
+def _direct_raises(
+    markers: dict[str, ast.ClassDef], context: PythonFileContext, provenance: ResourceProvenance
+) -> set[ast.ClassDef]:
+    candidates = set(markers.values())
+    raised_markers: set[ast.ClassDef] = set()
+    value_errors: dict[ast.ClassDef, bool] = {}
     for raised in context.nodes(ast.Raise):
         target = raised.exc.func if isinstance(raised.exc, ast.Call) else raised.exc
-        if not isinstance(target, ast.Name) or provenance.binding(target.id, target) is not marker:
+        if not isinstance(target, ast.Name):
             continue
-        if not (_value_error_marker(marker, context, provenance) and _validation_callback(raised, context, provenance)):
-            return True
-    return False
+        marker = provenance.binding(target.id, target)
+        if not isinstance(marker, ast.ClassDef) or marker not in candidates or marker in raised_markers:
+            continue
+        if marker not in value_errors:
+            value_errors[marker] = _value_error_marker(marker, context, provenance)
+        if not (value_errors[marker] and _validation_callback(raised, context, provenance)):
+            raised_markers.add(marker)
+    return raised_markers
 
 
 def _value_error_marker(marker: ast.ClassDef, context: PythonFileContext, provenance: ResourceProvenance) -> bool:

{sarj_python_lint-1.95.0 → sarj_python_lint-1.97.0}/src/sarj_python_lint/rules/no_discarded_tagged_outcome.py

@@ -80,7 +80,7 @@ class NoDiscardedTaggedOutcome(ProjectRule):
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Review warning for standalone synchronous calls and directly awaited async calls to stable source-visible module functions. The return must resolve to at least two direct Pydantic, dataclass or required TypedDict variants sharing a string Literal discriminator with disjoint values. No name such as Result or Error establishes proof.",
-            "Module-local and prepared-project absolute imports, quoted bare aliases and PEP 604 returns, unquoted typing.Union and Annotated, and bounded non-generic type aliases are supported. Quoted typing-wrapper combinations, unknown receivers, decorated or generic functions, re-exports, optional/scalar branches, generic records, inheritance, dynamic namespaces, rebound identities and unsupported annotations abstain.",
+            "Module-local and prepared-project absolute imports, quoted bare aliases and PEP 604 returns, unquoted typing.Union and Annotated, and bounded non-generic type aliases are supported. Quoted typing-wrapper combinations, unknown receivers, decorated or generic functions, re-exports, optional/scalar branches, generic records, inheritance, dynamic namespaces, rebound or escaped callable identities, generator functions and unsupported annotations abstain.",
             "Named assignments, returned, passed or conditionally consumed results are preserved. A direct assignment to the single underscore target is an explicit discard and is reviewed. An unawaited async call belongs to coroutine checks. Direct class-body execution, generated sources and opaque providers are excluded. This rule identifies discarding; it does not prove that an assignment handles every variant or infer expected failure from a record name.",
             "String Literal tags must be direct instance fields on every variant and retain their original class-scope binding. Quoted field tags remain outside the proof; quoted module return annotations retain their source declaration anchor. Dynamic fields, optional TypedDict fields, non-string tags, computed Literal values and multi-field discriminator hierarchies are not inferred. No automatic rewrite changes call behavior or error handling.",
         ),
@@ -145,6 +145,7 @@ class _OutcomeCalls:
         self.contracts = DeclaredContracts(context)
         self.providers: dict[Path, PythonFileContext] = {context.path: context}
         self.outcomes: dict[_Function, bool] = {}
+        self.generator_owners: dict[Path, set[ast.AST | None]] = {}
 
     def discarded(self, statement: _Discard) -> bool:
         value = statement.value
@@ -162,11 +163,21 @@ class _OutcomeCalls:
             members = (
                 self._members(_Reference(source.context, function.returns, function), frozenset())
                 if function.returns is not None
+                and _callable_identity(source.context, function)
+                and self._non_generator(source)
                 else None
             )
             self.outcomes[function] = members is not None and self._tagged(members)
         return self.outcomes[function]
 
+    def _non_generator(self, source: _FunctionSource) -> bool:
+        owner = source.context
+        if owner.path not in self.generator_owners:
+            self.generator_owners[owner.path] = {
+                owner.static_resource_provenance.scope(node) for node in owner.nodes(ast.Yield, ast.YieldFrom)
+            }
+        return source.function not in self.generator_owners[owner.path]
+
     def _function_source(self, expression: ast.expr) -> _FunctionSource | None:
         provenance = self.context.static_resource_provenance
         if provenance.dynamic_namespace or provenance.wildcard:
@@ -325,6 +336,44 @@ class _OutcomeCalls:
         return _record_tags(declaration, provider)
 
 
+def _callable_identity(context: PythonFileContext, function: _Function) -> bool:
+    provenance = context.static_resource_provenance
+    pending: list[_Function | ast.Name] = [function]
+    seen: set[ast.AST] = set()
+    while pending:
+        binding = pending.pop()
+        if binding in seen:
+            continue
+        if len(seen) >= _MAX_DEPTH:
+            return False
+        seen.add(binding)
+        name = binding.id if isinstance(binding, ast.Name) else binding.name
+        if name in provenance.mutated or name in provenance.external_bindings:
+            return False
+        for read in provenance.binding_reads(name, binding):
+            parent = context.parents.get(read)
+            if isinstance(parent, ast.Call) and parent.func is read:
+                continue
+            target = _simple_callable_alias(context, read)
+            if target is None:
+                return False
+            pending.append(target)
+    return True
+
+
+def _simple_callable_alias(context: PythonFileContext, read: ast.Name) -> ast.Name | None:
+    assignment = context.parents.get(read)
+    if not isinstance(assignment, ast.Assign | ast.AnnAssign) or assignment.value is not read:
+        return None
+    if not isinstance(context.parents.get(assignment), ast.Module | ast.FunctionDef | ast.AsyncFunctionDef):
+        return None
+    targets = assignment.targets if isinstance(assignment, ast.Assign) else [assignment.target]
+    if len(targets) != 1 or not isinstance(targets[0], ast.Name):
+        return None
+    target = targets[0]
+    return target if context.static_resource_provenance.binding(target.id, target) is target else None
+
+
 def _union_children(node: ast.expr, context: PythonFileContext) -> list[ast.expr] | None:
     if isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
         return [node.left, node.right]