sarj-python-lint 0.2.0__tar.gz → 0.3.0__tar.gz

{sarj_python_lint-0.2.0 → sarj_python_lint-0.3.0}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.2.0
+Version: 0.3.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
-Project-URL: Homepage, https://github.com/sarj-ai/linting/tree/main/packages/python
-Project-URL: Repository, https://github.com/sarj-ai/linting
-Project-URL: Issues, https://github.com/sarj-ai/linting/issues
+Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
+Project-URL: Repository, https://github.com/sarj-ai/standards
+Project-URL: Issues, https://github.com/sarj-ai/standards/issues
 Author: sarj-ai
 License: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.13
+Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 
 # sarj-python-lint
@@ -27,13 +27,15 @@ uv tool install sarj-python-lint
 ## Pre-commit
 
 ```yaml
-- repo: https://github.com/sarj-ai/linting
+- repo: https://github.com/sarj-ai/standards
   rev: python-v0.2.0
   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
 ```
 
 ## CLI

{sarj_python_lint-0.2.0 → sarj_python_lint-0.3.0}/README.md

@@ -9,13 +9,15 @@ uv tool install sarj-python-lint
 ## Pre-commit
 
 ```yaml
-- repo: https://github.com/sarj-ai/linting
+- repo: https://github.com/sarj-ai/standards
   rev: python-v0.2.0
   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
 ```
 
 ## CLI

{sarj_python_lint-0.2.0 → sarj_python_lint-0.3.0}/pyproject.toml

@@ -1,17 +1,17 @@
 [project]
 name = "sarj-python-lint"
-version = "0.2.0"
+version = "0.3.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]
 license = { text = "MIT" }
-requires-python = ">=3.13"
+requires-python = ">=3.14"
 classifiers = [
   "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Quality Assurance",
 ]
 dependencies = []
@@ -20,16 +20,16 @@ dependencies = []
 sarj-python-lint = "sarj_python_lint.__main__:main"
 
 [project.urls]
-Homepage = "https://github.com/sarj-ai/linting/tree/main/packages/python"
-Repository = "https://github.com/sarj-ai/linting"
-Issues = "https://github.com/sarj-ai/linting/issues"
+Homepage = "https://github.com/sarj-ai/standards/tree/main/packages/python"
+Repository = "https://github.com/sarj-ai/standards"
+Issues = "https://github.com/sarj-ai/standards/issues"
 
 [dependency-groups]
 dev = [
-  "pytest>=8.0",
-  "pytest-benchmark>=4.0",
-  "ruff>=0.6",
-  "basedpyright>=1.20",
+  "pytest>=9.0",
+  "pytest-benchmark>=5.2",
+  "ruff>=0.15",
+  "basedpyright>=1.39",
 ]
 
 [build-system]

{sarj_python_lint-0.2.0 → sarj_python_lint-0.3.0}/src/sarj_python_lint/__init__.py

@@ -1,3 +1,3 @@
 """sarj-python-lint — custom Python + SQL lint rules."""
 
-__version__ = "0.1.4"
+__version__ = "0.2.0"

sarj_python_lint-0.3.0/src/sarj_python_lint/rules/__init__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from sarj_python_lint.rule_base import Rule
+from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
+    InefficientStringConcatInLoop,
+)
+from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
+from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
+from sarj_python_lint.rules.no_sentinel_return_on_except import NoSentinelReturnOnExcept
+from sarj_python_lint.rules.no_sequential_await import NoSequentialAwait
+from sarj_python_lint.rules.no_unreachable_after_terminal import (
+    NoUnreachableAfterTerminal,
+)
+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.pydantic_at_boundaries import PydanticAtBoundaries
+
+
+REGISTRY: dict[str, type[Rule]] = {
+    NoSequentialAwait.id: NoSequentialAwait,
+    InefficientStringConcatInLoop.id: InefficientStringConcatInLoop,
+    PreferDiscriminatedUnion.id: PreferDiscriminatedUnion,
+    PreferStrEnum.id: PreferStrEnum,
+    NoFatTryBlocks.id: NoFatTryBlocks,
+    PydanticAtBoundaries.id: PydanticAtBoundaries,
+    NoSentinelReturnOnExcept.id: NoSentinelReturnOnExcept,
+    NoUnreachableAfterTerminal.id: NoUnreachableAfterTerminal,
+    PreferConstantTimeSecretCompare.id: PreferConstantTimeSecretCompare,
+    NoSecretInLog.id: NoSecretInLog,
+}
+
+__all__ = ["REGISTRY"]

sarj_python_lint-0.3.0/src/sarj_python_lint/rules/no_fat_try_blocks.py

@@ -0,0 +1,82 @@
+"""SARJ007: `try` block whose body has more than 3 top-level statements.
+
+A fat `try` body obscures which statement is actually expected to raise and
+widens the blast radius of the `except` handlers: unrelated failures get
+caught (and often swallowed or mis-reported) by handlers written for a
+different operation. Keep the `try` skinny — isolate the throwing
+statement(s) and move the non-throwing setup and follow-up work outside.
+
+Only the top-level statements of the `try` body are counted; statements
+nested inside an `if` / `with` / loop within the body count as the single
+compound statement that contains them. Nested `try` blocks are checked
+independently. `try*` (PEP 654 except-groups) is held to the same limit.
+
+This is a direct Python port of the org's ESLint restriction
+`TryStatement > BlockStatement[body.length > 3]` in eslint.strict.mjs.
+
+Instead of:
+    try:
+        payload = build_payload(order)
+        response = client.send(payload)
+        record = parse(response)
+        store.save(record)
+    except HTTPError:
+        ...
+
+Prefer:
+    payload = build_payload(order)
+    try:
+        response = client.send(payload)
+    except HTTPError:
+        ...
+    record = parse(response)
+    store.save(record)
+
+References:
+- https://docs.python.org/3/tutorial/errors.html#handling-exceptions
+- https://docs.python.org/3/library/ast.html#ast.Try
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+_MAX_TRY_BODY_STATEMENTS = 3
+
+
+class NoFatTryBlocks(Rule):
+    """Try body longer than 3 statements — isolate the throwing statement(s)."""
+
+    id = "no-fat-try-blocks"
+    code = "SARJ007"
+    description = "Try block body exceeds 3 statements — keep try blocks skinny."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.Try, ast.TryStar)):
+                continue
+            if len(node.body) <= _MAX_TRY_BODY_STATEMENTS:
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        f"try block has {len(node.body)} statements "
+                        f"(max {_MAX_TRY_BODY_STATEMENTS}) — try blocks should "
+                        "isolate the throwing statement(s); move non-throwing "
+                        "work outside the try."
+                    ),
+                )
+            )
+        return diags

sarj_python_lint-0.3.0/src/sarj_python_lint/rules/no_secret_in_log.py

@@ -0,0 +1,116 @@
+"""SARJ012: detect secrets passed by keyword argument to a logging call.
+
+Logging a secret value (token, password, api key, jwt, credential, etc.) by
+keyword argument leaks it into log sinks — files, stdout, log aggregators —
+where it persists far beyond its intended lifetime and is readable by anyone
+with log access. Prefer redaction (`token_prefix=token[:6]`) or omission.
+
+We are deliberately precise: only the keyword-argument form
+(`logger.info("x", token=token)`) is flagged. F-strings are too noisy to detect
+reliably, so they're out of scope.
+
+References:
+- https://owasp.org/www-community/vulnerabilities/Information_exposure_through_log_files
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+# Logging method names (the `.attr` of the call's func).
+_LOG_METHODS = frozenset(
+    {"debug", "info", "warning", "warn", "error", "exception", "critical"}
+)
+
+# Names that look like a logger object. We're permissive on the object but
+# require it to plausibly be a logger to avoid flagging unrelated `.info(...)`
+# calls.
+_LOGGER_NAMES = frozenset({"logger", "log", "logging"})
+
+# A keyword name leaks a secret if it CONTAINS a secret word (so `AuthToken`,
+# `api_key`, `userPassword` all match) UNLESS it also carries a redaction marker
+# (`token_prefix`, `password_hash`, `secret_masked`) — those are the intended
+# safe forms, not the raw value.
+_SECRET_WORD_RE = re.compile(
+    r"token|secret|password|passwd|api_?key|jwt|credential|authorization",
+    re.IGNORECASE,
+)
+_REDACTION_RE = re.compile(
+    r"prefix|suffix|redact|mask|hash|hint|_len|length",
+    re.IGNORECASE,
+)
+
+
+def _is_secret_keyword(name: str) -> bool:
+    """True if the keyword name names a raw secret (not a redacted derivative)."""
+    if _REDACTION_RE.search(name):
+        return False
+    return _SECRET_WORD_RE.search(name) is not None
+
+
+class NoSecretInLog(Rule):
+    """Secret passed by keyword argument to a logging call."""
+
+    id = "no-secret-in-log"
+    code = "SARJ012"
+    description = "Secret passed by keyword to a logging call — redact or omit."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            if not _is_logging_call(node):
+                continue
+            for kw in node.keywords:
+                # `**kwargs` has arg=None — nothing to inspect.
+                if kw.arg is None:
+                    continue
+                if _is_secret_keyword(kw.arg):
+                    diags.append(
+                        Diagnostic(
+                            path=path,
+                            line=getattr(kw.value, "lineno", node.lineno),
+                            col=getattr(kw.value, "col_offset", node.col_offset) + 1,
+                            code=self.code,
+                            message=(
+                                f"Secret keyword `{kw.arg}` passed to a logging "
+                                "call leaks it to log sinks — redact "
+                                "(e.g. `token_prefix=token[:6]`) or omit it."
+                            ),
+                        )
+                    )
+        return diags
+
+
+def _is_logging_call(node: ast.Call) -> bool:
+    """Return True if `node` looks like `logger.<level>(...)`.
+
+    Precise on the method name (must be a known log level) and conservative on
+    the object: it must be a Name in {logger, log, logging} or an Attribute
+    ending in one of those (e.g. `self.logger`, `self.log`).
+    """
+    func = node.func
+    if not isinstance(func, ast.Attribute):
+        return False
+    if func.attr not in _LOG_METHODS:
+        return False
+    return _looks_like_logger(func.value)
+
+
+def _looks_like_logger(value: ast.AST) -> bool:
+    """Return True if `value` names a logger object (case-insensitively)."""
+    if isinstance(value, ast.Name):
+        return value.id.lower() in _LOGGER_NAMES
+    if isinstance(value, ast.Attribute):
+        # e.g. `self.logger`, `cls.log`
+        return value.attr.lower() in _LOGGER_NAMES
+    return False

sarj_python_lint-0.3.0/src/sarj_python_lint/rules/no_sentinel_return_on_except.py

@@ -0,0 +1,124 @@
+"""SARJ009: detect exception handlers that silently swallow via a sentinel return.
+
+An `except` block whose final statement is `return <sentinel>` (None, False,
+empty collection, empty string) and which never re-raises silently discards the
+error. Callers then can't distinguish "no result" from "something broke", which
+hides bugs and corrupts idempotency decisions.
+
+Prefer re-raising, or returning a typed result (e.g. a Result/Optional that the
+caller must explicitly handle).
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+
+class NoSentinelReturnOnExcept(Rule):
+    """Exception handler that swallows the error by returning a sentinel."""
+
+    id = "no-sentinel-return-on-except"
+    code = "SARJ009"
+    description = (
+        "`except` handler returns a sentinel and never re-raises — "
+        "the exception is silently swallowed."
+    )
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ExceptHandler):
+                continue
+            if not node.body:
+                continue
+            last = node.body[-1]
+            if not isinstance(last, ast.Return):
+                continue
+            # Bare `return` (value is None) is semantically `return None` — a
+            # sentinel. Only skip when there IS a value that isn't a sentinel.
+            if last.value is not None and not _is_sentinel(last.value):
+                continue
+            if _handler_reraises(node):
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=last.lineno,
+                    col=last.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "Exception is swallowed by returning a sentinel — "
+                        "re-raise, or return a typed result and handle it "
+                        "explicitly."
+                    ),
+                )
+            )
+        return diags
+
+
+def _is_sentinel(value: ast.expr) -> bool:
+    """True if `value` is a sentinel: None, False, empty collection/str, set()."""
+    if isinstance(value, ast.Constant):
+        # None, False, or empty string. Note: True / non-empty str / numbers
+        # are meaningful and must not be flagged.
+        if value.value is None or value.value is False:
+            return True
+        if isinstance(value.value, str) and value.value == "":
+            return True
+        return False
+    # Empty list / dict / set / tuple literals.
+    if isinstance(value, ast.List):
+        return len(value.elts) == 0
+    if isinstance(value, ast.Tuple):
+        return len(value.elts) == 0
+    if isinstance(value, ast.Set):
+        # `set()` is a call, not a Set node; `{}` is a Dict. A Set node always
+        # has at least one element, so it's never empty — but be explicit.
+        return len(value.elts) == 0
+    if isinstance(value, ast.Dict):
+        return len(value.keys) == 0
+    # `set()` call with no args.
+    if isinstance(value, ast.Call):
+        func = value.func
+        if (
+            isinstance(func, ast.Name)
+            and func.id == "set"
+            and not value.args
+            and not value.keywords
+        ):
+            return True
+        return False
+    return False
+
+
+def _handler_reraises(handler: ast.ExceptHandler) -> bool:
+    """True if the handler body contains a `raise`, ignoring nested functions.
+
+    A `raise` inside a nested def/lambda doesn't re-raise for *this* handler, so
+    we stop walking at function/lambda boundaries.
+    """
+    for stmt in handler.body:
+        if _contains_raise(stmt):
+            return True
+    return False
+
+
+def _contains_raise(node: ast.AST) -> bool:
+    """Walk `node`, returning True on a `raise`, but not crossing nested defs."""
+    # A `raise` inside a nested def/lambda doesn't re-raise for *this* handler,
+    # so a node that IS a function/lambda contributes no re-raise.
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+        return False
+    if isinstance(node, ast.Raise):
+        return True
+    for child in ast.iter_child_nodes(node):
+        if _contains_raise(child):
+            return True
+    return False

sarj_python_lint-0.3.0/src/sarj_python_lint/rules/no_unreachable_after_terminal.py

@@ -0,0 +1,75 @@
+"""SARJ010: detect unreachable code after a terminal statement.
+
+A terminal statement (`return`, `raise`, `break`, `continue`) ends control
+flow for the enclosing block. Any statement that immediately follows it in the
+same statement list can never execute — it is dead code, almost always a
+logic error (e.g. a `return` placed before cleanup, or a stray statement after
+a `break`).
+
+This is a pure structural check: for every statement-list field on every node
+(the `body`/`orelse`/`finalbody` lists of Module, FunctionDef, If, For, While,
+With, Try, ExceptHandler, etc.), if a terminal appears before the last element
+of that list, the statement immediately after it is unreachable.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import cast
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+# Statements that terminate control flow for their enclosing block.
+_TERMINALS = (ast.Return, ast.Raise, ast.Break, ast.Continue)
+
+# Fields on AST nodes that hold a list of statements (a block body).
+_BLOCK_FIELDS = ("body", "orelse", "finalbody")
+
+
+class NoUnreachableAfterTerminal(Rule):
+    """Code following a `return`/`raise`/`break`/`continue` is unreachable."""
+
+    id = "no-unreachable-after-terminal"
+    code = "SARJ010"
+    description = (
+        "Unreachable code after a terminal statement "
+        "(`return`/`raise`/`break`/`continue`)."
+    )
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            for field in _BLOCK_FIELDS:
+                raw = getattr(node, field, None)
+                if not isinstance(raw, list):
+                    continue
+                # `getattr` is untyped; the block fields (`body`/`orelse`/
+                # `finalbody`) only ever hold statements, so cast to a concrete
+                # element type to keep the `.lineno`/`.col_offset` access below
+                # well-typed under strict checking.
+                stmts = cast("list[ast.stmt]", raw)
+                # Find the first terminal that is not the last element; the
+                # statement immediately after it is unreachable.
+                for i in range(len(stmts) - 1):
+                    if isinstance(stmts[i], _TERMINALS):
+                        unreachable = stmts[i + 1]
+                        diags.append(
+                            Diagnostic(
+                                path=path,
+                                line=unreachable.lineno,
+                                col=unreachable.col_offset + 1,
+                                code=self.code,
+                                message=(
+                                    "Unreachable code — this statement follows a "
+                                    "`return`/`raise`/`break`/`continue` and can "
+                                    "never execute."
+                                ),
+                            )
+                        )
+                        break  # one diag per statement list (the first)
+        return diags

sarj_python_lint-0.3.0/src/sarj_python_lint/rules/prefer_constant_time_secret_compare.py

@@ -0,0 +1,95 @@
+"""SARJ011: detect `==`/`!=` comparisons on secret-like values.
+
+Comparing secrets (tokens, signatures, HMACs, password hashes, API keys) with
+`==`/`!=` is timing-attack-prone: short-circuiting on the first differing byte
+leaks information about how many leading bytes matched. Use
+`hmac.compare_digest(a, b)`, which compares in constant time.
+
+References:
+- https://docs.python.org/3/library/hmac.html#hmac.compare_digest
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+
+# Identifiers that look like secrets. Matched against Name.id / Attribute.attr.
+_SECRET_RE = re.compile(
+    r"token|secret|signature|api_?key|hmac|digest|password|passwd|hash",
+    re.IGNORECASE,
+)
+
+
+class PreferConstantTimeSecretCompare(Rule):
+    """Direct `==`/`!=` on a secret-like value — prefer hmac.compare_digest."""
+
+    id = "prefer-constant-time-secret-compare"
+    code = "SARJ011"
+    description = (
+        "Direct `==`/`!=` on a secret — prefer `hmac.compare_digest(a, b)`."
+    )
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            return []
+        diags: list[Diagnostic] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Compare):
+                continue
+            # Only single-operator comparisons using == or != (Eq/NotEq).
+            # Chained comparisons (a == b == c) and is/is not don't apply.
+            if len(node.ops) != 1:
+                continue
+            if not isinstance(node.ops[0], (ast.Eq, ast.NotEq)):
+                continue
+            operands = [node.left, *node.comparators]
+            # Skip presence checks: None/True/False, numbers, empty string "".
+            if any(_is_excluded_operand(op) for op in operands):
+                continue
+            if not any(_is_secret_operand(op) for op in operands):
+                continue
+            diags.append(
+                Diagnostic(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset + 1,
+                    code=self.code,
+                    message=(
+                        "Direct `==`/`!=` on a secret-like value is "
+                        "timing-attack-prone — prefer "
+                        "`hmac.compare_digest(a, b)`."
+                    ),
+                )
+            )
+        return diags
+
+
+def _is_secret_operand(node: ast.AST) -> bool:
+    """True if the operand's identifier matches the secret-name pattern."""
+    if isinstance(node, ast.Name):
+        return _SECRET_RE.search(node.id) is not None
+    if isinstance(node, ast.Attribute):
+        return _SECRET_RE.search(node.attr) is not None
+    return False
+
+
+def _is_excluded_operand(node: ast.AST) -> bool:
+    """True for presence/identity-style operands we never want to flag.
+
+    Covers `None`/`True`/`False`, numeric literals, and the empty string `""`.
+    """
+    if isinstance(node, ast.Constant):
+        value = node.value
+        if value is None or isinstance(value, bool):
+            return True
+        if isinstance(value, (int, float, complex)):
+            return True
+        if isinstance(value, str) and value == "":
+            return True
+    return False