claude-dev-env 1.50.0 → 1.50.1

package/hooks/blocking/pr_description_pr_number.py

@@ -0,0 +1,153 @@
+"""Detect body flags and recover the positional PR number from a gh command.
+
+Reports whether a captured shell command carries any body or body-file flag,
+and extracts the positional PR number (bare integer or GitHub PR URL) from a
+gh pr edit/comment command while skipping value-taking flags and their values.
+"""
+
+import re
+import shlex
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from blocking._gh_body_arg_utils import (  # noqa: E402
+    all_body_flags,
+    body_file_flag,
+    body_file_short_flag,
+    count_extra_tokens_to_skip_for_split_quoted_value,
+    get_logical_first_line,
+    is_flag_shaped_token,
+    is_unresolvable_shell_value,
+    match_body_file_equals_prefix,
+    match_body_flag_equals_prefix,
+    match_non_body_value_flag_equals_prefix,
+    non_body_value_flags,
+    strip_surrounding_quotes,
+)
+from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
+    GH_PR_COMMAND_MIN_TOKEN_COUNT,
+)
+
+
+def _resolve_positional_pr_number(token: str) -> int | None:
+    """Return the PR number named by a positional token, or None if it is not one.
+
+    Accepts either a bare integer literal or a GitHub PR URL whose final path
+    segment is ``/pull/<number>``. The token may carry surrounding quotes;
+    unresolvable shell variables are rejected.
+    """
+    stripped_candidate = strip_surrounding_quotes(token)
+    if is_unresolvable_shell_value(stripped_candidate):
+        return None
+    url_match = re.match(
+        r"^https?://[^/]+/[^/]+/[^/]+/pull/(\d+)(?:[/?#].*)?$",
+        stripped_candidate,
+    )
+    if url_match is not None:
+        try:
+            return int(url_match.group(1))
+        except ValueError:
+            return None
+    try:
+        return int(stripped_candidate)
+    except ValueError:
+        return None
+
+
+def _extract_pr_number_from_command(command: str) -> int | None:
+    """Return the PR number positional argument from a `gh pr edit|comment` command.
+
+    Skips value-taking non-body flags (and their value tokens) so that ``--repo owner/r``
+    pairs do not consume the trailing PR number. Accepts both a bare integer literal
+    and a GitHub PR URL (``https://github.com/o/r/pull/<n>``) in the positional slot.
+
+    Args:
+        command: The raw shell command captured by the hook.
+
+    Returns:
+        The PR number when one positional value (integer or URL) is present, else None.
+    """
+    logical_line = get_logical_first_line(command)
+    if not logical_line:
+        return None
+    try:
+        all_tokens = shlex.split(logical_line, posix=False)
+    except ValueError:
+        return None
+    if len(all_tokens) < GH_PR_COMMAND_MIN_TOKEN_COUNT:
+        return None
+    if all_tokens[0] != "gh" or all_tokens[1] != "pr":
+        return None
+    subcommand_token = all_tokens[2]
+    if subcommand_token not in {"edit", "comment"}:
+        return None
+    all_value_taking_bare_flags: frozenset[str] = (
+        non_body_value_flags | all_body_flags | {body_file_flag, body_file_short_flag}
+    )
+    token_index = GH_PR_COMMAND_MIN_TOKEN_COUNT
+    while token_index < len(all_tokens):
+        current_token = all_tokens[token_index]
+        matched_equals_prefix = (
+            match_non_body_value_flag_equals_prefix(current_token)
+            or match_body_flag_equals_prefix(current_token)
+            or match_body_file_equals_prefix(current_token)
+        )
+        if matched_equals_prefix is not None:
+            first_value_token = current_token[len(matched_equals_prefix) :]
+            remaining_raw_tokens = all_tokens[token_index + 1 :]
+            extra_skip = (
+                count_extra_tokens_to_skip_for_split_quoted_value(
+                    remaining_raw_tokens, first_value_token
+                )
+                or 0
+            )
+            token_index += 1 + extra_skip
+            continue
+        if current_token in all_value_taking_bare_flags:
+            token_index += 1
+            if token_index < len(all_tokens):
+                token_index += 1
+            continue
+        if is_flag_shaped_token(current_token):
+            token_index += 1
+            continue
+        resolved_pr_number = _resolve_positional_pr_number(current_token)
+        if resolved_pr_number is not None:
+            return resolved_pr_number
+        return None
+    return None
+
+
+def _command_carries_body_flag(command: str) -> bool:
+    """Return True when the command string carries any body or body-file flag.
+
+    Detects the body/body-file forms accepted by ``gh pr {create,edit,comment}``:
+
+    - Long flags: a single ``"--body" in command`` substring check catches
+      every long form — ``--body``, ``--body=<value>``, ``--body-file``, and
+      ``--body-file=<value>`` — because ``--body`` is a prefix of
+      ``--body-file``. No separate ``--body-file`` check is needed.
+    - Short flags, space-separated: ``-b <value>``, ``-F <value>`` — matched
+      as `` -b `` and `` -F `` so the literal substring cannot collide with a
+      surrounding token (e.g. ``-base``, ``-Foo``).
+    - Short flags, equal-attached: ``-b=<value>``, ``-F=<value>`` — matched
+      as `` -b=`` and `` -F=`` for the same anti-collision reason. The test
+      suite relies on this detection path.
+
+    Args:
+        command: The raw shell command captured by the hook.
+
+    Returns:
+        True if any documented body or body-file flag appears in the command.
+    """
+    return (
+        "--body" in command
+        or " -b " in command
+        or " -b=" in command
+        or " -F " in command
+        or " -F=" in command
+    )

package/hooks/blocking/pr_description_readability.py

@@ -0,0 +1,366 @@
+"""Score PR body readability and manage its persisted strike/threshold state.
+
+Computes Flesch Reading Ease and sentence-length metrics over the intro and
+first section of a PR body, escalates repeated readability failures through a
+persisted strike counter, applies the loosen/reset/enable/disable threshold
+overrides, and dispatches the readability-management CLI flags.
+"""
+
+import json
+import math
+import os
+import re
+import sys
+from pathlib import Path
+from typing import TextIO
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from blocking.pr_description_body_audit import strip_markdown_ceremony  # noqa: E402
+from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
+    ATOMIC_WRITE_TEMP_SUFFIX,
+    DEFAULT_READABILITY_THRESHOLDS,
+    FENCED_CODE_BLOCK_PATTERN,
+    FLESCH_BASE_SCORE,
+    FLESCH_PERFECT_SCORE,
+    FLESCH_SYLLABLES_PER_WORD_COEFFICIENT,
+    FLESCH_WORDS_PER_SENTENCE_COEFFICIENT,
+    HEADING_LINE_PATTERN,
+    READABILITY_AVG_SENTENCE_WORDS_CEILING,
+    READABILITY_ENABLED_STATE_FILE,
+    READABILITY_FLESCH_LOOSEN_FACTOR,
+    READABILITY_LOOSEN_CAP,
+    READABILITY_MAX_SENTENCE_WORDS_CEILING,
+    READABILITY_MIN_FLESCH_FLOOR,
+    READABILITY_SENTENCE_WORDS_LOOSEN_FACTOR,
+    READABILITY_STATE_FILE,
+    READABILITY_THRESHOLD_OVERRIDE_FILE,
+    ReadabilityThresholds,
+)
+from hooks_constants.setup_project_paths_constants import UTF8_ENCODING  # noqa: E402
+
+
+def _atomic_write_json(target_path: Path, all_payload_fields: dict[str, object]) -> None:
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path = target_path.with_suffix(target_path.suffix + ATOMIC_WRITE_TEMP_SUFFIX)
+    with open(temporary_path, "w", encoding=UTF8_ENCODING) as write_handle:
+        json.dump(all_payload_fields, write_handle)
+    os.replace(temporary_path, target_path)
+
+
+def _read_json_or_default(
+    target_path: Path, all_default_payload_fields: dict[str, object]
+) -> dict[str, object]:
+    if not target_path.exists():
+        return dict(all_default_payload_fields)
+    try:
+        with open(target_path, "r", encoding=UTF8_ENCODING) as read_handle:
+            loaded_payload = json.load(read_handle)
+    except (FileNotFoundError, PermissionError, OSError, json.JSONDecodeError):
+        return dict(all_default_payload_fields)
+    if not isinstance(loaded_payload, dict):
+        return dict(all_default_payload_fields)
+    return loaded_payload
+
+
+def _read_strike_count() -> int:
+    payload = _read_json_or_default(READABILITY_STATE_FILE, {"strikes": 0})
+    raw_count = payload.get("strikes", 0)
+    if isinstance(raw_count, int) and not isinstance(raw_count, bool):
+        return max(raw_count, 0)
+    return 0
+
+
+def _increment_strike_count() -> int:
+    payload = _read_json_or_default(READABILITY_STATE_FILE, {"strikes": 0})
+    raw_count = payload.get("strikes", 0)
+    is_valid_integer = isinstance(raw_count, int) and not isinstance(raw_count, bool)
+    starting_count = max(raw_count, 0) if is_valid_integer else 0
+    new_count = starting_count + 1
+    _atomic_write_json(READABILITY_STATE_FILE, {"strikes": new_count})
+    return new_count
+
+
+def _reset_strike_count() -> None:
+    _atomic_write_json(READABILITY_STATE_FILE, {"strikes": 0})
+
+
+def _load_readability_thresholds() -> ReadabilityThresholds:
+    payload = _read_json_or_default(READABILITY_THRESHOLD_OVERRIDE_FILE, {})
+    flesch_min_value = payload.get("flesch_min", DEFAULT_READABILITY_THRESHOLDS.flesch_min)
+    max_sentence_value = payload.get(
+        "max_sentence_words", DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
+    )
+    avg_sentence_value = payload.get(
+        "avg_sentence_words", DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
+    )
+    flesch_is_int = isinstance(flesch_min_value, int) and not isinstance(flesch_min_value, bool)
+    max_is_int = isinstance(max_sentence_value, int) and not isinstance(max_sentence_value, bool)
+    avg_is_int = isinstance(avg_sentence_value, int) and not isinstance(avg_sentence_value, bool)
+    resolved_flesch = (
+        flesch_min_value if flesch_is_int else DEFAULT_READABILITY_THRESHOLDS.flesch_min
+    )
+    resolved_max = (
+        max_sentence_value if max_is_int else DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
+    )
+    resolved_avg = (
+        avg_sentence_value if avg_is_int else DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
+    )
+    return ReadabilityThresholds(
+        flesch_min=resolved_flesch,
+        max_sentence_words=resolved_max,
+        avg_sentence_words=resolved_avg,
+    )
+
+
+def _read_loosens_used() -> int:
+    payload = _read_json_or_default(READABILITY_THRESHOLD_OVERRIDE_FILE, {})
+    raw_count = payload.get("loosens_used", 0)
+    if isinstance(raw_count, int) and not isinstance(raw_count, bool):
+        return max(raw_count, 0)
+    return 0
+
+
+def _is_readability_enabled() -> bool:
+    payload = _read_json_or_default(READABILITY_ENABLED_STATE_FILE, {"enabled": True})
+    enabled_value = payload.get("enabled", True)
+    if isinstance(enabled_value, bool):
+        return enabled_value
+    return True
+
+
+def _set_readability_enabled(enabled: bool) -> None:
+    _atomic_write_json(READABILITY_ENABLED_STATE_FILE, {"enabled": enabled})
+
+
+def _count_syllables_in_word(word: str) -> int:
+    all_vowel_characters: frozenset[str] = frozenset("aeiouy")
+    cleaned_word = "".join(
+        each_character for each_character in word.lower() if each_character.isalpha()
+    )
+    if not cleaned_word:
+        return 0
+    syllable_count = 0
+    is_previous_character_vowel = False
+    for each_character in cleaned_word:
+        is_vowel = each_character in all_vowel_characters
+        if is_vowel and not is_previous_character_vowel:
+            syllable_count += 1
+        is_previous_character_vowel = is_vowel
+    if cleaned_word.endswith("e") and syllable_count > 1:
+        syllable_count -= 1
+    return max(syllable_count, 1)
+
+
+def _split_sentences(text: str) -> list[str]:
+    sentence_split_pattern = re.compile(r"[.!?]+\s+")
+    cleaned_text = text.strip()
+    if not cleaned_text:
+        return []
+    raw_pieces = sentence_split_pattern.split(cleaned_text)
+    all_sentences = [each_piece.strip() for each_piece in raw_pieces if each_piece.strip()]
+    return all_sentences
+
+
+def _compute_flesch_reading_ease(text: str) -> float:
+    all_sentences = _split_sentences(text)
+    if not all_sentences:
+        return FLESCH_PERFECT_SCORE
+    all_words: list[str] = []
+    total_syllables = 0
+    for each_sentence in all_sentences:
+        sentence_words = [
+            each_token for each_token in re.split(r"\s+", each_sentence) if each_token
+        ]
+        all_words.extend(sentence_words)
+        for each_word in sentence_words:
+            total_syllables += _count_syllables_in_word(each_word)
+    total_words = len(all_words)
+    if total_words == 0:
+        return FLESCH_PERFECT_SCORE
+    total_sentences = len(all_sentences)
+    return (
+        FLESCH_BASE_SCORE
+        - FLESCH_WORDS_PER_SENTENCE_COEFFICIENT * (total_words / total_sentences)
+        - FLESCH_SYLLABLES_PER_WORD_COEFFICIENT * (total_syllables / total_words)
+    )
+
+
+def _extract_readability_target_text(body: str) -> str:
+    """Return the ceremony-stripped prose window scored for readability.
+
+    Strips fenced code blocks, then builds a window from the body's intro
+    paragraph plus its first section's prose. The intro paragraph ends at the
+    earliest boundary among the first blank line and the first ATX header; when
+    neither boundary exists the whole body is the intro. The first section runs
+    from just after that first header to the next header (or end of body). The
+    intro and first section are joined with a blank line and returned with
+    Markdown ceremony stripped.
+
+    Args:
+        body: The raw PR body markdown text.
+
+    Returns:
+        The ceremony-stripped intro-paragraph plus first-section prose window
+        used for readability scoring.
+    """
+    intro_paragraph = ""
+    body_without_fences = FENCED_CODE_BLOCK_PATTERN.sub("", body)
+    body_after_strip = body_without_fences.lstrip()
+    blank_line_position = body_after_strip.find("\n\n")
+    header_position_match = HEADING_LINE_PATTERN.search(body_after_strip)
+    header_position = header_position_match.start() if header_position_match else -1
+
+    if blank_line_position == -1 and header_position == -1:
+        intro_paragraph = body_after_strip
+    elif blank_line_position == -1:
+        intro_paragraph = body_after_strip[:header_position]
+    elif header_position == -1:
+        intro_paragraph = body_after_strip[:blank_line_position]
+    else:
+        first_boundary = min(blank_line_position, header_position)
+        intro_paragraph = body_after_strip[:first_boundary]
+
+    first_body_section = ""
+    if header_position_match is not None:
+        section_start = header_position_match.end()
+        remainder = body_after_strip[section_start:]
+        next_header_match = HEADING_LINE_PATTERN.search(remainder)
+        if next_header_match is not None:
+            first_body_section = remainder[: next_header_match.start()]
+        else:
+            first_body_section = remainder
+
+    combined_text = f"{intro_paragraph}\n\n{first_body_section}"
+    return strip_markdown_ceremony(combined_text)
+
+
+def _evaluate_readability_metrics(
+    target_text: str,
+    thresholds: ReadabilityThresholds,
+) -> list[str]:
+    all_metric_violations: list[str] = []
+    all_sentences = _split_sentences(target_text)
+    if not all_sentences:
+        return all_metric_violations
+    word_counts_per_sentence: list[int] = []
+    for each_sentence in all_sentences:
+        sentence_words = [
+            each_token for each_token in re.split(r"\s+", each_sentence) if each_token
+        ]
+        word_counts_per_sentence.append(len(sentence_words))
+    max_sentence_words = max(word_counts_per_sentence) if word_counts_per_sentence else 0
+    average_sentence_words = (
+        sum(word_counts_per_sentence) / len(word_counts_per_sentence)
+        if word_counts_per_sentence
+        else 0.0
+    )
+    if max_sentence_words > thresholds.max_sentence_words:
+        all_metric_violations.append(
+            f"Readability: longest sentence is {max_sentence_words} words "
+            f"(maximum {thresholds.max_sentence_words}); "
+            "split or rewrite the longest sentence"
+        )
+    if average_sentence_words > thresholds.avg_sentence_words:
+        all_metric_violations.append(
+            f"Readability: average sentence is {average_sentence_words:.1f} words "
+            f"(maximum {thresholds.avg_sentence_words}); "
+            "shorten or split your longest sentences"
+        )
+    flesch_score = _compute_flesch_reading_ease(target_text)
+    if flesch_score < thresholds.flesch_min:
+        all_metric_violations.append(
+            f"Readability: Flesch Reading Ease is {flesch_score:.1f} "
+            f"(minimum {thresholds.flesch_min}); use shorter words and sentences"
+        )
+    return all_metric_violations
+
+
+def _build_readability_escape_hatch_message() -> str:
+    return (
+        "Readability strike threshold reached. Pick one: "
+        "(1) python <enforcer-path> --readability-loosen to widen thresholds 10%, "
+        "(2) python <enforcer-path> --readability-disable to skip the readability check, "
+        "(3) python <enforcer-path> --readability-reset to zero the strike counter, "
+        "(4) reply with the body plus the intended message to report a false positive."
+    )
+
+
+def _apply_readability_loosen() -> str:
+    current_thresholds = _load_readability_thresholds()
+    loosens_used = _read_loosens_used()
+
+    if loosens_used >= READABILITY_LOOSEN_CAP:
+        return "cap_reached"
+
+    if current_thresholds.flesch_min <= READABILITY_MIN_FLESCH_FLOOR:
+        return "floor_reached"
+
+    if current_thresholds.max_sentence_words >= READABILITY_MAX_SENTENCE_WORDS_CEILING:
+        return "ceiling_reached"
+
+    if current_thresholds.avg_sentence_words >= READABILITY_AVG_SENTENCE_WORDS_CEILING:
+        return "ceiling_reached"
+
+    next_flesch = max(
+        READABILITY_MIN_FLESCH_FLOOR,
+        math.floor(current_thresholds.flesch_min * READABILITY_FLESCH_LOOSEN_FACTOR),
+    )
+    next_max_sentence = min(
+        READABILITY_MAX_SENTENCE_WORDS_CEILING,
+        math.ceil(current_thresholds.max_sentence_words * READABILITY_SENTENCE_WORDS_LOOSEN_FACTOR),
+    )
+    next_avg_sentence = min(
+        READABILITY_AVG_SENTENCE_WORDS_CEILING,
+        math.ceil(current_thresholds.avg_sentence_words * READABILITY_SENTENCE_WORDS_LOOSEN_FACTOR),
+    )
+
+    next_payload: dict[str, object] = {
+        "flesch_min": next_flesch,
+        "max_sentence_words": next_max_sentence,
+        "avg_sentence_words": next_avg_sentence,
+        "loosens_used": loosens_used + 1,
+    }
+    _atomic_write_json(READABILITY_THRESHOLD_OVERRIDE_FILE, next_payload)
+    return "ok"
+
+
+def _apply_readability_reset() -> None:
+    _reset_strike_count()
+    _atomic_write_json(READABILITY_THRESHOLD_OVERRIDE_FILE, {"loosens_used": 0})
+
+
+def _dispatch_cli_flag(
+    flag_token: str,
+    output_stream: TextIO,
+    error_stream: TextIO,
+) -> None:
+    """Handle a single readability-management CLI flag and exit the process."""
+    if flag_token == "--readability-loosen":
+        outcome = _apply_readability_loosen()
+        if outcome == "cap_reached":
+            error_stream.write(
+                "loosen cap reached; use --readability-disable or --readability-reset\n"
+            )
+            sys.exit(1)
+        if outcome in {"floor_reached", "ceiling_reached"}:
+            error_stream.write(
+                "thresholds already at floor/ceiling; use --readability-disable or --readability-reset\n"
+            )
+            sys.exit(1)
+        output_stream.write("readability thresholds loosened 10%\n")
+        sys.exit(0)
+    if flag_token == "--readability-reset":
+        _apply_readability_reset()
+        output_stream.write("readability strike counter and override thresholds reset\n")
+        sys.exit(0)
+    if flag_token == "--readability-disable":
+        _set_readability_enabled(False)
+        output_stream.write("readability check disabled\n")
+        sys.exit(0)
+    if flag_token == "--readability-enable":
+        _set_readability_enabled(True)
+        output_stream.write("readability check enabled\n")
+        sys.exit(0)

package/hooks/blocking/test_code_rules_enforcer_function_length.py

@@ -1,10 +1,15 @@
 """Tests for ``check_function_length``.
 
-Functions whose definition span (signature line through last body statement,
-inclusive) is at or above ``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60) block the
-write (small-function basis: Robert C. Martin, Clean Code Ch. 3 "Functions";
-Google Python Style Guide ~40-line function review hint). Spans below the
-threshold pass silently.
+Functions whose executable span (signature line through last body statement,
+inclusive, minus the leading docstring lines of the function and of every
+function or class nested within it) is at or above
+``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60) block the write (small-function
+basis: Robert C. Martin, Clean Code Ch. 3 "Functions"; Google Python Style
+Guide ~40-line function review hint — a measure of executable complexity,
+paired with the Guide's complete-docstring mandate for public APIs). Executable
+spans below the threshold pass silently, whatever the docstring adds to the
+full declared span; the issue message keeps reporting the full declared span so
+the commit gate's span recovery holds.
 
 Cited SYNTHESIS evidence: pa#143 F4, F9, F14 (three recurrences in one PR);
 pa#136 F20.
@@ -208,3 +213,129 @@ def test_reports_only_in_scope_violation_among_untouched_ones() -> None:
     )
     assert any("target_function" in each_issue for each_issue in issues)
     assert not any("leading_" in each_issue for each_issue in issues)
+
+
+def _build_docstring_function_source(
+    name: str, docstring_line_count: int, body_line_count: int
+) -> str:
+    """Build a function whose leading docstring spans ``docstring_line_count + 2``
+    source lines (opening summary line, the counted filler lines, closing quotes)
+    followed by ``body_line_count`` executable statements."""
+    docstring_lines = [
+        '    """Documented helper.',
+        *(
+            f"    documentation line {each_index}."
+            for each_index in range(docstring_line_count)
+        ),
+        '    """',
+    ]
+    all_source_lines = [
+        f"def {name}() -> None:",
+        *docstring_lines,
+        *(
+            f"    statement_{each_index} = {each_index}"
+            for each_index in range(body_line_count)
+        ),
+    ]
+    return "\n".join(all_source_lines) + "\n"
+
+
+def test_docstring_heavy_function_with_small_body_passes() -> None:
+    """A complete Google-style docstring must not push a small-bodied function
+    over the gate: the threshold measures executable lines only."""
+    source = _build_docstring_function_source(
+        "documented_compact_helper",
+        docstring_line_count=hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD,
+        body_line_count=5,
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"docstring lines must not count toward the gate, got: {issues!r}"
+
+
+def test_oversized_executable_body_blocks_despite_docstring() -> None:
+    """A docstring does not acquit a genuinely large executable body, and the
+    issue message reports the full declared span so the commit gate's
+    ``function_length_span_range`` recovery keeps covering the whole function."""
+    docstring_line_count = 10
+    body_line_count = hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD - 1
+    source = _build_docstring_function_source(
+        "documented_oversized_helper",
+        docstring_line_count=docstring_line_count,
+        body_line_count=body_line_count,
+    )
+    full_declared_span = 1 + (docstring_line_count + 2) + body_line_count
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert any("documented_oversized_helper" in each_issue for each_issue in issues)
+    assert any(f"is {full_declared_span} lines" in each_issue for each_issue in issues)
+
+
+def test_executable_span_boundary_sits_one_below_threshold() -> None:
+    """With the docstring excluded, an executable span of THRESHOLD - 1 passes
+    even though the full declared span sits far above the threshold."""
+    source = _build_docstring_function_source(
+        "documented_boundary_helper",
+        docstring_line_count=20,
+        body_line_count=hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD - 2,
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_builder_zero_docstring_line_count_keeps_span_contract() -> None:
+    """The builder's docstring-span contract (``docstring_line_count + 2``) holds
+    at the zero boundary, so hand-computed span oracles in tests cannot drift."""
+    source = _build_docstring_function_source(
+        "documented_minimal_helper", docstring_line_count=0, body_line_count=3
+    )
+    expected_total_lines = 1 + (0 + 2) + 3
+    assert len(source.splitlines()) == expected_total_lines
+
+
+def test_builder_zero_body_line_count_keeps_span_contract() -> None:
+    """The builder's span contract holds at the zero-body boundary, so a
+    docstring-only function's hand-computed span oracle cannot drift."""
+    source = _build_docstring_function_source(
+        "documented_bodyless_helper", docstring_line_count=5, body_line_count=0
+    )
+    expected_total_lines = 1 + (5 + 2) + 0
+    assert len(source.splitlines()) == expected_total_lines
+
+
+def test_nested_function_docstring_does_not_count_toward_outer() -> None:
+    """A nested helper's docstring is documentation too: the outer function's
+    executable span excludes every leading docstring within its declared span."""
+    nested_docstring_filler = "\n".join(
+        f"        nested documentation line {each_index}."
+        for each_index in range(hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD)
+    )
+    source = (
+        "def outer_documented_orchestrator() -> None:\n"
+        "    def nested_documented_helper() -> None:\n"
+        '        """Documented nested helper.\n'
+        f"{nested_docstring_filler}\n"
+        '        """\n'
+        "        nested_statement = 1\n"
+        "    outer_statement = 2\n"
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"nested docstring lines must not count toward the gate, got: {issues!r}"
+
+
+def test_nested_class_docstring_does_not_count_toward_outer() -> None:
+    """A nested class's docstring is documentation too: the outer function's
+    executable span excludes leading docstrings of nested classes as well."""
+    nested_class_docstring_filler = "\n".join(
+        f"        nested class documentation line {each_index}."
+        for each_index in range(hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD)
+    )
+    source = (
+        "def outer_class_documented_orchestrator() -> None:\n"
+        "    class NestedDocumentedConfig:\n"
+        '        """Documented nested class.\n'
+        f"{nested_class_docstring_filler}\n"
+        '        """\n'
+        "        nested_field = 1\n"
+        "    outer_statement = 2\n"
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"nested class docstring lines must not count toward the gate, got: {issues!r}"