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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.32.0
+Version: 0.33.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
@@ -102,6 +102,48 @@ each guard was built from are recorded in the rule module docstrings.
 `redundant-docstring` finds real volume on a codebase that has never had it
 (105 in noura-be), so the same baseline ratchet applies.
 
+### Docstring-ceremony rules (0.31.0)
+
+SARJ050 tests a *function* docstring against its *own signature*. That leaves
+three shapes it cannot reach, each now its own code so a consumer can baseline
+them separately:
+
+```yaml
+    - id: sarj-duplicated-override-docstring       # SARJ084
+    - id: sarj-redundant-class-docstring           # SARJ085
+    - id: sarj-docstring-args-restate-signature    # SARJ086
+```
+
+`SARJ084` flags an override whose docstring is **byte-identical** to the base
+method's, with the base resolved by undotted name inside the same file. There is
+no judgement call — the test is byte equality — and `inspect.getdoc`, `help()`,
+Sphinx and editor hovers all walk the MRO, so deleting the copy changes nothing
+a reader sees. 49 first-party findings, 49 true positives; 137 across 14 OSS
+repos, 18 sampled and read, 0 false positives.
+
+`SARJ085` flags a class docstring that only re-spells the class name — the case
+SARJ050's walker structurally never inspects. Its largest guard is that anything
+whose docstring becomes a **published schema description** (pydantic models,
+enums, `TypedDict`s, `@strawberry.type`) is exempt: that string is emitted as
+the JSON-Schema `description` and reaches OpenAPI documents and LLM tool
+schemas. The exemption costs 28 of 34 first-party findings and is not
+negotiable.
+
+`SARJ086` flags an `Args:` block whose every entry only re-spells its own
+parameter. It fires where SARJ050 cannot: the header word "args" is a content
+word no signature contains, so *any* `Args:` block makes a docstring
+permanently unflaggable by SARJ050 — 126 first-party functions carry one and
+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.
+
 ### House conventions moved out of consumer repos (0.21.0)
 
 ```yaml

{sarj_python_lint-0.32.0 → sarj_python_lint-0.33.0}/README.md

@@ -84,6 +84,48 @@ each guard was built from are recorded in the rule module docstrings.
 `redundant-docstring` finds real volume on a codebase that has never had it
 (105 in noura-be), so the same baseline ratchet applies.
 
+### Docstring-ceremony rules (0.31.0)
+
+SARJ050 tests a *function* docstring against its *own signature*. That leaves
+three shapes it cannot reach, each now its own code so a consumer can baseline
+them separately:
+
+```yaml
+    - id: sarj-duplicated-override-docstring       # SARJ084
+    - id: sarj-redundant-class-docstring           # SARJ085
+    - id: sarj-docstring-args-restate-signature    # SARJ086
+```
+
+`SARJ084` flags an override whose docstring is **byte-identical** to the base
+method's, with the base resolved by undotted name inside the same file. There is
+no judgement call — the test is byte equality — and `inspect.getdoc`, `help()`,
+Sphinx and editor hovers all walk the MRO, so deleting the copy changes nothing
+a reader sees. 49 first-party findings, 49 true positives; 137 across 14 OSS
+repos, 18 sampled and read, 0 false positives.
+
+`SARJ085` flags a class docstring that only re-spells the class name — the case
+SARJ050's walker structurally never inspects. Its largest guard is that anything
+whose docstring becomes a **published schema description** (pydantic models,
+enums, `TypedDict`s, `@strawberry.type`) is exempt: that string is emitted as
+the JSON-Schema `description` and reaches OpenAPI documents and LLM tool
+schemas. The exemption costs 28 of 34 first-party findings and is not
+negotiable.
+
+`SARJ086` flags an `Args:` block whose every entry only re-spells its own
+parameter. It fires where SARJ050 cannot: the header word "args" is a content
+word no signature contains, so *any* `Args:` block makes a docstring
+permanently unflaggable by SARJ050 — 126 first-party functions carry one and
+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.
+
 ### House conventions moved out of consumer repos (0.21.0)
 
 ```yaml

{sarj_python_lint-0.32.0 → sarj_python_lint-0.33.0}/pyproject.toml

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

sarj_python_lint-0.33.0/src/sarj_python_lint/rules/_docstrings.py

@@ -0,0 +1,317 @@
+"""Shared docstring analysis for the docstring-ceremony rules (SARJ050/084/085/086).
+
+Four rules ask overlapping questions about a docstring — "does this text say
+anything the signature does not?", "which decorators make this docstring an
+artefact someone else reads?", "where does the `Args:` block start?" — and the
+answers have to be identical across all four or the family contradicts itself.
+SARJ050 owned all of this privately until SARJ084-086 needed the same
+judgements; the definitions moved here unchanged rather than being copied.
+
+**`restates` is a DELETION test, not a value test.** It answers only "every
+content word of this text already appears in that identifier set". A False
+result means the text carries a word the signature does not — that is all. It
+must never be read as "this docstring is worthless"; the guards in each rule,
+plus `_comments.is_protected`, are what turn a restatement into a finding.
+
+**Section parsing is Google-style only.** `Args:` / `Returns:` / `Raises:` on
+their own line. NumPy style (`Parameters` followed by a `-----` underline) is
+deliberately not parsed: across 2,440 reviewable first-party files the corpus
+holds **2** NumPy docstrings, which is far too little evidence to tune a second
+parser against, and a half-recognised section is worse than an unrecognised one
+— it would let a rule read a `Parameters` heading as prose and judge the block
+on it.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING
+
+from sarj_python_lint.rules._comments import split_identifier, stem
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+# 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(
+    {
+        "a",
+        "all",
+        "an",
+        "and",
+        "are",
+        "as",
+        "at",
+        "based",
+        "be",
+        "been",
+        "being",
+        "by",
+        "class",
+        "current",
+        "do",
+        "does",
+        "false",
+        "for",
+        "from",
+        "function",
+        "get",
+        "gets",
+        "given",
+        "helper",
+        "if",
+        "in",
+        "instance",
+        "instances",
+        "into",
+        "is",
+        "it",
+        "its",
+        "method",
+        "new",
+        "object",
+        "objects",
+        "of",
+        "on",
+        "or",
+        "provided",
+        "return",
+        "returned",
+        "returns",
+        "s",
+        "set",
+        "sets",
+        "should",
+        "specified",
+        "that",
+        "the",
+        "these",
+        "this",
+        "those",
+        "to",
+        "true",
+        "using",
+        "value",
+        "values",
+        "was",
+        "when",
+        "whether",
+        "which",
+        "will",
+        "with",
+    }
+)
+
+WORD_RE = re.compile(r"[A-Za-z][A-Za-z0-9']*")
+
+_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+# Content the signature cannot carry, so the docstring is earning its place.
+VALUE_MARKER_RE = re.compile(
+    r"https?://|\bRFC\s?\d|:raises|\bRaises:|>>>|\bExamples?:|^\s*\.\. |"
+    r"\b(?:ms|msec|milliseconds?|seconds?|secs?|minutes?|hours?|days?|bytes?|kb|mb|gb|hz|khz|"
+    r"utc|iso.?8601|e\.?164|base64|utf-?8|px|dbfs?|db)\b|%",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+# Decorators whose docstring is consumed by something other than a reader, so
+# deleting it changes an artefact rather than tidying a file:
+#   - `function_tool` / `tool` hand it to a language model as the tool
+#     description, which is what the agent reasons over;
+#   - click and typer hand it to the terminal as `--help`;
+#   - FastAPI / Starlette / Flask routing decorators hand it to the OpenAPI
+#     schema as the operation description. That last one was found by the corpus
+#     sweep rather than predicted: a `@router.post(...)` handler's one-line
+#     docstring is the text an API consumer reads in the generated schema.
+PROMPT_DECORATOR_MARKERS = frozenset(
+    {
+        "agent",
+        "api_route",
+        "app",
+        "blueprint",
+        "cli",
+        "click",
+        "command",
+        "delete",
+        "function_tool",
+        "get",
+        "group",
+        "mcp",
+        "option",
+        "patch",
+        "post",
+        "put",
+        "route",
+        "router",
+        "server",
+        "tool",
+        "tools",
+        "typer",
+        "websocket",
+    }
+)
+
+# Google-style section headers, each alone on its line. `Args`/`Returns` are the
+# two the ceremony rules act on; the rest are listed so a rule can tell "this
+# docstring has an `Examples:` block" from "this docstring has prose containing
+# the word examples".
+_SECTION_RE = re.compile(
+    r"^[ \t]*(?P<name>Args|Arguments|Parameters|Params|Keyword Args|Keyword Arguments|"
+    r"Returns|Return|Yields|Yield|Raises|Attributes|Example|Examples|Note|Notes|"
+    r"Warning|Warnings|Warns|See Also|References|Todo|Other Parameters|Methods)\s*:[ \t]*$",
+    re.MULTILINE,
+)
+
+# One `Args:` entry: `name (type): description`, with the type parenthesis
+# optional. The leading indent is required — an unindented `name:` line is
+# ordinary prose with a colon in it, not a parameter entry.
+_ARG_ENTRY_RE = re.compile(r"^[ \t]+(?P<name>\*{0,2}[A-Za-z_]\w*)[ \t]*(?:\((?P<type>[^)]*)\))?[ \t]*:(?P<desc>.*)$")
+
+ARG_SECTIONS = ("Args", "Arguments", "Parameters", "Params", "Keyword Args", "Keyword Arguments")
+
+
+def sections(docstring: str) -> dict[str, str]:
+    """Split a Google-style docstring into `{"summary": ..., "<Section>": ...}`.
+
+    A docstring with no recognised header is all summary. Two blocks under the
+    same header (which a hand-edited docstring does produce) concatenate.
+
+    Returns:
+        The summary and every recognised section body, keyed by header name.
+
+    """
+    marks = [(match.start(), match.end(), match.group("name")) for match in _SECTION_RE.finditer(docstring)]
+    if not marks:
+        return {"summary": docstring}
+    out: dict[str, str] = {"summary": docstring[: marks[0][0]]}
+    for index, (_, header_end, name) in enumerate(marks):
+        body_end = marks[index + 1][0] if index + 1 < len(marks) else len(docstring)
+        out[name] = out.get(name, "") + docstring[header_end:body_end]
+    return out
+
+
+def arg_section(docstring: str) -> str | None:
+    """Return the parameter-documentation block of `docstring`, if it has one.
+
+    Returns:
+        The section body, or None when the docstring documents no parameters.
+
+    """
+    found = sections(docstring)
+    for name in ARG_SECTIONS:
+        if name in found:
+            return found[name]
+    return None
+
+
+def arg_entries(block: str) -> list[tuple[str, str, str]]:
+    """Parse an `Args:` block into `(name, type, description)` triples.
+
+    A line that is not an entry but follows one is that entry's wrapped
+    description. Folding those in is load-bearing rather than cosmetic: without
+    it the continuation row vanishes, and an entry whose informative half sits
+    on the second line reads as a bare restatement.
+
+    Returns:
+        One triple per documented parameter, in source order.
+
+    """
+    entries: list[list[str]] = []
+    for raw in block.splitlines():
+        match = _ARG_ENTRY_RE.match(raw)
+        if match is not None:
+            entries.append([match.group("name"), match.group("type") or "", match.group("desc").strip()])
+        elif entries and raw.strip():
+            entries[-1][2] += " " + raw.strip()
+    return [(name, type_, desc) for name, type_, desc in entries]
+
+
+def identifier_stems(text: str) -> set[str]:
+    """Collect the stemmed word parts of every identifier in `text`.
+
+    Returns:
+        The stems, lowercased.
+
+    """
+    return {stem(part) for match in _IDENTIFIER_RE.finditer(text) for part in split_identifier(match.group(0))}
+
+
+def decorator_markers(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> set[str]:
+    """Collect the lowercase word parts of every decorator on `node`.
+
+    Returns:
+        The decorator name parts, for matching against `PROMPT_DECORATOR_MARKERS`.
+
+    """
+    markers: set[str] = set()
+    for decorator in node.decorator_list:
+        target = decorator.func if isinstance(decorator, ast.Call) else decorator
+        try:
+            markers.update(part.lower() for part in re.split(r"\W+", ast.unparse(target)) if part)
+        except AttributeError, ValueError:  # pragma: no cover — unparse is total for these nodes
+            continue
+    return markers
+
+
+def annotation_tokens(annotation: ast.expr | None) -> list[str]:
+    """Split an annotation's rendered source into lowercase word parts.
+
+    Returns:
+        The word parts, or an empty list when there is no annotation.
+
+    """
+    if annotation is None:
+        return []
+    try:
+        rendered = ast.unparse(annotation)
+    except AttributeError, ValueError:  # pragma: no cover
+        return []
+    return [part for token in re.split(r"\W+", rendered) if token for part in split_identifier(token)]
+
+
+def signature_stems(node: ast.FunctionDef | ast.AsyncFunctionDef, class_name: str | None) -> set[str]:
+    """Collect every stem a reader can read off the signature.
+
+    The function name, the owning class name, every parameter name that is not
+    `self`/`cls`, and every annotation — parameter and return.
+
+    Returns:
+        The stems the signature already carries.
+
+    """
+    tokens = list(split_identifier(node.name))
+    if class_name is not None:
+        tokens.extend(split_identifier(class_name))
+    args = node.args
+    for arg in [*args.posonlyargs, *args.args, *args.kwonlyargs, args.vararg, args.kwarg]:
+        if arg is None:
+            continue
+        if arg.arg not in {"self", "cls"}:
+            tokens.extend(split_identifier(arg.arg))
+        tokens.extend(annotation_tokens(arg.annotation))
+    tokens.extend(annotation_tokens(node.returns))
+    return {stem(token) for token in tokens}
+
+
+def restates(text: str, known: Iterable[str]) -> bool:
+    """Report whether every content word of `text` is already in `known`.
+
+    A text with no content words at all (pure stopwords, or no words) returns
+    False: "says nothing" and "says only what the code says" are different
+    findings, and only the caller knows which one it wants.
+
+    Returns:
+        True when `text` adds no word the identifier set does not carry.
+
+    """
+    known_stems = set(known)
+    words = [match.group(0).lower() for match in WORD_RE.finditer(text)]
+    content = [word for word in words if word not in STOPWORDS]
+    if not content:
+        return False
+    return all(stem(word) in known_stems for word in content)

{sarj_python_lint-0.32.0 → sarj_python_lint-0.33.0}/src/sarj_python_lint/rules/_registry.py

@@ -3,7 +3,13 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from sarj_python_lint.rules.conditional_assertion_in_test import ConditionalAssertionInTest
+from sarj_python_lint.rules.docstring_args_restate_signature import (
+    DocstringArgsRestateSignature,
+)
 from sarj_python_lint.rules.duplicate_test_body import DuplicateTestBody
+from sarj_python_lint.rules.duplicated_override_docstring import (
+    DuplicatedOverrideDocstring,
+)
 from sarj_python_lint.rules.fixture_returns_bare_tuple import FixtureReturnsBareTuple
 from sarj_python_lint.rules.inefficient_string_concat_in_loop import (
     InefficientStringConcatInLoop,
@@ -84,6 +90,7 @@ from sarj_python_lint.rules.prefer_walrus_comprehension_filter import (
 from sarj_python_lint.rules.prefer_walrus_regex_match import PreferWalrusRegexMatch
 from sarj_python_lint.rules.prefer_walrus_stream_loop import PreferWalrusStreamLoop
 from sarj_python_lint.rules.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.single_public_export import SinglePublicExport
@@ -176,6 +183,9 @@ REGISTRY: dict[str, type[Rule]] = {
     PreferWalrusComprehensionFilter.id: PreferWalrusComprehensionFilter,
     PreferWalrusStreamLoop.id: PreferWalrusStreamLoop,
     PreferSelfTypeAnnotation.id: PreferSelfTypeAnnotation,
+    DuplicatedOverrideDocstring.id: DuplicatedOverrideDocstring,
+    RedundantClassDocstring.id: RedundantClassDocstring,
+    DocstringArgsRestateSignature.id: DocstringArgsRestateSignature,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.33.0/src/sarj_python_lint/rules/docstring_args_restate_signature.py

@@ -0,0 +1,172 @@
+"""SARJ086: an `Args:` block that only re-spells the parameter list.
+
+    def delete(self, key: str) -> None:
+        \"\"\"Drop the entry, and the tombstone the compactor would have read.
+
+        Args:                                  <- everything below is ceremony
+            key: The key of the value to delete
+        \"\"\"
+
+The summary earns its place — "the tombstone the compactor would have read" is
+not readable off the signature. The `Args:` block does not: every content word
+of every entry is already in the parameter's own name, its annotation, or the
+function name. It is a table of contents for a list of one. (That entry is real:
+`celery/celery/backends/azureblockblob.py:154`.)
+
+**The fix is to delete the `Args:` section only**, leaving the summary. That is
+safe, and it was checked against the shipped strict config rather than assumed:
+ruff's D417 (`undocumented-param`) does **not** fire on a Google-style docstring
+with no parameter section at all, so removing the block does not trade one
+finding for another. It is also the whole reason this rule exists and the
+sibling `Returns:` shape does not — deleting a `Returns:` section makes DOC201
+fire, so the only compliant remedy there is deleting a docstring whose summary
+may be the valuable part.
+
+**Why SARJ050 cannot reach this.** SARJ050 tests every content word of the
+docstring against the signature stems. The literal header word "args" is a
+content word and no signature contains it, so the mere presence of an `Args:`
+block makes a docstring permanently unflaggable by that rule, whatever the block
+says. Across the first-party corpus **126** functions carry a parsed `Args:`
+block; SARJ050 flags **0** of them.
+
+**Never flagged**
+
+- **One informative entry protects the whole block.** The test is over every
+  entry: a block where three entries restate and the fourth carries a default, a
+  unit, an example value or a constraint stays whole. Splitting a parameter
+  table is worse than leaving it. Relaxing this to "any entry restates" raises
+  the first-party count from 12 to 16 and immediately admits entries documenting
+  defaults.
+- **An entry with no description at all** — the bare `name (type):` stub. Every
+  one of the 8 first-party instances came from an OpenAPI client generator whose
+  output carries no generated-code marker, so a content-only check cannot see
+  it; judging a machine-emitted stub tells the author to edit a file that will
+  be regenerated. Dropping them is what takes the raw 20 findings to 12.
+- **An empty block, or one no entry parses out of.** Nothing to judge.
+- **Prompt / CLI / route decorators.** For an agent tool the `Args:` block is
+  part of the description shipped to the model; for click/typer it is the
+  argument help text — the same hard exemption SARJ050 makes.
+- **The protected class and the value markers**, evaluated over the block, so a
+  parameter documented with a unit, a status code, an RFC, a ticket or a causal
+  clause keeps its whole table.
+- **NumPy-style parameter blocks** (`Parameters` under a `-----` underline).
+  `_docstrings` parses Google style only; the first-party corpus holds 2 NumPy
+  docstrings in total, which is not enough evidence to tune a second parser.
+
+**What counts as "already in the signature".** The function's own name and its
+owning class contribute stems, not just the parameter's. An entry reading
+`token: JWT access token to verify` on a `JwtService.verify_access_token(token: str)`
+shape is a restatement, because "JWT" is on the class the caller types. That is also the
+loosest the test gets: of the 12 first-party findings, exactly one turned on a
+word supplied by the function name rather than the parameter, and it was judged
+borderline-true rather than false.
+
+**Measured.** 20 raw findings across 2,440 reviewable first-party files, 8 of
+them generator output that the empty-description guard removes, leaving **12**.
+All 12 were read: **12 true positives, 0 false** (1 borderline, above). The
+dominant shape is an ID parameter documented as its own name in title case.
+
+Over 14 OSS repos the predicate finds **864** (langchain 257, mlflow 256,
+dagster 137, litellm 107, prefect 87, celery 8, superset 8, airflow 4, and 0 in
+django, fastapi, saleor, sentry-python, warehouse, zulip). 20 were sampled
+across celery, superset and airflow and read: **20 true positives, 0 false**,
+including `celery/celery/app/task.py:1030` ("sig (Signature): signature to
+replace with."), `celery/celery/backends/cosmosdbsql.py:206`,
+`superset/superset/utils/jinja_template_validator.py:38` ("template_str: The
+template string to validate") and
+`airflow/providers/openlineage/src/airflow/providers/openlineage/utils/spark.py:131`
+("properties: Spark properties.").
+
+Suppress an intentional case with `# sarj-noqa: SARJ086 — <reason>`.
+"""
+
+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
+from sarj_python_lint.rules._docstrings import (
+    PROMPT_DECORATOR_MARKERS,
+    VALUE_MARKER_RE,
+    arg_entries,
+    arg_section,
+    decorator_markers,
+    identifier_stems,
+    restates,
+    signature_stems,
+)
+from sarj_python_lint.rules._paths import is_generated
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class DocstringArgsRestateSignature(Rule):
+    """An `Args:` block whose every entry only re-spells its own parameter."""
+
+    id: str = "docstring-args-restate-signature"
+    code: str = "SARJ086"
+    description: str = (
+        "`Args:` block adds nothing the signature does 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 d: d.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 = arg_section(docstring)
+        if block is None or VALUE_MARKER_RE.search(block) or is_protected(block):
+            return
+        if decorator_markers(node) & PROMPT_DECORATOR_MARKERS:
+            return
+        entries = arg_entries(block)
+        if not entries:
+            return
+        known = signature_stems(node, class_name)
+        for name, annotation, description in entries:
+            if not description:
+                return  # a machine-emitted `name (type):` stub — see the module docstring
+            if not restates(description, known | identifier_stems(name) | identifier_stems(annotation)):
+                return
+        expr = node.body[0]
+        diags.append(
+            Diagnostic(
+                path=path,
+                line=expr.lineno,
+                col=expr.col_offset + 1,
+                code=self.code,
+                message=self.description,
+            )
+        )