sarj-python-lint 0.38.0__tar.gz → 0.40.0__tar.gz

{sarj_python_lint-0.38.0 → sarj_python_lint-0.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.38.0
+Version: 0.40.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
@@ -159,6 +159,52 @@ family (`Returns: A new X` — whether the value is a copy is the one thing
 `-> Self` cannot say) now guarded. Three findings on this repo's own source, all
 true, all deleted. Measurements: [docs/rules/SARJ087.md](../../docs/rules/SARJ087.md).
 
+### Test ceremony, and the census it was chosen from (0.38.0)
+
+```yaml
+    - id: sarj-restated-test-docstring              # SARJ088
+    - id: sarj-test-phase-label-comment             # SARJ089
+```
+
+Every comment GROUP in 19 repositories / 45,900 Python files was collected with
+its adjacent code and classified: **451,482 groups, 1,293,022 lines**, of which
+the seven comment/docstring rules that predate this release reached **4.9%**.
+The full census table is in [docs/rules/SARJ088.md](../../docs/rules/SARJ088.md).
+
+The largest precisely-detectable class left in it is the **test docstring**:
+52,894 of them, 10.1% of every comment group, and SARJ050 reached 4.7%. It
+reached so few because SARJ050 measures a docstring against its *signature*, and
+a test's specification is its BODY. `SARJ088` measures it against the signature,
+the identifiers in the test's own body, and the vocabulary a test docstring
+spends on being a test. **5,382 findings; 98 read at source, 0 false positives
+on the shipped predicate.**
+
+`SARJ089` deletes the bare `# given` / `# when` / `# then` / `# Arrange` /
+`# Act` / `# Assert` phase label. 27,714 findings, 36 read, 0 false positives —
+but **94.5% come from one OSS suite**, and none from any first-party repo. It is
+a fence against the convention arriving, not a cleanup; adopt it behind the
+baseline ratchet.
+
+Shipped with them, `_docstrings.STOPWORDS` gained `FILLER_QUALIFIERS`: 31
+qualifiers that narrow nothing (`specific`, `appropriate`, `entire`, `overall`).
+One of these was the commonest single reason a pure restatement survived the
+whole family — `"""Get a specific account by ID."""` over
+`get_account(self, account_id: str)`. **+683 findings across SARJ050/085/086/087,
+-0; 58 of the delta read, ~3.4% false positives.** `main` was tried and rejected:
+as filler it makes `"""Main function."""` content-free, hence unflaggable.
+
+**Three shapes measured on the same census and rejected**, each on a seeded
+12-finding read at source:
+
+| shape | findings | true | why it fails |
+| --- | ---: | ---: | --- |
+| comment restates the `if` / `for` / `with` header below it | 225 | 3/12 | the population is BRANCH LABELS naming a case (`# PIL.Image` over `if isinstance(item, PILImage.Image)`), not narration |
+| comment restates a plain assignment (no call on the RHS) | 308 | 2/12 | the population heads a multi-line literal or a 3-statement block — a section label, which is SARJ016's subject |
+| multi-line comment run restating the block it heads | 119 | 1-2/12 | banners, Sphinx `#:` attribute docs, and worked calculations dominate |
+
+Those three are why SARJ049 still excludes block openers, plain assignments and
+multi-line runs. The exclusions are load-bearing, not unfinished work.
+
 ### House conventions moved out of consumer repos (0.21.0)
 
 ```yaml

{sarj_python_lint-0.38.0 → sarj_python_lint-0.40.0}/README.md

@@ -141,6 +141,52 @@ family (`Returns: A new X` — whether the value is a copy is the one thing
 `-> Self` cannot say) now guarded. Three findings on this repo's own source, all
 true, all deleted. Measurements: [docs/rules/SARJ087.md](../../docs/rules/SARJ087.md).
 
+### Test ceremony, and the census it was chosen from (0.38.0)
+
+```yaml
+    - id: sarj-restated-test-docstring              # SARJ088
+    - id: sarj-test-phase-label-comment             # SARJ089
+```
+
+Every comment GROUP in 19 repositories / 45,900 Python files was collected with
+its adjacent code and classified: **451,482 groups, 1,293,022 lines**, of which
+the seven comment/docstring rules that predate this release reached **4.9%**.
+The full census table is in [docs/rules/SARJ088.md](../../docs/rules/SARJ088.md).
+
+The largest precisely-detectable class left in it is the **test docstring**:
+52,894 of them, 10.1% of every comment group, and SARJ050 reached 4.7%. It
+reached so few because SARJ050 measures a docstring against its *signature*, and
+a test's specification is its BODY. `SARJ088` measures it against the signature,
+the identifiers in the test's own body, and the vocabulary a test docstring
+spends on being a test. **5,382 findings; 98 read at source, 0 false positives
+on the shipped predicate.**
+
+`SARJ089` deletes the bare `# given` / `# when` / `# then` / `# Arrange` /
+`# Act` / `# Assert` phase label. 27,714 findings, 36 read, 0 false positives —
+but **94.5% come from one OSS suite**, and none from any first-party repo. It is
+a fence against the convention arriving, not a cleanup; adopt it behind the
+baseline ratchet.
+
+Shipped with them, `_docstrings.STOPWORDS` gained `FILLER_QUALIFIERS`: 31
+qualifiers that narrow nothing (`specific`, `appropriate`, `entire`, `overall`).
+One of these was the commonest single reason a pure restatement survived the
+whole family — `"""Get a specific account by ID."""` over
+`get_account(self, account_id: str)`. **+683 findings across SARJ050/085/086/087,
+-0; 58 of the delta read, ~3.4% false positives.** `main` was tried and rejected:
+as filler it makes `"""Main function."""` content-free, hence unflaggable.
+
+**Three shapes measured on the same census and rejected**, each on a seeded
+12-finding read at source:
+
+| shape | findings | true | why it fails |
+| --- | ---: | ---: | --- |
+| comment restates the `if` / `for` / `with` header below it | 225 | 3/12 | the population is BRANCH LABELS naming a case (`# PIL.Image` over `if isinstance(item, PILImage.Image)`), not narration |
+| comment restates a plain assignment (no call on the RHS) | 308 | 2/12 | the population heads a multi-line literal or a 3-statement block — a section label, which is SARJ016's subject |
+| multi-line comment run restating the block it heads | 119 | 1-2/12 | banners, Sphinx `#:` attribute docs, and worked calculations dominate |
+
+Those three are why SARJ049 still excludes block openers, plain assignments and
+multi-line runs. The exclusions are load-bearing, not unfinished work.
+
 ### House conventions moved out of consumer repos (0.21.0)
 
 ```yaml

{sarj_python_lint-0.38.0 → sarj_python_lint-0.40.0}/pyproject.toml

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

{sarj_python_lint-0.38.0 → sarj_python_lint-0.40.0}/src/sarj_python_lint/rules/_docstrings.py

@@ -38,7 +38,7 @@ if TYPE_CHECKING:
 # Docstring filler that says nothing about *which* thing is being described.
 # `not` / `no` / `none` / `never` are deliberately ABSENT: a docstring that
 # negates the obvious reading of a name is the most useful kind there is.
-STOPWORDS = frozenset(
+_BASE_STOPWORDS = frozenset(
     {
         "a",
         "all",
@@ -107,6 +107,50 @@ STOPWORDS = frozenset(
     }
 )
 
+# Qualifiers that NARROW NOTHING. "a specific account", "the appropriate
+# config", "the entire widget" — strip the adjective and the sentence means
+# exactly what it meant. Kept as its own name because a single one of these
+# was the commonest reason a pure restatement survived the whole family; see
+# docs/rules/SARJ088.md for the measurement. `main`, `new`, `same` and `copy`
+# are NOT here: they name the thing or its identity, which is content.
+FILLER_QUALIFIERS = frozenset(
+    {
+        "actual",
+        "already",
+        "appropriate",
+        "associated",
+        "available",
+        "basic",
+        "correct",
+        "correctly",
+        "corresponding",
+        "default",
+        "desired",
+        "entire",
+        "existing",
+        "full",
+        "general",
+        "necessary",
+        "optional",
+        "overall",
+        "particular",
+        "properly",
+        "relevant",
+        "required",
+        "simple",
+        "single",
+        "specific",
+        "standard",
+        "successfully",
+        "suitable",
+        "supported",
+        "various",
+        "whole",
+    }
+)
+
+STOPWORDS = _BASE_STOPWORDS | FILLER_QUALIFIERS
+
 WORD_RE = re.compile(r"[A-Za-z][A-Za-z0-9']*")
 
 _IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")

{sarj_python_lint-0.38.0 → sarj_python_lint-0.40.0}/src/sarj_python_lint/rules/_registry.py

@@ -57,6 +57,7 @@ from sarj_python_lint.rules.no_unreachable_after_terminal import (
 )
 from sarj_python_lint.rules.over_mocked_test import OverMockedTest
 from sarj_python_lint.rules.parametrize_case_needs_id import ParametrizeCaseNeedsId
+from sarj_python_lint.rules.phase_label_comment import TestPhaseLabelComment
 from sarj_python_lint.rules.prefer_class_row import PreferClassRow
 from sarj_python_lint.rules.prefer_constant_time_secret_compare import (
     PreferConstantTimeSecretCompare,
@@ -94,6 +95,7 @@ from sarj_python_lint.rules.pydantic_at_boundaries import PydanticAtBoundaries
 from sarj_python_lint.rules.redundant_class_docstring import RedundantClassDocstring
 from sarj_python_lint.rules.redundant_docstring import RedundantDocstring
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
+from sarj_python_lint.rules.restated_test_docstring import RestatedTestDocstring
 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
@@ -186,6 +188,8 @@ REGISTRY: dict[str, type[Rule]] = {
     RedundantClassDocstring.id: RedundantClassDocstring,
     DocstringArgsRestateSignature.id: DocstringArgsRestateSignature,
     DocstringReturnsRestateSignature.id: DocstringReturnsRestateSignature,
+    RestatedTestDocstring.id: RestatedTestDocstring,
+    TestPhaseLabelComment.id: TestPhaseLabelComment,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.40.0/src/sarj_python_lint/rules/phase_label_comment.py

@@ -0,0 +1,57 @@
+"""SARJ089 — A bare Arrange/Act/Assert (or Given/When/Then) phase label in a test.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_phase_label_comment.py
+Evidence: https://github.com/sarj-ai/standards/blob/main/docs/rules/SARJ089.md
+"""
+
+from __future__ import annotations
+
+import re
+import tokenize
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule
+from sarj_python_lint.rules._comments import nested_comment_lines, standalone_comments
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# The phase vocabulary, as a whole-body match. `setup` and `teardown` are
+# deliberately ABSENT: SARJ016 already owns them through its section-label
+# vocabulary, and reporting one deletion twice makes the finding look bigger
+# than it is.
+_PHASE_RE = re.compile(
+    r"^(?:arrange|act|assert(?:ion)?s?|given|when|then|exercise|execute|verif(?:y|ication)|"
+    r"cleanup|prepare|sanity(?:\s+check)?|arrange\s*[/&+]\s*act|act\s*[/&+]\s*assert|"
+    r"given\s*[/&+]\s*when|when\s*[/&+]\s*then)"
+    r"\s*[.:;!\-–—]*\s*$",
+    re.IGNORECASE,
+)
+
+
+class TestPhaseLabelComment(Rule):
+    id: str = "test-phase-label-comment"
+    code: str = "SARJ089"
+    has_evidence: bool = True
+    description: str = (
+        "Bare test-phase label — delete it; a test whose phases need signposting "
+        "wants a named helper or a smaller test, not a comment."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated(path, source) or not is_test_path(path):
+            return []
+        try:
+            standalone, _ = standalone_comments(source)
+            nested = nested_comment_lines(source)
+        except tokenize.TokenError, IndentationError, SyntaxError:
+            return []
+        return [
+            Diagnostic(path=path, line=line, col=col + 1, code=self.code, message=self.description)
+            for line, col, body in standalone
+            if line not in nested and _PHASE_RE.match(body)
+        ]

sarj_python_lint-0.40.0/src/sarj_python_lint/rules/restated_test_docstring.py

@@ -0,0 +1,175 @@
+"""SARJ088 — A test docstring that only re-spells the test's own name and body.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_restated_test_docstring.py
+Evidence: https://github.com/sarj-ai/standards/blob/main/docs/rules/SARJ088.md
+"""
+
+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._ast_index import children
+from sarj_python_lint.rules._comments import is_protected, split_identifier, stem
+from sarj_python_lint.rules._docstrings import (
+    VALUE_MARKER_RE,
+    restates,
+    sections,
+    signature_stems,
+)
+from sarj_python_lint.rules._paths import is_generated, is_test_path
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# The vocabulary a test docstring spends on *being a test*. Folded into the
+# known-stem set rather than into `_docstrings.STOPWORDS`, so it widens this
+# rule alone and cannot silently move SARJ050/085/086/087.
+_TEST_CEREMONY = (
+    "assert", "asserted", "asserts", "behavior", "behaviour", "case", "cases", "check", "checked",
+    "checking", "checks", "confirm", "confirmed", "confirms", "correctly", "coverage", "covered", "covers",
+    "ensure", "ensured", "ensures", "ensuring", "exercise", "exercises", "expect", "expected", "expects",
+    "happy", "integration", "path", "properly", "regression", "scenario", "scenarios", "successful",
+    "successfully", "test", "tested", "testing", "tests", "unit", "validate", "validated", "validates",
+    "verified", "verifies", "verify", "verifying"
+)
+
+_CEREMONY_STEMS = frozenset(stem(word) for word in _TEST_CEREMONY)
+
+# Sections other than the summary are SARJ086/087's subject. A test docstring
+# carrying one is a different artefact and is left whole.
+_SUMMARY_ONLY = frozenset({"summary"})
+
+
+# The keyword singletons. `assert x is None` puts the word "None" on the screen
+# as surely as an identifier does, and `... is None` is the single most common
+# thing a test docstring re-spells.
+_SINGLETONS: dict[object, str] = {None: "none", True: "true", False: "false"}
+
+
+def _body_stems(node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    """Collect the stemmed word parts of every IDENTIFIER in the test body.
+
+    Identifiers and keyword singletons only — never string literals. A test body
+    is full of prose in strings ("user not found"), and letting those count as
+    "the code already says it" is what would turn an explanatory docstring into
+    a finding.
+
+    """
+    tokens: list[str] = []
+    for child in ast.walk(node):
+        match child:
+            case ast.Name():
+                tokens.extend(split_identifier(child.id))
+            case ast.Attribute():
+                tokens.extend(split_identifier(child.attr))
+            case ast.keyword() if child.arg is not None:
+                tokens.extend(split_identifier(child.arg))
+            case ast.arg():
+                tokens.extend(split_identifier(child.arg))
+            case ast.FunctionDef() | ast.AsyncFunctionDef() | ast.ClassDef():
+                tokens.extend(split_identifier(child.name))
+            case ast.Constant():
+                word = next((w for key, w in _SINGLETONS.items() if child.value is key), None)
+                if word is not None:
+                    tokens.append(word)
+            case _:
+                continue
+    return {stem(token) for token in tokens}
+
+
+def _is_test(node: ast.FunctionDef | ast.AsyncFunctionDef, class_name: str | None) -> bool:
+    if node.name.startswith("test_") or node.name == "test":
+        return True
+    return class_name is not None and class_name.startswith("Test") and node.name.startswith("test")
+
+
+class RestatedTestDocstring(Rule):
+    id: str = "restated-test-docstring"
+    code: str = "SARJ088"
+    has_evidence: bool = True
+    description: str = (
+        "Test docstring only re-spells the test's own name and body — delete it; "
+        "rename the test if the name does not already say it."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated(path, source) or not is_test_path(path):
+            return []
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        diags: list[Diagnostic] = []
+        self._walk(tree, None, path, diags)
+        return sorted(diags, key=lambda diag: diag.line)
+
+    def _walk(self, node: ast.AST, class_name: str | None, path: Path, diags: list[Diagnostic]) -> None:
+        for child in children(node):
+            if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef):
+                self._check_function(child, class_name, path, diags)
+            elif isinstance(child, ast.ClassDef):
+                self._check_class(child, path, diags)
+                self._walk(child, child.name, path, diags)
+            else:
+                self._walk(child, class_name, path, diags)
+
+    def _check_class(self, node: ast.ClassDef, path: Path, diags: list[Diagnostic]) -> None:
+        """Flag a `Test*` class whose docstring only re-spells its name and method names."""
+        if not node.name.startswith("Test") or node.bases or node.keywords:
+            return
+        docstring = ast.get_docstring(node, clean=True)
+        if not docstring or not self._is_plain_summary(docstring):
+            return
+        known = {stem(part) for part in split_identifier(node.name)} | _CEREMONY_STEMS
+        for child in node.body:
+            if isinstance(child, ast.FunctionDef | ast.AsyncFunctionDef):
+                known |= signature_stems(child, node.name)
+        if not restates(docstring, known):
+            return
+        expr = node.body[0]
+        diags.append(
+            Diagnostic(
+                path=path,
+                line=expr.lineno,
+                col=expr.col_offset + 1,
+                code=self.code,
+                message=self.description,
+            )
+        )
+
+    @staticmethod
+    def _is_plain_summary(docstring: str) -> bool:
+        """Report whether the docstring is a bare summary with nothing protected in it."""
+        if frozenset(sections(docstring)) != _SUMMARY_ONLY:
+            return False
+        return not is_protected(docstring) and not VALUE_MARKER_RE.search(docstring)
+
+    def _check_function(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        class_name: str | None,
+        path: Path,
+        diags: list[Diagnostic],
+    ) -> None:
+        if not _is_test(node, class_name):
+            return
+        docstring = ast.get_docstring(node, clean=True)
+        if not docstring or not self._is_plain_summary(docstring):
+            return
+        known = signature_stems(node, class_name) | _body_stems(node) | _CEREMONY_STEMS
+        if not restates(docstring, known):
+            return
+        expr = node.body[0]
+        diags.append(
+            Diagnostic(
+                path=path,
+                line=expr.lineno,
+                col=expr.col_offset + 1,
+                code=self.code,
+                message=self.description,
+            )
+        )

{sarj_python_lint-0.38.0 → sarj_python_lint-0.40.0}/src/sarj_python_lint/rules/zero_assertion_test.py

@@ -32,6 +32,56 @@ _RAISES_TOKEN_RE = re.compile(r"(^|_)(raises|warns|deprecated_call)", re.IGNOREC
 
 _RAISES_NAMES = frozenset({"raises", "warns", "fail"})
 
+# Library assertion helpers whose names contain none of the four tokens above.
+# The name heuristic is a good default and it has a blind spot: a widely used
+# assertion API is free to spell itself without the word "assert".
+#
+# MEASURED, 2026-07-31, over 39,893 content-deduplicated `.py` files: 4,386 of
+# this rule's 7,352 findings — 59.7% — were on test functions whose body calls
+# one of these, i.e. tests that assert perfectly well through a helper this rule
+# could not see. Three read at source (`test_run_without_stepwise`,
+# `test_repr_params_unknown_list`, `test_terminal_report_failedfirst`) are
+# assertion-complete; the flag was wrong in each.
+#
+# Two vocabularies, both exact names rather than a pattern, because the shapes
+# are too generic to match loosely:
+#
+#   * pytest's own `LineMatcher` (`_pytest.pytester`). `result.stdout
+#     .fnmatch_lines([...])` RAISES `Failed` on a mismatch — it is the canonical
+#     way to assert on CLI output, and any repo that tests a console script with
+#     the `pytester` fixture uses it. 438 findings.
+#   * `sqlalchemy.testing.assertions`, whose trailing underscore exists to dodge
+#     Python keywords (`is_`, `in_`). 3,948 findings.
+#
+# Kept as a closed set: a wildcard for "ends in an underscore" or "starts with
+# eq" would swallow unrelated user functions, and the whole point of this rule
+# is that a test which really does assert nothing stays flagged.
+_LIBRARY_ASSERTION_NAMES = frozenset({
+    # _pytest.pytester.LineMatcher
+    "fnmatch_lines",
+    "fnmatch_lines_random",
+    "no_fnmatch_line",
+    "no_re_match_line",
+    "re_match_lines",
+    "re_match_lines_random",
+    # sqlalchemy.testing.assertions
+    "eq_",
+    "eq_ignore_whitespace",
+    "eq_regex",
+    "in_",
+    "is_",
+    "is_false",
+    "is_instance_of",
+    "is_none",
+    "is_not",
+    "is_not_",
+    "is_not_none",
+    "is_true",
+    "ne_",
+    "not_in",
+    "not_in_",
+})
+
 _TEST_PREFIX = "test_"
 
 # Fluent verification DSLs reached through an attribute rather than a call name.
@@ -307,7 +357,9 @@ def _names_verification(func: ast.expr) -> bool:
 
 
 def _reads_as_verification(name: str) -> bool:
-    return bool(_ASSERTION_NAME_RE.search(name) or _RAISES_TOKEN_RE.search(name))
+    return name in _LIBRARY_ASSERTION_NAMES or bool(
+        _ASSERTION_NAME_RE.search(name) or _RAISES_TOKEN_RE.search(name)
+    )
 
 
 def _chain_has_fluent_marker(node: ast.expr) -> bool: