sarj-python-lint 0.82.5__tar.gz → 0.82.7__tar.gz

{sarj_python_lint-0.82.5 → sarj_python_lint-0.82.7}/PKG-INFO

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

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

{sarj_python_lint-0.82.5 → sarj_python_lint-0.82.7}/src/sarj_python_lint/_ratchet_cli.py

@@ -63,6 +63,7 @@ def _run(args: _Options) -> int:
             packages=baseline.packages,
             per_file_ceiling=args.per_file_ceiling,
             file_exceptions=baseline.file_exceptions,
+            file_selector_ceilings=baseline.file_selector_ceilings,
             excluded_subtrees=baseline.excluded_subtrees,
         )
 
@@ -85,6 +86,7 @@ def _run(args: _Options) -> int:
         packages=baseline.packages,
         per_file_ceiling=baseline.per_file_ceiling,
         file_exceptions=baseline.file_exceptions,
+        file_selector_ceilings=baseline.file_selector_ceilings,
         excluded_subtrees=excluded_subtrees,
     )
     try:
@@ -182,7 +184,10 @@ class _Result:
 
 
 app = typer.Typer(
-    help="Ratchet on lint/type suppressions: per-code, per-package and per-file ceilings that may only shrink.",
+    help=(
+        "Ratchet on lint/type suppressions: per-selector, per-package, per-file, and per-file-selector ceilings that "
+        "may only shrink."
+    ),
     add_completion=False,
     no_args_is_help=False,
     pretty_exceptions_enable=False,

{sarj_python_lint-0.82.5 → sarj_python_lint-0.82.7}/src/sarj_python_lint/ratchet.py

@@ -69,6 +69,7 @@ class Measurement:
     codes: Counter[str]
     packages: Counter[str]
     files: dict[str, int]
+    file_selectors: dict[str, Counter[str]]
 
     @property
     def total(self) -> int:
@@ -82,6 +83,7 @@ class Baseline:
     packages: dict[str, int] = field(default_factory=dict[str, int])
     per_file_ceiling: int = DEFAULT_PER_FILE_CEILING
     file_exceptions: dict[str, int] = field(default_factory=dict[str, int])
+    file_selector_ceilings: dict[str, dict[str, int]] | None = None
     excluded_subtrees: tuple[str, ...] = ()
 
 
@@ -113,6 +115,10 @@ _REMEDIATION: Final[Mapping[str, str]] = MappingProxyType(
             "burn one down here, or grandfather the file explicitly in the baseline's "
             "`files.exceptions`."
         ),
+        "file-selector": (
+            "A suppression for this selector is new to this file. Fix the finding instead of moving suppression debt "
+            "between files or selectors, or get the exact ceiling raise reviewed explicitly (`--update --allow-increase`)."
+        ),
     }
 )
 
@@ -128,6 +134,7 @@ def measure(
     codes: Counter[str] = Counter()
     package_counts: Counter[str] = Counter()
     files: dict[str, int] = {}
+    file_selectors: dict[str, Counter[str]] = {}
     excluded = tuple(_normalized_subtree(value) for value in excluded_subtrees)
     for package in packages:
         package_counts[package] = 0
@@ -142,7 +149,8 @@ def measure(
             n = sum(found.values())
             package_counts[package] += n
             files[relative] = n
-    return Measurement(codes=codes, packages=package_counts, files=files)
+            file_selectors[relative] = found
+    return Measurement(codes=codes, packages=package_counts, files=files, file_selectors=file_selectors)
 
 
 def count_source(source: str, *, ruff_aliases: Mapping[str, str] | None = None) -> Counter[str]:
@@ -173,6 +181,13 @@ def gate(measurement: Measurement, baseline: Baseline) -> list[Failure]:
         for key, n in sorted(measurement.files.items())
         if n > (ceiling := baseline.file_exceptions.get(key, baseline.per_file_ceiling))
     ]
+    if baseline.file_selector_ceilings is not None:
+        failures += [
+            Failure(dimension="file-selector", key=f"{path} [{code}]", ceiling=ceiling, actual=actual)
+            for path, codes in sorted(measurement.file_selectors.items())
+            for code, actual in sorted(codes.items())
+            if actual > (ceiling := baseline.file_selector_ceilings.get(path, {}).get(code, 0))
+        ]
     return failures
 
 
@@ -193,6 +208,9 @@ def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
         packages=dict(sorted(measurement.packages.items())),
         per_file_ceiling=baseline.per_file_ceiling,
         file_exceptions=dict(sorted(exceptions.items())),
+        file_selector_ceilings={
+            path: dict(sorted(codes.items())) for path, codes in sorted(measurement.file_selectors.items())
+        },
         excluded_subtrees=baseline.excluded_subtrees,
     )
 
@@ -214,6 +232,7 @@ def load_baseline(path: Path) -> Baseline:
         if isinstance(ceiling, int) and not isinstance(ceiling, bool)
         else DEFAULT_PER_FILE_CEILING,
         file_exceptions=_int_map(_get(files, "exceptions")),
+        file_selector_ceilings=_optional_nested_int_map(_get(files, "selectors")),
         excluded_subtrees=_string_tuple(_get(raw, "excluded_subtrees")),
     )
 
@@ -231,7 +250,8 @@ def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
             "Suppression ceilings, written by `sarj-ratchet --update`. Counts may "
             "only go DOWN: `codes` is per dialect+code, `packages` is per "
             "top-level package, `files.per_file_ceiling` caps any single file "
-            "with `files.exceptions` grandfathering the pre-existing hot spots. "
+            "with `files.exceptions` grandfathering the pre-existing hot spots, and "
+            "`files.selectors` prevents debt from moving between files or lint rules. "
             "Raising a ceiling requires `--update --allow-increase` and review."
         ),
         "packages_scanned": sorted(packages),
@@ -241,6 +261,7 @@ def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
         "files": {
             "per_file_ceiling": baseline.per_file_ceiling,
             "exceptions": baseline.file_exceptions,
+            "selectors": baseline.file_selector_ceilings or {},
         },
     }
     return json.dumps(payload, indent=2) + "\n"
@@ -258,13 +279,17 @@ def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_E
 
 
 def _int_map(value: object) -> dict[str, int]:
-    if not isinstance(value, dict):
+    if not _is_string_object_mapping(value):
         return {}
-    return {
-        key: count
-        for key, count in value.items()  # pyright: ignore[reportUnknownVariableType] — json leaves are Any; narrowed in the guard
-        if isinstance(key, str) and isinstance(count, int) and not isinstance(count, bool)
-    }
+    return {key: count for key, count in value.items() if isinstance(count, int) and not isinstance(count, bool)}
+
+
+def _optional_nested_int_map(value: object) -> dict[str, dict[str, int]] | None:
+    if value is None:
+        return None
+    if not _is_string_object_mapping(value):
+        return {}
+    return {path: counts for path, raw_counts in value.items() if (counts := _int_map(raw_counts))}
 
 
 def _string_tuple(value: object) -> tuple[str, ...]:
@@ -282,6 +307,13 @@ def _is_object_list(value: object) -> TypeGuard[list[object]]:
     return isinstance(value, list)
 
 
+def _is_string_object_mapping(value: object) -> TypeGuard[dict[str, object]]:
+    return isinstance(value, dict) and all(
+        isinstance(key, str)
+        for key in value  # pyright: ignore[reportUnknownVariableType] — runtime validation narrows untyped JSON keys.
+    )
+
+
 def _normalized_subtree(value: str) -> str:
     return value.strip("/")
 

{sarj_python_lint-0.82.5 → sarj_python_lint-0.82.7}/src/sarj_python_lint/rules/prefer_collection_comprehension.py

@@ -61,6 +61,15 @@ class _InitializedCollection:
 class _Candidate:
     kind: _CollectionKind
     name: str
+    action: str = "populates"
+
+
+@dataclass(frozen=True)
+class _LoopReplacement:
+    kind: _CollectionKind
+    expression: str
+    action: str = "populates"
+    allow_multiline: bool = False
 
 
 @final
@@ -74,8 +83,9 @@ class PreferCollectionComprehension(Rule):
             "spreads a declarative map/filter across mutable scaffolding."
         ),
         remediation=(
-            "Build the fresh collection with one dict, list, or set comprehension. Keep the loop when mutation is "
-            "incremental, evaluation order is observable, or the imperative form carries additional behavior."
+            "Build the fresh collection with one dict, list, or set comprehension. When a list candidate must be "
+            "computed once and reused in the element, bind it in the filter with :=. Keep the loop when mutation "
+            "is incremental, evaluation order is observable, or the imperative form carries additional behavior."
         ),
         category=RuleCategory.STYLE,
         autofix=AutofixPolicy.NONE,
@@ -83,17 +93,23 @@ class PreferCollectionComprehension(Rule):
             "Only function-local, adjacent empty initializers and one synchronous single-purpose loop are checked.",
             (
                 "The rule fills gaps left by Ruff PERF401, PERF403, and FURB142: derived dict projections, "
-                "destructured list projections, and filtered set builders."
+                "destructured list projections, narrowly filtered computed list candidates, and filtered set "
+                "builders."
             ),
             (
-                "Comments, loop-target leakage, try blocks, aliases, complex projections, and replacements wider "
-                "than 120 columns are excluded. No autofix is offered because dict key/value evaluation order can "
-                "differ."
+                "Comments, loop-target leakage, try blocks, aliases, complex projections, and replacements that "
+                "do not fit a 120-column line or a simple formatter-style multiline comprehension are excluded. "
+                "No autofix is offered because dict key/value evaluation order can differ."
             ),
             (
                 "Attribute projections can invoke properties or descriptors, so reviewers should keep the loop "
                 "when the relative order of those reads is observable."
             ),
+            (
+                "Computed list candidates are limited to one local assignment, a truthiness or None filter, and "
+                "one bounded projection. Validation, logging, exceptions, multiple guards, and secondary mutation "
+                "remain imperative."
+            ),
         ),
         examples=(
             RuleExample(
@@ -114,6 +130,47 @@ class PreferCollectionComprehension(Rule):
                 expected_count=1,
                 public=True,
             ),
+            RuleExample(
+                example_id="computed-filtered-list-loop",
+                title="Compute and filter a list candidate directly",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/intervals.py",
+                        "def clipped(items, bounds):\n"
+                        "    result: list[Interval] = []\n"
+                        "    for item in items:\n"
+                        "        value = item.clipped(bounds)\n"
+                        "        if value is not None:\n"
+                        "            result.append(value)\n"
+                        "    return result\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/intervals.py"),
+                expected_count=1,
+                public=True,
+                scenario="computed-filter",
+            ),
+            RuleExample(
+                example_id="computed-filtered-list-comprehension",
+                title="Keep a computed filtered list declarative",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/intervals.py",
+                        "def clipped(items, bounds):\n"
+                        "    return [\n"
+                        "        value\n"
+                        "        for item in items\n"
+                        "        if (value := item.clipped(bounds)) is not None\n"
+                        "    ]\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/intervals.py"),
+                expected_count=0,
+                public=True,
+                scenario="computed-filter",
+            ),
             RuleExample(
                 example_id="direct-dict-comprehension",
                 title="Keep the collection projection declarative",
@@ -163,10 +220,7 @@ class PreferCollectionComprehension(Rule):
                             line=loop.lineno,
                             col=loop.col_offset + 1,
                             code=self.code,
-                            message=(
-                                f"This loop only populates fresh {finding.kind} {finding.name!r} — prefer a "
-                                f"{finding.kind} comprehension."
-                            ),
+                            message=_message(finding),
                         )
                     )
         return sorted(diagnostics, key=lambda diagnostic: (diagnostic.line, diagnostic.col))
@@ -223,10 +277,12 @@ def _candidate(
     ):
         return None
 
-    kind = _loop_kind(loop, name, initialized.kind, bound_names)
-    if kind is None or not _replacement_fits(init, loop, name, kind):
+    replacement = _loop_replacement(loop, name, initialized.kind, bound_names, owner)
+    if replacement is None or not _replacement_fits(
+        init, name, replacement.expression, allow_multiline=replacement.allow_multiline
+    ):
         return None
-    return _Candidate(kind=kind, name=name)
+    return _Candidate(kind=replacement.kind, name=name, action=replacement.action)
 
 
 def _initialized_collection(statement: _Init) -> _InitializedCollection | None:
@@ -251,27 +307,179 @@ def _initialized_collection(statement: _Init) -> _InitializedCollection | None:
             return None
 
 
-def _loop_kind(
-    loop: ast.For, name: str, initialized_kind: _CollectionKind, bound_names: frozenset[str]
-) -> _CollectionKind | None:
+def _loop_replacement(
+    loop: ast.For,
+    name: str,
+    initialized_kind: _CollectionKind,
+    bound_names: frozenset[str],
+    owner: _Callable,
+) -> _LoopReplacement | None:
     if initialized_kind is _CollectionKind.DICT and len(loop.body) == 1:
         match loop.body[0]:
             case ast.Assign(targets=[ast.Subscript(value=ast.Name(id=target), slice=key)], value=value) if (
                 target == name
             ):
                 if _valid_dict_projection(key, value, name, bound_names):
-                    return _CollectionKind.DICT
+                    return _LoopReplacement(
+                        _CollectionKind.DICT,
+                        f"{{{ast.unparse(key)}: {ast.unparse(value)} for {ast.unparse(loop.target)} "
+                        f"in {ast.unparse(loop.iter)}}}",
+                    )
             case _:
                 pass
-    if initialized_kind is _CollectionKind.LIST and len(bound_names) > 1 and len(loop.body) == 1:
+    if initialized_kind is _CollectionKind.LIST:
+        replacement = _list_replacement(loop, name, bound_names, owner)
+        if replacement is not None:
+            return replacement
+    if initialized_kind is _CollectionKind.SET and len(loop.body) == 1:
+        return _set_replacement(loop, name, bound_names)
+    return None
+
+
+def _list_replacement(
+    loop: ast.For, name: str, bound_names: frozenset[str], owner: _Callable
+) -> _LoopReplacement | None:
+    if len(bound_names) > 1 and len(loop.body) == 1:
         expression = _single_method_argument(loop.body[0], name, "append")
         if expression is not None and not _loads_name(expression, name) and _simple_projection(expression, bound_names):
-            return _CollectionKind.LIST
-    if initialized_kind is _CollectionKind.SET and len(loop.body) == 1:
-        return _set_loop_kind(loop, name, bound_names)
+            return _LoopReplacement(
+                _CollectionKind.LIST,
+                f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)}]",
+            )
+
+    filtered = _filtered_list_parts(loop.body, name)
+    if filtered is not None and len(bound_names) > 1:
+        expression, test, inverted = filtered
+        if (
+            not _loads_name(expression, name)
+            and not _loads_name(test, name)
+            and _simple_projection(expression, bound_names)
+            and not _contains_prohibited_expression(test)
+        ):
+            condition = _condition_source(test, inverted=inverted)
+            return _LoopReplacement(
+                _CollectionKind.LIST,
+                f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} "
+                f"if {condition}]",
+                "filters and appends to",
+                allow_multiline=True,
+            )
+
+    return _computed_list_replacement(loop, name, bound_names, owner)
+
+
+def _filtered_list_parts(body: list[ast.stmt], name: str) -> tuple[ast.expr, ast.expr, bool] | None:
+    match body:
+        case [ast.If(test=test, body=[statement], orelse=[])]:
+            expression = _single_method_argument(statement, name, "append")
+            if expression is not None:
+                return expression, test, False
+        case [ast.If(test=test, body=[ast.Continue()], orelse=[]), statement]:
+            expression = _single_method_argument(statement, name, "append")
+            if expression is not None:
+                return expression, test, True
+        case _:
+            pass
     return None
 
 
+def _computed_list_replacement(
+    loop: ast.For, name: str, bound_names: frozenset[str], owner: _Callable
+) -> _LoopReplacement | None:
+    match loop.body:
+        case [ast.Assign(targets=[ast.Name(id=candidate)], value=value), *tail]:
+            pass
+        case _:
+            return None
+
+    if candidate == name or candidate in bound_names:
+        return None
+    if _target_binding_is_observable(owner, frozenset({candidate}), loop):
+        return None
+    if _loads_name(value, name) or _contains_prohibited_expression(value):
+        return None
+
+    filtered = _filtered_list_parts(tail, name)
+    if filtered is None:
+        return None
+    expression, test, inverted = filtered
+    condition_kind = _computed_condition_kind(test, candidate, inverted=inverted)
+    if condition_kind is None:
+        return None
+    if _loads_name(expression, name) or not _loads_name(expression, candidate):
+        return None
+    projection_names = bound_names | frozenset({candidate})
+    if not _bounded_list_projection(expression, projection_names):
+        return None
+
+    assignment = f"({candidate} := {ast.unparse(value)})"
+    condition = assignment if condition_kind == "truthy" else f"{assignment} is not None"
+    return _LoopReplacement(
+        _CollectionKind.LIST,
+        f"[{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} if {condition}]",
+        "computes, filters, and appends to",
+        allow_multiline=True,
+    )
+
+
+def _computed_condition_kind(test: ast.expr, candidate: str, *, inverted: bool) -> str | None:
+    if not inverted and isinstance(test, ast.Name) and test.id == candidate:
+        return "truthy"
+    if (
+        inverted
+        and isinstance(test, ast.UnaryOp)
+        and isinstance(test.op, ast.Not)
+        and isinstance(test.operand, ast.Name)
+        and test.operand.id == candidate
+    ):
+        return "truthy"
+    match test:
+        case ast.Compare(left=ast.Name(id=left), ops=[operator], comparators=[ast.Constant(value=None)]) if (
+            left == candidate
+            and ((not inverted and isinstance(operator, ast.IsNot)) or (inverted and isinstance(operator, ast.Is)))
+        ):
+            return "not-none"
+        case _:
+            return None
+
+
+def _bounded_list_projection(node: ast.expr, names: frozenset[str]) -> bool:
+    if _simple_projection(node, names):
+        return True
+    match node:
+        case ast.Call(func=func, args=args, keywords=keywords):
+            if any(isinstance(argument, ast.Starred) for argument in args):
+                return False
+            if any(keyword.arg is None for keyword in keywords):
+                return False
+            if not _dotted_name(func):
+                return False
+            values = (*args, *(keyword.value for keyword in keywords))
+            return all(
+                not any(isinstance(item, ast.Call) for item in ast.walk(value))
+                and not _contains_prohibited_expression(value)
+                for value in values
+            )
+        case _:
+            return False
+
+
+def _dotted_name(node: ast.expr) -> bool:
+    match node:
+        case ast.Name():
+            return True
+        case ast.Attribute(value=value):
+            return _dotted_name(value)
+        case _:
+            return False
+
+
+def _condition_source(test: ast.expr, *, inverted: bool) -> str:
+    if not inverted:
+        return ast.unparse(test)
+    return ast.unparse(ast.UnaryOp(op=ast.Not(), operand=test))
+
+
 def _single_method_argument(statement: ast.stmt, name: str, method: str) -> ast.expr | None:
     match statement:
         case ast.Expr(
@@ -383,37 +591,19 @@ def _set_is_shadowed(tree: ast.Module) -> bool:
     return False
 
 
-def _replacement_fits(init: _Init, loop: ast.For, name: str, kind: _CollectionKind) -> bool:
-    expression = _replacement_expression(loop, name, kind)
-    if expression is None:
-        return False
+def _replacement_fits(init: _Init, name: str, expression: str, *, allow_multiline: bool = False) -> bool:
     prefix = f"{name} = "
     if isinstance(init, ast.AnnAssign):
         prefix = f"{name}: {ast.unparse(init.annotation)} = "
-    return init.col_offset + len(prefix) + len(expression) <= _MAX_REPLACEMENT_WIDTH
-
-
-def _replacement_expression(loop: ast.For, name: str, kind: _CollectionKind) -> str | None:
-    match kind, loop.body:
-        case _CollectionKind.DICT, [ast.Assign(targets=[ast.Subscript(slice=key)], value=value)]:
-            return (
-                f"{{{ast.unparse(key)}: {ast.unparse(value)} for {ast.unparse(loop.target)} "
-                f"in {ast.unparse(loop.iter)}}}"
-            )
-        case _CollectionKind.LIST, [statement]:
-            argument = _single_method_argument(statement, name, "append")
-            if argument is not None:
-                return f"[{ast.unparse(argument)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)}]"
-        case _CollectionKind.SET, [ast.If(test=test, body=[statement], orelse=[])]:
-            argument = _single_method_argument(statement, name, "add")
-            if argument is not None:
-                return (
-                    f"{{{ast.unparse(argument)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} "
-                    f"if {ast.unparse(test)}}}"
-                )
-        case _:
-            pass
-    return None
+    if init.col_offset + len(prefix) + len(expression) <= _MAX_REPLACEMENT_WIDTH:
+        return True
+    if not allow_multiline or not (expression.startswith("[") and expression.endswith("]")):
+        return False
+    content = expression[1:-1]
+    return (
+        init.col_offset + len(prefix) + 1 <= _MAX_REPLACEMENT_WIDTH
+        and init.col_offset + 4 + len(content) <= _MAX_REPLACEMENT_WIDTH
+    )
 
 
 def _comment_lines(source: str) -> frozenset[int]:
@@ -429,7 +619,7 @@ def _has_comment(init: _Init, loop: ast.For, comments: frozenset[int]) -> bool:
     return any(init.lineno <= line <= end_line for line in comments)
 
 
-def _set_loop_kind(loop: ast.For, name: str, bound_names: frozenset[str]) -> _CollectionKind | None:
+def _set_replacement(loop: ast.For, name: str, bound_names: frozenset[str]) -> _LoopReplacement | None:
     match loop.body[0]:
         case ast.If(test=test, body=[body], orelse=[]):
             expression = _single_method_argument(body, name, "add")
@@ -440,7 +630,19 @@ def _set_loop_kind(loop: ast.For, name: str, bound_names: frozenset[str]) -> _Co
                 and _simple_projection(expression, bound_names)
                 and not _contains_prohibited_expression(test)
             ):
-                return _CollectionKind.SET
+                return _LoopReplacement(
+                    _CollectionKind.SET,
+                    f"{{{ast.unparse(expression)} for {ast.unparse(loop.target)} in {ast.unparse(loop.iter)} "
+                    f"if {ast.unparse(test)}}}",
+                )
         case _:
             pass
     return None
+
+
+def _message(finding: _Candidate) -> str:
+    qualifier = "filtered " if finding.action != "populates" else ""
+    return (
+        f"This loop only {finding.action} fresh {finding.kind} {finding.name!r} — prefer a "
+        f"{qualifier}{finding.kind} comprehension."
+    )