claude-dev-env 1.49.1 → 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.py

@@ -2602,3 +2602,68 @@ def test_banned_noun_word_boundary_flags_plural_results_identifier() -> None:
         "a plural banned-noun identifier must be flagged by the word-boundary "
         f"check; got: {issues!r}"
     )
+
+
+def test_ignored_must_check_return_flags_bare_awaited_call() -> None:
+    """A bare ``await find_and_click(...)`` statement discards its only failure signal.
+
+    The curated must-check functions are async, so the common real call site is a
+    bare ``await``-wrapped call. Unwrapping ``ast.Await`` before the Call check is
+    required for this case to be flagged.
+    """
+    source = "async def step() -> None:\n    await find_and_click('#x')\n"
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source, "/project/src/clicker.py"
+    )
+    assert any("find_and_click" in each_issue for each_issue in issues), (
+        f"a bare awaited must-check call must be flagged; got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_ignored_must_check_return_exempts_consumed_awaited_call() -> None:
+    """An assigned or branched-on awaited must-check call consumes its outcome."""
+    assigned = "async def step() -> None:\n    clicked = await find_and_click('#x')\n    print(clicked)\n"
+    branched = "async def step() -> None:\n    if await find_and_click('#x'):\n        pass\n"
+    assert (
+        code_rules_enforcer.check_ignored_must_check_return(assigned, "/project/src/clicker.py")
+        == []
+    )
+    assert (
+        code_rules_enforcer.check_ignored_must_check_return(branched, "/project/src/clicker.py")
+        == []
+    )
+
+
+def test_ignored_must_check_return_flags_edited_line_past_a_cap_of_earlier_violations() -> None:
+    """The cap must apply after scoping so the edited-line violation is never dropped.
+
+    Collecting only a cap's worth of violations in ``ast.walk`` order, then scoping,
+    fills the cap with earlier out-of-scope calls and discards the edited-line one —
+    the very violation the scoped enforcer exists to block. Every violation must be
+    collected before scoping so the edited line survives the diff filter.
+    """
+    pre_existing_call_count = 5
+    edited_call_line_number = pre_existing_call_count + 2
+    all_pre_existing_call_lines = [
+        f"    await find_and_click('#x{each_index}')"
+        for each_index in range(pre_existing_call_count)
+    ]
+    all_lines = (
+        ["async def step() -> None:"]
+        + all_pre_existing_call_lines
+        + ["    await find_and_click('#edited')"]
+    )
+    source = "\n".join(all_lines) + "\n"
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source,
+        "/project/src/clicker.py",
+        {edited_call_line_number},
+        False,
+    )
+    assert len(issues) == 1, (
+        f"the edited-line violation must survive a cap's worth of earlier calls; got: {issues!r}"
+    )
+    assert f"Line {edited_call_line_number}:" in issues[0], (
+        f"the single issue must name the edited line {edited_call_line_number}; got: {issues!r}"
+    )