sarj-python-lint 0.12.2__tar.gz → 0.14.0__tar.gz

{sarj_python_lint-0.12.2 → sarj_python_lint-0.14.0}/PKG-INFO

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

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

sarj_python_lint-0.14.0/src/sarj_python_lint/rules/_paths.py

@@ -0,0 +1,58 @@
+"""Shared file-scope predicates for the file-scope-gated rules.
+
+A single definition of "is this a test file?" so the test-scoped rules
+(SARJ031 no-sleep-in-test-body, SARJ036 no-raw-sql-in-tests) and the rules
+that *exempt* tests (SARJ014 prefer-timedelta-for-durations, SARJ015
+prefer-struct-over-namedtuple, SARJ026 prefer-namedtuple-over-tuple-return,
+SARJ034 kwonly-same-type-params) never diverge on what counts as a test file.
+
+Also the single definition of "is this a generated file?" (SARJ016/034):
+generated code mirrors whatever its generator emits, so style rules cannot be
+acted on there.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TEST_DIR_NAMES = frozenset({"tests", "test"})
+
+_GENERATED_RE = re.compile(r"auto-?generated|generated by|do not edit", re.IGNORECASE)
+
+_GENERATED_HEADER_LINES = 5
+
+
+def is_generated_source(source: str) -> bool:
+    """Report whether `source` self-identifies as generated code.
+
+    Checks the first few lines for the conventional markers
+    ("autogenerated", "generated by", "do not edit").
+
+    Returns:
+        True when the file header carries a generated-code marker.
+
+    """
+    head = source.splitlines()[:_GENERATED_HEADER_LINES]
+    return any(_GENERATED_RE.search(line) for line in head)
+
+
+def is_test_path(path: Path) -> bool:
+    """Report whether `path` is a test file.
+
+    A test file is `conftest.py`, a `test_*.py` / `*_test.py` stem, or any file
+    under a `tests` / `test` directory segment.
+
+    Returns:
+        True when `path` belongs to the test tree.
+
+    """
+    name = path.name
+    if name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    return any(part in _TEST_DIR_NAMES for part in path.parts)

{sarj_python_lint-0.12.2 → sarj_python_lint-0.14.0}/src/sarj_python_lint/rules/_registry.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
 from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
 )
+from sarj_python_lint.rules.kwonly_same_type_params import KwonlySameTypeParams
 from sarj_python_lint.rules.no_aggregation_in_store_query import (
     NoAggregationInStoreQuery,
 )
@@ -13,10 +14,12 @@ from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
 from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
+from sarj_python_lint.rules.no_file_level_suppression import NoFileLevelSuppression
 from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
 from sarj_python_lint.rules.no_query_with_many_joins import NoQueryWithManyJoins
+from sarj_python_lint.rules.no_raw_sql_in_tests import NoRawSqlInTests
 from sarj_python_lint.rules.no_repeated_string_literal import NoRepeatedStringLiteral
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
 from sarj_python_lint.rules.no_select_star import NoSelectStar
@@ -30,6 +33,10 @@ from sarj_python_lint.rules.prefer_class_row import PreferClassRow
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
     PreferConstantTimeSecretCompare,
 )
+from sarj_python_lint.rules.prefer_match_assert_never import PreferMatchAssertNever
+from sarj_python_lint.rules.prefer_module_level_constant import (
+    PreferModuleLevelConstant,
+)
 from sarj_python_lint.rules.prefer_namedtuple_over_tuple_return import (
     PreferNamedtupleOverTupleReturn,
 )
@@ -52,6 +59,13 @@ if TYPE_CHECKING:
     from sarj_python_lint.rule_base import Rule
 
 
+# Retired codes — never reuse these for new rules:
+#   SARJ004, SARJ005 (retired before the standards merge),
+#   SARJ027, SARJ029, SARJ030 (dropped in 0.11.1 as too noisy),
+#   SARJ033 httpx-client-requires-timeout, SARJ035 no-import-time-settings
+#   (dropped by user veto after the 0.13.x mined-rules review),
+#   SARJ037 no-trivial-single-use-helper (prototyped and dropped for FP rate;
+#   see the 0.13.1 inlining commit for the corpus analysis).
 REGISTRY: dict[str, type[Rule]] = {
     NoSequentialAwait.id: NoSequentialAwait,
     InefficientStringConcatInLoop.id: InefficientStringConcatInLoop,
@@ -79,6 +93,11 @@ REGISTRY: dict[str, type[Rule]] = {
     SinglePublicExport.id: SinglePublicExport,
     Stepdown.id: Stepdown,
     NoRepeatedStringLiteral.id: NoRepeatedStringLiteral,
+    PreferMatchAssertNever.id: PreferMatchAssertNever,
+    KwonlySameTypeParams.id: KwonlySameTypeParams,
+    NoRawSqlInTests.id: NoRawSqlInTests,
+    NoFileLevelSuppression.id: NoFileLevelSuppression,
+    PreferModuleLevelConstant.id: PreferModuleLevelConstant,
 }
 
 __all__ = ["REGISTRY"]

{sarj_python_lint-0.12.2 → sarj_python_lint-0.14.0}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -19,6 +19,17 @@ 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.
 
+A target whose intermediate values are CONSUMED per iteration is a probe, not
+an accumulator — `"".join` at the end cannot replace it. Two consumption
+shapes are exempt (both minimized from pydantic's unique-name generation):
+
+* the enclosing `while` test reads the target
+  (`while name in taken: name += "_"`), or
+* the loop body reads the target outside its own accumulation statement
+  (`globals.setdefault(reference_name, model)` then `reference_name += "_"`).
+
+A pure accumulator is only ever written inside the loop, so it keeps firing.
+
 References:
 - https://docs.python.org/3/library/stdtypes.html#str.join
 - https://wiki.python.org/moin/PythonSpeed/PerformanceTips
@@ -71,29 +82,66 @@ class _ConcatVisitor(ast.NodeVisitor):
         self._loop_depth: int = 0
         self._string_vars: list[frozenset[str]] = [frozenset()]
         self._loop_reassigns: list[dict[str, list[int]]] = []
+        self._loop_reads: list[frozenset[str]] = []
+        self._while_probe_names: list[frozenset[str]] = []
         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
+            saved_probes = self._while_probe_names
+            saved_reads = self._loop_reads
             self._loop_depth = 0
+            self._while_probe_names = []
+            self._loop_reads = []
             self._string_vars.append(_string_typed_locals(node))
             super().generic_visit(node)
             self._string_vars.pop()
             self._loop_depth = saved_depth
+            self._while_probe_names = saved_probes
+            self._loop_reads = saved_reads
             return
         if isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
             self._loop_depth += 1
             self._loop_reassigns.append(_loop_local_reassignments(node))
+            self._loop_reads.append(_loop_read_names(node))
+            if isinstance(node, ast.While):
+                self._while_probe_names.append(frozenset(_test_names(node.test)))
             super().generic_visit(node)
+            if isinstance(node, ast.While):
+                self._while_probe_names.pop()
+            self._loop_reads.pop()
             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):
+        if (
+            self._loop_depth
+            and self._is_in_loop_concat(node)
+            and not self._is_loop_local_target(node)
+            and not self._is_probe_target(node)
+        ):
             self.hits.append(node)
         super().generic_visit(node)
 
+    def _is_probe_target(self, node: ast.AugAssign | ast.Assign) -> bool:
+        """Report whether the concat target's intermediate values are consumed.
+
+        A target read by an enclosing while test, or read inside a loop body
+        outside its own accumulation, is a probe (unique-name generation):
+        every intermediate value matters, so `join` cannot replace the growth.
+
+        Returns:
+            True when the target is consumed per iteration rather than only grown.
+
+        """
+        target_src = ast.unparse(self._accumulation_target(node))
+        if any(target_src in names for names in self._while_probe_names):
+            return True
+        # Only the INNERMOST loop's reads consume the growth per iteration; a
+        # read in an outer loop body sees only the finished inner accumulation.
+        return bool(self._loop_reads) and target_src in self._loop_reads[-1]
+
     def _is_loop_local_target(self, node: ast.AugAssign | ast.Assign) -> bool:
         """Report whether the concat target is freshly rebound earlier this iteration.
 
@@ -153,6 +201,48 @@ class _ConcatVisitor(ast.NodeVisitor):
         return False
 
 
+def _test_names(test: ast.expr) -> set[str]:
+    """Collect the source text of every Name/Attribute read in a while test.
+
+    Returns:
+        The unparsed reads appearing in the test expression.
+
+    """
+    return {ast.unparse(n) for n in ast.walk(test) if isinstance(n, (ast.Name, ast.Attribute))}
+
+
+def _loop_read_names(loop: ast.For | ast.AsyncFor | ast.While) -> frozenset[str]:
+    """Collect names READ in the loop body outside their own accumulation.
+
+    An `s += x` stores (no Load of `s`); an `s = s + x` self-read is excluded.
+    Any other Load — a call argument, a subscript key, a comparison — consumes
+    the intermediate value, which marks the target as a probe. Nested
+    function/lambda bodies are excluded (they run in their own scope).
+
+    Returns:
+        The unparsed Name/Attribute reads in the loop's own body.
+
+    """
+    reads: set[str] = set()
+    stack: list[ast.AST] = list(loop.body)
+    while stack:
+        node = stack.pop()
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)):
+            continue
+        if isinstance(node, ast.Assign) and len(node.targets) == 1:
+            target = node.targets[0]
+            if _is_accumulation_assign(target, node.value) and isinstance(node.value, ast.BinOp):
+                # Skip the self-read operand; still record reads in the other one.
+                other = _other_add_operand(target, node.value)
+                if other is not None:
+                    stack.append(other)
+                continue
+        stack.extend(ast.iter_child_nodes(node))
+        if isinstance(node, (ast.Name, ast.Attribute)) and isinstance(node.ctx, ast.Load):
+            reads.add(ast.unparse(node))
+    return frozenset(reads)
+
+
 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.
 

sarj_python_lint-0.14.0/src/sarj_python_lint/rules/kwonly_same_type_params.py

@@ -0,0 +1,261 @@
+"""SARJ034: >=2 positional parameters with the same primitive annotation — swap-prone.
+
+`def transfer(source_id: str, target_id: str)` accepts `transfer(target, source)`
+without a whisper from the type checker: two positional parameters with the same
+primitive type are indistinguishable at the call site, and the resulting swap
+bugs pass typecheck, pass review, and fail in production. Reviewers asked for a
+keyword-only marker (`*`) in ~11 PRs, always with the same suggestion block:
+
+    # flagged
+    def transfer(source_id: str, target_id: str) -> None: ...
+
+    # preferred — call sites must name the arguments
+    def transfer(*, source_id: str, target_id: str) -> None: ...
+
+Fires only when EVERY narrowing gate holds:
+
+* the function has >= 2 positional parameters (excluding a leading `self`/`cls`)
+  whose annotations are IDENTICAL and are a bare primitive (`str`, `int`,
+  `float`, `bool`) — primitives carry no domain meaning, so the call site has
+  nothing to disambiguate with. Same-typed domain objects
+  (`a: Money, b: Money`) are left to review: arithmetic/comparison helpers over
+  a domain type are often legitimately symmetric.
+
+Never flags — these signatures cannot or should not change:
+
+* dunder methods (`__init__`, `__eq__`, ... — protocol-pinned or pervasively
+  called positionally),
+* `visit_*` / `test_*` functions (visitor dispatch and pytest fixtures are
+  framework-called with positional conventions),
+* functions decorated `@override` / `@overload` / `@abstractmethod` (an
+  override cannot unilaterally change the parent's signature; overload/abstract
+  signatures are contracts),
+* HTTP route handlers — any decorator of the shape
+  `@<name>.get/post/put/patch/delete/head/options/websocket(...)` (`router`,
+  `app`, `api`, ...): FastAPI binds handler parameters by NAME (path/query
+  keys), so the positional shape is never called swap-prone by a human,
+* test files (`_paths.is_test_path`) — test fakes and helpers mirror the
+  signatures of the code under test and cannot unilaterally change them,
+* generated files (`_paths.is_generated_source`) — the signature mirrors
+  whatever the generator emits (found via trio's `_generated_io_kqueue.py`),
+* functions whose name is referenced as a VALUE anywhere in the module
+  (passed to a registry, returned, stored) — the signature is a callback
+  protocol shared with other implementations and cannot change unilaterally
+  (found via attrs' `fmt_setter` family and sphinx `app.connect` handlers),
+* the implementation of `@overload`-decorated stubs — a same-named sibling
+  in the same scope carries `@overload`, so the impl's positional shape is
+  pinned by the declared overloads (found via trio's `getsockopt`),
+* signatures whose same-typed params differ only by a numeric suffix
+  (`value_1: float, value_2: float`) — the numbering declares the function
+  symmetric, so argument order genuinely does not matter (found via
+  pydantic's `almost_equal_floats`),
+* parameters that are already keyword-only (behind `*`) or positional-only
+  (before `/`, a deliberate positional API). Note this is per-parameter, not
+  per-signature: `def f(a: str, b: str, *, c: int)` is still flagged, because
+  `a`/`b` sit BEFORE the marker and remain swap-prone. A `*args` variadic
+  likewise does not shield same-type params in front of it.
+
+Parameters with defaults still count (documented judgment call: a default does
+not make the call site any less swappable).
+
+Symmetric functions (`def add(x: int, y: int)`) where order genuinely does not
+matter are suppressed with `# sarj-noqa: SARJ034 — <reason>`.
+"""
+
+from __future__ import annotations
+
+import ast
+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._paths import is_generated_source, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_MIN_SAME_TYPE = 2
+
+_PRIMITIVES = frozenset({"str", "int", "float", "bool"})
+
+_EXEMPT_DECORATORS = frozenset({"override", "overload", "abstractmethod"})
+
+_HTTP_ROUTE_METHODS = frozenset(
+    {"get", "post", "put", "patch", "delete", "head", "options", "websocket"}
+)
+
+_EXEMPT_NAME_PREFIXES = ("visit_", "test_")
+
+
+class KwonlySameTypeParams(Rule):
+    """>=2 positional params sharing one primitive annotation — insert `*`."""
+
+    id: str = "kwonly-same-type-params"
+    code: str = "SARJ034"
+    description: str = (
+        "two or more positional parameters with the same primitive annotation "
+        "are swap-prone — make them keyword-only by inserting `*`."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_test_path(path) or is_generated_source(source):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        value_referenced = _value_referenced_names(tree)
+        overload_names = _overload_stub_names(tree)
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if _is_exempt(node):
+                continue
+            if node.name in value_referenced or node.name in overload_names:
+                continue
+            offending = _swap_prone_annotation(node.args)
+            if offending is None:
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"`{node.name}` takes multiple positional `{offending}` "
+                        "parameters — swap-prone at call sites; insert `*` to "
+                        "make them keyword-only."
+                    ),
+                )
+            )
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _is_exempt(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    name = node.name
+    if name.startswith("__") and name.endswith("__"):
+        return True
+    if name.startswith(_EXEMPT_NAME_PREFIXES):
+        return True
+    return any(
+        (isinstance(dec, ast.Name) and dec.id in _EXEMPT_DECORATORS)
+        or (isinstance(dec, ast.Attribute) and dec.attr in _EXEMPT_DECORATORS)
+        or _is_route_decorator(dec)
+        for dec in node.decorator_list
+    )
+
+
+def _is_route_decorator(dec: ast.expr) -> bool:
+    """Report whether `dec` is an HTTP-route decorator like `@router.get(...)`.
+
+    Matches `<Name>.<http method>` — optionally called — for any receiver name
+    (`router`, `app`, `api`, ...). FastAPI binds handler parameters by name, so
+    a route handler's positional shape is not swap-prone at any call site.
+
+    Returns:
+        True when the decorator is an HTTP-route registration.
+
+    """
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    match target:
+        case ast.Attribute(value=ast.Name(), attr=attr) if attr in _HTTP_ROUTE_METHODS:
+            return True
+        case _:
+            return False
+
+
+def _swap_prone_annotation(args: ast.arguments) -> str | None:
+    """Find a primitive annotation shared by >= 2 swap-prone positional parameters.
+
+    A leading `self`/`cls` is excluded. Only bare-`Name` primitive annotations
+    participate — `str | None`, `Literal[...]`, and domain types never group.
+    Only `args.args` (positional-or-keyword) parameters count: keyword-only
+    parameters (behind `*`) cannot be swapped positionally, and positional-only
+    parameters (before `/`) are a deliberate positional API. A `*`/`*args`/`/`
+    marker therefore exempts exactly the parameters it protects — never the
+    same-type pair sitting in front of it.
+
+    A group whose parameter names differ only by a numeric suffix
+    (`value_1`/`value_2`) is a declared-symmetric signature and never groups.
+
+    Returns:
+        The offending primitive name, or None when the signature is fine.
+
+    """
+    params = list(args.args)
+    if params and params[0].arg in {"self", "cls"}:
+        params = params[1:]
+    groups: dict[str, list[str]] = {}
+    for p in params:
+        if isinstance(ann := p.annotation, ast.Name) and ann.id in _PRIMITIVES:
+            groups.setdefault(ann.id, []).append(p.arg)
+    for name, arg_names in sorted(groups.items(), key=lambda kv: -len(kv[1])):
+        if len(arg_names) >= _MIN_SAME_TYPE and not _is_symmetric_numbering(arg_names):
+            return name
+    return None
+
+
+_NUMERIC_SUFFIX_RE = re.compile(r"_?\d+$")
+
+
+def _is_symmetric_numbering(arg_names: list[str]) -> bool:
+    """Report whether every name in the group is one stem plus a numeric suffix.
+
+    `value_1`/`value_2` (or `x1`/`x2`) declare a symmetric function — argument
+    order genuinely does not matter, so the group is not swap-prone.
+
+    Returns:
+        True when all names share one stem and differ only by a number.
+
+    """
+    stems = {_NUMERIC_SUFFIX_RE.sub("", name) for name in arg_names}
+    return len(stems) == 1 and all(_NUMERIC_SUFFIX_RE.search(name) for name in arg_names)
+
+
+def _value_referenced_names(tree: ast.AST) -> frozenset[str]:
+    """Names referenced as a VALUE (loaded but not called) anywhere in the module.
+
+    A function whose name appears as a bare value — passed to a registry,
+    returned, stored in a collection — implements a callback protocol whose
+    positional shape is shared with other implementations; it cannot go
+    keyword-only unilaterally.
+
+    Returns:
+        The set of names loaded outside call position.
+
+    """
+    call_funcs = {
+        id(node.func) for node in ast.walk(tree) if isinstance(node, ast.Call)
+    }
+    return frozenset(
+        node.id
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) and id(node) not in call_funcs
+    )
+
+
+def _overload_stub_names(tree: ast.AST) -> frozenset[str]:
+    """Names carrying an `@overload` decorator anywhere in the module.
+
+    The undecorated implementation of an overloaded function shares its name
+    with the stubs; its positional shape is pinned by the declared overloads.
+
+    Returns:
+        The set of `@overload`-decorated function names.
+
+    """
+    return frozenset(
+        node.name
+        for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and any(
+            (isinstance(dec, ast.Name) and dec.id == "overload")
+            or (isinstance(dec, ast.Attribute) and dec.attr == "overload")
+            for dec in node.decorator_list
+        )
+    )

{sarj_python_lint-0.12.2 → sarj_python_lint-0.14.0}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -25,7 +25,17 @@ 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.
+`# nosec`, `# TODO`, `# FIXME`, `# language=` (IDE injection), shebangs, and
+coding declarations.
+
+Also NOT flagged (famous-repo sweep hardening):
+- generated files (`_paths.is_generated_source`) — their banners are the
+  generator's warning header, not hand-written cruft;
+- a punctuation-only "banner" directly beneath a texty comment line — that is
+  an RST-style heading underline or an ASCII-diagram row inside a prose comment
+  essay (trio's epoll/socket design essays), not a code-section separator;
+- step narration that carries a rationale marker (`because`, `since`,
+  `so that`, `otherwise`) — "First, take the lock, because ..." is a *why*.
 
 Suppress an intentional case with `# sarj-noqa: SARJ016 — <reason>`.
 """
@@ -39,6 +49,7 @@ import tokenize
 from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule
+from sarj_python_lint.rules._paths import is_generated_source
 
 
 if TYPE_CHECKING:
@@ -67,6 +78,7 @@ _DIRECTIVE_PREFIXES = (
     "hack",
     "xxx:",
     "-*-",
+    "language=",
 )
 
 _LICENSE_RE = re.compile(
@@ -108,6 +120,10 @@ _STEP_NARRATION_RE = re.compile(
     re.IGNORECASE,
 )
 
+# A rationale marker turns step narration into a legitimate *why* comment
+# ("First, we take the outer send lock, because of Trio's standard semantics").
+_RATIONALE_RE = re.compile(r"\b(?:because|since|so that|otherwise)\b", re.IGNORECASE)
+
 # Self-admitted meta-commentary — the "why later", not the why. Owner-tagged
 # directive markers are handled elsewhere (as directives) and kept.
 _META_COMMENTARY_RE = re.compile(
@@ -150,9 +166,33 @@ def _is_redundant_narration(body: str) -> bool:
     c = body.strip()
     if not c or _looks_like_code(c):
         return False
+    if _RATIONALE_RE.search(c):
+        return False  # "First, take the lock, because ..." carries a why
     return bool(_STEP_NARRATION_RE.search(c) or _META_COMMENTARY_RE.search(c))
 
 
+def _is_heading_underline(body: str, prev_body: str | None) -> bool:
+    """Report whether a punctuation-only banner underlines a texty comment line.
+
+    An RST-style heading underline (`# Literature review` / `# -----------`) or
+    an ASCII-diagram row directly beneath a texty row lives INSIDE a prose
+    comment block — it is typography, not a code-section separator.
+
+    Returns:
+        True when the banner sits directly under a texty, non-banner comment.
+
+    """
+    if not _BANNER_FULL_RE.match(body):
+        return False
+    if prev_body is None:
+        return False
+    return (
+        any(_is_word_char(ch) for ch in prev_body)
+        and not _is_banner(prev_body)
+        and not _looks_like_code(prev_body)
+    )
+
+
 def _is_banner(body: str) -> bool:
     if not body:
         return False
@@ -236,6 +276,12 @@ class NoCommentCruft(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated_source(source):
+            return []
+        # A Sphinx `docs/**/conf.py` is quickstart-generated boilerplate whose
+        # `# -- Section ----` banners are the tool's own convention.
+        if path.name == "conf.py" and "docs" in path.parts:
+            return []
         try:
             standalone, first_code_line = _standalone_comments(source)
         except tokenize.TokenError, IndentationError, SyntaxError:
@@ -255,6 +301,8 @@ class NoCommentCruft(Rule):
     @staticmethod
     def _classify(body: str, prev_body: str | None) -> str | None:
         if _is_banner(body):
+            if _is_heading_underline(body, prev_body):
+                return None
             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):