sarj-python-lint 0.11.1__tar.gz → 0.12.1__tar.gz

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.11.1
+Version: 0.12.1
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/pyproject.toml

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

sarj_python_lint-0.12.1/src/sarj_python_lint/__init__.py

@@ -0,0 +1,6 @@
+"""sarj-python-lint — custom Python + SQL lint rules."""
+
+from sarj_python_lint._version import __version__
+
+
+__all__ = ["__version__"]

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/__main__.py

@@ -1,4 +1,4 @@
-"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>"""
+"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>."""
 
 from __future__ import annotations
 
@@ -106,7 +106,12 @@ def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
 
 
 def _apply_baseline(diags: list[Diagnostic], baseline: dict[str, dict[str, int]]) -> list[Diagnostic]:
-    """Suppress up to the baselined count per (path, code); excess diags survive."""
+    """Suppress up to the baselined count per (path, code); excess diags survive.
+
+    Returns:
+        The diagnostics that exceed the baselined count for their (path, code).
+
+    """
     seen: Counter[tuple[str, str]] = Counter()
     out: list[Diagnostic] = []
     for d in diags:

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/_secret_names.py

@@ -95,12 +95,16 @@ _CAMEL_RE = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+")
 _SEGMENT_RE = re.compile(r"[^A-Za-z0-9]+")
 
 
-def _tokens(identifier: str) -> list[str]:
-    """Ordered lowercase tokens from snake_case + camelCase decomposition.
+def identifier_tokens(identifier: str) -> list[str]:
+    """Return ordered lowercase tokens from snake_case + camelCase decomposition.
 
     Also yields each whole snake/kebab segment lowercased, so a pathological
     mixed-case single word like `ToKeN` (which camel-splitting shreds into
     `to`/`ke`/`n`) still surfaces its intended `token` form.
+
+    Returns:
+        The ordered lowercase tokens decomposed from `identifier`.
+
     """
     tokens: list[str] = []
     for segment in _SEGMENT_RE.split(identifier):
@@ -112,8 +116,13 @@ def _tokens(identifier: str) -> list[str]:
 
 
 def is_secret_name(identifier: str) -> bool:
-    """True if `identifier` names raw secret material (a credential, not metadata)."""
-    tokens = _tokens(identifier)
+    """Report whether `identifier` names raw secret material (a credential, not metadata).
+
+    Returns:
+        True when `identifier` denotes a credential rather than metadata.
+
+    """
+    tokens = identifier_tokens(identifier)
     if tokens and tokens[-1] in _INNOCUOUS_WORDS:
         return False
     if any(tok in _SECRET_WORDS for tok in tokens):
@@ -122,5 +131,10 @@ def is_secret_name(identifier: str) -> bool:
 
 
 def _has_api_key(tokens: list[str]) -> bool:
-    """True if `api` is immediately followed by `key` (the split form of `api_key`)."""
+    """Report whether `api` is immediately followed by `key` (the split form of `api_key`).
+
+    Returns:
+        True when an `api` token is directly followed by a `key` token.
+
+    """
     return any(a == "api" and b == "key" for a, b in pairwise(tokens))

sarj_python_lint-0.12.1/src/sarj_python_lint/_version.py

@@ -0,0 +1,20 @@
+"""Resolve the installed package version, with a source-tree fallback."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _resolve_version() -> str:
+    """Return the installed distribution version, or a dev sentinel from source.
+
+    Returns:
+        The distribution version string, or ``"0.0.0.dev0"`` when the package is
+        not installed (running straight from a source checkout).
+
+    """
+    try:
+        return version("sarj-python-lint")
+    except PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+__version__ = _resolve_version()

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rule_base.py

@@ -5,13 +5,13 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 import ast
 from dataclasses import dataclass
+from pathlib import Path
 import re
 from typing import TYPE_CHECKING
 
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from pathlib import Path
 
 
 # Suppression syntax. Two forms supported:
@@ -28,9 +28,13 @@ _SARJ_NOQA_RE = re.compile(
 
 
 def is_suppressed(source_lines: Sequence[str], line: int, code: str) -> bool:
-    """Return True if the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
+    """Report whether the diagnostic's line carries a `# sarj-noqa[: CODE]` comment.
 
     `line` is 1-based to match Diagnostic.line.
+
+    Returns:
+        True when the line is suppressed for `code`.
+
     """
     if line < 1 or line > len(source_lines):
         return False
@@ -57,7 +61,12 @@ class Diagnostic:
     message: str
 
     def format(self) -> str:
-        """Ruff-compatible: `path:line:col: CODE message`."""
+        """Render the finding ruff-compatibly as `path:line:col: CODE message`.
+
+        Returns:
+            The formatted single-line diagnostic string.
+
+        """
         return f"{self.path}:{self.line}:{self.col}: {self.code} {self.message}"
 
 
@@ -82,7 +91,12 @@ _last_parse: tuple[tuple[str, int, int], 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."""
+    """Parse `source`, memoizing the most recent file so N rules share one parse.
+
+    Returns:
+        The parsed module, or None when `source` has a syntax error.
+
+    """
     global _last_parse  # ruff:ignore[global-statement] — single-slot memo; the CLI runs rules per file sequentially
     key = (str(path), len(source), hash(source))
     if _last_parse is not None and _last_parse[0] == key:

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/_logging.py

@@ -16,11 +16,15 @@ _LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
 
 
 def is_logger_expr(expr: ast.expr) -> bool:
-    """True if `expr` evaluates to a logger.
+    """Report whether `expr` evaluates to a logger.
 
     Resolves the whole receiver chain so adapter/builder/factory calls are
     caught: `logger.bind(...).info(...)`, `logger.opt(lazy=True).debug(...)`,
     `logging.getLogger(__name__).info(...)`, `self.logger.error(...)`.
+
+    Returns:
+        True when `expr` resolves to a logger receiver.
+
     """
     if isinstance(expr, ast.Name):
         return expr.id.lower() in _LOGGER_NAMES

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/_sql.py

@@ -11,10 +11,36 @@ before any keyword or comment scan.
 from __future__ import annotations
 
 import ast
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def is_store_module(path: Path) -> bool:
+    """Report whether `path` is a store-layer module: basename ends `_store.py`, or lives under a `stores/` directory.
+
+    The SQL store-lint rules (SARJ018/020/021) encode store-write semantics —
+    column-naming, ON-CONFLICT upserts, no Postgres-side aggregation — that only
+    apply to the store layer. Non-store SQL (Flask view handlers, a Django ORM
+    SQL generator) legitimately writes `SELECT *`, bare `INSERT`, and `COUNT()`,
+    so those files are out of scope.
+
+    Returns:
+        True when `path` belongs to the store layer.
+
+    """
+    return path.name.endswith("_store.py") or "stores" in path.parts
 
 
 def sql_string_value(node: ast.expr) -> str | None:
-    """Reconstruct a (possibly `+`-concatenated) string literal, else None."""
+    """Reconstruct a (possibly `+`-concatenated) string literal, else None.
+
+    Returns:
+        The reconstructed string, or None when `node` is not a string literal.
+
+    """
     if isinstance(node, ast.Constant) and isinstance(node.value, str):
         return node.value
     if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
@@ -35,6 +61,10 @@ def strip_sql_noise(text: str) -> str:
     preserved so line offsets — and therefore diagnostic positions — do not
     shift. Doubled quotes (`''` / `""`) are SQL's in-string escape and keep the
     scanner inside the literal.
+
+    Returns:
+        `text` with string-literal contents and comment bodies blanked out.
+
     """
     out = list(text)
     n = len(text)

sarj_python_lint-0.12.1/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -0,0 +1,294 @@
+"""SARJ002: detect O(n²) single-accumulator string growth inside loops.
+
+Growing a string with `s += <str>` or `s = s + <str>` inside a loop is O(n²)
+in CPython because strings are immutable — each step allocates a new string and
+copies the previous one. Append to a list and `"".join(parts)` at the end for
+O(n).
+
+The rule fires only on genuine single-string accumulation. It deliberately does
+NOT treat a `str()/repr()/format()` coercion, a `.join()` / `.format()` /
+`.strftime()` call, or an `os.path.join(...)`-style call as accumulation — those
+are either the prescribed remedy or a bounded per-iteration transform, not the
+O(n²) defect. Per-slot writes (`parts[i] = ...`) and idempotent rebinding
+(`x = f(x)`) are likewise excluded.
+
+A target that is freshly (re)bound earlier in the same loop body — `desc = ...`
+then `desc += suffix`, or a tuple unpack `obj, path = q.popleft()` then
+`path += ...` — is loop-local: it starts empty each iteration, so the growth is
+bounded, not cross-iteration accumulation. Only a target initialised BEFORE the
+loop is a true O(n²) accumulator, so a preceding non-accumulating rebind of the
+target inside the loop suppresses the diagnostic.
+
+References:
+- https://docs.python.org/3/library/stdtypes.html#str.join
+- https://wiki.python.org/moin/PythonSpeed/PerformanceTips
+
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, TypeGuard, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+
+class InefficientStringConcatInLoop(Rule):
+    """O(n²) string concatenation in a loop."""
+
+    id: str = "inefficient-string-concat-in-loop"
+    code: str = "SARJ002"
+    description: str = "`s += '...'` / `s = s + '...'` in a loop is O(n²); append to a list and join."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        visitor = _ConcatVisitor()
+        visitor.visit(tree)
+        return [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message="String concat in a loop is O(n²). Append to a list and `''.join(...)`.",
+            )
+            for node in visitor.hits
+        ]
+
+
+class _ConcatVisitor(ast.NodeVisitor):
+    """Single O(n) pass flagging each in-loop string accumulation exactly once."""
+
+    def __init__(self) -> None:
+        self._loop_depth: int = 0
+        self._string_vars: list[frozenset[str]] = [frozenset()]
+        self._loop_reassigns: list[dict[str, list[int]]] = []
+        self.hits: list[ast.AugAssign | ast.Assign] = []
+
+    @override
+    def generic_visit(self, node: ast.AST) -> None:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            saved_depth = self._loop_depth
+            self._loop_depth = 0
+            self._string_vars.append(_string_typed_locals(node))
+            super().generic_visit(node)
+            self._string_vars.pop()
+            self._loop_depth = saved_depth
+            return
+        if isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
+            self._loop_depth += 1
+            self._loop_reassigns.append(_loop_local_reassignments(node))
+            super().generic_visit(node)
+            self._loop_reassigns.pop()
+            self._loop_depth -= 1
+            return
+        if self._loop_depth and self._is_in_loop_concat(node) and not self._is_loop_local_target(node):
+            self.hits.append(node)
+        super().generic_visit(node)
+
+    def _is_loop_local_target(self, node: ast.AugAssign | ast.Assign) -> bool:
+        """Report whether the concat target is freshly rebound earlier this iteration.
+
+        A target rebound (not self-accumulated) before the concat inside the same
+        innermost loop body starts empty each pass, so its growth is bounded.
+
+        Returns:
+            True when the target is loop-local rather than a cross-iteration accumulator.
+
+        """
+        target = self._accumulation_target(node)
+        rebinds = self._loop_reassigns[-1].get(ast.unparse(target), ())
+        return any(line < node.lineno for line in rebinds)
+
+    def _accumulation_target(self, node: ast.AugAssign | ast.Assign) -> ast.expr:
+        if isinstance(node, ast.AugAssign):
+            return node.target
+        for target in node.targets:
+            if self._is_self_add_growth(target, node.value):
+                return target
+        return node.targets[0]
+
+    def _is_in_loop_concat(self, node: ast.AST) -> TypeGuard[ast.AugAssign | ast.Assign]:
+        if isinstance(node, ast.AugAssign):
+            return isinstance(node.op, ast.Add) and self._is_string_growth(node.target, node.value)
+        if isinstance(node, ast.Assign):
+            return any(self._is_self_add_growth(target, node.value) for target in node.targets)
+        return False
+
+    def _is_self_add_growth(self, target: ast.expr, value: ast.expr) -> bool:
+        """Report whether `s = s + <str>` rebinds the target to itself-plus-more.
+
+        Returns:
+            True when the assignment is a BinOp(Add) accumulation onto the target.
+
+        """
+        if not isinstance(value, ast.BinOp) or not isinstance(value.op, ast.Add):
+            return False
+        other = _other_add_operand(target, value)
+        if other is None:
+            return False
+        return self._is_string_growth(target, other)
+
+    def _is_string_growth(self, target: ast.expr, rhs: ast.expr) -> bool:
+        """Report whether appending `rhs` to `target` is single-string accumulation.
+
+        Returns:
+            True when the append grows a string-typed target.
+
+        """
+        if isinstance(target, ast.Subscript):
+            return False
+        if _looks_like_string(rhs):
+            return True
+        if isinstance(rhs, ast.Name) and isinstance(target, ast.Name):
+            return target.id in self._string_vars[-1]
+        return False
+
+
+def _loop_local_reassignments(loop: ast.For | ast.AsyncFor | ast.While) -> dict[str, list[int]]:
+    """Map each target rebound inside this loop's own body to the lines that rebind it.
+
+    Only rebinds that are NOT self-accumulation (`s = s + x`) count — those are the
+    defect itself, not a fresh reset. Nested loops / functions / classes are their
+    own scope and are excluded.
+
+    Returns:
+        Target source string → line numbers where it is freshly (re)bound.
+
+    """
+    reassigns: dict[str, list[int]] = {}
+    for stmt in loop.body:
+        _collect_reassignments(stmt, reassigns)
+    return reassigns
+
+
+def _collect_reassignments(node: ast.AST, reassigns: dict[str, list[int]]) -> None:
+    if isinstance(
+        node,
+        (ast.For, ast.AsyncFor, ast.While, ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef),
+    ):
+        return
+    if isinstance(node, ast.Assign):
+        for target in node.targets:
+            for bound in _iter_binding_targets(target):
+                if not _is_accumulation_assign(bound, node.value):
+                    reassigns.setdefault(ast.unparse(bound), []).append(bound.lineno)
+    elif (
+        isinstance(node, ast.AnnAssign)
+        and node.value is not None
+        and not _is_accumulation_assign(node.target, node.value)
+    ):
+        reassigns.setdefault(ast.unparse(node.target), []).append(node.target.lineno)
+    for child in ast.iter_child_nodes(node):
+        _collect_reassignments(child, reassigns)
+
+
+def _iter_binding_targets(target: ast.expr) -> Iterator[ast.Name | ast.Attribute]:
+    """Yield the Name / Attribute leaves a binding target rebinds.
+
+    Subscript leaves (`acc[i] = ...`) are per-slot writes, not a rebind of the
+    accumulator itself, so they are skipped.
+
+    Yields:
+        Each Name / Attribute node the target binds.
+
+    """
+    if isinstance(target, (ast.Tuple, ast.List)):
+        for elt in target.elts:
+            yield from _iter_binding_targets(elt)
+    elif isinstance(target, ast.Starred):
+        yield from _iter_binding_targets(target.value)
+    elif isinstance(target, (ast.Name, ast.Attribute)):
+        yield target
+
+
+def _is_accumulation_assign(target: ast.expr, value: ast.expr) -> bool:
+    if isinstance(value, ast.BinOp) and isinstance(value.op, ast.Add):
+        return _other_add_operand(target, value) is not None
+    return False
+
+
+def _other_add_operand(target: ast.expr, binop: ast.BinOp) -> ast.expr | None:
+    """Return the non-target operand of `target + x` / `x + target`.
+
+    Returns:
+        The other operand, or None if neither side matches the target.
+
+    """
+    target_src = ast.unparse(target)
+    if ast.unparse(binop.left) == target_src:
+        return binop.right
+    if ast.unparse(binop.right) == target_src:
+        return binop.left
+    return None
+
+
+def _string_typed_locals(func: ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda) -> frozenset[str]:
+    """Collect names assigned a string-literal-ish value in this function's own body.
+
+    Used as the string-typed signal for bare-`Name` accumulation (`buf += line`):
+    a numeric accumulator (`total = 0`) is absent, so `total += x` stays clean.
+
+    Returns:
+        The frozenset of locally string-typed names.
+
+    """
+    if isinstance(func, ast.Lambda):
+        return frozenset()
+    names: set[str] = set()
+    for stmt in func.body:
+        _collect_string_targets(stmt, names)
+    return frozenset(names)
+
+
+def _collect_string_targets(node: ast.AST, names: set[str]) -> None:
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)):
+        return
+    if isinstance(node, ast.Assign) and _looks_like_string(node.value):
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                names.add(target.id)
+    if (
+        isinstance(node, ast.AnnAssign)
+        and node.value is not None
+        and isinstance(node.target, ast.Name)
+        and _looks_like_string(node.value)
+    ):
+        names.add(node.target.id)
+    for child in ast.iter_child_nodes(node):
+        _collect_string_targets(child, names)
+
+
+def _looks_like_string(node: ast.AST) -> bool:
+    """Report whether this expression is obviously a string at runtime.
+
+    Deliberately conservative: a bare call (`str(x)`, `",".join(...)`,
+    `os.path.join(...)`) is NOT treated as a string — those shapes also appear in
+    benign one-shot reassignment and are not the accumulation defect.
+
+    Returns:
+        True when the expression is heuristically string-typed.
+
+    """
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return True
+    if isinstance(node, ast.JoinedStr):  # f-string
+        return True
+    if isinstance(node, ast.NamedExpr):  # walrus `(y := <str>)`
+        return _looks_like_string(node.value)
+    if isinstance(node, ast.IfExp):  # ternary — string only if both branches are
+        return _looks_like_string(node.body) and _looks_like_string(node.orelse)
+    if isinstance(node, ast.BinOp):
+        if isinstance(node.op, ast.Add):
+            return _looks_like_string(node.left) or _looks_like_string(node.right)
+        if isinstance(node.op, ast.Mod):  # `"row %s" % x` — left operand decides
+            return _looks_like_string(node.left)
+    return False

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/no_aggregation_in_store_query.py

@@ -38,7 +38,7 @@ import re
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
-from sarj_python_lint.rules._sql import sql_string_value, strip_sql_noise
+from sarj_python_lint.rules._sql import is_store_module, sql_string_value, strip_sql_noise
 
 
 if TYPE_CHECKING:
@@ -121,6 +121,8 @@ class NoAggregationInStoreQuery(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if not is_store_module(path):
+            return []
         # A diagnostic needs some string literal that carries both a query verb
         # and an aggregation keyword; `source` is a strict superset of every
         # literal, so if either class is absent from the whole file no diagnostic

{sarj_python_lint-0.11.1 → sarj_python_lint-0.12.1}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -20,7 +20,10 @@ readability audit, not this rule):
    block of `#` lines.
 
 Deliberately NOT flagged: trailing/standalone *prose* comments (the legitimate
-"why"), and directive comments — `# type:`, `# noqa`, `# sarj-noqa`,
+"why"); code-shaped *illustrations* — a line that parses as Python but sits
+under a prose lead-in (`# For example:`, a wrapped sentence) or carries
+pseudo-code markers (`%sent%`, `[opt]`, `<FunctionBody>`, `...`); and directive
+comments — `# type:`, `# noqa`, `# sarj-noqa`,
 `# pragma:`, `# pyright:`, `# mypy:`, `# fmt:`, `# isort:`, `# ruff:`,
 `# nosec`, `# TODO`, `# FIXME`, shebangs, and coding declarations.
 
@@ -43,6 +46,7 @@ if TYPE_CHECKING:
 
 
 _LEADING_PREAMBLE_MIN = 4
+_PROSE_MIN_WORDS = 3
 
 _DIRECTIVE_PREFIXES = (
     "type:",
@@ -90,6 +94,11 @@ _CODE_HEADER_RE = re.compile(
 )
 _ASSIGN_OR_CALL_RE = re.compile(r"^[A-Za-z_][\w.\[\]]*\s*(?:=|:=|\+=|-=|\*=|/=)\s*\S|^[A-Za-z_][\w.]*\(")
 
+# Pseudo-code / grammar-example markers (`%sent%`, `[opt]`, `<FunctionBody>`,
+# `...`). Real commented-out code doesn't carry these — they mark an
+# illustration inside a doc comment, not a line that was once executed.
+_PSEUDOCODE_RE = re.compile(r"%[^%\s]+%|\[opt\]|<[^<>]+>|\.\.\.")
+
 
 def _comment_body(raw: str) -> str:
     return raw.lstrip("#").strip()
@@ -125,6 +134,8 @@ def _looks_like_code(body: str) -> bool:
     c = body.strip()
     if not c:
         return False
+    if _PSEUDOCODE_RE.search(c):
+        return False
     if _CODE_STMT_RE.match(c):
         return _compiles(c)
     if _RISKY_STMT_RE.match(c):
@@ -138,6 +149,27 @@ def _looks_like_code(body: str) -> bool:
     return False
 
 
+def _is_prose_line(body: str) -> bool:
+    """Report whether `body` reads as a natural-language sentence, not code.
+
+    Used to spot a doc/prose comment that immediately precedes a code-shaped
+    line: `# For example:` above `# result = {**a, **b}`, or a wrapped sentence
+    whose second line happens to parse as an expression. Such a line is an
+    illustration / prose continuation, not commented-out code.
+
+    Returns:
+        True when `body` reads as prose.
+
+    """
+    c = body.strip()
+    if not c or _is_banner(c) or _is_directive(c) or _looks_like_code(c):
+        return False
+    if c.endswith(":"):
+        return True
+    words = [w for w in re.split(r"\s+", c) if any(ch.isalpha() for ch in w)]
+    return len(words) >= _PROSE_MIN_WORDS
+
+
 def _compiles(snippet: str) -> bool:
     try:
         ast.parse(snippet)
@@ -176,20 +208,24 @@ class NoCommentCruft(Rule):
         except tokenize.TokenError, IndentationError, SyntaxError:
             return []
         diags: dict[int, Diagnostic] = {}
+        by_line = {line: body for line, _, body in standalone}
         for line, col, body in standalone:
             if _is_directive(body):
                 continue
-            msg = self._classify(body)
+            prev_body = by_line.get(line - 1)
+            msg = self._classify(body, prev_body)
             if msg is not None:
                 diags[line] = Diagnostic(path=path, line=line, col=col + 1, code=self.code, message=msg)
         self._flag_leading_preamble(standalone, first_code_line, path, diags)
         return [diags[k] for k in sorted(diags)]
 
     @staticmethod
-    def _classify(body: str) -> str | None:
+    def _classify(body: str, prev_body: str | None) -> str | None:
         if _is_banner(body):
             return "Section-banner / region comment — structure code with functions, not ASCII rules."
         if _looks_like_code(body):
+            if prev_body is not None and _is_prose_line(prev_body):
+                return None
             return "Commented-out code — delete it; git history remembers."
         return None
 
@@ -240,6 +276,10 @@ def _standalone_comments(source: str) -> tuple[list[tuple[int, int, str]], int]:
 
     A comment is standalone when it is the only content on its line. `first code
     line` is the row of the first real code token (a large sentinel if none).
+
+    Returns:
+        The standalone comments and the first code line's row.
+
     """
     out: list[tuple[int, int, str]] = []
     first_code_line = 1 << 30