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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.27.0
+Version: 0.29.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.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.27.0"
+version = "0.29.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.29.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.29.0}/src/sarj_python_lint/rules/_logging.py

@@ -12,7 +12,10 @@ import ast
 
 _LOGGER_NAMES = frozenset({"logger", "log", "logging", "loguru", "_logger", "_log"})
 
-_LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
+# Public: `no_fstring_in_log._chain_has_getlogger` must test the SAME set with
+# the SAME casing, or a factory can be a logger to one and not the other.
+LOGGER_FACTORIES = frozenset({"getlogger", "get_logger"})
+_LOGGER_FACTORIES = LOGGER_FACTORIES
 
 
 def is_logger_expr(expr: ast.expr) -> bool:

{sarj_python_lint-0.27.0 → sarj_python_lint-0.29.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.29.0/src/sarj_python_lint/rules/_suppression_comments.py

@@ -0,0 +1,59 @@
+"""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
+    ]

{sarj_python_lint-0.27.0 → sarj_python_lint-0.29.0}/src/sarj_python_lint/rules/no_fstring_in_log.py

@@ -76,7 +76,7 @@ from typing import TYPE_CHECKING, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 from sarj_python_lint.rules._ast_index import nodes
-from sarj_python_lint.rules._logging import is_logger_expr
+from sarj_python_lint.rules._logging import LOGGER_FACTORIES, is_logger_expr
 
 
 if TYPE_CHECKING:
@@ -102,6 +102,11 @@ _LOG_METHODS = frozenset(
 # Keyword arguments defined by stdlib `logging` (and never structured fields).
 # Their presence marks the call as a stdlib logger, for which the loguru-style
 # structured-keyword rewrite is wrong.
+# The stdlib factory spelling. `logging.getLogger` is camelCase; structlog uses
+# snake_case `get_logger`, and that difference is the only static signal telling
+# a dotted stdlib factory from a dotted structlog one.
+_STDLIB_FACTORY = "getLogger"
+
 _STDLIB_ONLY_KWARGS = frozenset({"exc_info", "stack_info", "extra"})
 
 
@@ -272,13 +277,45 @@ def _is_stdlib_logging_call(node: ast.Call, stdlib: _StdlibLoggers) -> bool:
 
 
 def _chain_has_getlogger(expr: ast.expr) -> bool:
+    """Report whether a stdlib `logging` factory appears anywhere in the receiver chain.
+
+    Matched against the SAME set and casing as `_logging.is_logger_expr`, and that
+    parity is load-bearing. When `is_logger_expr` learned to recognise a bare
+    `get_logger()` callee, this guard still tested the exact string `"getLogger"`,
+    so a snake_case factory returning a *stdlib* logger became a logger to the
+    rule but not a stdlib logger to the guard — and the rule then advised
+    `logger.info("msg", key=value)` on an API that rejects it.
+
+    That advice fails in the worst possible way: stdlib `Logger._log` raises
+    `TypeError: got an unexpected keyword argument`, but only when the call is
+    actually emitted, so the code is green at the default WARNING level and
+    breaks the moment log level is raised to INFO. The shim that triggers it —
+    `def get_logger(name): return logging.getLogger(name)` — ships in
+    huggingface_hub, transformers, fastmcp, mcp and speechmatics, all present in
+    consumer virtualenvs.
+
+    Returns:
+        True when the chain names a stdlib logging factory.
+
+    """
     node = expr
     while True:
         if isinstance(node, ast.Call):
             called = node.func
-            if isinstance(called, ast.Attribute) and called.attr == "getLogger":
+            # DOTTED callee: only the stdlib spelling counts. `structlog.get_logger()`
+            # must NOT be suppressed — structlog's keyword API is exactly what this
+            # rule's advice targets, and it is the rule's main true positive.
+            if isinstance(called, ast.Attribute) and called.attr == _STDLIB_FACTORY:
                 return True
-            if isinstance(called, ast.Name) and called.id == "getLogger":
+            # BARE callee: `get_logger()` and `getLogger()` are both ambiguous — the
+            # name alone cannot tell `from structlog import get_logger` from a shim
+            # `def get_logger(n): return logging.getLogger(n)`, and such shims ship in
+            # huggingface_hub, transformers, fastmcp, mcp and speechmatics. Suppress
+            # both, because the failure is asymmetric: a false NEGATIVE costs one
+            # style nit, while a false POSITIVE advises `logger.info("m", k=v)` on a
+            # stdlib logger, which raises `TypeError` — and only once log level is
+            # raised to INFO, so it is green in tests and breaks in production.
+            if isinstance(called, ast.Name) and called.id.lower() in LOGGER_FACTORIES:
                 return True
             node = called
         elif isinstance(node, ast.Attribute):

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()

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

@@ -1,343 +0,0 @@
-"""SARJ079: comprehensive Python pattern matching and match-assignment rule.
-
-Combines all pattern-matching and match-expression quality checks into a unified rule:
-
-1. Consecutive `case` arms with identical bodies -> merge into `case A() | B():`
-2. `case Cls():` arms reaching back for subject fields -> use pattern destructuring `case Cls(a=a, b=b):`
-3. Closed-set `match` dispatch with silent fallthrough `case _:` -> require `assert_never(...)`
-4. Regex match pre-assignment before `if` -> use assignment expression `if match := re.search(...):`
-
-Corpus evidence. Sweeping across 7 repositories (bulbul, noura-be, fastapi, pydantic, httpx, requests, rich)
-validates pattern matching best practices across 2,032 Python source files with 0 false positives.
-"""
-
-from __future__ import annotations
-
-import ast
-from typing import TYPE_CHECKING, override
-
-from sarj_python_lint.rule_base import Diagnostic, Rule, is_suppressed, parse_or_none
-from sarj_python_lint.rules._ast_index import nodes, walk
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-# --------------------------------------------------------------------------- #
-# Sub-check 1: Or-Patterns                                                    #
-# --------------------------------------------------------------------------- #
-
-_MIN_RUN = 2
-_MIN_ATTR_READS = 2
-_MIN_REAL_CASES = 2
-_EMPTY_BODY_NODES = (ast.Pass,)
-
-
-def _is_empty_body(body: list[ast.stmt]) -> bool:
-    if len(body) != 1:
-        return False
-    stmt = body[0]
-    return isinstance(stmt, _EMPTY_BODY_NODES) or (
-        isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Constant) and stmt.value.value is Ellipsis
-    )
-
-
-def _is_irrefutable(pattern: ast.pattern) -> bool:
-    return isinstance(pattern, ast.MatchAs) and pattern.pattern is None
-
-
-def _is_mergeable_arm(case: ast.match_case) -> bool:
-    if case.guard is not None:
-        return False
-    if _is_irrefutable(case.pattern):
-        return False
-    return not _is_empty_body(case.body)
-
-
-def _bound_names(pattern: ast.pattern) -> set[str]:
-    names: set[str] = set()
-
-    class BoundNameVisitor(ast.NodeVisitor):
-        def visit_MatchAs(self, node: ast.MatchAs) -> None:
-            if node.name:
-                names.add(node.name)
-            self.generic_visit(node)
-
-        def visit_MatchStar(self, node: ast.MatchStar) -> None:
-            if node.name:
-                names.add(node.name)
-            self.generic_visit(node)
-
-        def visit_MatchMapping(self, node: ast.MatchMapping) -> None:
-            if node.rest:
-                names.add(node.rest)
-            self.generic_visit(node)
-
-    BoundNameVisitor().visit(pattern)
-    return names
-
-
-def _nodes_equal(n1: ast.AST, n2: ast.AST) -> bool:
-    return ast.dump(n1) == ast.dump(n2)
-
-
-def _arms_merge(a: ast.match_case, b: ast.match_case) -> bool:
-    if _bound_names(a.pattern) != _bound_names(b.pattern):
-        return False
-    if len(a.body) != len(b.body):
-        return False
-    return all(map(_nodes_equal, a.body, b.body, strict=True))
-
-
-def _mergeable_runs(node: ast.Match) -> list[list[ast.match_case]]:
-    runs: list[list[ast.match_case]] = []
-    current: list[ast.match_case] = []
-    for case in node.cases:
-        if current and _is_mergeable_arm(case) and _arms_merge(current[-1], case):
-            current.append(case)
-            continue
-        if len(current) >= _MIN_RUN:
-            runs.append(current)
-        current = [case] if _is_mergeable_arm(case) else []
-    if len(current) >= _MIN_RUN:
-        runs.append(current)
-    return runs
-
-
-def _render_pattern(pattern: ast.pattern) -> str:
-    if isinstance(pattern, ast.MatchClass):
-        cls_name = ast.unparse(pattern.cls) if hasattr(ast, "unparse") else "Class"
-        return f"{cls_name}()"
-    if isinstance(pattern, ast.MatchValue):
-        return ast.unparse(pattern.value) if hasattr(ast, "unparse") else "Value"
-    return "pattern"
-
-
-# --------------------------------------------------------------------------- #
-# Sub-check 2: Pattern Destructuring                                          #
-# --------------------------------------------------------------------------- #
-
-
-def _check_destructuring(node: ast.Match, path: Path, source_lines: list[str], code: str) -> list[Diagnostic]:
-    diags: list[Diagnostic] = []
-    if not isinstance(node.subject, ast.Name):
-        return []
-    subject_name = node.subject.id
-
-    for case in node.cases:
-        if not isinstance(case.pattern, ast.MatchClass):
-            continue
-        if case.pattern.patterns or case.pattern.kwd_attrs:
-            continue
-
-        attr_reads: set[str] = set()
-        for b_node in case.body:
-            for subnode in walk(b_node):
-                if (
-                    isinstance(subnode, ast.Attribute)
-                    and isinstance(subnode.value, ast.Name)
-                    and subnode.value.id == subject_name
-                ):
-                    attr_reads.add(subnode.attr)
-
-        if len(attr_reads) >= _MIN_ATTR_READS:
-            line = case.pattern.lineno
-            col = case.pattern.col_offset + 1
-            if not is_suppressed(source_lines, line, code):
-                fields_str = ", ".join(sorted(attr_reads))
-                cls_name = _render_pattern(case.pattern)
-                diags.append(
-                    Diagnostic(
-                        path=path,
-                        line=line,
-                        col=col,
-                        code=code,
-                        message=(
-                            f"`case {cls_name}:` reads fields ({fields_str}) from subject `{subject_name}` — "
-                            f"use pattern destructuring `case {cls_name[:-2]}({fields_str}):` instead."
-                        ),
-                    )
-                )
-    return diags
-
-
-# --------------------------------------------------------------------------- #
-# Sub-check 3: Closed-set Assert Never                                        #
-# --------------------------------------------------------------------------- #
-
-
-def _check_assert_never(node: ast.Match, path: Path, source_lines: list[str], code: str) -> list[Diagnostic]:
-    diags: list[Diagnostic] = []
-    if not node.cases:
-        return []
-
-    last_case = node.cases[-1]
-    if not _is_irrefutable(last_case.pattern) or last_case.guard is not None:
-        return []
-
-    if _is_empty_body(last_case.body):
-        real_cases = node.cases[:-1]
-        if len(real_cases) >= _MIN_REAL_CASES and all(
-            isinstance(c.pattern, ast.MatchValue | ast.MatchClass) for c in real_cases
-        ):
-            line = last_case.pattern.lineno
-            col = last_case.pattern.col_offset + 1
-            if not is_suppressed(source_lines, line, code):
-                diags.append(
-                    Diagnostic(
-                        path=path,
-                        line=line,
-                        col=col,
-                        code=code,
-                        message=(
-                            "Closed-set `match` has a silent `case _:` fallthrough — "
-                            "use `assert_never(...)` to ensure exhaustiveness."
-                        ),
-                    )
-                )
-    return diags
-
-
-# --------------------------------------------------------------------------- #
-# Sub-check 4: Regex Walrus Match                                             #
-# --------------------------------------------------------------------------- #
-
-
-def _is_regex_call(node: ast.AST) -> bool:
-    if not isinstance(node, ast.Call):
-        return False
-    func = node.func
-    if isinstance(func, ast.Attribute):
-        if func.attr not in {"search", "match", "fullmatch", "finditer"}:
-            return False
-        if isinstance(func.value, ast.Name) and func.value.id in {"re", "regex", "pattern", "compiled_pattern"}:
-            return True
-        if isinstance(func.value, ast.Attribute) and func.value.attr in {"pattern", "regex", "_pattern"}:
-            return True
-    return False
-
-
-def _is_simple_truthy_test(test_node: ast.AST, var_name: str) -> bool:
-    if isinstance(test_node, ast.Name) and test_node.id == var_name:
-        return True
-    if (
-        isinstance(test_node, ast.Compare)
-        and isinstance(test_node.left, ast.Name)
-        and test_node.left.id == var_name
-        and len(test_node.ops) == 1
-        and isinstance(test_node.ops[0], ast.IsNot)
-    ):
-        right = test_node.comparators[0]
-        if isinstance(right, ast.Constant) and right.value is None:
-            return True
-    return False
-
-
-def _is_name_used_after(stmts: list[ast.stmt], start_idx: int, name: str) -> bool:
-    class UsageVisitor(ast.NodeVisitor):
-        used: bool = False
-
-        def visit_Name(self, node: ast.Name) -> None:
-            if node.id == name:
-                self.used = True
-            self.generic_visit(node)
-
-    visitor = UsageVisitor()
-    for st in stmts[start_idx:]:
-        visitor.visit(st)
-        if visitor.used:
-            return True
-    return False
-
-
-# --------------------------------------------------------------------------- #
-# Main Rule Class                                                             #
-# --------------------------------------------------------------------------- #
-
-
-class PreferPatternMatching(Rule):
-    """Unified Python pattern matching and regex assignment match rule."""
-
-    id: str = "prefer-pattern-matching"
-    code: str = "SARJ079"
-    description: str = (
-        "promote modern Python pattern matching idioms (or-patterns, destructuring, "
-        "exhaustiveness, and regex match assignments)."
-    )
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        tree = parse_or_none(path, source)
-        if tree is None:
-            return []
-
-        source_lines = source.splitlines()
-        diags: list[Diagnostic] = []
-
-        # The loop body does Match-specific work *and* a generic scan of every
-        # node that has a statement body, so it needs every node, in walk order.
-        for node in nodes(tree, ast.AST):
-            if isinstance(node, ast.Match):
-                for run in _mergeable_runs(node):
-                    p1 = _render_pattern(run[0].pattern)
-                    p2 = _render_pattern(run[1].pattern)
-                    line = run[0].pattern.lineno
-                    col = run[0].pattern.col_offset + 1
-                    if not is_suppressed(source_lines, line, self.code):
-                        diags.append(
-                            Diagnostic(
-                                path=path,
-                                line=line,
-                                col=col,
-                                code=self.code,
-                                message=(
-                                    f"{len(run)} consecutive `case` arms repeat an identical body — merge them "
-                                    f"into one or-pattern (`case {p1} | {p2}:`) so the shared handling is written once."
-                                ),
-                            )
-                        )
-                diags.extend(_check_destructuring(node, path, source_lines, self.code))
-                diags.extend(_check_assert_never(node, path, source_lines, self.code))
-
-            raw_body = getattr(node, "body", None)
-            if isinstance(raw_body, list):
-                body: list[ast.stmt] = [st for st in raw_body if isinstance(st, ast.stmt)]  # pyright: ignore[reportUnknownVariableType]
-                for i in range(len(body) - 1):
-                    s1 = body[i]
-                    s2 = body[i + 1]
-
-                    if not (
-                        isinstance(s1, ast.Assign) and len(s1.targets) == 1 and isinstance(s1.targets[0], ast.Name)
-                    ):
-                        continue
-                    var_name = s1.targets[0].id
-
-                    if not _is_regex_call(s1.value) or not isinstance(s2, ast.If):
-                        continue
-
-                    if not _is_simple_truthy_test(s2.test, var_name) or _is_name_used_after(body, i + 2, var_name):
-                        continue
-
-                    if not is_suppressed(source_lines, s1.lineno, self.code):
-                        diags.append(
-                            Diagnostic(
-                                path=path,
-                                line=s1.lineno,
-                                col=s1.col_offset + 1,
-                                code=self.code,
-                                message=(
-                                    f"Regex match pre-assignment `{var_name} = ...` before `if` — "
-                                    f"combine into `if ({var_name} := ...):`."
-                                ),
-                            )
-                        )
-
-        seen: set[tuple[int, int]] = set()
-        unique_diags: list[Diagnostic] = []
-        for d in diags:
-            if (d.line, d.col) not in seen:
-                seen.add((d.line, d.col))
-                unique_diags.append(d)
-
-        return sorted(unique_diags, key=lambda d: (d.line, d.col))

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

@@ -1,149 +0,0 @@
-"""SARJ075: Rename a Python module stem to match its primary public export.
-
-Semantic File Naming Rule:
-When a Python module has a single primary public export (a sole top-level `class`
-or `def`), its filename stem should semantically reflect that export's name in
-`snake_case`.
-
-Examples:
-  - File `user_data.py` containing sole `class UserAccountService:` -> rename to `user_account_service.py`.
-  - File `score_stuff.py` containing sole `def calculate_user_score():` -> rename to `calculate_user_score.py`.
-
-Exemptions (Corpus-validated against noura-be, bulbul, fastapi, requests, pydantic, flask, trio):
-  - Framework convention filenames (`models.py`, `views.py`, `urls.py`, `settings.py`, `config.py`, `errors.py`, `exceptions.py`, `admin.py`, `serializers.py`, `base.py`).
-  - Dunder & entrypoint files (`__init__.py`, `conftest.py`, `__main__.py`, `main.py`).
-  - Test and documentation paths (`test_*.py`, `*_test.py`, `docs/`, `docs_src/`, `examples/`, `tutorials/`).
-  - Private modules starting with `_` (`_signature.py`).
-  - Entrypoint functions (`main`, `run`, `cli`, `setup`, `teardown`, `execute`, `asyncio_detailed`, `sync_detailed`).
-  - Generated source files (`is_generated_source`).
-  - Modules with multiple public classes/functions or public `UPPER_SNAKE` constants.
-
-"""
-
-from __future__ import annotations
-
-import ast
-import re
-from typing import TYPE_CHECKING, override
-
-from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-_SKIPPED_FILENAMES = frozenset({"__init__.py", "conftest.py", "__main__.py", "main.py"})
-
-_FRAMEWORK_CONVENTION_FILENAMES = frozenset(
-    {
-        "models.py",
-        "admin.py",
-        "apps.py",
-        "views.py",
-        "urls.py",
-        "forms.py",
-        "serializers.py",
-        "base.py",
-        "settings.py",
-        "config.py",
-        "configuration.py",
-        "errors.py",
-        "exceptions.py",
-        "conftest.py",
-        "__main__.py",
-        "__init__.py",
-        "main.py",
-        "middleware.py",
-        "tasks.py",
-        "signals.py",
-        "routing.py",
-    }
-)
-
-_GENERIC_ENTRYPOINT_FUNCTIONS = frozenset(
-    {"main", "run", "cli", "setup", "teardown", "execute", "asyncio_detailed", "sync_detailed"}
-)
-
-_DOCS_OR_EXAMPLES_PATTERN = re.compile(r"[/\\](docs|docs_src|examples|tutorials|samples)[/\\]|tutorial\d*|example\d*")
-
-_ACRONYM_OVERRIDES: dict[str, str] = {"OAuth": "Oauth", "GraphQL": "Graphql", "gRPC": "Grpc"}
-_CAMEL_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
-
-
-def _snake_case(name: str) -> str:
-    for camel, replacement in _ACRONYM_OVERRIDES.items():
-        name = name.replace(camel, replacement)
-    return _CAMEL_BOUNDARY_RE.sub("_", name).lower()
-
-
-def _has_public_constant(tree: ast.Module) -> bool:
-    targets: list[ast.expr] = []
-    for stmt in tree.body:
-        match stmt:
-            case ast.Assign(targets=assigned):
-                targets.extend(assigned)
-            case ast.AnnAssign(target=target):
-                targets.append(target)
-            case _:
-                pass
-    return any(
-        isinstance(t, ast.Name) and not t.id.startswith("_") and t.id == t.id.upper() and any(c.isalpha() for c in t.id)
-        for t in targets
-    )
-
-
-class PrimaryExportFileName(Rule):
-    """Rename a Python module stem to match its sole primary public class/def export."""
-
-    id: str = "primary-export-file-name"
-    code: str = "SARJ075"
-    description: str = "A module with a single primary public export should be named after that export."
-
-    @override
-    def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if path.suffix not in {".py", ".pyi"}:
-            return []
-        if path.name in _SKIPPED_FILENAMES or path.name.lower() in _FRAMEWORK_CONVENTION_FILENAMES:
-            return []
-        if path.stem.startswith("_"):
-            return []
-        if is_test_path(path) or is_generated_source(source):
-            return []
-        if _DOCS_OR_EXAMPLES_PATTERN.search(str(path)):
-            return []
-
-        tree = parse_or_none(path, source)
-        if tree is None:
-            return []
-
-        public_defs = [
-            node
-            for node in tree.body
-            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)) and not node.name.startswith("_")
-        ]
-        if len(public_defs) != 1 or _has_public_constant(tree):
-            return []
-
-        primary = public_defs[0]
-        if primary.name in _GENERIC_ENTRYPOINT_FUNCTIONS:
-            return []
-
-        expected_stem = _snake_case(primary.name)
-        if path.stem == expected_stem:
-            return []
-
-        return [
-            Diagnostic(
-                path=path,
-                line=primary.lineno,
-                col=primary.col_offset + 1,
-                code=self.code,
-                message=(
-                    f"module stem `{path.stem}` does not match its primary public "
-                    f"export `{primary.name}` — rename the file to `{expected_stem}.py` to "
-                    f"describe its responsibility."
-                ),
-            )
-        ]