sarj-python-lint 1.100.0__tar.gz → 1.101.1__tar.gz

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.100.0
+Version: 1.101.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/
@@ -19,7 +19,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.14
 Requires-Dist: packaging==26.3
 Requires-Dist: ruff>=0.17.2
-Requires-Dist: sarj-rule-contracts==0.5.0
+Requires-Dist: sarj-rule-contracts==0.6.0
 Requires-Dist: sqlglot==30.24.0
 Requires-Dist: typer==0.27.3
 Description-Content-Type: text/markdown

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "1.100.0"
+version = "1.101.1"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
@@ -15,7 +15,7 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
-dependencies = ["sarj-rule-contracts==0.5.0", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
+dependencies = ["sarj-rule-contracts==0.6.0", "packaging==26.3", "ruff>=0.17.2", "sqlglot==30.24.0", "typer==0.27.3"]
 
 [project.scripts]
 sarj-python-lint = "sarj_python_lint.__main__:main"

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/_autofix.py

@@ -2,13 +2,14 @@ from __future__ import annotations
 
 import ast
 from bisect import bisect_left, insort
+from dataclasses import dataclass
 from functools import cached_property
 from hashlib import sha256
 from io import StringIO
 from itertools import pairwise
 import re
 import tokenize
-from typing import TYPE_CHECKING, Final, NamedTuple
+from typing import TYPE_CHECKING, Final, Literal, NamedTuple
 from unicodedata import normalize
 
 from sarj_rule_contracts import TextEdit, apply_edits
@@ -80,6 +81,8 @@ _WALRUS_CODES = frozenset({"SARJ081", "SARJ432"})
 _JWT_POSITIONAL_PREFIX_ARGUMENTS = 3
 _STREAM_MIN_BODY_LENGTH = 3
 _CONSTANT_TRUE_DEPTH_LIMIT = 32
+# Bound accepted revisions; each rule still owns its work and replacement size.
+_MAX_FIX_PASSES: Final = 256
 _PURE_STRING_TRANSFORMS: Final[dict[str, str]] = {
     "strip": "stripped_value",
     "lower": "lowered_value",
@@ -1360,6 +1363,18 @@ _BUILDERS: Final[dict[str, Callable[[_Source, Diagnostic], list[TextEdit]]]] = {
 }
 
 
+@dataclass(frozen=True, slots=True)
+class _FixCandidate:
+    code: str
+    edits: tuple[TextEdit, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _FixPass:
+    edits: tuple[TextEdit, ...]
+    codes: tuple[str, ...]
+
+
 def fix_source(path: Path, source: str, *, rule_ids: Sequence[str] | None = None) -> str:
     from sarj_python_lint.__main__ import check_source  # ruff: ignore[import-outside-top-level] -- the CLI imports this entry point lazily.
 
@@ -1371,6 +1386,8 @@ def fix_source(path: Path, source: str, *, rule_ids: Sequence[str] | None = None
         # Only the closed alias builder owns aligned physical-line buffers and token coordinates here.
         rules = [rule for rule in rules if rule.code == "SARJ531"]
     seen: set[bytes] = set()
+    applied_codes: set[str] = set()
+    passes = 0
     current = source
     while (fingerprint := sha256(current.encode("utf-8")).digest()) not in seen:
         seen.add(fingerprint)
@@ -1380,30 +1397,43 @@ def fix_source(path: Path, source: str, *, rule_ids: Sequence[str] | None = None
         if not candidates:
             return current
         # Batch independent candidates; overlapping candidates get fresh offsets on the next pass.
-        updated = apply_edits(current, _coherent_edits(candidates))
+        selected_pass = _coherent_edits(candidates)
+        updated = apply_edits(current, selected_pass.edits)
         compile(updated, str(path), "exec", dont_inherit=True)
         if updated == current:
             return current
+        if passes == _MAX_FIX_PASSES:
+            raise _convergence_error(path, reason="pass budget exhausted", passes=passes, codes=applied_codes)
+        passes += 1
+        applied_codes.update(selected_pass.codes)
         current = updated
-    msg = f"Python autofixes did not converge: {path}"
-    raise ValueError(msg)
+    raise _convergence_error(path, reason="source cycle", passes=passes, codes=applied_codes)
+
+
+def _convergence_error(
+    path: Path, *, reason: Literal["pass budget exhausted", "source cycle"], passes: int, codes: set[str]
+) -> ValueError:
+    participants = ", ".join(sorted(codes)) or "none"
+    msg = f"Python autofixes did not converge: {path} ({reason}; passes={passes}; rules={participants})"
+    return ValueError(msg)
 
 
-def _candidate_edits(context: PythonFileContext, diagnostics: Sequence[Diagnostic]) -> list[list[TextEdit]]:
+def _candidate_edits(context: PythonFileContext, diagnostics: Sequence[Diagnostic]) -> list[_FixCandidate]:
     view = _Source(context, diagnostics)
     return [
-        edits
+        _FixCandidate(diagnostic.code, tuple(edits))
         for diagnostic in diagnostics
         if (builder := _BUILDERS.get(diagnostic.code)) is not None
         if (edits := builder(view, diagnostic))
     ]
 
 
-def _coherent_edits(candidates: list[list[TextEdit]]) -> list[TextEdit]:
+def _coherent_edits(candidates: list[_FixCandidate]) -> _FixPass:
     accepted: list[TextEdit] = []
+    codes: list[str] = []
     known: set[TextEdit] = set()
     for candidate in candidates:
-        additions = sorted(set(candidate) - known)
+        additions = sorted(set(candidate.edits) - known)
         if any(map(_overlap, additions, additions[1:], strict=False)):
             continue
         for edit in additions:
@@ -1416,7 +1446,9 @@ def _coherent_edits(candidates: list[list[TextEdit]]) -> list[TextEdit]:
             for edit in additions:
                 insort(accepted, edit)
             known.update(additions)
-    return accepted
+            if additions:
+                codes.append(candidate.code)
+    return _FixPass(tuple(accepted), tuple(dict.fromkeys(codes)))
 
 
 def _overlap(first: TextEdit, second: TextEdit) -> bool:

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/_parallel.py

@@ -143,19 +143,24 @@ def check_parallel(
             for path, source in loaded.items()
         )
         for result in pool.map(_check_file, items, chunksize=1, buffersize=workers * 4):
-            if result.needs_serial:
-                # Drain the actual worker results so another initializer/file
-                # failure cannot be disguised as a clean serial replay.
-                needs_serial = True
+            # Drain actual results after either replay signal so a later worker
+            # failure cannot be disguised as a clean serial replay.
+            if needs_serial:
                 continue
             resolutions.update(result.resolutions)
             modules.update(result.modules)
             # A worker cannot hit either order-dependent limit when the whole
             # union stays strictly below it. At the boundary, discard all output.
-            if not needs_serial and (
-                len(resolutions) >= LOCAL_SOURCE_CACHE_LIMIT or len(modules) >= LOCAL_SOURCE_CACHE_LIMIT
+            if (
+                result.needs_serial
+                or len(resolutions) >= LOCAL_SOURCE_CACHE_LIMIT
+                or len(modules) >= LOCAL_SOURCE_CACHE_LIMIT
             ):
-                return None
+                needs_serial = True
+                diagnostics.clear()
+                resolutions.clear()
+                modules.clear()
+                continue
             diagnostics.extend(result.diagnostics)
         return None if needs_serial else diagnostics
     finally:

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/_copy_on_write.py

@@ -973,10 +973,8 @@ class CopyOnWriteAnalysis:
                 summaries[key] = _summary_value(_OwnershipSummary(alternatives))
             bindings[name] = summaries[key]
 
-    def _scan(self, statements: list[ast.stmt], bindings: dict[str, _Value]) -> None:
-        for statement in statements:
-            if self._statement(statement, bindings):
-                return
+    def _scan(self, statements: list[ast.stmt], bindings: dict[str, _Value]) -> bool:
+        return any(self._statement(statement, bindings) for statement in statements)
 
     def _statement(self, statement: ast.stmt, bindings: dict[str, _Value]) -> bool:
         match statement:
@@ -991,7 +989,7 @@ class CopyOnWriteAnalysis:
                     self._write(target, bindings)
                     self._bind(target, None, bindings)
             case ast.If():
-                self._branches(statement, bindings)
+                return self._branches(statement, bindings)
             case ast.For() | ast.AsyncFor():
                 self._for(statement, bindings)
             case ast.Expr(value=ast.Call() as call):
@@ -1026,16 +1024,16 @@ class CopyOnWriteAnalysis:
             self._write(target, bindings)
             self._bind(target, value, bindings)
 
-    def _branches(self, statement: ast.If, bindings: dict[str, _Value]) -> None:
+    def _branches(self, statement: ast.If, bindings: dict[str, _Value]) -> bool:
         self._expression(statement.test, bindings)
         branches: list[dict[str, _Value]] = []
         for positive, block in ((True, statement.body), (False, statement.orelse)):
             branch = dict(bindings)
             self._refine(statement.test, branch, positive=positive)
-            self._scan(block, branch)
-            if not block or not isinstance(block[-1], (ast.Return, ast.Raise)):
+            if not self._scan(block, branch):
                 branches.append(branch)
         self._join(branches, bindings)
+        return not branches
 
     def _for(self, statement: ast.For | ast.AsyncFor, bindings: dict[str, _Value]) -> None:
         self._expression(statement.iter, bindings)

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/_namespace_access.py

@@ -48,7 +48,7 @@ def dynamic_namespace_access(
 def _namespace_api_aliases(nodes: Iterable[ast.AST]) -> set[str]:
     aliases = set(_NAMESPACE_APIS) | {"__builtins__"}
     for node in nodes:
-        if not isinstance(node, ast.ImportFrom) or node.module not in _MODULE_APIS:
+        if not isinstance(node, ast.ImportFrom) or node.level != 0 or node.module not in _MODULE_APIS:
             continue
         members = _MODULE_APIS[node.module]
         aliases.update(alias.asname or alias.name for alias in node.names if alias.name in members)

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/_opaque_contracts.py

@@ -16,6 +16,7 @@ if TYPE_CHECKING:
     from pathlib import Path
 
     from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._local_source import LocalSourceFacts
 
 
 type _Function = ast.FunctionDef | ast.AsyncFunctionDef
@@ -111,11 +112,13 @@ class OpaqueContractFacts:
         context: PythonFileContext,
         facts: MappingShapeFacts,
         *,
+        local_source: LocalSourceFacts,
         modules: dict[Path, OpaqueContractFacts] | None = None,
         budget: _ProofBudget | None = None,
     ) -> None:
         self.context = context
         self.facts = facts
+        self.local_source = local_source
         self.native = NativeObjectContracts(context, facts)
         self.guards: dict[str, _Refinement | None] = {}
         self.checked: dict[_Function, frozenset[ast.arg]] = {}
@@ -712,20 +715,24 @@ class OpaqueContractFacts:
 
     def _imported_source(self, qualified: str) -> tuple[OpaqueContractFacts, ast.FunctionDef] | None:
         module, _, name = qualified.rpartition(".")
-        path = self.context.session.local_source.resolve_module(
-            self.context.path, module, 0, facts=self.context.session.first_party
-        )
+        path = self.local_source.resolve_module(self.context.path, module, 0, facts=self.context.session.first_party)
         if path is not None and (owner := self.modules.get(path.resolve())) is not None:
             return owner.export(name)
         if len(self.modules) >= _MAX_GUARDS:
             return None
-        loaded = self.context.session.local_source.read_module(path) if path is not None else None
+        loaded = self.local_source.read_module(path) if path is not None else None
         if loaded is None:
             return None
         from sarj_python_lint._file_context import PythonFileContext  # ruff: ignore[import-outside-top-level] -- source loading runs after AnalysisSession initialization.
 
         context = PythonFileContext(loaded.path, loaded.source, self.context.session)
-        owner = OpaqueContractFacts(context, MappingShapeFacts(context), modules=self.modules, budget=self.budget)
+        owner = OpaqueContractFacts(
+            context,
+            MappingShapeFacts(context),
+            local_source=self.local_source,
+            modules=self.modules,
+            budget=self.budget,
+        )
         return owner.export(name)
 
     def export(self, name: str) -> tuple[OpaqueContractFacts, ast.FunctionDef] | None:

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/_project_index.py

@@ -156,6 +156,11 @@ class SourceUnit:
     captured: CapturedSource | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class _AmbiguousModuleSources:
+    paths: tuple[Path, ...]
+
+
 @dataclass(frozen=True, slots=True)
 class LoadedSource:
     path: Path
@@ -276,8 +281,18 @@ class ProjectIndexSet:
         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)
+        by_module: dict[str, dict[Path, SourceUnit]] = {}
+        for unit in units.values():
+            if unit.module is not None:
+                by_module.setdefault(unit.module, {})[unit.path] = unit
+        self._by_module = MappingProxyType(
+            {
+                module: next(iter(candidates.values()))
+                if len(candidates) == 1
+                else _AmbiguousModuleSources(tuple(candidates))
+                for module, candidates in by_module.items()
+            }
+        )
         classes: dict[SymbolRef, ClassSummary] = {}
         nominals: dict[str, set[SymbolRef]] = {}
         _collect_unit_symbols(units, classes, nominals)
@@ -429,7 +444,8 @@ class ProjectIndexSet:
         return False
 
     def source_unit(self, module: str) -> SourceUnit | None:
-        return self._by_module.get(module)
+        source = self._by_module.get(module)
+        return source if isinstance(source, SourceUnit) else None
 
     def _namespace_write_inventory(self) -> Mapping[str, _ImportNamespaceWrites]:
         def resolve(origin: SymbolRef) -> tuple[SymbolRef, ...] | None:

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/no_delete_statement.py

@@ -136,6 +136,6 @@ class NoDeleteStatement(Rule):
                     "immutably, or add an exact SARJ442 suppression explaining why deletion is required."
                 ),
             )
-            for node in context.nodes(ast.AST)
-            if isinstance(node, ast.Delete) and not is_suppressed(source_lines, node.lineno, self.code)
+            for node in context.nodes(ast.Delete)
+            if not is_suppressed(source_lines, node.lineno, self.code)
         ]

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/prefer_direct_import_module.py

@@ -71,10 +71,11 @@ class PreferDirectImportModule(Rule):
     def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
         if context.generated or context.tree is None or "import_module" not in context.symbol_source:
             return []
+        provenance = context.resource_provenance
         loader_references = {
             reference
             for call in context.nodes(ast.Call)
-            if context.imports.resolved_qualified_name(call.func) == "importlib.import_module"
+            if provenance.runtime_import_name(call.func) == "importlib.import_module"
             for reference in ast.walk(call.func)
         }
         if dynamic_namespace_access(
@@ -96,7 +97,7 @@ class PreferDirectImportModule(Rule):
             if isinstance(statement, ast.Assign | ast.AnnAssign | ast.Expr)
             and isinstance(node := statement.value, ast.Call)
             and (module := _literal_module(node)) is not None
-            and context.resource_provenance.runtime_import_name(node.func) == "importlib.import_module"
+            and provenance.runtime_import_name(node.func) == "importlib.import_module"
         ]
 
 

{sarj_python_lint-1.100.0 → sarj_python_lint-1.101.1}/src/sarj_python_lint/rules/prefer_precise_object_contract.py

@@ -15,6 +15,7 @@ from sarj_python_lint.rule_base import (
     RuleExample,
     Severity,
 )
+from sarj_python_lint.rules._local_source import LocalSourceFacts
 from sarj_python_lint.rules._native_object_contracts import builtin_object, builtin_symbol
 from sarj_python_lint.rules._opaque_contracts import REFINEMENT_TYPES, OpaqueContractFacts
 from sarj_python_lint.rules.require_pydantic_for_mapping_shape import MappingShapeFacts
@@ -48,7 +49,7 @@ class PreferPreciseObjectContract(Rule):
             "Safe fixes narrow only a bare builtin object return annotation to builtin str for a closed private nested synchronous helper returning one exact string literal, with every call used directly as an if test and all containing return contracts explicit. Existing inert/metadata/binding proofs must hold; public/domain/container/parameter/model contracts and other result uses remain review-only.",
             "Checks builtin object in function signatures and class field annotations, including supported containers, callables, optional unions and quoted annotations. Local opaque values, object() sentinels, Literal/Annotated metadata, framework hooks, proven override signatures, and registered raw Pydantic callbacks are excluded. Functions that directly validate an object parameter through a source-visible BaseModel, BaseSettings or RootModel model_validate call, positionally or with obj=, retain that raw boundary. JSON text inputs still require a text or byte contract. Aliases must resolve to their source declaration and their bodies use definition scope. Alias graphs are bounded and shared branches reuse their facts. Imported or shadowed application types named object are preserved. Genuine opaque public contracts can use an explained exact-code exception; narrowing outside the exact private truthiness-only subset remains manual.",
             "An import-proven TypeGuard or TypeIs retains bare object on its guarded positional parameter and unchecked object slots in its declared refinement result; other object parameters remain checked. Guard correctness belongs to the type-guard rules. Universal type[object] class contracts and the return of a canonical module-level PEP 562 __getattr__ hook retain their opaque runtime contracts.",
-            "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.",
+            "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 use a bounded per-file proof cache, captured source inputs and 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.",
@@ -131,7 +132,9 @@ class PreferPreciseObjectContract(Rule):
         if facts.provenance.wildcard:
             return []
         findings: list[Diagnostic] = []
-        opaque = OpaqueContractFacts(context, facts)
+        opaque = OpaqueContractFacts(
+            context, facts, local_source=LocalSourceFacts(source_inputs=context.session.source_inputs)
+        )
         for owner, annotation in _contracts(context):
             if not _has_object(annotation, context, facts, at=annotation):
                 continue