claude-dev-env 1.76.0 → 1.78.0

package/hooks/blocking/code_rules_docstrings.py

@@ -31,24 +31,49 @@ 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,
+    ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES,
     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_COMPANION_MODULE_RESOLUTION_DEPTH,
+    PYTHON_MODULE_FILE_SUFFIX,
+    WORD_BOUNDARY_REGEX,
     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_MARK_GLYPH_ENUMERATION_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,
+    ALL_ZIPFILE_WRITE_MODE_VALUES,
+    DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME,
+    MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
+    ZIPFILE_ALLOW_ZIP64_KEYWORD,
+    ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX,
+    ZIPFILE_MODE_KEYWORD,
+    ZIPFILE_MODE_POSITIONAL_INDEX,
+    ZIPFILE_WRITER_CLASS_NAME,
     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_NAMED_MARKS_FOR_PROSE_ENUMERATION,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
     MINIMUM_TOKENS_FOR_DISPATCH_CALLEE,
@@ -57,10 +82,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,
@@ -1010,6 +1038,203 @@ def check_docstring_tuple_enumeration_match(content: str, file_path: str) -> lis
     return issues[:MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES]
 
 
+def _known_glyph_marker_members(
+    sequence_node: ast.Tuple | ast.List,
+) -> frozenset[str] | None:
+    normalized_glyphs: set[str] = set()
+    for each_element in sequence_node.elts:
+        if not (
+            isinstance(each_element, ast.Constant)
+            and isinstance(each_element.value, str)
+        ):
+            return None
+        normalized_glyph = each_element.value.strip()
+        if normalized_glyph not in ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES:
+            return None
+        normalized_glyphs.add(normalized_glyph)
+    return frozenset(normalized_glyphs)
+
+
+def _assignment_targets_and_sequence(
+    statement: ast.stmt,
+) -> tuple[list[str], ast.Tuple | ast.List | None]:
+    if isinstance(statement, ast.Assign) and isinstance(
+        statement.value, (ast.Tuple, ast.List)
+    ):
+        plain_target_names = [
+            each_target.id
+            for each_target in statement.targets
+            if isinstance(each_target, ast.Name)
+        ]
+        return plain_target_names, statement.value
+    if (
+        isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and isinstance(statement.value, (ast.Tuple, ast.List))
+    ):
+        return [statement.target.id], statement.value
+    return [], None
+
+
+def _module_glyph_marker_tuples(parsed_tree: ast.Module) -> dict[str, frozenset[str]]:
+    glyphs_by_constant: dict[str, frozenset[str]] = {}
+    for each_statement in parsed_tree.body:
+        target_names, sequence_node = _assignment_targets_and_sequence(each_statement)
+        if sequence_node is None:
+            continue
+        marker_glyphs = _known_glyph_marker_members(sequence_node)
+        if marker_glyphs is None:
+            continue
+        if len(marker_glyphs) < MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION:
+            continue
+        for each_target_name in target_names:
+            glyphs_by_constant[each_target_name] = marker_glyphs
+    return glyphs_by_constant
+
+
+def _companion_module_file(dotted_module: str, file_path: str) -> Path | None:
+    relative_module_path = Path(*dotted_module.split(".")).with_suffix(
+        PYTHON_MODULE_FILE_SUFFIX
+    )
+    file_directory = Path(file_path).parent
+    candidate_roots = [file_directory, *file_directory.parents]
+    for each_root in candidate_roots[:MAX_COMPANION_MODULE_RESOLUTION_DEPTH]:
+        candidate_path = each_root / relative_module_path
+        if candidate_path.is_file():
+            return candidate_path
+    return None
+
+
+def _companion_glyph_marker_tuples(companion_path: Path) -> dict[str, frozenset[str]]:
+    try:
+        companion_source = companion_path.read_text(encoding="utf-8")
+        companion_tree = ast.parse(companion_source)
+    except (OSError, ValueError, SyntaxError):
+        return {}
+    return _module_glyph_marker_tuples(companion_tree)
+
+
+def _import_brings_upper_snake_name(import_node: ast.ImportFrom) -> bool:
+    return any(
+        ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_alias.name)
+        for each_alias in import_node.names
+    )
+
+
+def _imported_glyph_marker_tuples(
+    parsed_tree: ast.Module, file_path: str
+) -> dict[str, frozenset[str]]:
+    glyphs_by_imported_name: dict[str, frozenset[str]] = {}
+    for each_statement in parsed_tree.body:
+        if not isinstance(each_statement, ast.ImportFrom):
+            continue
+        if not each_statement.module:
+            continue
+        if not _import_brings_upper_snake_name(each_statement):
+            continue
+        companion_path = _companion_module_file(each_statement.module, file_path)
+        if companion_path is None:
+            continue
+        companion_tuples = _companion_glyph_marker_tuples(companion_path)
+        for each_alias in each_statement.names:
+            if each_alias.name not in companion_tuples:
+                continue
+            imported_name = each_alias.asname or each_alias.name
+            glyphs_by_imported_name[imported_name] = companion_tuples[each_alias.name]
+    return glyphs_by_imported_name
+
+
+def _docstring_names_mark_glyph(docstring_text: str, normalized_glyph: str) -> bool:
+    lowercased_docstring = docstring_text.lower()
+    for each_name in ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES[normalized_glyph]:
+        boundary_wrapped_name = (
+            WORD_BOUNDARY_REGEX + re.escape(each_name) + WORD_BOUNDARY_REGEX
+        )
+        if re.search(boundary_wrapped_name, lowercased_docstring):
+            return True
+    return False
+
+
+def _marks_named_in_docstring(
+    docstring_text: str, all_marker_glyphs: frozenset[str]
+) -> set[str]:
+    return {
+        each_glyph
+        for each_glyph in all_marker_glyphs
+        if _docstring_names_mark_glyph(docstring_text, each_glyph)
+    }
+
+
+def _text_names_multiple_marks(content_text: str) -> bool:
+    all_known_glyphs = frozenset(ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES)
+    named_glyphs = _marks_named_in_docstring(content_text, all_known_glyphs)
+    return len(named_glyphs) >= MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION
+
+
+def check_docstring_punctuation_mark_enumeration_coverage(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring that names some marks of a glyph tuple but omits one.
+
+    A module reads a tuple of punctuation-mark glyphs as its detection set. The
+    tuple is defined in the module or imported from a companion module beside it.
+    A docstring then enumerates those marks by their English names. When the
+    prose names a closed set of marks but leaves one the tuple holds unnamed, a
+    reader trusts the enumeration and believes an active mark never triggers the
+    check. This is the shape that appears when a glyph joins the tuple while the
+    prose enumeration stays as it was.
+
+    The check binds only when a docstring names two or more marks of one tuple. A
+    docstring that mentions a single mark, names every mark, or describes
+    unrelated punctuation is left alone. This is the deterministic glyph-prose
+    slice of Category O6 docstring-prose-vs-implementation drift, the companion
+    to check_docstring_tuple_enumeration_match for glyph members named in prose
+    rather than identifier members named in inline code. It covers hook
+    infrastructure, where the affected detection tuples live.
+
+    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 mark enumeration omits a glyph the tuple it
+        describes holds, capped at the module limit.
+    """
+    if is_strict_test_file(file_path):
+        return []
+    if not _text_names_multiple_marks(content):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    glyphs_by_constant = {
+        **_module_glyph_marker_tuples(parsed_tree),
+        **_imported_glyph_marker_tuples(parsed_tree, file_path),
+    }
+    if not glyphs_by_constant:
+        return []
+    issues: list[str] = []
+    for each_line, each_docstring in _documentable_docstrings_with_line(parsed_tree):
+        for each_constant_name in sorted(glyphs_by_constant):
+            marker_glyphs = glyphs_by_constant[each_constant_name]
+            named_glyphs = _marks_named_in_docstring(each_docstring, marker_glyphs)
+            if len(named_glyphs) < MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION:
+                continue
+            omitted_glyphs = marker_glyphs - named_glyphs
+            if not omitted_glyphs:
+                continue
+            issues.append(
+                f"Line {each_line}: docstring names {sorted(named_glyphs)} from "
+                f"{each_constant_name} but omits {sorted(omitted_glyphs)} — name every "
+                "mark the tuple holds so the enumeration matches the detection set "
+                "(Category O6 docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES:
+                return issues[:MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES]
+    return issues[:MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES]
+
+
 def _returns_section_text(docstring_text: str) -> str:
     docstring_lines = docstring_text.splitlines()
     returns_section_lines: list[str] = []
@@ -1111,6 +1336,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 +1799,392 @@ 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]
+
+
+def _raises_section_text(docstring_text: str) -> str:
+    docstring_lines = docstring_text.splitlines()
+    raises_section_lines: list[str] = []
+    inside_raises_section = False
+    for each_line in docstring_lines:
+        stripped_line = each_line.strip()
+        if stripped_line == "Raises:":
+            inside_raises_section = True
+            continue
+        if not inside_raises_section:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        raises_section_lines.append(stripped_line)
+    return " ".join(raises_section_lines)
+
+
+def _call_argument_by_keyword_or_position(
+    call_node: ast.Call, keyword_name: str, positional_index: int
+) -> ast.expr | None:
+    for each_keyword in call_node.keywords:
+        if each_keyword.arg == keyword_name:
+            return each_keyword.value
+    if positional_index >= len(call_node.args):
+        return None
+    if any(
+        isinstance(each_argument, ast.Starred)
+        for each_argument in call_node.args[: positional_index + 1]
+    ):
+        return None
+    return call_node.args[positional_index]
+
+
+def _call_opens_zipfile_write_mode_writer(call_node: ast.Call) -> bool:
+    callee = call_node.func
+    if isinstance(callee, ast.Attribute):
+        callee_name = callee.attr
+    elif isinstance(callee, ast.Name):
+        callee_name = callee.id
+    else:
+        return False
+    if callee_name != ZIPFILE_WRITER_CLASS_NAME:
+        return False
+    mode_argument = _call_argument_by_keyword_or_position(
+        call_node, ZIPFILE_MODE_KEYWORD, ZIPFILE_MODE_POSITIONAL_INDEX
+    )
+    return (
+        isinstance(mode_argument, ast.Constant)
+        and mode_argument.value in ALL_ZIPFILE_WRITE_MODE_VALUES
+    )
+
+
+def _zipfile_writer_forbids_zip64(call_node: ast.Call) -> bool:
+    allow_zip64_argument = _call_argument_by_keyword_or_position(
+        call_node, ZIPFILE_ALLOW_ZIP64_KEYWORD, ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX
+    )
+    return (
+        isinstance(allow_zip64_argument, ast.Constant)
+        and allow_zip64_argument.value is False
+    )
+
+
+def _function_documents_unraisable_largezipfile(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    docstring_text: str,
+) -> bool:
+    if DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME not in _raises_section_text(docstring_text):
+        return False
+    write_mode_writers = [
+        each_descendant
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+        if isinstance(each_descendant, ast.Call)
+        and _call_opens_zipfile_write_mode_writer(each_descendant)
+    ]
+    if not write_mode_writers:
+        return False
+    return not any(
+        _zipfile_writer_forbids_zip64(each_writer) for each_writer in write_mode_writers
+    )
+
+
+def check_docstring_raises_unraisable_largezipfile(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a Raises clause naming LargeZipFile over a default-ZIP64 writer.
+
+    The drift this catches: a function whose docstring Raises clause lists
+    ``zipfile.LargeZipFile`` while the function opens its ``zipfile.ZipFile``
+    writer in a write mode (``w``/``a``/``x``) with ``allowZip64`` left at its
+    default of True. The stdlib raises ``LargeZipFile`` only when an entry needs
+    ZIP64 AND ``allowZip64`` is False; with ZIP64 permitted the writer
+    transparently uses it and never raises. The Raises entry then documents an
+    exception the body cannot produce, so a caller guarding ``LargeZipFile`` on
+    the strength of the docstring guards an unreachable path. This is the
+    deterministic slice of Category O6 docstring-prose-vs-implementation drift
+    where a writer opened with default ZIP64 disagrees with a LargeZipFile
+    Raises clause.
+
+    The check binds only when the function opens at least one write-mode
+    ``ZipFile`` and every such writer permits ZIP64, so a function that forbids
+    ZIP64 on any writer (``allowZip64=False``, by keyword or position), a
+    read-only open, and a function that opens no writer — where the exception may
+    propagate from a callee — are all left alone.
+
+    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 LargeZipFile Raises clause names an
+        unreachable exception, 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_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_documents_unraisable_largezipfile(each_node, docstring_text):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring Raises lists "
+            "zipfile.LargeZipFile, but the function opens its ZipFile writer with ZIP64 "
+            "permitted (allowZip64 defaults to True) — LargeZipFile raises only when "
+            "allowZip64 is False, so drop the entry or pass allowZip64=False "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES]