sarj-python-lint 0.72.0__tar.gz → 0.73.0__tar.gz

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.72.0
+Version: 0.73.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-0.72.0 → sarj_python_lint-0.73.0}/pyproject.toml

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

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/__init__.py

@@ -1,5 +1,3 @@
-"""sarj-python-lint — custom Python lint rules."""
-
 from sarj_python_lint._ratchet_cli import main as run_ratchet
 from sarj_python_lint._version import __version__
 

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/__main__.py

@@ -1,5 +1,3 @@
-"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>."""
-
 from __future__ import annotations
 
 import argparse
@@ -99,7 +97,11 @@ def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
         diags.extend(
             diagnostic
             for diagnostic in deduplicate_diagnostics(
-                [diagnostic for diagnostic in raw if not is_suppressed(source_lines, diagnostic.line, diagnostic.code)],
+                [
+                    diagnostic
+                    for diagnostic in raw
+                    if diagnostic.code == "SARJ419" or not is_suppressed(source_lines, diagnostic.line, diagnostic.code)
+                ],
                 source=source,
             )
         )
@@ -113,7 +115,6 @@ def analyze(
     baseline: Path | None = None,
     root: Path | None = None,
 ) -> list[Diagnostic]:
-    """Return native diagnostics without rendering CLI output."""
     diagnostics = _check(rule_ids, paths)
     return diagnostics if baseline is None else _apply_baseline(diagnostics, _read_baseline(baseline), root=root)
 
@@ -121,13 +122,23 @@ def analyze(
 _DIAGNOSTIC_PRECEDENCE = MappingProxyType(
     {
         "SARJ003": frozenset({"SARJ080"}),
-        "SARJ084": frozenset({"SARJ050", "SARJ091"}),
-        "SARJ088": frozenset({"SARJ050", "SARJ085", "SARJ091"}),
-        "SARJ092": frozenset({"SARJ086", "SARJ087"}),
+        "SARJ050": frozenset({"SARJ420"}),
+        "SARJ084": frozenset({"SARJ050", "SARJ091", "SARJ420"}),
+        "SARJ085": frozenset({"SARJ420"}),
+        "SARJ086": frozenset({"SARJ420"}),
+        "SARJ087": frozenset({"SARJ420"}),
+        "SARJ088": frozenset({"SARJ050", "SARJ085", "SARJ091", "SARJ420"}),
+        "SARJ091": frozenset({"SARJ420"}),
+        "SARJ092": frozenset({"SARJ086", "SARJ087", "SARJ420"}),
         "SARJ093": frozenset({"SARJ034"}),
+        "SARJ099": frozenset({"SARJ420"}),
     }
 )
 
+_DOCSTRING_PRECEDENCE_CODES = frozenset(
+    {"SARJ050", "SARJ084", "SARJ085", "SARJ086", "SARJ087", "SARJ088", "SARJ091", "SARJ092", "SARJ099"}
+)
+
 
 class _OwnerLocation(NamedTuple):
     line: int
@@ -135,9 +146,10 @@ class _OwnerLocation(NamedTuple):
 
 
 def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = None) -> list[Diagnostic]:
-    """Keep the most specific remediation at a source location."""
     codes = frozenset(diagnostic.code for diagnostic in diags)
-    needs_docstring_owners = "SARJ092" in codes and not codes.isdisjoint(_DIAGNOSTIC_PRECEDENCE["SARJ092"])
+    needs_docstring_owners = ("SARJ092" in codes and not codes.isdisjoint(_DIAGNOSTIC_PRECEDENCE["SARJ092"])) or (
+        "SARJ420" in codes and not codes.isdisjoint(_DOCSTRING_PRECEDENCE_CODES)
+    )
     docstring_owners = _docstring_owner_locations(source) if source is not None and needs_docstring_owners else {}
     needs_signature_owners = "SARJ093" in codes and "SARJ034" in codes
     signature_owners = (
@@ -183,31 +195,29 @@ def deduplicate_diagnostics(diags: list[Diagnostic], *, source: str | None = Non
     ]
 
 
-def _function_signature_owner_locations(source: str) -> dict[int, tuple[int, int]]:
-    """Map signature lines to their function opening for cross-rule precedence."""
+def _function_signature_owner_locations(source: str) -> dict[int, _OwnerLocation]:
     try:
         tree = ast.parse(source)
     except SyntaxError:
         return {}
-    owners: dict[int, tuple[int, int]] = {}
+    owners: dict[int, _OwnerLocation] = {}
     for node in ast.walk(tree):
         if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
         body_line = node.body[0].lineno if node.body else node.lineno + 1
         end_line = max(node.lineno, body_line - 1)
-        owners.update(dict.fromkeys(range(node.lineno, end_line + 1), (node.lineno, node.col_offset + 1)))
+        owners.update(dict.fromkeys(range(node.lineno, end_line + 1), _OwnerLocation(node.lineno, node.col_offset + 1)))
     return owners
 
 
-def _docstring_owner_locations(source: str) -> dict[int, tuple[int, int]]:
-    """Map every physical docstring line to the opening expression that owns it."""
+def _docstring_owner_locations(source: str) -> dict[int, _OwnerLocation]:
     try:
         tree = ast.parse(source)
     except SyntaxError:
         tree = None
     if tree is None:
         return {}
-    owners: dict[int, tuple[int, int]] = {}
+    owners: dict[int, _OwnerLocation] = {}
     for node in ast.walk(tree):
         if not isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)) or not node.body:
             continue
@@ -218,7 +228,7 @@ def _docstring_owner_locations(source: str) -> dict[int, tuple[int, int]]:
             and isinstance(expression.value.value, str)
         ):
             continue
-        location = (expression.lineno, expression.col_offset + 1)
+        location = _OwnerLocation(expression.lineno, expression.col_offset + 1)
         lines = range(expression.lineno, (expression.end_lineno or expression.lineno) + 1)
         owners.update(dict.fromkeys(lines, location))
     return owners
@@ -245,7 +255,6 @@ class _Args(argparse.Namespace):
 
 
 def _explain(wanted: str) -> int:
-    """Print a rule's description and its derived examples link."""
     key = wanted.strip()
     cls = REGISTRY.get(key) or next((c for c in REGISTRY.values() if c.code.upper() == key.upper()), None)
     if cls is None:
@@ -267,7 +276,6 @@ def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
 
 
 def _baseline_path(path: Path, *, root: Path | None = None) -> str:
-    """Make baselines portable when a caller supplies repository-absolute paths."""
     try:
         return path.resolve().relative_to((Path.cwd() if root is None else root).resolve()).as_posix()
     except ValueError:
@@ -275,7 +283,6 @@ def _baseline_path(path: Path, *, root: Path | None = None) -> str:
 
 
 def _read_baseline(path: Path) -> dict[str, dict[str, int]]:
-    """Load a baseline file, keeping only well-formed `{path: {CODE: count}}` entries."""
     raw: object = json.loads(  # pyright: ignore[reportAny] — json.loads is an untyped stdlib boundary; the shape is narrowed below
         path.read_text(encoding="utf-8")
     )
@@ -299,7 +306,6 @@ def _apply_baseline(
     *,
     root: Path | None = None,
 ) -> list[Diagnostic]:
-    """Suppress up to the baselined count per (path, code); excess diags survive."""
     seen: Counter[tuple[str, str]] = Counter()
     out: list[Diagnostic] = []
     for d in diags:

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/_filesystem.py

@@ -1,5 +1,3 @@
-"""Small safe filesystem primitives shared by command-line workflows."""
-
 from __future__ import annotations
 
 import os
@@ -8,7 +6,6 @@ import tempfile
 
 
 def atomic_write_text(path: Path, contents: str) -> None:
-    """Replace an existing-parent destination atomically."""
     if not path.parent.is_dir():
         msg = f"baseline parent does not exist: {path.parent}"
         raise OSError(msg)

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/_ratchet_cli.py

@@ -1,5 +1,3 @@
-"""CLI: `sarj-ratchet [--baseline PATH] [--package DIR]... [--update [--allow-increase]] [ROOT]`."""
-
 from __future__ import annotations
 
 import argparse
@@ -50,7 +48,6 @@ class _Args(argparse.Namespace):
 
 
 def main(argv: list[str] | None = None) -> int:
-    """Run the ratchet."""
     args = _build_parser().parse_args(argv, namespace=_Args())
     root = args.root.resolve()
     baseline_path = args.baseline if args.baseline is not None else root / _DEFAULT_BASELINE_NAME
@@ -128,7 +125,6 @@ def main(argv: list[str] | None = None) -> int:
 
 
 def _build_parser() -> argparse.ArgumentParser:
-    """Assemble the argument parser."""
     parser = argparse.ArgumentParser(
         prog="sarj-ratchet",
         description=(
@@ -180,7 +176,6 @@ def _update(
     *,
     allow_increase: bool,
 ) -> int:
-    """Re-seed the baseline, refusing raises unless they were explicitly reviewed."""
     would_raise = gate(measurement, baseline)
     if would_raise and not allow_increase:
         sys.stderr.write("REFUSED: --update would raise ceilings; pass --allow-increase if this was reviewed:\n")

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/_secret_names.py

@@ -1,5 +1,3 @@
-"""Recognize secret-bearing identifiers for SARJ011 and SARJ012."""
-
 from __future__ import annotations
 
 from itertools import pairwise
@@ -67,7 +65,6 @@ _SEGMENT_RE = re.compile(r"[^A-Za-z0-9]+")
 
 
 def identifier_tokens(identifier: str) -> list[str]:
-    """Return lowercase whole segments and their camel-case words."""
     tokens: list[str] = []
     for segment in _SEGMENT_RE.split(identifier):
         if not segment:
@@ -79,7 +76,6 @@ def identifier_tokens(identifier: str) -> list[str]:
 
 
 def leading_word(identifier: str) -> str | None:
-    """Return the first camel- or delimiter-separated word, lowercased."""
     for segment in _SEGMENT_RE.split(identifier):
         if not segment:
             continue
@@ -89,7 +85,6 @@ def leading_word(identifier: str) -> str | None:
 
 
 def is_secret_name(identifier: str) -> bool:
-    """Report whether `identifier` names raw secret material (a credential, not metadata)."""
     tokens = identifier_tokens(identifier)
     if tokens and tokens[-1] in _INNOCUOUS_WORDS:
         return False
@@ -101,5 +96,4 @@ def is_secret_name(identifier: str) -> bool:
 
 
 def _has_api_key(tokens: list[str]) -> bool:
-    """Report whether `api` is immediately followed by `key` (the split form of `api_key`)."""
     return any(a == "api" and b == "key" for a, b in pairwise(tokens))

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/_version.py

@@ -1,5 +1,3 @@
-"""Resolve the installed package version, with a source-tree fallback."""
-
 from importlib.metadata import PackageNotFoundError, version
 
 

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/ratchet.py

@@ -1,5 +1,3 @@
-"""Suppression ratchet: count every escape hatch in a tree and let the count only shrink."""
-
 from __future__ import annotations
 
 from collections import Counter
@@ -7,7 +5,7 @@ from dataclasses import dataclass, field
 import json
 import re
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Final, TypeGuard
+from typing import TYPE_CHECKING, Final, NamedTuple, TypeGuard
 
 
 if TYPE_CHECKING:
@@ -32,6 +30,12 @@ DEFAULT_EXCLUDED_DIR_NAMES: Final = frozenset(
     }
 )
 
+
+class Improvement(NamedTuple):
+    previous: int
+    current: int
+
+
 DEFAULT_PER_FILE_CEILING: Final = 10
 
 _NOQA_RE: Final = re.compile(r"#\s*noqa:\s*([A-Z][A-Z0-9]+(?:\s*,\s*[A-Z][A-Z0-9]+)*)")
@@ -50,8 +54,6 @@ _BARE_TYPE_IGNORE_KEY: Final = "type-ignore"
 
 @dataclass(frozen=True, slots=True)
 class Measurement:
-    """What one scan of the tree found."""
-
     codes: Counter[str]
     packages: Counter[str]
     files: dict[str, int]
@@ -64,8 +66,6 @@ class Measurement:
 
 @dataclass(frozen=True, slots=True)
 class Baseline:
-    """Ceilings by code, package, and file so cleanup in one dimension cannot finance debt in another."""
-
     codes: dict[str, int] = field(default_factory=dict[str, int])
     packages: dict[str, int] = field(default_factory=dict[str, int])
     per_file_ceiling: int = DEFAULT_PER_FILE_CEILING
@@ -75,15 +75,12 @@ class Baseline:
 
 @dataclass(frozen=True, slots=True)
 class Failure:
-    """One ceiling that the measurement exceeded."""
-
     dimension: str
     key: str
     ceiling: int
     actual: int
 
     def format(self) -> str:
-        """Render the failure with the remediation for its dimension."""
         head = f"FAIL[{self.dimension}] {self.key}: {self.actual} suppressions, ceiling {self.ceiling}."
         return f"{head} {_REMEDIATION[self.dimension]}"
 
@@ -115,7 +112,6 @@ def measure(
     excluded_dir_names: frozenset[str] = DEFAULT_EXCLUDED_DIR_NAMES,
     excluded_subtrees: Iterable[str] = (),
 ) -> Measurement:
-    """Count every suppression under `root`, bucketed by code, package and file."""
     codes: Counter[str] = Counter()
     package_counts: Counter[str] = Counter()
     files: dict[str, int] = {}
@@ -137,7 +133,6 @@ def measure(
 
 
 def count_source(source: str) -> Counter[str]:
-    """Count the suppressions in one file's text, keyed by dialect and code."""
     counts: Counter[str] = Counter()
     for line in source.splitlines():
         _count_line(line, counts)
@@ -145,7 +140,6 @@ def count_source(source: str) -> Counter[str]:
 
 
 def gate(measurement: Measurement, baseline: Baseline) -> list[Failure]:
-    """Compare a measurement against the baseline's three ceilings."""
     failures = [
         Failure(dimension="code", key=key, ceiling=c, actual=n)
         for key, n in sorted(measurement.codes.items())
@@ -164,18 +158,16 @@ def gate(measurement: Measurement, baseline: Baseline) -> list[Failure]:
     return failures
 
 
-def improvements(measurement: Measurement, baseline: Baseline) -> dict[str, tuple[int, int]]:
-    """Find the code keys now below their ceiling — the wins worth locking in."""
-    out: dict[str, tuple[int, int]] = {}
+def improvements(measurement: Measurement, baseline: Baseline) -> dict[str, Improvement]:
+    out: dict[str, Improvement] = {}
     for key, ceiling in baseline.codes.items():
         actual = measurement.codes.get(key, 0)
         if actual < ceiling:
-            out[key] = (ceiling, actual)
+            out[key] = Improvement(ceiling, actual)
     return out
 
 
 def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
-    """Build the baseline that `--update` would write from a measurement."""
     # Recompute exceptions so a file loses grandfathering as soon as it reaches the ceiling.
     exceptions = {path: n for path, n in measurement.files.items() if n > baseline.per_file_ceiling}
     return Baseline(
@@ -188,7 +180,6 @@ def seed(measurement: Measurement, baseline: Baseline) -> Baseline:
 
 
 def load_baseline(path: Path) -> Baseline:
-    """Read a baseline JSON file, ignoring entries of the wrong shape."""
     raw: object = json.loads(  # pyright: ignore[reportAny] — json.loads is an untyped stdlib boundary; every read below narrows
         path.read_text(encoding="utf-8")
     )
@@ -206,14 +197,12 @@ def load_baseline(path: Path) -> Baseline:
 
 
 def _get(mapping: object, key: str) -> object:
-    """Read one key out of a value that may or may not be a JSON object."""
     if not isinstance(mapping, dict):
         return None
     return mapping.get(key)  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] — json leaves are Any
 
 
 def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
-    """Render a baseline as the JSON text to write."""
     payload = {
         "_comment": (
             "Suppression ceilings, written by `sarj-ratchet --update`. Counts may "
@@ -235,7 +224,6 @@ def dump_baseline(baseline: Baseline, packages: Iterable[str]) -> str:
 
 
 def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_EXCLUDED_DIR_NAMES) -> list[str]:
-    """List the top-level directories under `root` that contain Python files."""
     return sorted(
         name
         for child in root.iterdir()
@@ -247,7 +235,6 @@ def discover_packages(root: Path, excluded_dir_names: frozenset[str] = DEFAULT_E
 
 
 def _int_map(value: object) -> dict[str, int]:
-    """Narrow a JSON value to `{str: int}`, dropping anything else."""
     if not isinstance(value, dict):
         return {}
     return {
@@ -281,7 +268,6 @@ def _inside_subtree(relative: str, subtree: str) -> bool:
 
 
 def _python_files(root: Path, excluded_dir_names: frozenset[str]) -> Iterator[Path]:
-    """Yield every `.py` file under `root`, skipping excluded directories."""
     if not root.is_dir():
         return
     for path in sorted(root.rglob("*.py")):
@@ -290,7 +276,6 @@ def _python_files(root: Path, excluded_dir_names: frozenset[str]) -> Iterator[Pa
 
 
 def _read(path: Path) -> str:
-    """Read a source file, treating undecodable bytes as empty."""
     try:
         return path.read_text(encoding="utf-8")
     except UnicodeDecodeError, OSError:
@@ -298,7 +283,6 @@ def _read(path: Path) -> str:
 
 
 def _count_line(line: str, counts: Counter[str]) -> None:
-    """Add one line's suppressions to `counts`."""
     if file_noqa := _FILE_NOQA_RE.match(line):
         listed = file_noqa.group(1)
         if listed:

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/rule_base.py

@@ -1,5 +1,3 @@
-"""Base types for sarj-python-lint rules."""
-
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -30,7 +28,6 @@ _SARJ_NOQA_RE = re.compile(
 
 
 def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
-    """Report whether the diagnostic's line carries a `# sarj-noqa[: CODE]` comment."""
     if line < 1 or line > len(source_lines):
         return False
     text = source_lines[line - 1]
@@ -46,22 +43,16 @@ def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
 
 
 class Severity(StrEnum):
-    """Whether a diagnostic blocks the lint command."""
-
     WARNING = "warning"
     ERROR = "error"
 
 
 class ColumnEncoding(StrEnum):
-    """Coordinate system used by a native diagnostic's one-based column."""
-
     UTF8_BYTES = "utf8-bytes"
     CODEPOINTS = "codepoints"
 
 
 class RuleCategory(StrEnum):
-    """Small cross-engine taxonomy used by generated rule directories."""
-
     ARCHITECTURE = "architecture"
     CORRECTNESS = "correctness"
     MAINTAINABILITY = "maintainability"
@@ -72,16 +63,12 @@ class RuleCategory(StrEnum):
 
 
 class AutofixPolicy(StrEnum):
-    """Strongest source mutation a rule can safely offer."""
-
     NONE = "none"
     SUGGESTION = "suggestion"
     SAFE = "safe"
 
 
 class ExampleOutcome(StrEnum):
-    """Expected result when a rule checks one documentation example."""
-
     MATCH = "match"
     NO_MATCH = "no-match"
 
@@ -94,8 +81,6 @@ type ExamplePath = str
 
 @dataclass(frozen=True, slots=True)
 class ExampleFile:
-    """One virtual source file in a rule example."""
-
     path: PurePosixPath
     source: str = field(repr=False)
 
@@ -109,14 +94,11 @@ class ExampleFile:
 
     @classmethod
     def python(cls, path: ExamplePath, source: str) -> Self:
-        """Build a Python example file without leaking path parsing into rules."""
         return cls(PurePosixPath(path), source)
 
 
 @dataclass(frozen=True, slots=True)
 class RuleExample:
-    """A reviewed, executable example; examples are private unless opted in."""
-
     example_id: str
     outcome: ExampleOutcome
     files: tuple[ExampleFile, ...]
@@ -166,8 +148,6 @@ class RuleExample:
 
 @dataclass(frozen=True, slots=True)
 class RuleDocumentation:
-    """Source-authored rule prose and reviewed examples."""
-
     summary: str
     rationale: str
     remediation: str
@@ -214,8 +194,6 @@ class RuleDocumentation:
 
 @dataclass(frozen=True, slots=True)
 class NativeRuleSpec:
-    """Complete native rule record adapted from a rule class and its authored docs."""
-
     engine: str
     rule_id: str
     code: str
@@ -241,8 +219,6 @@ class NativeRuleSpec:
 
 @dataclass(frozen=True, slots=True)
 class Diagnostic:
-    """A single lint finding."""
-
     path: Path
     line: int
     col: int
@@ -252,14 +228,11 @@ class Diagnostic:
     column_encoding: ColumnEncoding = ColumnEncoding.UTF8_BYTES
 
     def format(self) -> str:
-        """Render the finding ruff-compatibly as `path:line:col: CODE message`."""
         label = "warning: " if self.severity is Severity.WARNING else ""
         return f"{self.path}:{self.line}:{self.col}: {self.code} {label}{self.message}"
 
 
 class Rule(ABC):
-    """Base class for a single lint rule."""
-
     id: str
     code: str
     description: str
@@ -267,7 +240,6 @@ class Rule(ABC):
 
     @abstractmethod
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        """Inspect the given source."""
         raise NotImplementedError
 
     @classmethod
@@ -280,7 +252,6 @@ class Rule(ABC):
 
     @classmethod
     def native_spec(cls) -> NativeRuleSpec | None:
-        """Adapt source-owned documentation while deriving engine, ID, and code."""
         authored = cls.documentation
         if authored is None:
             return None
@@ -306,18 +277,14 @@ class Rule(ABC):
 
     @classmethod
     def public_examples(cls) -> tuple[RuleExample, ...]:
-        """Return the rule's explicitly publishable canonical fixtures."""
         spec = cls.native_spec()
         return () if spec is None else spec.public_examples
 
 
 class ProjectRule(Rule):
-    """A rule that may resolve first-party symbols prepared once per CLI run."""
-
     _project_indexes: ProjectIndexSet | None = None
 
     def prepare(self, indexes: ProjectIndexSet) -> None:
-        """Attach immutable project symbols before checking the selected files."""
         self._project_indexes = indexes
 
 
@@ -325,7 +292,6 @@ _last_parse: tuple[str, str, ast.Module | None] | None = None
 
 
 def parse_or_none(path: Path, source: str) -> ast.Module | None:
-    """Parse `source`, memoizing the most recent file so N rules share one parse."""
     global _last_parse  # ruff:ignore[global-statement] — single-slot memo; the CLI runs rules per file sequentially
     path_key = str(path)
     if _last_parse is not None and _last_parse[0] == path_key and _last_parse[1] is source:

{sarj_python_lint-0.72.0 → sarj_python_lint-0.73.0}/src/sarj_python_lint/rules/_ast_index.py

@@ -1,5 +1,3 @@
-"""One tree traversal per file, shared by every rule that needs node lookups."""
-
 # Breadth-first order and isinstance semantics intentionally match ast.walk because rules rely on first-match order.
 
 from __future__ import annotations
@@ -16,7 +14,6 @@ _AST = ast.AST
 
 
 def children(node: ast.AST) -> list[ast.AST]:
-    """`node`'s direct children, in the same order as `ast.iter_child_nodes`."""
     out: list[ast.AST] = []
     for name in node._fields:
         value: object = getattr(node, name, None)
@@ -28,7 +25,6 @@ def children(node: ast.AST) -> list[ast.AST]:
 
 
 def walk(node: ast.AST) -> Iterator[ast.AST]:
-    """Yield `node` and every descendant, breadth-first."""
     queue: list[ast.AST] = [node]
     i = 0
     while i < len(queue):
@@ -45,8 +41,6 @@ def walk(node: ast.AST) -> Iterator[ast.AST]:
 
 @final
 class _NodeIndex:
-    """A module's nodes partitioned by exact class, in breadth-first order."""
-
     __slots__ = ("_buckets", "_flat", "_queries")
 
     def __init__(self, tree: ast.AST) -> None:
@@ -73,7 +67,6 @@ class _NodeIndex:
         self._queries: dict[tuple[type[ast.AST], ...], list[ast.AST]] = {}
 
     def query(self, types: tuple[type[ast.AST], ...]) -> list[ast.AST]:
-        """Return every node matching `isinstance(node, types)`, breadth-first."""
         hit = self._queries.get(types)
         if hit is not None:
             return hit
@@ -98,7 +91,6 @@ _last_index: tuple[ast.AST, _NodeIndex] | None = None
 
 
 def nodes[NodeT: ast.AST](tree: ast.AST, *types: type[NodeT]) -> list[NodeT]:
-    """Index a whole-file tree; use `walk` for subtrees and never mutate indexed nodes."""
     global _last_index  # ruff: ignore[global-statement] — single-slot memo, mirroring `parse_or_none`
     if _last_index is None or _last_index[0] is not tree:
         _last_index = (tree, _NodeIndex(tree))