sarj-python-lint 1.70.2__tar.gz → 1.72.1__tar.gz

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/PKG-INFO

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

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

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/src/sarj_python_lint/__init__.py

@@ -1,3 +1,5 @@
+from sarj_python_lint._analysis_session import AnalysisSession as AnalysisSession
+from sarj_python_lint._fixes import apply_fixes as apply_fixes, python_source_hash as python_source_hash
 from sarj_python_lint._ratchet_cli import run_ratchet as run_ratchet
 from sarj_python_lint._source import python_source_encoding as python_source_encoding
 from sarj_python_lint._version import __version__ as __version__

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/src/sarj_python_lint/_file_context.py

@@ -5,7 +5,7 @@ from functools import cached_property
 from typing import TYPE_CHECKING, final
 
 from sarj_python_lint._analysis_session import AnalysisSession
-from sarj_python_lint._source import symbol_prefilter_source
+from sarj_python_lint._source import python_source_lines, symbol_prefilter_source
 from sarj_python_lint.rules._annotation_semantics import AnnotationSemantics
 from sarj_python_lint.rules._ast_index import NodeIndex
 from sarj_python_lint.rules._fastapi import FastapiIndex
@@ -47,7 +47,7 @@ class PythonFileContext:
 
     @cached_property
     def source_lines(self) -> list[str]:
-        return self.source.splitlines()
+        return python_source_lines(self.source)
 
     @cached_property
     def generated(self) -> bool:

sarj_python_lint-1.72.1/src/sarj_python_lint/_fixes.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import ast
+from hashlib import sha256
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rule_base import AutofixPolicy
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from sarj_python_lint.rule_base import Fix
+
+
+def python_source_hash(source: str) -> str:
+    canonical = source.removeprefix("\ufeff").replace("\r\n", "\n").replace("\r", "\n")
+    return sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def apply_fixes(source: str, fixes: Sequence[Fix]) -> str:
+    if not fixes:
+        return source
+    digest = python_source_hash(source)
+    prefix = "\ufeff" if source.startswith("\ufeff") else ""
+    raw = source[len(prefix) :].encode("utf-8")
+    lines = raw.splitlines(keepends=True)
+    offsets = [0]
+    for line in lines:
+        offsets.append(offsets[-1] + len(line))
+    if not lines or lines[-1].endswith((b"\n", b"\r")):
+        lines.append(b"")
+
+    def offset(line: int, col: int) -> int:
+        if line < 1 or line > len(lines) or col < 1 or col > len(lines[line - 1].rstrip(b"\r\n")) + 1:
+            msg = "fix position is outside the source"
+            raise ValueError(msg)
+        prefix = lines[line - 1][: col - 1]
+        prefix.decode("utf-8")
+        return offsets[line - 1] + len(prefix)
+
+    edits: list[tuple[int, int, bytes]] = []
+    for fix in fixes:
+        if fix.safety is not AutofixPolicy.SAFE or fix.source_hash != digest or not fix.edits:
+            msg = "fix must be safe, nonempty and match the complete source revision"
+            raise ValueError(msg)
+        for edit in fix.edits:
+            start = offset(edit.start_line, edit.start_col)
+            end = offset(edit.end_line, edit.end_col)
+            if end < start:
+                msg = "fix range runs backwards"
+                raise ValueError(msg)
+            edits.append((start, end, edit.replacement.encode("utf-8")))
+    edits.sort()
+    result: list[bytes] = []
+    previous = 0
+    for start, end, replacement in edits:
+        if start < previous:
+            msg = "fix groups overlap"
+            raise ValueError(msg)
+        result.extend((raw[previous:start], replacement))
+        previous = end
+    result.append(raw[previous:])
+    fixed = b"".join(result).decode("utf-8")
+    tree = ast.parse(fixed)
+    compile(tree, "<native-fix>", "exec")
+    return prefix + fixed

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/src/sarj_python_lint/_parallel.py

@@ -87,7 +87,8 @@ def check_parallel(
     resolutions: set[_ResolutionKey] = set()
     modules: set[Path] = set()
     try:
-        for result in pool.map(_check_file, loaded.items(), chunksize=1, buffersize=workers):
+        # Keep workers busy while an earlier file delays ordered results.
+        for result in pool.map(_check_file, loaded.items(), chunksize=1, buffersize=workers * 4):
             resolutions.update(result.resolutions)
             modules.update(result.modules)
             # A worker cannot hit either order-dependent limit when the whole

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/src/sarj_python_lint/_source.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from io import BytesIO
+import re
 import tokenize
 from typing import TYPE_CHECKING
 import unicodedata
@@ -19,6 +20,11 @@ def read_python_source(path: Path) -> str:
         return stream.read()
 
 
+def python_source_lines(source: str) -> list[str]:
+    lines = re.split(r"\r\n?|\n", source)
+    return lines[:-1] if not lines[-1] else lines
+
+
 def symbol_prefilter_source(source: str) -> str:
     # Only necessary symbol gates may use this view; parse and locate original source.
     return source if source.isascii() else unicodedata.normalize("NFKC", source)

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/src/sarj_python_lint/rule_base.py

@@ -75,6 +75,28 @@ class ColumnEncoding(StrEnum):
     CODEPOINTS = "codepoints"
 
 
+@dataclass(frozen=True, slots=True)
+class TextEdit:
+    """An exact, half-open range of one-based lines and UTF-8 byte columns.
+
+    Columns refer to decoded source without its original leading BOM.
+    """
+
+    start_line: int
+    start_col: int
+    end_line: int
+    end_col: int
+    replacement: str
+
+
+@dataclass(frozen=True, slots=True)
+class Fix:
+    title: str
+    safety: AutofixPolicy
+    source_hash: str
+    edits: tuple[TextEdit, ...]
+
+
 @dataclass(frozen=True, slots=True)
 class Diagnostic:
     path: Path
@@ -84,6 +106,7 @@ class Diagnostic:
     message: str
     severity: Severity = Severity.ERROR
     column_encoding: ColumnEncoding = ColumnEncoding.UTF8_BYTES
+    fixes: tuple[Fix, ...] = ()
 
     def format(self) -> str:
         label = "warning: " if self.severity is Severity.WARNING else ""

sarj_python_lint-1.72.1/src/sarj_python_lint/rules/_local_alias_fix.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import ast
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from sarj_python_lint._fixes import python_source_hash
+from sarj_python_lint._source import python_source_encoding
+from sarj_python_lint.rule_base import AutofixPolicy, Fix, TextEdit
+from sarj_python_lint.rules._suppression_comments import comment_lines
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_NAMESPACE_MUTATORS = frozenset(
+    {
+        "setattr",
+        "delattr",
+        "setitem",
+        "delitem",
+        "__setattr__",
+        "__delattr__",
+        "__setitem__",
+        "__delitem__",
+        "__init__",
+        "__ior__",
+        "ior",
+        "methodcaller",
+        "patch",
+        "clear",
+        "pop",
+        "popitem",
+        "setdefault",
+        "update",
+    }
+)
+
+
+class LocalAliasFixes:
+    def __init__(self, context: PythonFileContext) -> None:
+        self.context = context
+
+    @cached_property
+    def _lines(self) -> tuple[bytes, ...]:
+        return tuple(line.encode("utf-8") for line in self.context.source_lines)
+
+    def spelling(self, node: ast.Name) -> str:
+        return self._lines[node.lineno - 1][node.col_offset : node.end_col_offset].decode("utf-8")
+
+    @cached_property
+    def _available(self) -> bool:
+        context = self.context
+        return (
+            python_source_encoding(context.source.encode("utf-8")) in {"utf-8", "utf-8-sig"}
+            and context.imports.builtin_is_unshadowed("dict")
+            and not any("dict" in bindings for bindings in context.resource_provenance.bindings.values())
+            and context.resource_provenance.builtin_namespace_untouched
+            and not any(node.attr == "__code__" for node in context.nodes(ast.Attribute))
+            and not _visible_namespace_mutation(context)
+        )
+
+    @cached_property
+    def _comments(self) -> Mapping[int, str]:
+        return comment_lines(tuple(self.context.source_lines))
+
+    @cached_property
+    def _digest(self) -> str:
+        return python_source_hash(self.context.source)
+
+    def for_alias(self, assignment: ast.Assign, use: ast.Name) -> tuple[Fix, ...]:
+        context = self.context
+        owner = context.parents.get(assignment)
+        if not isinstance(owner, ast.FunctionDef | ast.AsyncFunctionDef):
+            return ()
+        if not isinstance(context.parents.get(owner), ast.Module) or owner.decorator_list or owner.type_params:
+            return ()
+        args = owner.args
+        parameters = [*args.posonlyargs, *args.args, *args.kwonlyargs]
+        if len(parameters) != 1 or args.vararg or args.kwarg or args.defaults or any(args.kw_defaults):
+            return ()
+        source = assignment.value
+        if not isinstance(source, ast.Name) or parameters[0].arg != source.id:
+            return ()
+        body = owner.body[1:] if ast.get_docstring(owner) is not None else owner.body
+        if body[:1] != [assignment] or len(body[1:]) != 1 or not isinstance(body[-1], ast.Return):
+            return ()
+        call = body[-1].value
+        if not isinstance(call, ast.Call) or not isinstance(call.func, ast.Name) or call.func.id != "dict":
+            return ()
+        if call.args or len(call.keywords) != 1 or call.keywords[0].value is not use or not self._available:
+            return ()
+        edits = self._edits(assignment, use, source=source, owner=owner)
+        if not edits:
+            return ()
+        return (Fix("Pass the original local directly", AutofixPolicy.SAFE, self._digest, edits),)
+
+    def _edits(
+        self,
+        assignment: ast.Assign,
+        use: ast.Name,
+        *,
+        source: ast.Name,
+        owner: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> tuple[TextEdit, ...]:
+        if any(line in self._comments for line in range(owner.lineno, (owner.end_lineno or owner.lineno) + 1)):
+            return ()
+        if assignment.end_lineno != assignment.lineno:
+            return ()
+        line = self.context.source_lines[assignment.lineno - 1]
+        raw = self._lines[assignment.lineno - 1]
+        if (
+            raw[: assignment.col_offset].strip()
+            or raw[assignment.end_col_offset :].strip()
+            or ";" in line
+            or "\\" in line
+        ):
+            return ()
+        return (
+            TextEdit(assignment.lineno, 1, assignment.lineno + 1, 1, ""),
+            TextEdit(
+                use.lineno,
+                use.col_offset + 1,
+                use.end_lineno or use.lineno,
+                (use.end_col_offset or 0) + 1,
+                self.spelling(source),
+            ),
+        )
+
+
+def _visible_namespace_mutation(context: PythonFileContext) -> bool:
+    if _imports_unittest(context):
+        return True
+    for node in context.nodes(ast.Name, ast.alias, ast.Attribute, ast.Subscript, ast.AugAssign):
+        match node:
+            case ast.Name(id=name) | ast.alias(name=name):
+                if name in _NAMESPACE_MUTATORS:
+                    return True
+            case ast.Attribute(attr=name, ctx=ctx):
+                if name in _NAMESPACE_MUTATORS or not isinstance(ctx, ast.Load):
+                    return True
+            case ast.Subscript(ctx=ctx):
+                if not isinstance(ctx, ast.Load):
+                    return True
+            case ast.AugAssign(op=op):
+                if isinstance(op, ast.BitOr):
+                    return True
+    return False
+
+
+def _imports_unittest(context: PythonFileContext) -> bool:
+    for node in context.nodes(ast.Import):
+        if any(alias.name.partition(".")[0] == "unittest" for alias in node.names):
+            return True
+    return any(
+        node.module is not None and node.module.partition(".")[0] == "unittest"
+        for node in context.nodes(ast.ImportFrom)
+    )

{sarj_python_lint-1.70.2 → sarj_python_lint-1.72.1}/src/sarj_python_lint/rules/no_redundant_local_alias.py

@@ -19,6 +19,7 @@ from sarj_python_lint.rule_base import (
     Severity,
 )
 from sarj_python_lint.rules._ast_index import children
+from sarj_python_lint.rules._local_alias_fix import LocalAliasFixes
 from sarj_python_lint.rules._suppression_comments import comment_lines
 
 
@@ -82,9 +83,9 @@ class NoRedundantLocalAlias(Rule):
         default_level=Severity.WARNING,
         summary="Remove a local alias used only for its matching keyword argument.",
         rationale="An extra local binding makes readers trace two names for one value when the keyword already communicates its role.",
-        remediation="Pass the original local directly to the matching keyword and remove the unannotated alias assignment after review.",
+        remediation="Apply the safe fix where offered; otherwise pass the original local to the matching keyword and remove the unannotated alias after review.",
         category=RuleCategory.MAINTAINABILITY,
-        autofix=AutofixPolicy.NONE,
+        autofix=AutofixPolicy.SAFE,
         limitations=(
             "Only unannotated, single-target `alias = original` assignments with one binding and one read at `alias=alias` are checked.",
             "The original must be a parameter or an earlier initialized local with one binding; reassignment, deletion, imports, alias chains and uncertain initialization are excluded.",
@@ -93,10 +94,35 @@ class NoRedundantLocalAlias(Rule):
             "Typed aliases, files with type comments, same-scope quoted references and conditional reads of either local are excluded. Captured bindings and module/class aliases are preserved.",
             "Files with wildcard imports, Pydantic imports or references to known namespace readers, dynamic attribute getters or reference-count observers are excluded. Wildcard exports cannot establish builtin identity; computed type names can consume caller-local bindings without a Name read in the AST.",
             "Dynamic class construction and class-valued references to type are excluded. Direct, unshadowed unary type(value) queries and standard-library dataclasses remain supported.",
-            "Generated source, stubs and malformed input are excluded. Arbitrary external frame introspection is not modeled.",
-            "No autofix is offered; readability judgments, multiple reads, positional forwarding and more complex control flow remain outside the contract.",
+            "Generated source, stubs and malformed input are excluded; files must compile with normal module execution flags. Arbitrary external frame introspection is not modeled.",
+            "Safe fixes are limited to undecorated module functions with one required parameter, an optional existing docstring, a clean single-line alias and a tail return of unshadowed builtin dict with exactly the matching keyword. Recorded dict bindings, visible attribute/subscript writes, setter, mapping-mutator, ior, methodcaller or patch references, unittest imports, `|=` assignments, comments, non-UTF8 encodings, type parameters and visible code-object inspection prevent fixes. Mutation guards also exclude unrelated ordinary mappings, nonmutating methodcaller uses, harmless unittest imports and integer `|=` assignments. Other calls remain diagnostic-only; arbitrary external tracing, reflection and monkeypatching are not modeled.",
+            "Readability judgments, multiple reads, positional forwarding and more complex control flow remain outside the contract.",
         ),
         examples=(
+            RuleExample(
+                example_id="safe-builtin-tail",
+                scenario="safe-fix",
+                title="A safe builtin mapping return",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "case.py", "def render(item):\n    payload = item\n    return dict(payload=payload)\n"
+                    ),
+                ),
+                focus_path=PurePosixPath("case.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="direct-builtin-tail",
+                scenario="safe-fix",
+                title="Return the original local in the mapping",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("case.py", "def render(item):\n    return dict(payload=item)\n"),),
+                focus_path=PurePosixPath("case.py"),
+                expected_count=0,
+                public=True,
+            ),
             RuleExample(
                 example_id="keyword-supplies-role",
                 title="The keyword supplies the role",
@@ -138,6 +164,7 @@ class NoRedundantLocalAlias(Rule):
         quoted = _quoted_references(context, provenance, names)
         positions = {statement: i for owner in context.nodes(*_SUITES) for i, statement in enumerate(owner.body)}
         findings: list[Diagnostic] = []
+        fixes = LocalAliasFixes(context)
         for assignment in candidates:
             target = assignment.targets[0]
             source = assignment.value
@@ -152,14 +179,17 @@ class NoRedundantLocalAlias(Rule):
                 continue
             if not _stable_source(source, assignment, provenance, positions, conditional_sources):
                 continue
+            target_spelling = fixes.spelling(target)
+            source_spelling = fixes.spelling(source)
             findings.append(
                 Diagnostic(
                     path=context.path,
                     line=target.lineno,
                     col=target.col_offset + 1,
                     code=self.code,
-                    message=f"Local `{target.id}` only forwards `{source.id}` to `{target.id}=`; pass `{source.id}` directly and remove the alias.",
+                    message=f"Local `{target_spelling}` only forwards `{source_spelling}` to `{target_spelling}=`; pass `{source_spelling}` directly and remove the alias.",
                     severity=Severity.WARNING,
+                    fixes=fixes.for_alias(assignment, use),
                 )
             )
         return findings
@@ -204,7 +234,7 @@ def _local_assignments(context: PythonFileContext, names: set[str]) -> list[ast.
         and isinstance(node.value, ast.Name)
         and node.targets[0].id != node.value.id
     ]
-    if not candidates or context.has_wildcard_import or context.dynamic_namespace or _observes_references(context):
+    if not candidates or context.has_wildcard_import:
         return []
     provenance = context.resource_provenance
     blocked = {provenance.scope(node) for node in context.nodes(*_UNCERTAIN)}
@@ -214,11 +244,23 @@ def _local_assignments(context: PythonFileContext, names: set[str]) -> list[ast.
     eligible = [
         node for node in candidates if isinstance(scope := provenance.scope(node), _FUNCTIONS) and scope not in blocked
     ]
-    if not eligible or context.generated or _has_type_comments(context):
+    if not eligible or context.dynamic_namespace or _observes_references(context):
+        return []
+    if context.generated or _has_type_comments(context) or not _compiles(context):
         return []
     return eligible
 
 
+def _compiles(context: PythonFileContext) -> bool:
+    if context.tree is None:
+        return False
+    try:
+        compile(context.tree, str(context.path), "exec")
+    except SyntaxError:
+        return False
+    return True
+
+
 def _has_type_comments(context: PythonFileContext) -> bool:
     return any(_TYPE_COMMENT.search(comment) for comment in comment_lines(tuple(context.source_lines)).values())