sarj-python-lint 0.13.1__tar.gz → 0.15.0__tar.gz

{sarj_python_lint-0.13.1 → sarj_python_lint-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.13.1
+Version: 0.15.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
@@ -42,6 +42,32 @@ uv tool install sarj-python-lint
     - id: sarj-no-fstring-in-log
 ```
 
+### Test-quality rules (0.15.0)
+
+Mined from an AST audit of ~7,500 test functions across two production repos.
+Every one is scoped to test files and carries the false-positive guard that made
+it shippable; the module docstring for each records the population it was
+measured against.
+
+```yaml
+    - id: sarj-mock-without-spec                   # SARJ040
+    - id: sarj-test-loops-over-literal-cases       # SARJ041
+    - id: sarj-parametrize-case-needs-id           # SARJ042
+    - id: sarj-zero-assertion-test                 # SARJ043
+    - id: sarj-fixture-returns-bare-tuple          # SARJ044
+    - id: sarj-kwarg-heavy-construction-in-test    # SARJ045
+    - id: sarj-xfail-requires-strict               # SARJ046
+    - id: sarj-sleep-with-computed-arg-in-test     # SARJ047
+```
+
+Adopting these against an existing suite is easier through the baseline ratchet
+than as a big-bang fix — snapshot the current counts, then let them only shrink:
+
+```bash
+sarj-python-lint check --rule mock-without-spec --update-baseline test-quality-baseline.json python/
+sarj-python-lint check --rule mock-without-spec --baseline test-quality-baseline.json python/
+```
+
 ## CLI
 
 ```bash

sarj_python_lint-0.15.0/README.md

@@ -0,0 +1,66 @@
+# sarj-python-lint
+
+Custom Python lint rules via stdlib `ast`. Designed for pre-commit. For SQL rules see [`sarj-sql-lint`](../sql/).
+
+```bash
+uv tool install sarj-python-lint
+```
+
+## Pre-commit
+
+```yaml
+- repo: https://github.com/sarj-ai/standards
+  rev: python-v0.2.0
+  hooks:
+    - id: sarj-no-sequential-await
+    - id: sarj-inefficient-string-concat-in-loop
+    - id: sarj-prefer-str-enum
+    - id: sarj-no-fat-try-blocks
+    - id: sarj-pydantic-at-boundaries
+    - id: sarj-prefer-class-row
+    - id: sarj-prefer-timedelta-for-durations
+    - id: sarj-prefer-struct-over-namedtuple
+    - id: sarj-no-comment-cruft
+    - id: sarj-no-fstring-in-log
+```
+
+### Test-quality rules (0.15.0)
+
+Mined from an AST audit of ~7,500 test functions across two production repos.
+Every one is scoped to test files and carries the false-positive guard that made
+it shippable; the module docstring for each records the population it was
+measured against.
+
+```yaml
+    - id: sarj-mock-without-spec                   # SARJ040
+    - id: sarj-test-loops-over-literal-cases       # SARJ041
+    - id: sarj-parametrize-case-needs-id           # SARJ042
+    - id: sarj-zero-assertion-test                 # SARJ043
+    - id: sarj-fixture-returns-bare-tuple          # SARJ044
+    - id: sarj-kwarg-heavy-construction-in-test    # SARJ045
+    - id: sarj-xfail-requires-strict               # SARJ046
+    - id: sarj-sleep-with-computed-arg-in-test     # SARJ047
+```
+
+Adopting these against an existing suite is easier through the baseline ratchet
+than as a big-bang fix — snapshot the current counts, then let them only shrink:
+
+```bash
+sarj-python-lint check --rule mock-without-spec --update-baseline test-quality-baseline.json python/
+sarj-python-lint check --rule mock-without-spec --baseline test-quality-baseline.json python/
+```
+
+## CLI
+
+```bash
+sarj-python-lint check --rule no-sequential-await path/to/file.py
+sarj-python-lint list-rules
+```
+
+Diagnostic format is `path:line:col: CODE message` — Ruff-compatible.
+
+## Suppression
+
+Inline `# sarj-noqa: SARJ00X — <reason>` on the offending line.
+
+Each rule's source under `src/sarj_python_lint/rules/` carries its own `description` and diagnostic message.

{sarj_python_lint-0.13.1 → sarj_python_lint-0.15.0}/pyproject.toml

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

{sarj_python_lint-0.13.1 → sarj_python_lint-0.15.0}/src/sarj_python_lint/rules/_registry.py

@@ -2,10 +2,13 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from sarj_python_lint.rules.fixture_returns_bare_tuple import FixtureReturnsBareTuple
 from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
 )
+from sarj_python_lint.rules.kwarg_heavy_construction_in_test import KwargHeavyConstructionInTest
 from sarj_python_lint.rules.kwonly_same_type_params import KwonlySameTypeParams
+from sarj_python_lint.rules.mock_without_spec import MockWithoutSpec
 from sarj_python_lint.rules.no_aggregation_in_store_query import (
     NoAggregationInStoreQuery,
 )
@@ -14,6 +17,7 @@ from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
     NoCorsWildcardWithCredentials,
 )
 from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
+from sarj_python_lint.rules.no_file_level_suppression import NoFileLevelSuppression
 from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
@@ -28,11 +32,15 @@ from sarj_python_lint.rules.no_sleep_in_test_body import NoSleepInTestBody
 from sarj_python_lint.rules.no_unreachable_after_terminal import (
     NoUnreachableAfterTerminal,
 )
+from sarj_python_lint.rules.parametrize_case_needs_id import ParametrizeCaseNeedsId
 from sarj_python_lint.rules.prefer_class_row import PreferClassRow
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
     PreferConstantTimeSecretCompare,
 )
 from sarj_python_lint.rules.prefer_match_assert_never import PreferMatchAssertNever
+from sarj_python_lint.rules.prefer_module_level_constant import (
+    PreferModuleLevelConstant,
+)
 from sarj_python_lint.rules.prefer_namedtuple_over_tuple_return import (
     PreferNamedtupleOverTupleReturn,
 )
@@ -45,10 +53,16 @@ from sarj_python_lint.rules.prefer_timedelta_for_durations import (
 )
 from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
 from sarj_python_lint.rules.single_public_export import SinglePublicExport
+from sarj_python_lint.rules.sleep_with_computed_arg_in_test import SleepWithComputedArgInTest
 from sarj_python_lint.rules.stepdown import Stepdown
 from sarj_python_lint.rules.store_insert_requires_on_conflict import (
     StoreInsertRequiresOnConflict,
 )
+from sarj_python_lint.rules.test_loops_over_literal_cases import (
+    TestLoopsOverLiteralCases,
+)
+from sarj_python_lint.rules.xfail_requires_strict import XfailRequiresStrict
+from sarj_python_lint.rules.zero_assertion_test import ZeroAssertionTest
 
 
 if TYPE_CHECKING:
@@ -92,6 +106,16 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferMatchAssertNever.id: PreferMatchAssertNever,
     KwonlySameTypeParams.id: KwonlySameTypeParams,
     NoRawSqlInTests.id: NoRawSqlInTests,
+    NoFileLevelSuppression.id: NoFileLevelSuppression,
+    PreferModuleLevelConstant.id: PreferModuleLevelConstant,
+    MockWithoutSpec.id: MockWithoutSpec,
+    TestLoopsOverLiteralCases.id: TestLoopsOverLiteralCases,
+    ParametrizeCaseNeedsId.id: ParametrizeCaseNeedsId,
+    FixtureReturnsBareTuple.id: FixtureReturnsBareTuple,
+    KwargHeavyConstructionInTest.id: KwargHeavyConstructionInTest,
+    XfailRequiresStrict.id: XfailRequiresStrict,
+    SleepWithComputedArgInTest.id: SleepWithComputedArgInTest,
+    ZeroAssertionTest.id: ZeroAssertionTest,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.15.0/src/sarj_python_lint/rules/fixture_returns_bare_tuple.py

@@ -0,0 +1,159 @@
+"""SARJ044: a fixture returning a bare tuple forces positional unpacking everywhere.
+
+`return org, user` makes every consumer write `org, user = setup_orgs()` and
+know the order by heart. Adding a third value silently shifts every call site's
+meaning rather than breaking it loudly, and a mis-ordered unpack
+(`user, org = ...`) type-checks fine and fails somewhere far away. A `NamedTuple`
+or a small frozen dataclass names the fields, so consumers destructure by name,
+new fields are additive, and the type checker catches a swap at the call site.
+
+This is the house rule the codebase already applies to production code, applied
+to fixtures. `CLAUDE.md` states it directly for ordinary functions — "No bare
+multi-field tuples across a boundary... a `NamedTuple`... never a positional
+`tuple[A, B]`" — and SARJ026 enforces it there. Fixtures were never covered,
+which is exactly why they drifted.
+
+Fires when ALL of these hold:
+
+* the file is a test file, and the function carries a `@pytest.fixture` or
+  `@pytest_asyncio.fixture` decorator (in any spelling: bare, called, or
+  attribute-qualified),
+* and the fixture's own body has a top-level `return`/`yield` of a **tuple
+  display** with at least two elements.
+
+The nearest-enclosing-function check (the SARJ031 technique) is what makes this
+safe: a factory fixture that returns a closure which itself returns a tuple is
+attributed to the closure, not the fixture, and does not fire. That pattern is
+common and legitimate — the tuple crosses the closure's boundary, not the
+fixture's.
+
+Deliberately NOT flagged:
+
+* a `NamedTuple`, dataclass, or any other constructor call — those are
+  `ast.Call` nodes, never `ast.Tuple`, so the correct alternative can never be
+  mistaken for the smell,
+* a single-element tuple — nothing to mis-order,
+* a starred tuple (`return *pair, extra`) — the arity is not statically known,
+* a tuple returned from a nested helper or closure inside the fixture.
+"""
+
+from __future__ import annotations
+
+import ast
+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_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_FIXTURE = "fixture"
+
+_MIN_FIELDS = 2
+
+_FUNC_NODES = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+class FixtureReturnsBareTuple(Rule):
+    """A fixture returning a bare tuple forces every consumer to unpack by position."""
+
+    id: str = "fixture-returns-bare-tuple"
+    code: str = "SARJ044"
+    description: str = (
+        "Fixture returns a bare multi-field tuple — return a NamedTuple so consumers destructure by name."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        """Flag pytest fixtures whose own body returns or yields a bare tuple.
+
+        Returns:
+            One diagnostic per bare-tuple return, sorted by position.
+
+        """
+        if not is_test_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        diags = [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=(
+                    f"this fixture hands back a bare {count}-field tuple, so every consumer unpacks it "
+                    "positionally and a reorder fails silently. Return a `NamedTuple` (or a frozen "
+                    "dataclass) so the fields are named."
+                ),
+            )
+            for node, count in _bare_tuple_results(tree)
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _bare_tuple_results(tree: ast.Module) -> list[tuple[ast.expr, int]]:
+    hits: list[tuple[ast.expr, int]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, _FUNC_NODES) or not _is_fixture(node):
+            continue
+        hits.extend(_tuple_results_of(node))
+    return hits
+
+
+def _is_fixture(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return any(_names_fixture(dec) for dec in node.decorator_list)
+
+
+def _names_fixture(dec: ast.expr) -> bool:
+    # `@pytest.fixture`, `@pytest.fixture(scope=...)`, `@fixture`, `@pytest_asyncio.fixture`.
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    if isinstance(target, ast.Attribute):
+        return target.attr == _FIXTURE
+    return isinstance(target, ast.Name) and target.id == _FIXTURE
+
+
+def _tuple_results_of(fixture: ast.FunctionDef | ast.AsyncFunctionDef) -> list[tuple[ast.expr, int]]:
+    found: list[tuple[ast.expr, int]] = []
+    for stmt in fixture.body:
+        found.extend(_scan_for_results(stmt))
+    return found
+
+
+def _scan_for_results(node: ast.AST) -> list[tuple[ast.expr, int]]:
+    # Descend through control flow but never into a nested function: a tuple
+    # returned by a closure the fixture builds crosses the closure's boundary,
+    # not the fixture's, so it is a different (and legitimate) shape.
+    if isinstance(node, (*_FUNC_NODES, ast.Lambda)):
+        return []
+    found: list[tuple[ast.expr, int]] = []
+    value = _returned_value(node)
+    if value is not None:
+        count = _bare_tuple_arity(value)
+        if count >= _MIN_FIELDS:
+            found.append((value, count))
+    for child in ast.iter_child_nodes(node):
+        found.extend(_scan_for_results(child))
+    return found
+
+
+def _returned_value(node: ast.AST) -> ast.expr | None:
+    if isinstance(node, ast.Return):
+        return node.value
+    if isinstance(node, ast.Expr) and isinstance(node.value, ast.Yield):
+        return node.value.value
+    return None
+
+
+def _bare_tuple_arity(value: ast.expr) -> int:
+    if not isinstance(value, ast.Tuple):
+        return 0
+    if any(isinstance(elt, ast.Starred) for elt in value.elts):
+        return 0
+    return len(value.elts)

sarj_python_lint-0.15.0/src/sarj_python_lint/rules/kwarg_heavy_construction_in_test.py

@@ -0,0 +1,144 @@
+"""SARJ045: a domain object built with many kwargs inline belongs in a builder.
+
+A test that constructs `SarjBeneficiary(id=..., name=..., iban=..., bank=...,
+status=..., created_at=..., updated_at=..., owner=..., currency=...)` in its own
+body states nine facts, and typically only one of them is the thing under test.
+The other eight are noise the reader must scan past to find the interesting
+field, and every one of them has to be revisited when the model gains a required
+column — across every test that spells the object out. A builder or factory with
+defaults collapses that to `build_beneficiary(status="frozen")`, which says what
+the test is about.
+
+Fires when ALL of these hold:
+
+* the file is a test file, and the **nearest enclosing function** of the call is
+  named `test_*`,
+* and the call passes more than eight keyword arguments.
+
+The nearest-enclosing-function guard is what makes this rule worth having rather
+than noise. A blind sweep of both corpora found 113 kwarg-heavy constructions,
+but 96 of them sit inside a module-level `_make_*`/`_build_*` helper — which is
+precisely the factory this rule asks for, already written. Counting those would
+have meant nagging at the well-factored code and rewarding the sloppy kind.
+Scoped to calls directly in a test body, the population drops to 17.
+
+The threshold is deliberately high. Eight keywords is well past the point where
+a constructor call is self-explanatory, and it was chosen so the rule fires only
+where the audited corpora showed a genuine builder was missing — in at least
+three cases (`digital-bank/banking-ai/chat/tests/test_chat_store.py`) the fix is
+a one-line import of a `build_sarj_beneficiary` helper that already exists in
+`common/testing/builders.py`.
+
+Deliberately NOT flagged:
+
+* calls inside a fixture, a `_make_*` helper, or any non-test function — that is
+  the factory, and it is allowed to be verbose exactly once,
+* positional arguments — a call with many positionals is a different smell, and
+  ruff's own rules already discourage it,
+* `dict(...)` and literal dict displays — those are data, not a domain object,
+  and naming their keys is the point rather than the problem.
+"""
+
+from __future__ import annotations
+
+import ast
+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_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_MAX_KEYWORDS = 8
+
+# `dict(a=1, b=2, ...)` is a mapping literal, not a domain object.
+_DATA_CALLABLES = frozenset({"dict"})
+
+
+class KwargHeavyConstructionInTest(Rule):
+    """A >8-keyword construction directly in a test body wants a builder."""
+
+    id: str = "kwarg-heavy-construction-in-test"
+    code: str = "SARJ045"
+    description: str = "Object built with many keywords inline in a test — extract a builder with defaults."
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        """Flag kwarg-heavy constructions sitting directly in a test body.
+
+        Returns:
+            One diagnostic per over-wide construction, sorted by position.
+
+        """
+        if not is_test_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+
+        visitor = _KwargHeavyVisitor()
+        visitor.visit(tree)
+        diags = [
+            Diagnostic(
+                path=path,
+                line=node.lineno,
+                col=node.col_offset + 1,
+                code=self.code,
+                message=(
+                    f"this call passes {count} keywords inline, so the one field under test is buried "
+                    "and every other test repeats the same boilerplate. Extract a builder with "
+                    "defaults and override only what this test is about."
+                ),
+            )
+            for node, count in visitor.hits
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+class _KwargHeavyVisitor(ast.NodeVisitor):
+    """Flag wide keyword calls whose nearest enclosing function is a test.
+
+    Mirrors SARJ031's enclosing-function stack so a construction inside a
+    `_make_*` helper or fixture declared anywhere in the file is attributed to
+    that helper — the factory is allowed to be verbose.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._func_names: list[str | None] = []
+        self.hits: list[tuple[ast.Call, int]] = []
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        self._func_names.append(node.name)
+        self.generic_visit(node)
+        self._func_names.pop()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_Lambda(self, node: ast.Lambda) -> None:
+        self._func_names.append(None)
+        self.generic_visit(node)
+        self._func_names.pop()
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if self._in_test_function() and not _is_data_callable(node.func):
+            named = [kw for kw in node.keywords if kw.arg is not None]
+            if len(named) > _MAX_KEYWORDS:
+                self.hits.append((node, len(named)))
+        self.generic_visit(node)
+
+    def _in_test_function(self) -> bool:
+        nearest = self._func_names[-1] if self._func_names else None
+        return nearest is not None and nearest.startswith("test_")
+
+
+def _is_data_callable(func: ast.expr) -> bool:
+    return isinstance(func, ast.Name) and func.id in _DATA_CALLABLES