sarj-python-lint 0.7.0__tar.gz → 0.9.0__tar.gz

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/.gitignore

@@ -30,3 +30,7 @@ Thumbs.db
 .vscode/
 .zed/
 *.swp
+
+# Claude Code local state (shared settings.json is tracked)
+.claude/*
+!.claude/settings.json

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.7.0
+Version: 0.9.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
@@ -32,7 +32,6 @@ uv tool install sarj-python-lint
   hooks:
     - id: sarj-no-sequential-await
     - id: sarj-inefficient-string-concat-in-loop
-    - id: sarj-prefer-discriminated-union
     - id: sarj-prefer-str-enum
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/README.md

@@ -14,7 +14,6 @@ uv tool install sarj-python-lint
   hooks:
     - id: sarj-no-sequential-await
     - id: sarj-inefficient-string-concat-in-loop
-    - id: sarj-prefer-discriminated-union
     - id: sarj-prefer-str-enum
     - id: sarj-no-fat-try-blocks
     - id: sarj-pydantic-at-boundaries

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/pyproject.toml

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

sarj_python_lint-0.9.0/src/sarj_python_lint/__init__.py

@@ -0,0 +1,9 @@
+"""sarj-python-lint — custom Python + SQL lint rules."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("sarj-python-lint")
+except PackageNotFoundError:  # running from an uninstalled source tree
+    __version__ = "0.0.0.dev0"

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/src/sarj_python_lint/__main__.py

@@ -1,7 +1,10 @@
-"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] <files>"""
+"""CLI: sarj-python-lint check --rule <id> [--rule <id2>] [--baseline <json>] <files>"""
+
 from __future__ import annotations
 
 import argparse
+from collections import Counter
+import json
 from pathlib import Path
 import sys
 
@@ -11,9 +14,21 @@ from sarj_python_lint.rules import REGISTRY
 
 
 SKIP_DIR_NAMES = {
-    "node_modules", ".venv", "venv", ".git", "dist", "build", ".next",
-    "coverage", "__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache",
-    ".turbo", ".yarn", ".pnpm-store",
+    "node_modules",
+    ".venv",
+    "venv",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "coverage",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    ".turbo",
+    ".yarn",
+    ".pnpm-store",
 }
 
 # Skip files larger than this — they are almost always generated/vendored, not
@@ -70,12 +85,36 @@ class _Args(argparse.Namespace):
     cmd: str | None
     rule: list[str]
     files: list[Path]
+    baseline: Path | None
+    update_baseline: Path | None
 
     def __init__(self) -> None:
         super().__init__()
         self.cmd = None
         self.rule = []
         self.files = []
+        self.baseline = None
+        self.update_baseline = None
+
+
+def _baseline_counts(diags: list[Diagnostic]) -> dict[str, dict[str, int]]:
+    counts: dict[str, dict[str, int]] = {}
+    for d in diags:
+        counts.setdefault(str(d.path), {})
+        counts[str(d.path)][d.code] = counts[str(d.path)].get(d.code, 0) + 1
+    return counts
+
+
+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."""
+    seen: Counter[tuple[str, str]] = Counter()
+    out: list[Diagnostic] = []
+    for d in diags:
+        key = (str(d.path), d.code)
+        seen[key] += 1
+        if seen[key] > baseline.get(key[0], {}).get(key[1], 0):
+            out.append(d)
+    return out
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -93,6 +132,16 @@ def main(argv: list[str] | None = None) -> int:
         required=True,
         help="Rule ID (repeat for multiple).",
     )
+    check_p.add_argument(
+        "--baseline",
+        type=Path,
+        help="Per-file shrink-only baseline JSON: {path: {CODE: count}}. Diags up to the baselined count are suppressed.",
+    )
+    check_p.add_argument(
+        "--update-baseline",
+        type=Path,
+        help="Write the current per-file diagnostic counts to this JSON and exit 0.",
+    )
     check_p.add_argument("files", nargs="+", type=Path)
 
     sub.add_parser("list-rules", help="List available rule IDs.")
@@ -106,6 +155,14 @@ def main(argv: list[str] | None = None) -> int:
         return 0
 
     diags = _check(args.rule, args.files)
+    if args.update_baseline is not None:
+        args.update_baseline.write_text(json.dumps(_baseline_counts(diags), indent=2, sort_keys=True) + "\n")
+        sys.stdout.write(
+            f"baseline written: {args.update_baseline} ({len(diags)} diagnostics over {len(_baseline_counts(diags))} files)\n"
+        )
+        return 0
+    if args.baseline is not None:
+        diags = _apply_baseline(diags, json.loads(args.baseline.read_text()))
     for d in diags:
         sys.stdout.write(d.format() + "\n")
     return 1 if diags else 0

sarj_python_lint-0.9.0/src/sarj_python_lint/_secret_names.py

@@ -0,0 +1,126 @@
+"""Shared predicate for deciding whether an identifier names secret material.
+
+Used by both SARJ011 (`prefer-constant-time-secret-compare`) and SARJ012
+(`no-secret-in-log`) so the two rules never diverge on what counts as a secret.
+
+The historical implementation matched a secret word as a bare *substring*, which
+misfired on a large false-positive class observed in a real audit:
+
+- LLM usage counters that merely embed `token`: `token_count`, `prompt_tokens`,
+  `completion_tokens`, `total_tokens`, `max_tokens`, `n_tokens`, `num_tokens`,
+  `tokenize`, `tokenizer`, `token_budget`.
+- Row-id / handle names: `api_key_id`, `*_key_id` — the id of a key row, not the
+  key material.
+- Boolean feature / presence / state flags: `password_enabled`,
+  `token_present`, `password_set`, `password_configured` — a boolean answering
+  "is it there / was it set", not the credential itself. A `type` discriminator
+  is the same: `token_type` is `"Bearer"`, `credential_type` is a class name.
+- Innocent words embedding a secret word: `secretary` (embeds `secret`).
+
+We fix this with two changes:
+
+1. Match a secret word only as a WHOLE token (after snake_case / camelCase
+   splitting), never a substring. This alone clears `tokenize`, `tokenizer`,
+   `secretary`, and every *pluralized* `tokens` counter (plural `tokens` is not
+   the singular secret word `token`).
+2. Disqualify an identifier whose TRAILING token is a counter / row-id / flag
+   marker (`count`, `budget`, `id`, `enabled`, ...) even when a secret word is
+   also present — this clears `token_count`, `api_key_id`, `password_enabled`,
+   while still catching a credential that merely leads with such a word
+   (`valid_token`, `present_token` are secrets, not flags).
+"""
+
+from __future__ import annotations
+
+from itertools import pairwise
+import re
+
+
+_SECRET_WORDS = frozenset(
+    {
+        "token",
+        "secret",
+        "password",
+        "passwd",
+        "jwt",
+        "secrets",
+        "passwords",
+        "credential",
+        "credentials",
+        "authorization",
+        "signature",
+        "hmac",
+        "digest",
+        "hash",
+        "apikey",
+    }
+)
+
+# Tokens that mark a counter, row-id, feature flag, or boolean presence/state
+# marker. As the TRAILING token they mean the identifier is metadata *about* a
+# secret, not the secret itself, so it is not a leak / timing surface even when a
+# secret word is also present: `token_present`, `password_set`, and
+# `password_configured` are booleans, not credentials. Leading such a word does
+# not disqualify — `valid_token` / `present_token` are credentials.
+_INNOCUOUS_WORDS = frozenset(
+    {
+        "count",
+        "counts",
+        "budget",
+        "limit",
+        "limits",
+        "id",
+        "ids",
+        "enabled",
+        "disabled",
+        "flag",
+        "flags",
+        "present",
+        "set",
+        "unset",
+        "configured",
+        "missing",
+        "required",
+        "valid",
+        "invalid",
+        "exists",
+        "type",
+        "types",
+    }
+)
+
+# camelCase / PascalCase / ALLCAPS / digit run splitter, applied to each
+# snake/kebab segment. `APIKey` -> ["API", "Key"], `authToken` -> ["auth", "Token"].
+_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.
+
+    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.
+    """
+    tokens: list[str] = []
+    for segment in _SEGMENT_RE.split(identifier):
+        if not segment:
+            continue
+        tokens.append(segment.lower())
+        tokens.extend(part.lower() for part in _CAMEL_RE.findall(segment))
+    return tokens
+
+
+def is_secret_name(identifier: str) -> bool:
+    """True if `identifier` names raw secret material (a credential, not metadata)."""
+    tokens = _tokens(identifier)
+    if tokens and tokens[-1] in _INNOCUOUS_WORDS:
+        return False
+    if any(tok in _SECRET_WORDS for tok in tokens):
+        return True
+    return _has_api_key(tokens)
+
+
+def _has_api_key(tokens: list[str]) -> bool:
+    """True if `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.7.0 → sarj_python_lint-0.9.0}/src/sarj_python_lint/rule_base.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+import ast
 from dataclasses import dataclass
 import re
 from typing import TYPE_CHECKING
@@ -75,3 +76,20 @@ class Rule(ABC):
     def check(self, path: Path, source: str) -> list[Diagnostic]:
         """Inspect the given source. Return zero or more diagnostics."""
         raise NotImplementedError
+
+
+_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."""
+    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:
+        return _last_parse[1]
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError:
+        tree = None
+    _last_parse = (key, tree)
+    return tree

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/src/sarj_python_lint/rules/_logging.py

@@ -12,7 +12,7 @@ import ast
 
 _LOGGER_NAMES = frozenset({"logger", "log", "logging", "loguru", "_logger", "_log"})
 
-_LOGGER_FACTORIES = frozenset({"getlogger", "getchild"})
+_LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
 
 
 def is_logger_expr(expr: ast.expr) -> bool:

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/src/sarj_python_lint/rules/_registry.py

@@ -13,6 +13,7 @@ from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
 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_query_with_many_joins import NoQueryWithManyJoins
+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
 from sarj_python_lint.rules.no_sentinel_return_on_except import NoSentinelReturnOnExcept
@@ -24,7 +25,6 @@ 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_discriminated_union import PreferDiscriminatedUnion
 from sarj_python_lint.rules.prefer_str_enum import PreferStrEnum
 from sarj_python_lint.rules.prefer_struct_over_namedtuple import (
     PreferStructOverNamedtuple,
@@ -33,6 +33,8 @@ from sarj_python_lint.rules.prefer_timedelta_for_durations import (
     PreferTimedeltaForDurations,
 )
 from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
+from sarj_python_lint.rules.single_public_export import SinglePublicExport
+from sarj_python_lint.rules.stepdown import Stepdown
 from sarj_python_lint.rules.store_insert_requires_on_conflict import (
     StoreInsertRequiresOnConflict,
 )
@@ -45,7 +47,6 @@ if TYPE_CHECKING:
 REGISTRY: dict[str, type[Rule]] = {
     NoSequentialAwait.id: NoSequentialAwait,
     InefficientStringConcatInLoop.id: InefficientStringConcatInLoop,
-    PreferDiscriminatedUnion.id: PreferDiscriminatedUnion,
     PreferClassRow.id: PreferClassRow,
     PreferStrEnum.id: PreferStrEnum,
     NoFatTryBlocks.id: NoFatTryBlocks,
@@ -63,6 +64,9 @@ REGISTRY: dict[str, type[Rule]] = {
     NoQueryWithManyJoins.id: NoQueryWithManyJoins,
     NoAggregationInStoreQuery.id: NoAggregationInStoreQuery,
     NoSelectStar.id: NoSelectStar,
+    SinglePublicExport.id: SinglePublicExport,
+    Stepdown.id: Stepdown,
+    NoRepeatedStringLiteral.id: NoRepeatedStringLiteral,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.9.0/src/sarj_python_lint/rules/_sql.py

@@ -0,0 +1,81 @@
+"""Shared SQL-literal helpers for the SQL-aware store-lint rules (SARJ018-021).
+
+These rules scan raw SQL embedded in Python string literals for keywords
+(`JOIN`, `COUNT`, `ON CONFLICT`, `*`, ...). Scanning the raw text conflates SQL
+*code* with SQL string-literal *values*: `WHERE p = 'join'` holds no JOIN, a
+`--` inside a quoted value is not a comment, and a backtick inside a value is not
+a BigQuery table quote. `strip_sql_noise` neutralizes both classes of noise
+before any keyword or comment scan.
+"""
+
+from __future__ import annotations
+
+import ast
+
+
+def sql_string_value(node: ast.expr) -> str | None:
+    """Reconstruct a (possibly `+`-concatenated) string literal, else None."""
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
+        left = sql_string_value(node.left)
+        right = sql_string_value(node.right)
+        if left is not None and right is not None:
+            return left + right
+    return None
+
+
+def strip_sql_noise(text: str) -> str:
+    """Blank out SQL string-literal contents and comment bodies.
+
+    A single left-to-right scan, so precedence between strings and comments is
+    correct: a `--` or quote inside a string literal is protected (masked as
+    string data, never read as a comment), and a quote inside a comment is
+    ignored. Every masked character becomes a space except newlines, which are
+    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.
+    """
+    out = list(text)
+    n = len(text)
+    i = 0
+    while i < n:
+        ch = text[i]
+        if ch in {"'", '"'}:
+            out[i] = " "
+            i += 1
+            while i < n:
+                c = text[i]
+                if c == ch:
+                    if i + 1 < n and text[i + 1] == ch:
+                        out[i] = out[i + 1] = " "
+                        i += 2
+                        continue
+                    out[i] = " "
+                    i += 1
+                    break
+                if c != "\n":
+                    out[i] = " "
+                i += 1
+            continue
+        if ch == "-" and i + 1 < n and text[i + 1] == "-":
+            while i < n and text[i] != "\n":
+                out[i] = " "
+                i += 1
+            continue
+        if ch == "/" and i + 1 < n and text[i + 1] == "*":
+            out[i] = out[i + 1] = " "
+            i += 2
+            while i < n and not (text[i] == "*" and i + 1 < n and text[i + 1] == "/"):
+                if text[i] != "\n":
+                    out[i] = " "
+                i += 1
+            if i < n:
+                out[i] = " "
+                i += 1
+                if i < n:
+                    out[i] = " "
+                    i += 1
+            continue
+        i += 1
+    return "".join(out)

{sarj_python_lint-0.7.0 → sarj_python_lint-0.9.0}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import ast
 from typing import TYPE_CHECKING, override
 
-from sarj_python_lint.rule_base import Diagnostic, Rule
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 
 
 if TYPE_CHECKING:
@@ -30,9 +30,8 @@ class InefficientStringConcatInLoop(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        try:
-            tree = ast.parse(source, filename=str(path))
-        except SyntaxError:
+        tree = parse_or_none(path, source)
+        if tree is None:
             return []
         visitor = _ConcatVisitor()
         visitor.visit(tree)
@@ -42,38 +41,56 @@ class InefficientStringConcatInLoop(Rule):
                 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(...)`."
-                ),
+                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 `+=` exactly once."""
+    """Single O(n) pass flagging each in-loop string concat exactly once."""
 
     def __init__(self) -> None:
         self._loop_depth: int = 0
-        self.hits: list[ast.AugAssign] = []
+        self.hits: list[ast.AugAssign | ast.Assign] = []
 
     @override
     def generic_visit(self, node: ast.AST) -> None:
-        if isinstance(node, (ast.For, ast.While)):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            saved = self._loop_depth
+            self._loop_depth = 0
+            super().generic_visit(node)
+            self._loop_depth = saved
+            return
+        if isinstance(node, (ast.For, ast.AsyncFor, ast.While)):
             self._loop_depth += 1
             super().generic_visit(node)
             self._loop_depth -= 1
             return
-        if (
-            self._loop_depth
-            and isinstance(node, ast.AugAssign)
-            and isinstance(node.op, ast.Add)
-            and _looks_like_string(node.value)
-        ):
+        if self._loop_depth and self._is_in_loop_concat(node):
             self.hits.append(node)
         super().generic_visit(node)
 
+    @staticmethod
+    def _is_in_loop_concat(node: ast.AST) -> bool:
+        if isinstance(node, ast.AugAssign):
+            return isinstance(node.op, ast.Add) and _looks_like_string(node.value)
+        if isinstance(node, ast.Assign):
+            return _looks_like_string(node.value) and any(
+                _target_referenced_in(target, node.value) for target in node.targets
+            )
+        return False
+
+
+def _target_referenced_in(target: ast.expr, value: ast.expr) -> bool:
+    """True when the assignment target is read on the RHS (self-accumulation)."""
+    target_src = ast.unparse(target)
+    return any(
+        ast.unparse(sub) == target_src
+        for sub in ast.walk(value)
+        if isinstance(sub, (ast.Name, ast.Attribute, ast.Subscript))
+    )
+
 
 def _looks_like_string(node: ast.AST) -> bool:
     """Heuristic for 'this RHS is probably a string at runtime'."""
@@ -81,13 +98,20 @@ def _looks_like_string(node: ast.AST) -> bool:
         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.Call):
         # str(...) / repr(...) / format / strftime — usually string
         if isinstance(node.func, ast.Name) and node.func.id in {"str", "repr", "format"}:
             return True
         if isinstance(node.func, ast.Attribute):
             return node.func.attr in {"format", "strftime", "join"}
-    if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Add):
-        # `+` propagates string-ness if either side is a string
-        return _looks_like_string(node.left) or _looks_like_string(node.right)
+    if isinstance(node, ast.BinOp):
+        if isinstance(node.op, ast.Add):
+            # `+` propagates string-ness if either side is a string
+            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