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

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

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

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

sarj_python_lint-0.12.2/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.12.0 → sarj_python_lint-0.12.2}/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.12.0 → sarj_python_lint-0.12.2}/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.2/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.12.0 → sarj_python_lint-0.12.2}/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.12.0 → sarj_python_lint-0.12.2}/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.12.0 → sarj_python_lint-0.12.2}/src/sarj_python_lint/rules/_sql.py

@@ -19,19 +19,28 @@ if TYPE_CHECKING:
 
 
 def is_store_module(path: Path) -> bool:
-    """True for a store-layer module: basename ends `_store.py`, or the file lives under a `stores/` directory.
+    """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):
@@ -52,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.0 → sarj_python_lint-0.12.2}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -12,20 +12,29 @@ 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, override
+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
 
 
@@ -61,6 +70,7 @@ class _ConcatVisitor(ast.NodeVisitor):
     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
@@ -75,14 +85,38 @@ class _ConcatVisitor(ast.NodeVisitor):
             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):
+        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_in_loop_concat(self, node: ast.AST) -> bool:
+    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):
@@ -90,7 +124,12 @@ class _ConcatVisitor(ast.NodeVisitor):
         return False
 
     def _is_self_add_growth(self, target: ast.expr, value: ast.expr) -> bool:
-        """`s = s + <str>` — a BinOp(Add) rebinding the target to itself-plus-more."""
+        """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)
@@ -99,7 +138,12 @@ class _ConcatVisitor(ast.NodeVisitor):
         return self._is_string_growth(target, other)
 
     def _is_string_growth(self, target: ast.expr, rhs: ast.expr) -> bool:
-        """True when appending `rhs` to `target` is single-string accumulation."""
+        """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):
@@ -109,8 +153,76 @@ class _ConcatVisitor(ast.NodeVisitor):
         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:
-    """The non-target operand of `target + x` / `x + target`, or None if absent."""
+    """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
@@ -119,17 +231,20 @@ def _other_add_operand(target: ast.expr, binop: ast.BinOp) -> ast.expr | None:
     return None
 
 
-def _string_typed_locals(func: ast.AST) -> frozenset[str]:
-    """Names assigned a string-literal-ish value in this function's own body.
+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.
+
     """
-    body = getattr(func, "body", None)
-    if not isinstance(body, list):
+    if isinstance(func, ast.Lambda):
         return frozenset()
     names: set[str] = set()
-    for stmt in body:
+    for stmt in func.body:
         _collect_string_targets(stmt, names)
     return frozenset(names)
 
@@ -153,11 +268,15 @@ def _collect_string_targets(node: ast.AST, names: set[str]) -> None:
 
 
 def _looks_like_string(node: ast.AST) -> bool:
-    """Heuristic for 'this expression is obviously a string at runtime'.
+    """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

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

@@ -99,6 +99,26 @@ _ASSIGN_OR_CALL_RE = re.compile(r"^[A-Za-z_][\w.\[\]]*\s*(?:=|:=|\+=|-=|\*=|/=)\
 # illustration inside a doc comment, not a line that was once executed.
 _PSEUDOCODE_RE = re.compile(r"%[^%\s]+%|\[opt\]|<[^<>]+>|\.\.\.")
 
+# Step-narration lead-ins ("First, ...", "Then, ...", "Finally, ...", "Step 2:").
+# A trailing comma/colon is required so English adverbs ("finally the invariant
+# holds") aren't mistaken for an enumeration marker.
+_STEP_NARRATION_RE = re.compile(
+    r"^(?:first(?:ly)?|second(?:ly)?|third(?:ly)?|then|next|after(?:wards| that)?"
+    r"|finally|lastly|now)\s*[,:]\s*\S|^step\s+\d+\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(
+    r"\b(?:for now|keeping (?:it|this) simple|could be (?:refactored|improved|cleaned up|simplified)"
+    r"|refactor(?:ed|ing)? (?:later|this)|not sure (?:if|whether|why|how)"
+    r"|quick[- ](?:and[- ]dirty|fix)|(?:a |bit of a )?hacky|is a hack"
+    r"|temporary (?:solution|workaround|fix|hack)|revisit (?:this|later|below)"
+    r"|clean (?:this|it) up|not ideal|placeholder for now)\b",
+    re.IGNORECASE,
+)
+
 
 def _comment_body(raw: str) -> str:
     return raw.lstrip("#").strip()
@@ -120,6 +140,19 @@ def _is_directive(body: str) -> bool:
     return False
 
 
+def _is_redundant_narration(body: str) -> bool:
+    """Whether a comment merely narrates the code (step markers, meta-commentary).
+
+    Returns:
+        True for step-narration lead-ins and self-admitted meta-commentary.
+
+    """
+    c = body.strip()
+    if not c or _looks_like_code(c):
+        return False
+    return bool(_STEP_NARRATION_RE.search(c) or _META_COMMENTARY_RE.search(c))
+
+
 def _is_banner(body: str) -> bool:
     if not body:
         return False
@@ -150,12 +183,16 @@ def _looks_like_code(body: str) -> bool:
 
 
 def _is_prose_line(body: str) -> bool:
-    """Return True if `body` reads as a natural-language sentence, not code.
+    """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):
@@ -223,6 +260,8 @@ class NoCommentCruft(Rule):
             if prev_body is not None and _is_prose_line(prev_body):
                 return None
             return "Commented-out code — delete it; git history remembers."
+        if _is_redundant_narration(body):
+            return "Comment narrates the code — delete it or say why, not what. Code is self-documenting."
         return None
 
     def _flag_leading_preamble(
@@ -272,6 +311,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

{sarj_python_lint-0.12.0 → sarj_python_lint-0.12.2}/src/sarj_python_lint/rules/no_cors_wildcard_with_credentials.py

@@ -15,6 +15,7 @@ would be a valid further tightening).
 
 References:
 - https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#credentialed_requests_and_wildcards
+
 """
 
 from __future__ import annotations
@@ -75,15 +76,24 @@ class NoCorsWildcardWithCredentials(Rule):
 
 
 def _is_true_literal(node: ast.expr) -> bool:
-    """True only for the literal `True` (not `1`, not a truthy expression)."""
+    """Report whether `node` is the literal `True` (not `1`, not a truthy expression).
+
+    Returns:
+        True only when `node` is the `True` constant.
+
+    """
     return isinstance(node, ast.Constant) and node.value is True
 
 
 def _contains_star_literal(node: ast.expr) -> bool:
-    """True if a `"*"` string `Constant` appears anywhere in `node`'s subtree.
+    """Report whether a `"*"` string `Constant` appears anywhere in `node`'s subtree.
 
     Walking the whole subtree catches both `["*"]` and the `allowed if flag else
     ["*"]` conditional branch. A dynamic `allow_origins=some_var` has no `"*"`
     literal, so it does not fire.
+
+    Returns:
+        True when a `"*"` literal appears in the subtree.
+
     """
     return any(isinstance(child, ast.Constant) and child.value == "*" for child in ast.walk(node))