sarj-python-lint 0.27.0__tar.gz → 0.28.0__tar.gz

{sarj_python_lint-0.27.0 → sarj_python_lint-0.28.0}/PKG-INFO

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

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

{sarj_python_lint-0.27.0 → sarj_python_lint-0.28.0}/src/sarj_python_lint/rules/_comments.py

@@ -397,7 +397,12 @@ def restates(comment_tokens: Sequence[str], code: Iterable[str]) -> bool:
 _LAYOUT_TOKENS = frozenset({tokenize.NL, tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT})
 _NON_CODE_TOKENS = _LAYOUT_TOKENS | frozenset({tokenize.COMMENT, tokenize.ENCODING, tokenize.ENDMARKER})
 
-_Scan = tuple[list[tuple[int, int, str]], list[tuple[int, int, str]], set[int], int]
+# `(line, col0, body, standalone)` for every comment, in source order. This is
+# what `_suppression_comments` needs, and it is a by-product of the pass below
+# rather than a reason to run a second one — see `all_comments`.
+_Ordered = list[tuple[int, int, str, bool]]
+
+_Scan = tuple[list[tuple[int, int, str]], list[tuple[int, int, str]], set[int], int, _Ordered]
 
 _last_scan: tuple[str, _Scan] | None = None
 
@@ -405,6 +410,7 @@ _last_scan: tuple[str, _Scan] | None = None
 def _scan(source: str) -> _Scan:
     standalone: list[tuple[int, int, str]] = []
     trailing: list[tuple[int, int, str]] = []
+    ordered: _Ordered = []
     nested: set[int] = set()
     first_code_line = 1 << 30
     prev_end_row = 0
@@ -412,8 +418,11 @@ def _scan(source: str) -> _Scan:
     readline = io.StringIO(source).readline
     for tok in tokenize.generate_tokens(readline):
         if tok.type == tokenize.COMMENT:
-            entry = (tok.start[0], tok.start[1], tok.string.lstrip("#").strip())
-            (trailing if tok.start[0] == prev_end_row else standalone).append(entry)
+            body = tok.string.lstrip("#").strip()
+            entry = (tok.start[0], tok.start[1], body)
+            is_standalone = tok.start[0] != prev_end_row
+            (standalone if is_standalone else trailing).append(entry)
+            ordered.append((tok.start[0], tok.start[1], body, is_standalone))
             if depth > 0:
                 nested.add(tok.start[0])
         elif tok.type == tokenize.OP:
@@ -425,7 +434,28 @@ def _scan(source: str) -> _Scan:
             prev_end_row = tok.end[0]
         if tok.type not in _NON_CODE_TOKENS:
             first_code_line = min(first_code_line, tok.start[0])
-    return standalone, trailing, nested, first_code_line
+    return standalone, trailing, nested, first_code_line, ordered
+
+
+def all_comments(source: str) -> tuple[_Ordered, int]:
+    """Return every comment as `(line, col0, body, standalone)`, plus the first code line.
+
+    Exists so the suppression rules (SARJ038/054) can share this module's
+    tokenize pass instead of running a second one. Both scanners computed the
+    same three facts — comment text, whether it stands alone on its line, and
+    where the first real code token is — from identical token-class sets, so the
+    second pass was pure duplicated work: SARJ038 alone spent ~4% of total rule
+    time on it.
+
+    `col0` is 0-based, matching this module's other accessors; the suppression
+    layer adds one for its 1-based `Comment.col`.
+
+    Returns:
+        The ordered comments and the first code line's row.
+
+    """
+    _, _, _, first_code_line, ordered = _scan_memo(source)
+    return ordered, first_code_line
 
 
 def _scan_memo(source: str) -> _Scan:
@@ -482,7 +512,7 @@ def standalone_comments(source: str) -> tuple[list[tuple[int, int, str]], int]:
         The standalone comments and the first code line's row.
 
     """
-    standalone, _, _, first_code_line = _scan_memo(source)
+    standalone, _, _, first_code_line, _ = _scan_memo(source)
     return standalone, first_code_line
 
 

{sarj_python_lint-0.27.0 → sarj_python_lint-0.28.0}/src/sarj_python_lint/rules/_registry.py

@@ -69,7 +69,6 @@ from sarj_python_lint.rules.prefer_non_nullable_collection import (
     PreferNonNullableCollection,
 )
 from sarj_python_lint.rules.prefer_or_pattern import PreferOrPattern
-from sarj_python_lint.rules.prefer_pattern_matching import PreferPatternMatching
 from sarj_python_lint.rules.prefer_real_store_in_tests import PreferRealStoreInTests
 from sarj_python_lint.rules.prefer_self_type_annotation import PreferSelfTypeAnnotation
 from sarj_python_lint.rules.prefer_str_enum import PreferStrEnum
@@ -84,9 +83,6 @@ from sarj_python_lint.rules.prefer_walrus_comprehension_filter import (
 )
 from sarj_python_lint.rules.prefer_walrus_regex_match import PreferWalrusRegexMatch
 from sarj_python_lint.rules.prefer_walrus_stream_loop import PreferWalrusStreamLoop
-from sarj_python_lint.rules.primary_export_file_name import (
-    PrimaryExportFileName,
-)
 from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
 from sarj_python_lint.rules.redundant_docstring import RedundantDocstring
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
@@ -173,11 +169,9 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferFstringOverConcat.id: PreferFstringOverConcat,
     PreferMatchPatternDestructuring.id: PreferMatchPatternDestructuring,
     PreferOrPattern.id: PreferOrPattern,
-    PreferPatternMatching.id: PreferPatternMatching,
     RequirePortForService.id: RequirePortForService,
     PreferNonNullableCollection.id: PreferNonNullableCollection,
     PreferMatchTypeDispatch.id: PreferMatchTypeDispatch,
-    PrimaryExportFileName.id: PrimaryExportFileName,
     PreferWalrusRegexMatch.id: PreferWalrusRegexMatch,
     PreferWalrusComprehensionFilter.id: PreferWalrusComprehensionFilter,
     PreferWalrusStreamLoop.id: PreferWalrusStreamLoop,

sarj_python_lint-0.28.0/src/sarj_python_lint/rules/_suppression_comments.py

@@ -0,0 +1,69 @@
+"""Shared comment tokenizer for the suppression-directive rules (SARJ038, SARJ054).
+
+Comments do not survive `ast.parse`, so any rule that judges a suppression
+*comment* has to lex the file. Both suppression rules need the same three facts
+about every comment — its text, whether it stands alone on its line, and whether
+it precedes the module's first statement — so they share one scanner rather than
+drifting apart on what "file-level" means.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sarj_python_lint.rules._comments import all_comments
+
+
+@dataclass(frozen=True, slots=True)
+class Comment:
+    """One comment token, with the context that decides whether it is file-level."""
+
+    line: int
+    col: int
+    body: str
+    standalone: bool
+    before_first_statement: bool = False
+
+
+def scan_comments(source: str) -> list[Comment]:
+    """Describe every comment in `source`, in source order.
+
+    A comment is standalone when no token ended on its line before it, and
+    precedes the first statement when it sits above the first non-comment,
+    non-layout token.
+
+    Anything `tokenize` cannot lex propagates as `tokenize.TokenError`,
+    `IndentationError` or `SyntaxError`; callers treat that as "no diagnostics".
+
+    Built from `_comments.all_comments`, which is the same tokenize pass the
+    comment-hygiene rules already run. This module used to lex the file a second
+    time to compute exactly the same three facts from identical token-class
+    sets, which cost SARJ038 ~4% of total rule time for no additional
+    information. The memo now lives in one place rather than two.
+
+    Returns:
+        Every comment, in source order. `Comment` is frozen and the list is
+        read-only to callers.
+
+    """
+    ordered, first_statement_line = all_comments(source)
+    return [
+        Comment(
+            line=line,
+            col=col + 1,
+            body=body,
+            standalone=standalone,
+            before_first_statement=line < first_statement_line,
+        )
+        for line, col, body, standalone in ordered
+    ]
+
+
+def comment_body(raw: str) -> str:
+    """Strip a comment token down to its directive text.
+
+    Returns:
+        The comment text without its leading `#` markers or surrounding space.
+
+    """
+    return raw.lstrip("#").strip()

{sarj_python_lint-0.27.0 → sarj_python_lint-0.28.0}/src/sarj_python_lint/rules/no_gen_random_uuid_in_sql.py

@@ -66,6 +66,11 @@ if TYPE_CHECKING:
 
 _GEN_RANDOM_UUID_RE = re.compile(r"\bgen_random_uuid\s*\(", re.IGNORECASE)
 
+# The whole-source gate in `check`. Deliberately weaker than the pattern above —
+# the identifier alone, no paren — so it cannot exclude a file whose masked SQL
+# would have matched. See the comment at its use site.
+_NAMES_GEN_RANDOM_UUID_RE = re.compile(r"gen_random_uuid", re.IGNORECASE)
+
 # A string only counts as SQL when it carries a structural keyword. Without this
 # the rule fires on prose that names the function — including this module's own
 # docstring.
@@ -111,6 +116,30 @@ class NoGenRandomUuidInSql(Rule):
             The diagnostics, sorted by (line, col).
 
         """
+        # Naming the function is a NECESSARY condition for any finding: the
+        # match runs against `strip_sql_noise(literal)`, and that only ever
+        # removes characters, so text absent from the file cannot appear in the
+        # masked literal. Checking the raw source first skips the parse and the
+        # per-literal SQL masking for the ~100% of files that never mention it.
+        #
+        # This rule is not store-gated and so masked every string literal in
+        # every file, which made it the worst cost-per-finding in the registry
+        # (2 findings across 21 corpora, at ~125 ms each). The gate removes that
+        # for no loss of coverage — verified by measuring the corpus before and
+        # after, not by inspection.
+        #
+        # The gate deliberately tests only the identifier, NOT the full
+        # `_GEN_RANDOM_UUID_RE`, which also requires the open paren. Masking can
+        # delete characters *between* the name and its paren — `gen_random_uuid
+        # /* c */ ()` masks to `gen_random_uuid ()` and matches — so gating on
+        # the stricter pattern would drop a finding the rule would otherwise
+        # report. A gate must be strictly weaker than the predicate it guards.
+        #
+        # It is case-insensitive for the same reason `_GEN_RANDOM_UUID_RE` is: a
+        # `DEFAULT GEN_RANDOM_UUID()` in upper-case SQL is a real finding, and a
+        # plain `"gen_random_uuid" in source` test would silently drop it.
+        if not _NAMES_GEN_RANDOM_UUID_RE.search(source):
+            return []
         if is_generated_source(source):
             return []
         tree = parse_or_none(path, source)

{sarj_python_lint-0.27.0 → sarj_python_lint-0.28.0}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -1,12 +1,38 @@
-"""SARJ080: prefer match/case over control-flow try/raise and sequential type guards.
+"""SARJ080: prefer match/case over sequential sentinel/type guards.
 
 Parsers and field deserializers often contain hideous type-dispatch idioms:
-sequential `if x is None: return x` / `if isinstance(x, Unset): return x` guards,
-followed by a `try` block containing `if not isinstance(x, T): raise TypeError()`
-to artificially jump control flow into an `except (TypeError, ...): pass` block.
-
-Raising an exception inside a `try` block solely to trigger that block's `except`
-handler is using `raise` as a goto (control flow via exceptions).
+sequential `if x is None: return x` / `if isinstance(x, Unset): return x` guards
+walking a value through one shape at a time, where a single `match` states the
+whole dispatch at once.
+
+DELIBERATELY NOT FLAGGED: `raise` inside a `try` block
+------------------------------------------------------
+
+This rule used to carry a second detector for the other half of that idiom —
+raising inside a `try` purely to jump into its own `except` handler, i.e. using
+`raise` as a goto. That detector was removed because ruff already reports it and
+our shipped config already enables it.
+
+`ruff.strict.toml` selects `ALL` and does not ignore `TRY`, so `TRY301`
+(`raise-within-try`, "Abstract `raise` to an inner function") is live in every
+consumer. Measured across 21 corpora, the removed arm produced 1,756 findings of
+which 1,649 (93.9%) sat on a line ruff already flagged, and construction
+confirms the columns match exactly, not merely the line:
+
+    try:
+        if not isinstance(x, str):
+            raise TypeError        # ruff TRY301 at 13:13, old SARJ080 at 13:13
+
+The 107 positions TRY301 structurally misses are `raise`s inside an `except`
+body caught by an *outer* `try`. That is a real gap, but not one worth 1,649
+double reports — and 5 of those positions already carry an explicit
+`# noqa: TRY301`, a decision the team made that a second code would quietly
+re-open.
+
+The surviving sequential-guard detector has NO ruff counterpart: the same sweep
+found 0 of its 476 positions shared with TRY301, and `RET505` is the closest
+thing ruff has, firing only on `elif`-after-`return` rather than on separate
+`if ...: return` statements.
 
 Preferred Python 3.10+ match/case patterns:
 - For `None`: `case None:`
@@ -42,59 +68,9 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 
-_GENERIC_EXCEPTIONS = frozenset({"Exception", "BaseException"})
 _MIN_SENTINEL_COUNT = 2
 
 
-def _get_caught_exception_names(handlers: list[ast.ExceptHandler]) -> set[str] | None:
-    """Extract caught exception class names.
-
-    Returns:
-        A set of exception class names, or None if a catch-all handler (bare `except:`) is present.
-
-    """
-    caught: set[str] = set()
-    for h in handlers:
-        if h.type is None:
-            return None
-        if isinstance(h.type, ast.Name):
-            caught.add(h.type.id)
-        elif isinstance(h.type, ast.Tuple):
-            for elt in h.type.elts:
-                if isinstance(elt, ast.Name):
-                    caught.add(elt.id)
-                elif isinstance(elt, ast.Attribute):
-                    caught.add(elt.attr)
-                    caught.add(ast.unparse(elt))
-        elif isinstance(h.type, ast.Attribute):
-            caught.add(h.type.attr)
-            caught.add(ast.unparse(h.type))
-    return caught
-
-
-def _raised_exception_name(raise_node: ast.Raise) -> str | None:
-    """Extract exception class name from `raise Exc()` or `raise Exc`.
-
-    Returns:
-        The exception class name, or None if no exception is specified.
-
-    """
-    exc = raise_node.exc
-    if exc is None:
-        return None
-    if isinstance(exc, ast.Call):
-        func = exc.func
-        if isinstance(func, ast.Name):
-            return func.id
-        if isinstance(func, ast.Attribute):
-            return func.attr
-    elif isinstance(exc, ast.Name):
-        return exc.id
-    elif isinstance(exc, ast.Attribute):
-        return exc.attr
-    return None
-
-
 def _guard_target_var_name(stmt: ast.stmt) -> str | None:
     """Extract target variable name if statement is `if x is None: return ...` or `if isinstance(x, ...): return ...`.
 
@@ -191,75 +167,25 @@ class _TypeDispatchVisitor(ast.NodeVisitor):
         self.path: Path = path
         self.code: str = code
         self.diags: list[Diagnostic] = []
-        self.try_stack: list[set[str] | None] = []
-
-    def visit_Try(self, node: ast.Try | ast.TryStar) -> None:
-        caught = _get_caught_exception_names(node.handlers)
-        self.try_stack.append(caught)
-        for stmt in node.body:
-            self.visit(stmt)
-        self.try_stack.pop()
-        for handler in node.handlers:
-            self.visit(handler)
-        for stmt in node.orelse:
-            self.visit(stmt)
-        for stmt in node.finalbody:
-            self.visit(stmt)
-
-    @override
-    def visit_TryStar(self, node: ast.TryStar) -> None:
-        self.visit_Try(node)
-
-    def visit_Raise(self, node: ast.Raise) -> None:
-        if self.try_stack:
-            exc_name = _raised_exception_name(node)
-            if exc_name is not None:
-                # Search outward through active try scopes
-                for caught in reversed(self.try_stack):
-                    is_caught = caught is None or exc_name in caught or bool(caught & _GENERIC_EXCEPTIONS)
-                    if is_caught:
-                        self.diags.append(
-                            Diagnostic(
-                                path=self.path,
-                                line=node.lineno,
-                                col=node.col_offset + 1,
-                                code=self.code,
-                                message=(
-                                    f"Control-flow raise in try block — 'raise {exc_name}()' "
-                                    f"jumps directly to local except handler. Refactor to 'match/case' "
-                                    f"(e.g., 'case str():') to handle types directly."
-                                ),
-                            )
-                        )
-                        break
-        self.generic_visit(node)
 
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         self.diags.extend(_check_sequential_type_guards(node, self.path, self.code))
-        saved_stack = self.try_stack
-        self.try_stack = []
         self.generic_visit(node)
-        self.try_stack = saved_stack
 
     def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
         self.diags.extend(_check_sequential_type_guards(node, self.path, self.code))
-        saved_stack = self.try_stack
-        self.try_stack = []
         self.generic_visit(node)
-        self.try_stack = saved_stack
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         self.generic_visit(node)
 
 
 class PreferMatchTypeDispatch(Rule):
-    """Prefer match/case over try/raise control flow and sequential type guards."""
+    """Prefer match/case over sequential sentinel/type guards."""
 
     id: str = "prefer-match-type-dispatch"
     code: str = "SARJ080"
-    description: str = (
-        "Control-flow raise in try block or sequential type guards — prefer Python 3.10+ match/case pattern matching."
-    )
+    description: str = "Sequential sentinel/type guards — prefer Python 3.10+ match/case pattern matching."
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:

sarj_python_lint-0.27.0/src/sarj_python_lint/rules/_suppression_comments.py

@@ -1,96 +0,0 @@
-"""Shared comment tokenizer for the suppression-directive rules (SARJ038, SARJ054).
-
-Comments do not survive `ast.parse`, so any rule that judges a suppression
-*comment* has to lex the file. Both suppression rules need the same three facts
-about every comment — its text, whether it stands alone on its line, and whether
-it precedes the module's first statement — so they share one scanner rather than
-drifting apart on what "file-level" means.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, replace
-import io
-import tokenize
-
-
-# Sentinel row for "this file has no statement at all" (empty / comments-only):
-# every comment then counts as preceding the first statement.
-_NO_STATEMENT_LINE = 1 << 30
-
-_LAYOUT_TOKENS = frozenset({tokenize.NL, tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT})
-_NON_STATEMENT_TOKENS = _LAYOUT_TOKENS | frozenset({tokenize.COMMENT, tokenize.ENCODING, tokenize.ENDMARKER})
-
-
-@dataclass(frozen=True, slots=True)
-class Comment:
-    """One comment token, with the context that decides whether it is file-level."""
-
-    line: int
-    col: int
-    body: str
-    standalone: bool
-    before_first_statement: bool = False
-
-
-_last_scan: tuple[str, list[Comment]] | None = None
-
-
-def scan_comments(source: str) -> list[Comment]:
-    """Tokenize `source` and describe every comment in it.
-
-    A comment is standalone when no token ended on its line before it, and
-    precedes the first statement when it sits above the first non-comment,
-    non-layout token.
-
-    Anything `tokenize` cannot lex propagates as `tokenize.TokenError`,
-    `IndentationError` or `SyntaxError`; callers treat that as "no diagnostics".
-
-    Memoized in a single slot, like `_comments._scan_memo` and
-    `rule_base.parse_or_none`: both suppression rules ask the same question about
-    the same file, and the CLI runs rules per file, so one slot removes the
-    second tokenize pass. `Comment` is frozen and the returned list is read-only
-    to callers.
-
-    Returns:
-        Every comment, in source order.
-
-    """
-    global _last_scan  # ruff: ignore[global-statement] — single-slot memo; the CLI runs rules per file sequentially
-    if _last_scan is not None and _last_scan[0] is source:
-        return _last_scan[1]
-    result = _scan(source)
-    _last_scan = (source, result)
-    return result
-
-
-def _scan(source: str) -> list[Comment]:
-    comments: list[Comment] = []
-    first_statement_line = _NO_STATEMENT_LINE
-    prev_end_row = 0
-    readline = io.StringIO(source).readline
-    for tok in tokenize.generate_tokens(readline):
-        if tok.type == tokenize.COMMENT:
-            comments.append(
-                Comment(
-                    line=tok.start[0],
-                    col=tok.start[1] + 1,
-                    body=comment_body(tok.string),
-                    standalone=tok.start[0] != prev_end_row,
-                )
-            )
-        if tok.type not in _LAYOUT_TOKENS:
-            prev_end_row = tok.end[0]
-        if tok.type not in _NON_STATEMENT_TOKENS:
-            first_statement_line = min(first_statement_line, tok.start[0])
-    return [replace(c, before_first_statement=c.line < first_statement_line) for c in comments]
-
-
-def comment_body(raw: str) -> str:
-    """Strip a comment token down to its directive text.
-
-    Returns:
-        The comment text without its leading `#` markers or surrounding space.
-
-    """
-    return raw.lstrip("#").strip()