sarj-python-lint 0.35.0__tar.gz → 0.36.0__tar.gz

{sarj_python_lint-0.35.0 → sarj_python_lint-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.35.0
+Version: 0.36.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
@@ -137,12 +137,27 @@ SARJ050 flags none of them. The remedy deletes the section and keeps the
 summary, which was checked against the shipped strict config: ruff's D417 does
 not fire on a docstring with no parameter section.
 
-The sibling `Returns:` shape was measured and **rejected**: deleting a
-`Returns:` section makes DOC201 fire, so the only compliant remedy is deleting a
-docstring whose summary may be the valuable part. Two more were rejected on
-volume — property docstrings restating the property name and reST/epydoc type
-duplication (`:type x: int`, `:rtype:`) both measure **0** first-party findings
-outside generated code.
+Two more shapes were rejected on volume — property docstrings restating the
+property name and reST/epydoc type duplication (`:type x: int`, `:rtype:`) both
+measure **0** first-party findings outside generated code.
+
+### The `Returns:` half (0.36.0)
+
+```yaml
+    - id: sarj-docstring-returns-restate-signature  # SARJ087
+```
+
+`SARJ087` is the `Returns:` sibling of SARJ086, and it was **rejected once**:
+deleting a `Returns:` section used to make ruff's DOC201 fire, so the only
+compliant remedy was deleting the whole docstring. #164 then removed DOC201 from
+`ruff.strict.toml` as a rule that DEMANDS prose, and the premise expired — under
+the shipped config the section goes and the summary stays.
+
+756 findings over 33 OSS repos / 35,254 files; two seeded samples of 40 and 20
+read against source gave **~2%** false positives, the whole of which was one
+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).
 
 ### House conventions moved out of consumer repos (0.21.0)
 

{sarj_python_lint-0.35.0 → sarj_python_lint-0.36.0}/README.md

@@ -119,12 +119,27 @@ SARJ050 flags none of them. The remedy deletes the section and keeps the
 summary, which was checked against the shipped strict config: ruff's D417 does
 not fire on a docstring with no parameter section.
 
-The sibling `Returns:` shape was measured and **rejected**: deleting a
-`Returns:` section makes DOC201 fire, so the only compliant remedy is deleting a
-docstring whose summary may be the valuable part. Two more were rejected on
-volume — property docstrings restating the property name and reST/epydoc type
-duplication (`:type x: int`, `:rtype:`) both measure **0** first-party findings
-outside generated code.
+Two more shapes were rejected on volume — property docstrings restating the
+property name and reST/epydoc type duplication (`:type x: int`, `:rtype:`) both
+measure **0** first-party findings outside generated code.
+
+### The `Returns:` half (0.36.0)
+
+```yaml
+    - id: sarj-docstring-returns-restate-signature  # SARJ087
+```
+
+`SARJ087` is the `Returns:` sibling of SARJ086, and it was **rejected once**:
+deleting a `Returns:` section used to make ruff's DOC201 fire, so the only
+compliant remedy was deleting the whole docstring. #164 then removed DOC201 from
+`ruff.strict.toml` as a rule that DEMANDS prose, and the premise expired — under
+the shipped config the section goes and the summary stays.
+
+756 findings over 33 OSS repos / 35,254 files; two seeded samples of 40 and 20
+read against source gave **~2%** false positives, the whole of which was one
+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).
 
 ### House conventions moved out of consumer repos (0.21.0)
 

{sarj_python_lint-0.35.0 → sarj_python_lint-0.36.0}/pyproject.toml

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

{sarj_python_lint-0.35.0 → sarj_python_lint-0.36.0}/src/sarj_python_lint/rules/_registry.py

@@ -6,6 +6,9 @@ from sarj_python_lint.rules.conditional_assertion_in_test import ConditionalAsse
 from sarj_python_lint.rules.docstring_args_restate_signature import (
     DocstringArgsRestateSignature,
 )
+from sarj_python_lint.rules.docstring_returns_restate_signature import (
+    DocstringReturnsRestateSignature,
+)
 from sarj_python_lint.rules.duplicate_test_body import DuplicateTestBody
 from sarj_python_lint.rules.duplicated_override_docstring import (
     DuplicatedOverrideDocstring,
@@ -184,6 +187,7 @@ REGISTRY: dict[str, type[Rule]] = {
     DuplicatedOverrideDocstring.id: DuplicatedOverrideDocstring,
     RedundantClassDocstring.id: RedundantClassDocstring,
     DocstringArgsRestateSignature.id: DocstringArgsRestateSignature,
+    DocstringReturnsRestateSignature.id: DocstringReturnsRestateSignature,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.36.0/src/sarj_python_lint/rules/docstring_returns_restate_signature.py

@@ -0,0 +1,115 @@
+"""SARJ087 — A `Returns:` block that only re-spells the name and the return annotation.
+
+Examples: https://github.com/sarj-ai/standards/blob/main/packages/python/tests/rules/test_docstring_returns_restate_signature.py
+Evidence: https://github.com/sarj-ai/standards/blob/main/docs/rules/SARJ087.md
+"""
+
+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._ast_index import children
+from sarj_python_lint.rules._comments import is_protected
+from sarj_python_lint.rules._docstrings import (
+    PROMPT_DECORATOR_MARKERS,
+    VALUE_MARKER_RE,
+    decorator_markers,
+    restates,
+    sections,
+    signature_stems,
+)
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+_RETURN_SECTIONS = ("Returns", "Return", "Yields", "Yield")
+
+# Identity semantics: whether the value handed back is a FRESH object or the
+# receiver itself is the one fact `-> Self` and `-> Foo` cannot carry, and the
+# words that state it (`new`, `copy`, `same`) are stopwords for the restatement
+# tokenizer, so the block reads as pure ceremony without this.
+_IDENTITY_RE = re.compile(
+    r"\b(?:new|copy|copies|copied|clone[ds]?|fresh|same|itself|self|shallow|deep|"
+    r"in[- ]place|unchanged|original)\b",
+    re.IGNORECASE,
+)
+
+
+def _return_block(docstring: str) -> str | None:
+    found = sections(docstring)
+    for name in _RETURN_SECTIONS:
+        if name in found:
+            return found[name]
+    return None
+
+
+class DocstringReturnsRestateSignature(Rule):
+    id: str = "docstring-returns-restate-signature"
+    code: str = "SARJ087"
+    has_evidence: bool = True
+    description: str = (
+        "`Returns:` block adds nothing the name and the return annotation do not "
+        "already say — delete the section and keep the summary."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        if is_generated(path, source):
+            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)
+                self._walk(child, class_name, path, diags)
+            elif isinstance(child, ast.ClassDef):
+                self._walk(child, child.name, path, diags)
+            else:
+                self._walk(child, class_name, path, diags)
+
+    def _check_function(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        class_name: str | None,
+        path: Path,
+        diags: list[Diagnostic],
+    ) -> None:
+        docstring = ast.get_docstring(node, clean=True)
+        if not docstring:
+            return
+        block = _return_block(docstring)
+        if block is None:
+            return
+        if VALUE_MARKER_RE.search(block) or is_protected(block) or _IDENTITY_RE.search(block):
+            return
+        if decorator_markers(node) & PROMPT_DECORATOR_MARKERS:
+            return
+        stems = signature_stems(node, class_name)
+        # The whole-docstring case is SARJ050's; reporting it here too would
+        # make one deletion look like two findings.
+        if restates(docstring, stems):
+            return
+        if not restates(block, stems):
+            return
+        expr = node.body[0]
+        diags.append(
+            Diagnostic(
+                path=path,
+                line=expr.lineno,
+                col=expr.col_offset + 1,
+                code=self.code,
+                message=self.description,
+            )
+        )