sarj-python-lint 0.30.0__tar.gz → 0.32.0__tar.gz

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/PKG-INFO

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

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

sarj_python_lint-0.32.0/src/sarj_python_lint/rules/_paths.py

@@ -0,0 +1,173 @@
+"""Shared file-scope predicates for the file-scope-gated rules.
+
+A single definition of "is this a test file?" so the test-scoped rules
+(SARJ031 no-sleep-in-test-body, SARJ036 no-raw-sql-in-tests) and the rules
+that *exempt* tests (SARJ014 prefer-timedelta-for-durations, SARJ015
+prefer-struct-over-namedtuple, SARJ026 prefer-namedtuple-over-tuple-return,
+SARJ034 kwonly-same-type-params) never diverge on what counts as a test file.
+
+Also the single definition of "is this a generated file?" (SARJ016/034):
+generated code mirrors whatever its generator emits, so style rules cannot be
+acted on there.
+
+That definition is deliberately two-sided. `is_generated_source` reads the
+header, which works for protoc/`@generated` tooling but is useless for the
+generators that emit no banner at all. Measured on a checked-in
+openapi-python-client SDK: 240 generated modules, *zero* carrying a marker in
+their first five lines. `is_generated_path` covers those by looking at where
+the file sits instead of what it says. `is_generated` is the predicate rules
+should call — it is the union, and neither half alone is enough.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+import re
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_TEST_DIR_NAMES = frozenset({"tests", "test"})
+
+# `auto-?generated` misses "automatically generated", which is the phrase
+# @generated tooling, protoc and OpenAPI generators emit most often.
+_GENERATED_RE = re.compile(
+    r"auto(?:-|matically )?generated|generated by|do not edit|@generated",
+    re.IGNORECASE,
+)
+
+_GENERATED_HEADER_LINES = 5
+
+_GENERATED_DIR_NAMES = frozenset({"generated", "vendor", "vendored"})
+
+# A directory holding one of these is a code-generator root: the file is the
+# generator's own config or ignore list, and the emitted package is checked in
+# beneath it. Every entry is a filename published by a code generator —
+# OpenAPI Generator, swagger-codegen, openapi-python-client, buf, and
+# graphql-code-generator's `codegen.*` family. None is specific to any one
+# repository's layout.
+_CODEGEN_MARKER_NAMES = (
+    ".openapi-generator",
+    ".openapi-generator-ignore",
+    ".swagger-codegen-ignore",
+    "openapi-python-client.yml",
+    "openapi-python-client.yaml",
+    "codegen.yml",
+    "codegen.yaml",
+    "codegen.config.yml",
+    "codegen.config.yaml",
+    "buf.gen.yaml",
+    "buf.gen.yml",
+)
+
+# Ancestor walks stop at the repository root. Without this a file two levels
+# deep would stat every directory up to `/` looking for a marker.
+_REPO_ROOT_MARKERS = (".git",)
+
+# Guards against a pathological path (or a symlink loop) turning the ancestor
+# walk into an unbounded stat storm. No real source tree is this deep.
+_MAX_ANCESTOR_DEPTH = 40
+
+
+def is_generated_source(source: str) -> bool:
+    """Report whether `source` self-identifies as generated code.
+
+    Checks the first few lines for the conventional markers
+    ("autogenerated", "generated by", "do not edit").
+
+    Returns:
+        True when the file header carries a generated-code marker.
+
+    """
+    head = source.splitlines()[:_GENERATED_HEADER_LINES]
+    return any(_GENERATED_RE.search(line) for line in head)
+
+
+@cache
+def _is_codegen_root(directory: Path) -> bool:
+    """Report whether `directory` holds a code generator's config or ignore file.
+
+    Cached: a corpus run asks this of the same handful of directories once per
+    file, and the answer is a filesystem probe.
+
+    Returns:
+        True when the directory carries a generator marker file.
+
+    """
+    return any((directory / name).exists() for name in _CODEGEN_MARKER_NAMES)
+
+
+@cache
+def _is_repo_root(directory: Path) -> bool:
+    """Report whether `directory` is a repository root.
+
+    Returns:
+        True when the directory carries a repository marker (`.git`).
+
+    """
+    return any((directory / name).exists() for name in _REPO_ROOT_MARKERS)
+
+
+def is_generated_path(path: Path) -> bool:
+    """Report whether `path` sits in a tree of generated or vendored code.
+
+    Two signals, both about location rather than content:
+
+    * a `generated` / `vendor` / `vendored` directory anywhere in the path, and
+    * a code-generator root among the ancestors — a directory holding an
+      `.openapi-generator-ignore`, `codegen.config.yml` or similar.
+
+    The generator root itself stays linted: the config file's neighbours are
+    the hand-written driver script that invokes the generator, while the
+    emitted package is checked in one level down. Only the subtree below the
+    root is treated as generated.
+
+    Returns:
+        True when the file is machine-written output rather than source.
+
+    """
+    if any(part.lower() in _GENERATED_DIR_NAMES for part in path.parts):
+        return True
+    for depth, ancestor in enumerate(path.parents):
+        if depth >= _MAX_ANCESTOR_DEPTH:
+            break
+        # `depth == 0` is the file's own directory: a generator config sitting
+        # next to the file makes the file the generator, not its output.
+        if depth and _is_codegen_root(ancestor):
+            return True
+        if _is_repo_root(ancestor):
+            break
+    return False
+
+
+def is_generated(path: Path, source: str) -> bool:
+    """Report whether the file is generated, by either header or location.
+
+    The predicate every rule that exempts generated code should call. Checking
+    only the header misses banner-less generators; checking only the path
+    misses a generated file dropped into a hand-written tree.
+
+    Returns:
+        True when the file is machine-written output rather than source.
+
+    """
+    return is_generated_source(source) or is_generated_path(path)
+
+
+def is_test_path(path: Path) -> bool:
+    """Report whether `path` is a test file.
+
+    A test file is `conftest.py`, a `test_*.py` / `*_test.py` stem, or any file
+    under a `tests` / `test` directory segment.
+
+    Returns:
+        True when `path` belongs to the test tree.
+
+    """
+    name = path.name
+    if name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    return any(part in _TEST_DIR_NAMES for part in path.parts)

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/duplicate_test_body.py

@@ -182,7 +182,7 @@ Deliberately NOT flagged:
 * **short bodies.** A two-statement test is not evidence of copy-paste — call,
   assert, done, and any two tests of the same helper look alike. The 3-statement
   floor is what keeps the rule from firing on every well-factored unit suite,
-* **generated test modules** (`is_generated_source`) — a generator emitting N
+* **generated test modules** (`_paths.is_generated`) — a generator emitting N
   near-identical cases is the generator's business, and the fix would be
   overwritten on the next regeneration,
 * the **first** member of a group. The diagnostic goes on the copies and points
@@ -200,7 +200,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 children
 from sarj_python_lint.rules._comments import standalone_comments, trailing_comments
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -286,7 +286,7 @@ class DuplicateTestBody(Rule):
             by position.
 
         """
-        if not is_test_path(path) or is_generated_source(source):
+        if not is_test_path(path) or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/inefficient_string_concat_in_loop.py

@@ -34,7 +34,7 @@ References:
 - https://docs.python.org/3/library/stdtypes.html#str.join
 - https://wiki.python.org/moin/PythonSpeed/PerformanceTips
 
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -49,7 +49,7 @@ from typing import TYPE_CHECKING, TypeGuard, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 from sarj_python_lint.rules._ast_index import children, walk
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -66,7 +66,7 @@ class InefficientStringConcatInLoop(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         if "+" not in source or ("for " not in source and "while " not in source):
             return []

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/kwonly_same_type_params.py

@@ -42,7 +42,7 @@ Never flags — these signatures cannot or should not change:
   `black/scripts/diff_shades_gha_helper.py:167`),
 * test files (`_paths.is_test_path`) — test fakes and helpers mirror the
   signatures of the code under test and cannot unilaterally change them,
-* generated files (`_paths.is_generated_source`) — the signature mirrors
+* generated files (`_paths.is_generated`) — the signature mirrors
   whatever the generator emits (found via trio's `_generated_io_kqueue.py`),
 * functions whose name is referenced as a VALUE anywhere in the module
   (passed to a registry, returned, stored) — the signature is a callback
@@ -101,7 +101,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, walk
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -196,7 +196,7 @@ class KwonlySameTypeParams(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_test_path(path) or is_generated_source(source):
+        if is_test_path(path) or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/mock_without_spec.py

@@ -38,7 +38,9 @@ Deliberately NOT flagged:
 * `create_autospec(...)`, `mock.ANY`, `mock.sentinel`, `mock.call` — specced by
   construction or not doubles at all,
 * bare `Mock` referenced without being called (annotations, `isinstance`
-  checks) — only a construction can carry a spec argument.
+  checks) — only a construction can carry a spec argument,
+* a canned callable stub bound to an attribute (`receiver.method =
+  AsyncMock(return_value=...)`) — see exemption 4 below.
 
 The import-backed name check is the load-bearing false-positive guard. Test
 suites routinely define their own `Mock`-suffixed fakes (`MockVisionBankClient`,
@@ -92,6 +94,45 @@ of this rule reported 137 hits, of which 38 were false positives:
    constructions lexically inside an `ImportError`/`ModuleNotFoundError`
    handler.
 
+4. **A canned callable stub bound to an attribute (146 hits, 18.8%).** Measured
+   over the two first-party repos (bulbul + noura-be, 777 hits), the single
+   largest shape was `receiver.method = Mock(...)` — 283 hits, 36.4%. It is not
+   an unspecced *collaborator*; it replaces one callable on a receiver that
+   already exists, and the contract this rule protects belongs to that receiver.
+   Either the receiver carries `spec=` — in which case production's call through
+   a renamed attribute raises `AttributeError` off the specced parent and the
+   test fails loudly, which is exactly the rot this rule wants — or the receiver
+   is itself flagged here at its own construction, and reporting the leaf as
+   well says the same thing twice. Evidence:
+   `bulbul/python/agent/tests/conftest.py:167-170`, where
+   `backchanneler = mock.Mock(spec=Backchanneler)` is followed by
+   `backchanneler.start_audio = mock.AsyncMock()` / `.run = ...` / `.stop = ...`
+   — model spec discipline, and three findings; and
+   `bulbul/python/bulbul/tests/integrations/test_zoho_notifications_handler.py:86`
+   (`crm_service.get_record = mock.AsyncMock(return_value=record)`), where the
+   only thing the file reads off `crm_service.get_record` is
+   `assert_awaited_once_with`. `AsyncMock` dominates the shape (164 of 283)
+   because `Mock(spec=X)` children are not awaitable, so a specced double *must*
+   have its async methods stubbed this way to be usable at all.
+
+   The guard demands POSITIVE evidence of callability — a canned
+   `return_value=`/`side_effect=`, a mock-API read off the path
+   (`recv.method.assert_called_once_with(...)`), or an invocation — on top of
+   the absence of any domain-attribute read. Absence alone is not enough:
+   `agent/tests/test_for_call_settings.py:64` (`room.local_participant =
+   mock.Mock()`) is an object double this file never happens to walk, and it
+   stays flagged, as do the 60 namespace doubles the corpus does walk —
+   `test_for_call_settings.py:71,74,76` (`api.room` / `api.sip` / `api.egress`,
+   read back as `.delete_room`, `.create_sip_participant`,
+   `.start_room_composite_egress`) and `agent/tests/conftest.py:246-247`
+   (`job_context.api`, `job_context.api.sip`).
+
+   What this gives up is arity: `AsyncMock(spec=Store.get)` would reject a call
+   whose signature no longer matches, and the exempted stubs will not. That is
+   the narrower half of the defect, and it is the half `patch.object(mod,
+   "func")` still gets flagged for, since `autospec=True` is a one-word fix
+   there and there is no equivalent for a raw attribute assignment.
+
 The 99 survivors are true positives: unspecced `MagicMock()` doubles for real
 types (`black/tests/test_black.py:2933`, a `MagicMock()` standing in for `Path`
 and answering `.relative_to`/`.resolve`/`.is_dir`/`.is_file`), and
@@ -175,6 +216,11 @@ _MOCK_API_ATTRS = frozenset(
 # An import that failed leaves nothing importable to spec against.
 _IMPORT_FAILURES = frozenset({"ImportError", "ModuleNotFoundError"})
 
+# Keywords that canned-answer a *call*. You only say what a double returns, or
+# raises, when something is going to invoke it — so their presence is positive
+# evidence that the double stands in for one callable rather than an object.
+_CANNED_RESULT_KEYWORDS = frozenset({"return_value", "side_effect"})
+
 
 class MockWithoutSpec(Rule):
     """A `unittest.mock` double built with no `spec=` accepts any attribute."""
@@ -321,6 +367,9 @@ class _FileFacts:
         self.reads: dict[str, set[str]] = {}
         self.called: set[str] = set()
         self.import_fallbacks: set[ast.Call] = set()
+        self.attribute_target: dict[ast.Call, str] = {}
+        self.path_reads: dict[str, set[str]] = {}
+        self.path_calls: set[str] = set()
 
     @classmethod
     def from_tree(cls, tree: ast.Module) -> _FileFacts:
@@ -339,16 +388,39 @@ class _FileFacts:
             elif isinstance(node, ast.Attribute):
                 if isinstance(node.value, ast.Name):
                     found.reads.setdefault(node.value.id, set()).add(node.attr)
+                found._record_path_read(node)
             elif isinstance(node, ast.Call):
                 if isinstance(node.func, ast.Name):
                     found.called.add(node.func.id)
+                found._record_path_call(node)
             elif _catches_import_failure(node):
                 found.import_fallbacks.update(child for child in walk(node) if isinstance(child, ast.Call))
         return found
 
     def _bind(self, target: ast.expr | None, value: ast.expr | None) -> None:
-        if isinstance(target, ast.Name) and isinstance(value, ast.Call):
+        if not isinstance(value, ast.Call):
+            return
+        if isinstance(target, ast.Name):
             self.bound_name[value] = target.id
+        elif isinstance(target, ast.Attribute):
+            path = _dotted_path(target)
+            if path is not None:
+                self.attribute_target[value] = path
+
+    def _record_path_read(self, node: ast.Attribute) -> None:
+        # Load context only. `recv.method = Mock()` is a *store* through
+        # `recv.method`; counting it would make every stub look like a namespace
+        # double read back through its own name.
+        if not isinstance(node.ctx, ast.Load):
+            return
+        path = _dotted_path(node.value)
+        if path is not None:
+            self.path_reads.setdefault(path, set()).add(node.attr)
+
+    def _record_path_call(self, node: ast.Call) -> None:
+        path = _dotted_path(node.func)
+        if path is not None:
+            self.path_calls.add(path)
 
     def is_call_recorder(self, node: ast.Call) -> bool:
         """Report whether the double bound by `node` is only ever called and introspected.
@@ -368,6 +440,58 @@ class _FileFacts:
             return False
         return self.reads.get(name, set()) <= _MOCK_API_ATTRS
 
+    def is_method_stub(self, node: ast.Call) -> bool:
+        """Report whether `node` is a canned stub for one method of some receiver.
+
+        `receiver.method = AsyncMock(return_value=...)` replaces a single
+        callable, not an object. The contract this rule protects belongs to the
+        *receiver* — it is the receiver's construction that either carries
+        `spec=` or is itself flagged here — and a callable has no attribute
+        surface for `spec=` to fence. Two conditions must hold:
+
+        * nothing but the mock API is read back off the assigned path, so the
+          double is not standing in for an object the test walks, and
+        * something positively marks it as a callable — a canned
+          `return_value=`/`side_effect=`, an `assert_called*`-style read, or an
+          invocation of the path.
+
+        The second condition is what keeps `room.local_participant = Mock()`
+        flagged: absence of attribute reads is not evidence of callability, and
+        a namespace double that this file happens never to walk is exactly the
+        case `spec=` exists for.
+
+        Returns:
+            True when the double is a canned callable stub bound to an attribute.
+
+        """
+        path = self.attribute_target.get(node)
+        if path is None:
+            return False
+        seen = self.path_reads.get(path, set())
+        if not seen <= _MOCK_API_ATTRS:
+            return False
+        canned = any(kw.arg in _CANNED_RESULT_KEYWORDS for kw in node.keywords)
+        return canned or bool(seen) or path in self.path_calls
+
+
+def _dotted_path(expr: ast.expr) -> str | None:
+    """Render a pure `name.attr.attr` chain as a dotted string.
+
+    Returns:
+        The dotted path, or None when the chain is rooted in anything other than
+        a bare name (a subscript, a call, a literal), where two occurrences of
+        the same text need not denote the same object.
+
+    """
+    parts: list[str] = []
+    while isinstance(expr, ast.Attribute):
+        parts.append(expr.attr)
+        expr = expr.value
+    if not isinstance(expr, ast.Name):
+        return None
+    parts.append(expr.id)
+    return ".".join(reversed(parts))
+
 
 def _catches_import_failure(handler: ast.ExceptHandler) -> bool:
     caught = handler.type
@@ -386,7 +510,7 @@ def _unspecced_calls(tree: ast.Module, names: _MockNames, facts: _FileFacts) ->
         label = _render_callee(node.func, symbol)
         if _has_spec_argument(node) or _has_positional_replacement(node, label):
             continue
-        if node in facts.import_fallbacks or facts.is_call_recorder(node):
+        if node in facts.import_fallbacks or facts.is_call_recorder(node) or facts.is_method_stub(node):
             continue
         hits.append((node, label))
     return hits

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/no_comment_cruft.py

@@ -66,7 +66,7 @@ comments — `# type:`, `# noqa`, `# sarj-noqa`,
 coding declarations.
 
 Also NOT flagged (famous-repo sweep hardening):
-- generated files (`_paths.is_generated_source`) — their banners are the
+- generated files (`_paths.is_generated`) — their banners are the
   generator's warning header, not hand-written cruft;
 - a punctuation-only "banner" directly beneath a texty comment line — that is
   an RST-style heading underline or an ASCII-diagram row inside a prose comment
@@ -153,7 +153,7 @@ from sarj_python_lint.rules._comments import (
     nested_comment_lines,
     standalone_comments,
 )
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -683,7 +683,7 @@ class NoCommentCruft(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         # A Sphinx `docs/**/conf.py` is quickstart-generated boilerplate whose
         # `# -- Section ----` banners are the tool's own convention.

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/no_fat_try_blocks.py

@@ -69,7 +69,7 @@ References:
 - https://docs.python.org/3/tutorial/errors.html#handling-exceptions
 - https://docs.python.org/3/library/ast.html#ast.Try
 
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -86,7 +86,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 children, nodes
 from sarj_python_lint.rules._logging import is_logger_expr
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -330,7 +330,7 @@ class NoFatTryBlocks(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/no_gen_random_uuid_in_sql.py

@@ -56,7 +56,7 @@ from typing import TYPE_CHECKING, final, 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._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 from sarj_python_lint.rules._sql import strip_sql_noise
 
 
@@ -111,7 +111,7 @@ class NoGenRandomUuidInSql(Rule):
             The diagnostics, sorted by (line, col).
 
         """
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/no_repeated_string_literal.py

@@ -84,7 +84,7 @@ duplicate can be suppressed per-line with `# sarj-noqa: SARJ024 — <reason>`.
 
 Skipped entirely: `conftest.py`, test files (`test_*.py` or under a `tests/`
 directory) — fixtures legitimately repeat literal payloads.
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -100,7 +100,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 children, walk
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -130,7 +130,7 @@ class NoRepeatedStringLiteral(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         if _is_skipped_path(path):
             return []

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/no_restated_comment.py

@@ -105,7 +105,7 @@ from sarj_python_lint.rules._comments import (
     restates,
     standalone_comments,
 )
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -299,7 +299,7 @@ class NoRestatedComment(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         try:
             standalone, _ = standalone_comments(source)

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/no_stdlib_logging.py

@@ -62,7 +62,7 @@ from typing import TYPE_CHECKING, final, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
 from sarj_python_lint.rules._ast_index import nodes, walk
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -113,7 +113,7 @@ class NoStdlibLogging(Rule):
             The diagnostics, sorted by (line, col).
 
         """
-        if is_test_path(path) or _EXEMPT_DIR_NAMES.intersection(path.parts) or is_generated_source(source):
+        if is_test_path(path) or _EXEMPT_DIR_NAMES.intersection(path.parts) or is_generated(path, source):
             return []
         # Every diagnostic comes from an `import logging...` statement, which
         # cannot exist unless the module name is spelled in the text. Checking

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/prefer_fstring_over_concat.py

@@ -206,7 +206,7 @@ Deliberately NOT flagged:
   f-string" would restyle an injection instead of fixing it, and this rule must
   not become a competing SQL rule. The keyword match is case-SENSITIVE, so
   prose like `"copied from " + src` is not mistaken for a query. 7 hits,
-* **generated files** (`_paths.is_generated_source`). Re-running the generator
+* **generated files** (`_paths.is_generated`). Re-running the generator
   discards any edit, so a style finding there can never be acted on — the same
   exemption SARJ002 makes. 5 hits, all in bulbul's Speakeasy
   `python/sdk/src/sarj_platform_sdk/`.
@@ -229,7 +229,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, walk
 from sarj_python_lint.rules._logging import is_logger_expr
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -326,7 +326,7 @@ class PreferFstringOverConcat(Rule):
             One diagnostic per outermost offending concatenation, sorted by position.
 
         """
-        if "+" not in source or is_generated_source(source):
+        if "+" not in source or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/prefer_match_type_dispatch.py

@@ -27,6 +27,18 @@ Example refactoring:
         case dict():
             return parse_dict(data)
     return cast(..., data)
+
+## Not reported
+
+* **generated files** (`_paths.is_generated`). This is the exemption that
+  matters most for this rule: the try/raise idiom in the module summary above
+  is *transcribed from* openapi-python-client's `_parse_*` template, and it
+  reproduces once per nullable field. Before the path half of `is_generated`
+  existed, 314 of this rule's 334 findings over two first-party corpora came
+  from a single checked-in SDK — a tree the consuming repo already excludes
+  from ruff, from its pre-commit hook and from its CI invocation. The
+  generator's output is not a refactor anyone can accept; re-running the
+  generator would undo it. The 20 findings that remain are hand-written.
 """
 
 from __future__ import annotations
@@ -35,7 +47,7 @@ import ast
 from typing import TYPE_CHECKING, final, override
 
 from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -263,7 +275,7 @@ class PreferMatchTypeDispatch(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/prefer_module_level_constant.py

@@ -69,7 +69,7 @@ Deliberately NOT flagged:
   so they are reads, while `x.sort()` mutates in place and bails.
 * **Tiny displays** (`< _MIN_ELEMENTS` entries) read better next to their use.
 * **Test files and generated files** (`_paths.is_test_path` /
-  `_paths.is_generated_source`): fixture tables belong next to the assertion
+  `_paths.is_generated`): fixture tables belong next to the assertion
   that explains them, and generated code mirrors its generator.
 * **Bindings the function never reads** and **functions that call `locals()` /
   `vars()`**. Both are the same hole in the escape analysis: a local can leave
@@ -104,7 +104,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 children, nodes
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -194,7 +194,7 @@ class PreferModuleLevelConstant(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_test_path(path) or is_generated_source(source):
+        if is_test_path(path) or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/prefer_namedtuple_over_tuple_return.py

@@ -70,7 +70,7 @@ Suppress a deliberate positional return with `# sarj-noqa: SARJ026 — <reason>`
 References:
 - https://docs.python.org/3/library/typing.html#typing.NamedTuple
 
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -87,7 +87,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 children, nodes, walk
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -147,7 +147,7 @@ class PreferNamedtupleOverTupleReturn(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         if is_test_path(path):
             return []

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/prefer_non_nullable_collection.py

@@ -40,7 +40,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 walk
-from sarj_python_lint.rules._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -61,7 +61,7 @@ class PreferNonNullableCollection(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_test_path(path) or _is_generated_or_vendored_path(path) or is_generated_source(source):
+        if is_test_path(path) or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:
@@ -94,10 +94,6 @@ class PreferNonNullableCollection(Rule):
         return diags
 
 
-def _is_generated_or_vendored_path(path: Path) -> bool:
-    return any(part.lower() in {"generated", "vendor", "vendored"} for part in path.parts)
-
-
 def _qualified_name(node: ast.expr) -> str:
     if isinstance(node, ast.Name):
         return node.id

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/prefer_timedelta_for_durations.py

@@ -71,7 +71,7 @@ Suppress an intentional raw-numeric duration with `# sarj-noqa: SARJ014 — <rea
 References:
 - https://docs.python.org/3/library/datetime.html#timedelta-objects
 
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -87,7 +87,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._paths import is_generated_source, is_test_path
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -164,7 +164,7 @@ class PreferTimedeltaForDurations(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         if is_test_path(path):
             return []

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/redundant_docstring.py

@@ -55,7 +55,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 children
 from sarj_python_lint.rules._comments import is_protected, split_identifier, stem
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -239,7 +239,7 @@ class RedundantDocstring(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/require_port_for_service.py

@@ -266,7 +266,7 @@ 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
+from sarj_python_lint.rules._paths import is_generated, is_test_path
 
 
 if TYPE_CHECKING:
@@ -429,7 +429,7 @@ class RequirePortForService(Rule):
             One diagnostic per unsubstitutable service class, sorted by position.
 
         """
-        if not _is_library_source(path) or is_generated_source(source):
+        if not _is_library_source(path) or is_generated(path, source):
             return []
         tree = parse_or_none(path, source)
         if tree is None:

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/single_public_export.py

@@ -39,7 +39,7 @@ a `tests/` directory), and framework-convention filenames whose stem is fixed by
 a framework/tool and cannot be renamed (`models.py`, `views.py`, `base.py`, ...).
 Modules whose single export already snake-cases to the stem are not flagged
 (there is nothing to improve).
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -53,7 +53,7 @@ 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
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -134,7 +134,7 @@ class SinglePublicExport(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         if _is_skipped_path(path):
             return []

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/stepdown.py

@@ -58,7 +58,7 @@ Never fires on:
   `_code_str`). Siblings are excluded — an identically-named sibling method is a
   different method. Callers in classes outside the module remain invisible to
   syntactic analysis.
-* **generated files** (`_paths.is_generated_source`). Their layout is the
+* **generated files** (`_paths.is_generated`). Their layout is the
   generator's, and re-running the generator discards any edit, so a finding
   there can never be acted on in place. Measured on the 69 `DO NOT EDIT`
   files git-tracked across bulbul and noura-be — Speakeasy's
@@ -73,7 +73,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 children
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -112,7 +112,7 @@ class Stepdown(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         if _is_test_path(path):
             return []

{sarj_python_lint-0.30.0 → sarj_python_lint-0.32.0}/src/sarj_python_lint/rules/trailing_value_narration.py

@@ -69,7 +69,7 @@ from sarj_python_lint.rules._comments import (
     stem,
     trailing_comments,
 )
-from sarj_python_lint.rules._paths import is_generated_source
+from sarj_python_lint.rules._paths import is_generated
 
 
 if TYPE_CHECKING:
@@ -191,7 +191,7 @@ class TrailingValueNarration(Rule):
 
     @override
     def check(self, path: Path, source: str) -> list[Diagnostic]:
-        if is_generated_source(source):
+        if is_generated(path, source):
             return []
         try:
             trailing = trailing_comments(source)

sarj_python_lint-0.30.0/src/sarj_python_lint/rules/_paths.py

@@ -1,63 +0,0 @@
-"""Shared file-scope predicates for the file-scope-gated rules.
-
-A single definition of "is this a test file?" so the test-scoped rules
-(SARJ031 no-sleep-in-test-body, SARJ036 no-raw-sql-in-tests) and the rules
-that *exempt* tests (SARJ014 prefer-timedelta-for-durations, SARJ015
-prefer-struct-over-namedtuple, SARJ026 prefer-namedtuple-over-tuple-return,
-SARJ034 kwonly-same-type-params) never diverge on what counts as a test file.
-
-Also the single definition of "is this a generated file?" (SARJ016/034):
-generated code mirrors whatever its generator emits, so style rules cannot be
-acted on there.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import TYPE_CHECKING
-
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-_TEST_DIR_NAMES = frozenset({"tests", "test"})
-
-# `auto-?generated` misses "automatically generated", which is the phrase
-# @generated tooling, protoc and OpenAPI generators emit most often.
-_GENERATED_RE = re.compile(
-    r"auto(?:-|matically )?generated|generated by|do not edit|@generated",
-    re.IGNORECASE,
-)
-
-_GENERATED_HEADER_LINES = 5
-
-
-def is_generated_source(source: str) -> bool:
-    """Report whether `source` self-identifies as generated code.
-
-    Checks the first few lines for the conventional markers
-    ("autogenerated", "generated by", "do not edit").
-
-    Returns:
-        True when the file header carries a generated-code marker.
-
-    """
-    head = source.splitlines()[:_GENERATED_HEADER_LINES]
-    return any(_GENERATED_RE.search(line) for line in head)
-
-
-def is_test_path(path: Path) -> bool:
-    """Report whether `path` is a test file.
-
-    A test file is `conftest.py`, a `test_*.py` / `*_test.py` stem, or any file
-    under a `tests` / `test` directory segment.
-
-    Returns:
-        True when `path` belongs to the test tree.
-
-    """
-    name = path.name
-    if name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py"):
-        return True
-    return any(part in _TEST_DIR_NAMES for part in path.parts)