claude-dev-env 1.75.0 → 1.77.0

package/hooks/blocking/code_rules_docstrings.py

@@ -31,23 +31,34 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES,
     ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES,
     ALL_DOCSTRING_NON_CONSTANT_REFERENCE_MARKERS,
+    ALL_DOCSTRING_RUNON_JOINER_MARKERS,
     ALL_GENERIC_CHECK_NAME_TOKENS,
     ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_REFERENCE_MARKER_WINDOW,
+    DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN,
+    DOCSTRING_RUNON_SENTENCE_WORD_LIMIT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
     MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
+    MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
     MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
+    MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
+    ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES,
+    ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES,
+    ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES,
+    MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
     MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES,
     MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES,
     MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES,
+    MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK,
+    MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK,
     MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
@@ -57,10 +68,13 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CAPS_WITH_UNDERSCORE_PATTERN,
+    ALL_CARDINAL_NUMBER_WORD_VALUES,
     ALL_DOCSTRING_ARGS_SECTION_HEADERS,
     ALL_DOCSTRING_TERMINATING_SECTION_HEADERS,
     ALL_SELF_AND_CLS_PARAMETER_NAMES,
     DOCSTRING_ARG_ENTRY_PATTERN,
+    DOCSTRING_CARDINAL_OUTCOME_PHRASE_PATTERN,
+    DOCSTRING_MULTI_SEGMENT_SNAKE_TOKEN_PATTERN,
     DOCSTRING_PLURAL_FAMILY_STOP_PATTERN,
     IDENTIFIER_SHAPED_TUPLE_MEMBER_PATTERN,
     INLINE_CODE_TOKEN_PATTERN,
@@ -1111,6 +1125,122 @@ def check_docstring_returns_plural_cardinality(content: str, file_path: str) ->
     return issues[:MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES]
 
 
+def _referenced_constant_families(parsed_tree: ast.Module) -> dict[str, set[str]]:
+    members_by_family: dict[str, set[str]] = {}
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(each_node, ast.Name):
+            continue
+        if not isinstance(each_node.ctx, ast.Load):
+            continue
+        if not ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_node.id):
+            continue
+        family_prefix, _, member_suffix = each_node.id.partition("_")
+        if not member_suffix:
+            continue
+        members_by_family.setdefault(family_prefix, set()).add(member_suffix.lower())
+    return members_by_family
+
+
+def _eligible_constant_families(parsed_tree: ast.Module) -> dict[str, set[str]]:
+    return {
+        each_family: each_members
+        for each_family, each_members in _referenced_constant_families(parsed_tree).items()
+        if len(each_members) >= MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK
+    }
+
+
+def _docstring_snake_case_tokens(docstring_text: str) -> set[str]:
+    return set(DOCSTRING_MULTI_SEGMENT_SNAKE_TOKEN_PATTERN.findall(docstring_text))
+
+
+def _docstring_stated_outcome_cardinals(docstring_text: str) -> set[int]:
+    return {
+        ALL_CARDINAL_NUMBER_WORD_VALUES[each_match.group(1).lower()]
+        for each_match in DOCSTRING_CARDINAL_OUTCOME_PHRASE_PATTERN.finditer(docstring_text)
+    }
+
+
+def _documentable_docstrings_with_line(parsed_tree: ast.Module) -> list[tuple[int, str]]:
+    docstrings_with_line: list[tuple[int, str]] = []
+    module_docstring = ast.get_docstring(parsed_tree) or ""
+    if module_docstring:
+        docstrings_with_line.append((1, module_docstring))
+    for each_node in ast.walk(parsed_tree):
+        if not isinstance(
+            each_node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+        ):
+            continue
+        node_docstring = ast.get_docstring(each_node) or ""
+        if node_docstring:
+            docstrings_with_line.append((each_node.lineno, node_docstring))
+    return docstrings_with_line
+
+
+def check_docstring_cardinal_count_matches_constant_family(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring cardinal count that under-names a referenced constant family.
+
+    The drift this catches: a docstring states a cardinal count of an outcome
+    family (``Covers the four outcome branches: ...``) and enumerates that
+    family's members in prose, while the module references more members of the
+    same ``UPPER_SNAKE`` constant family than the count names. The prose
+    under-describes the code — a reader trusts the count and the enumeration to
+    be the full set, but the module imports and exercises an outcome the summary
+    omits. The check binds only when the docstring states a cardinal beside an
+    outcome noun, names two or more members of one referenced family, leaves at
+    least one referenced family member unnamed, and the family member count
+    differs from every stated cardinal; a complete enumeration, a count that
+    matches the family, and a single passing mention are all left alone. This is
+    the deterministic cardinal-count slice of Category O6
+    docstring-prose-vs-implementation drift. The check runs on test files too,
+    since the drift class lives in a test-module summary.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring whose cardinal count and enumeration omit a
+        referenced constant-family member, capped at the module limit.
+    """
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    eligible_families = _eligible_constant_families(parsed_tree)
+    if not eligible_families:
+        return []
+    issues: list[str] = []
+    for each_line, each_docstring in _documentable_docstrings_with_line(parsed_tree):
+        stated_cardinals = _docstring_stated_outcome_cardinals(each_docstring)
+        if not stated_cardinals:
+            continue
+        docstring_tokens = _docstring_snake_case_tokens(each_docstring)
+        if not docstring_tokens:
+            continue
+        for each_family in sorted(eligible_families):
+            family_members = eligible_families[each_family]
+            named_members = docstring_tokens & family_members
+            if len(named_members) < MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK:
+                continue
+            omitted_members = family_members - docstring_tokens
+            if not omitted_members:
+                continue
+            if len(family_members) in stated_cardinals:
+                continue
+            issues.append(
+                f"Line {each_line}: docstring names {sorted(stated_cardinals)} as the "
+                f"{each_family}_ count but the module references {len(family_members)} "
+                f"{each_family}_ constants — omits {sorted(omitted_members)}; match the "
+                "count and enumeration to the referenced family "
+                "(Category O6 docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES:
+                return issues[:MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES]
+    return issues[:MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES]
+
+
 def _called_callee_name(statement: ast.stmt) -> str:
     candidate_expression: ast.expr | None = None
     if isinstance(statement, ast.Expr):
@@ -1458,3 +1588,251 @@ def check_docstring_names_undefined_constant(content: str, file_path: str) -> li
             if len(issues) >= MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES:
                 return issues[:MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES]
     return issues[:MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES]
+
+
+def _args_entry_prose_by_argument(docstring_text: str) -> dict[str, str]:
+    docstring_lines = docstring_text.splitlines()
+    args_section_index = _find_args_section_index(docstring_lines)
+    if args_section_index is None:
+        return {}
+    prose_by_argument: dict[str, list[str]] = {}
+    current_argument_name: str | None = None
+    entry_indent: int | None = None
+    for each_line in docstring_lines[args_section_index + 1:]:
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        current_indent = len(each_line) - len(each_line.lstrip())
+        if current_indent == 0:
+            break
+        if entry_indent is None:
+            entry_indent = current_indent
+        if current_indent <= entry_indent:
+            entry_match = DOCSTRING_ARG_ENTRY_PATTERN.match(stripped_line)
+            if entry_match is not None:
+                current_argument_name = entry_match.group(1)
+                prose_by_argument[current_argument_name] = [stripped_line]
+                continue
+        if current_argument_name is not None:
+            prose_by_argument[current_argument_name].append(stripped_line)
+    return {
+        each_name: " ".join(each_lines).lower()
+        for each_name, each_lines in prose_by_argument.items()
+    }
+
+
+def _argument_prose_scopes_a_single_line(argument_prose: str) -> bool:
+    if any(
+        each_phrase in argument_prose for each_phrase in ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES
+    ):
+        return False
+    return any(
+        each_phrase in argument_prose for each_phrase in ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES
+    )
+
+
+def _call_node_builds_two_argument_range(call_node: ast.Call) -> bool:
+    callee = call_node.func
+    return (
+        isinstance(callee, ast.Name)
+        and callee.id == "range"
+        and len(call_node.args) >= MINIMUM_TOKENS_FOR_DISPATCH_CALLEE
+    )
+
+
+def _function_body_scopes_a_span_by_intersection(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    builds_range_span = False
+    calls_span_scoper = False
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Call):
+            continue
+        if _call_node_builds_two_argument_range(each_node):
+            builds_range_span = True
+        if _call_callee_name(each_node) in ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES:
+            calls_span_scoper = True
+    return builds_range_span and calls_span_scoper
+
+
+def check_docstring_args_single_line_scope_vs_span(content: str, file_path: str) -> list[str]:
+    """Flag a docstring Args entry scoping a finding to one line over a span body.
+
+    The drift this catches: an ``Args:`` entry whose prose says a finding blocks
+    "only when its block-anchor line is among the changed lines" (a single named
+    line) while the function body builds a ``range(...)`` span over the finding's
+    source lines and routes it through a span-intersection scoper that blocks when
+    ANY line of the span is among the changed lines. The Args sentence claims a
+    narrower single-line scope than the body applies, so an edit touching a
+    non-anchor line of the span still blocks — contradicting the Args entry. This
+    is the deterministic slice of Category O6 docstring-vs-implementation drift
+    for an Args single-line scope claim disagreeing with a span-intersection body.
+
+    An entry is left alone when its prose says "any line of" / "any line in" its
+    span, since that wording matches the span body. The body is judged a
+    span-intersection scoper only when it both builds a two-argument ``range(...)``
+    and calls a known span scoper, so a body that scopes by a single line never
+    trips the check. Hook infrastructure is in scope here — the import-sort gate
+    that carries this drift class is itself a hook — and test files are exempt.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose Args single-line scope claim disagrees with
+        its span-intersection body, capped at the module limit.
+    """
+    if is_test_file(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        if not _function_body_scopes_a_span_by_intersection(each_node):
+            continue
+        for each_argument, each_prose in _args_entry_prose_by_argument(docstring_text).items():
+            if not _argument_prose_scopes_a_single_line(each_prose):
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}() Args entry '{each_argument}' "
+                "scopes a finding to a single line ('anchor line is among the changed lines') "
+                "while the body builds a range() span and scopes by span intersection — an "
+                "edit touching any non-anchor line of the span still blocks; restate the Args "
+                "entry as 'any line of its span is among the changed lines' (Category O6 "
+                "docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES:
+                return issues[:MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES]
+    return issues[:MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES]
+
+
+def _is_narrative_cut_header(stripped_line: str) -> bool:
+    return (
+        stripped_line in ALL_DOCSTRING_TERMINATING_SECTION_HEADERS
+        or stripped_line in ALL_DOCSTRING_ARGS_SECTION_HEADERS
+    )
+
+
+def _docstring_narrative_text(docstring_text: str) -> str:
+    narrative_lines: list[str] = []
+    for each_line in docstring_text.splitlines():
+        stripped_line = each_line.strip()
+        if _is_narrative_cut_header(stripped_line):
+            break
+        narrative_lines.append(stripped_line)
+    return " ".join(narrative_lines)
+
+
+def _sentence_word_count(sentence_text: str) -> int:
+    return sum(
+        1
+        for each_token in sentence_text.split()
+        if any(each_character.isalnum() for each_character in each_token)
+    )
+
+
+def _sentence_carries_joiner_marker(sentence_text: str) -> bool:
+    return any(
+        each_marker in sentence_text for each_marker in ALL_DOCSTRING_RUNON_JOINER_MARKERS
+    )
+
+
+def _runon_sentences(narrative_text: str) -> list[str]:
+    flagged_sentences: list[str] = []
+    for each_sentence in DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN.split(narrative_text):
+        stripped_sentence = each_sentence.strip()
+        if not stripped_sentence:
+            continue
+        if _sentence_word_count(stripped_sentence) <= DOCSTRING_RUNON_SENTENCE_WORD_LIMIT:
+            continue
+        if not _sentence_carries_joiner_marker(stripped_sentence):
+            continue
+        flagged_sentences.append(stripped_sentence)
+    return flagged_sentences
+
+
+def _documentable_docstring_targets(
+    parsed_tree: ast.Module,
+) -> list[tuple[int, str, str]]:
+    documentable_targets: list[tuple[int, str, str]] = []
+    module_docstring = ast.get_docstring(parsed_tree)
+    if module_docstring and parsed_tree.body:
+        documentable_targets.append((parsed_tree.body[0].lineno, "module", module_docstring))
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if isinstance(each_node, ast.ClassDef):
+            class_docstring = ast.get_docstring(each_node)
+            if class_docstring:
+                documentable_targets.append((each_node.lineno, each_node.name, class_docstring))
+            continue
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_node.name):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        function_docstring = _function_docstring_text(each_node)
+        if function_docstring:
+            documentable_targets.append(
+                (each_node.lineno, f"{each_node.name}()", function_docstring)
+            )
+    return documentable_targets
+
+
+def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
+    """Flag a docstring narrative sentence that reads as a dense run-on wall.
+
+    A readable docstring breaks its narrative into short sentences a general
+    developer follows on the first read. The one mechanical mark of a wall is a
+    single sentence that runs past the word limit while chaining clauses with an
+    em-dash or a semicolon. This check inspects the narrative prose of module,
+    class, and public-function docstrings — the text before the first structured
+    section header (``Args:``, ``Arguments:``, ``Returns:``, ``Yields:``,
+    ``Raises:``, ``Note:``, ``Notes:``, ``Example:``, or ``Examples:``) — and
+    reports a sentence that is both over the word limit and joined by one of those
+    marks.
+    Whether the prose paints a concrete, illustrative picture is judgment the
+    plain-illustrative-docstrings audit lane carries; this gate catches only the
+    run-on mark.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring whose narrative carries a run-on sentence, capped
+        at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_line_number, each_label, each_docstring in _documentable_docstring_targets(
+        parsed_tree
+    ):
+        flagged_sentences = _runon_sentences(_docstring_narrative_text(each_docstring))
+        if not flagged_sentences:
+            continue
+        run_on_word_count = _sentence_word_count(flagged_sentences[0])
+        issues.append(
+            f"Line {each_line_number}: {each_label} docstring carries a {run_on_word_count}-word "
+            "run-on sentence — break the narrative into short, illustrative sentences a general "
+            "developer reads in one pass (plain-illustrative-docstrings)"
+        )
+        if len(issues) >= MAX_DOCSTRING_RUNON_SENTENCE_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]