claude-dev-env 1.49.1 → 1.50.1

package/hooks/blocking/pr_description_body_audit.py

@@ -0,0 +1,148 @@
+"""Audit PR body markdown for prose substance, shape, and structural rules.
+
+Strips Markdown ceremony to measure substantive prose, classifies the body as
+trivial, standard, or heavy, enumerates section headers, prepares the prose
+scanned for vague language, and flags self-closing references to the PR's own
+number and the discouraged "This PR ..." opening. Vague-language enforcement
+runs in validate_pr_body in pr_description_enforcer.py.
+"""
+
+import re
+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 hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
+    BLOCKQUOTE_LINE_PATTERN,
+    BLOCKQUOTE_MARKER_PATTERN,
+    BOLD_PAIR_PATTERN,
+    BULLET_MARKER_PATTERN,
+    FENCED_CODE_BLOCK_PATTERN,
+    HEADING_LINE_PATTERN,
+    HEAVY_MIN_BODY_CHARS_FOR_CLASSIFICATION,
+    HEAVY_SHAPE,
+    INLINE_CODE_PATTERN,
+    LINK_TEXT_PATTERN,
+    SELF_REFERENCE_PATTERN_TEMPLATE,
+    STANDARD_SHAPE,
+    TABLE_ROW_LINE_PATTERN,
+    THIS_PR_OPENING_PATTERN,
+    TRIVIAL_BODY_CHAR_THRESHOLD,
+    TRIVIAL_SHAPE,
+    WHITESPACE_RUN_PATTERN,
+)
+
+
+def strip_markdown_ceremony(body: str) -> str:
+    """Return the body with Markdown ceremony stripped to leave underlying prose.
+
+    Removes fenced code, inline code, heading lines, blockquote markers,
+    bullet list markers, bold/emphasis markers, and Markdown link targets.
+    Whitespace is preserved so callers can collapse or measure it as needed.
+    """
+    body_without_fences = FENCED_CODE_BLOCK_PATTERN.sub("", body)
+    body_without_inline_code = INLINE_CODE_PATTERN.sub("", body_without_fences)
+    body_without_blockquotes = BLOCKQUOTE_MARKER_PATTERN.sub("", body_without_inline_code)
+    body_without_headings = HEADING_LINE_PATTERN.sub("", body_without_blockquotes)
+    body_without_bullets = BULLET_MARKER_PATTERN.sub("", body_without_headings)
+    body_without_bold = BOLD_PAIR_PATTERN.sub(r"\1", body_without_bullets)
+    body_without_emphasis = body_without_bold.replace("*", "")
+    body_without_links = LINK_TEXT_PATTERN.sub(r"\1", body_without_emphasis)
+    return body_without_links
+
+
+def _count_substantive_prose_chars(body: str) -> int:
+    """Return the count of prose characters after stripping Markdown ceremony.
+
+    Collapses internal whitespace so a body of only headers and bullets --
+    no real WHY paragraph -- registers as effectively empty.
+    """
+    stripped_body = strip_markdown_ceremony(body)
+    body_collapsed = WHITESPACE_RUN_PATTERN.sub(" ", stripped_body).strip()
+    return len(body_collapsed)
+
+
+def _extract_vague_scan_text(body: str) -> str:
+    """Return the prose to scan for vague language, with non-prose regions removed.
+
+    Drops whole blockquote lines and whole pipe-delimited table rows, then strips
+    the same Markdown ceremony as the prose-count path -- which removes fenced
+    code, inline code, and whole heading lines. This exempts vague phrases that
+    appear only inside code fences, inline code, Markdown headings, quoted
+    reviewer text, or pipe-delimited example tables -- those are not the author's
+    own prose. A pipe-delimited row carries at least two pipes; a line with a
+    single leading pipe, or a borderless table row with no leading pipe, stays in
+    scope.
+    """
+    without_blockquote_lines = BLOCKQUOTE_LINE_PATTERN.sub("", body)
+    without_table_rows = TABLE_ROW_LINE_PATTERN.sub("", without_blockquote_lines)
+    return strip_markdown_ceremony(without_table_rows)
+
+
+def _iter_section_headers(body: str) -> list[str]:
+    """Return every ATX heading line in the body, preserving canonical form.
+
+    HEADING_LINE_PATTERN matches the leading hash run (one or more hash
+    characters at line start), so the result spans every ATX level.
+    Downstream callers in this module only test specific two-hash header
+    strings, so matching every heading level keeps the parser permissive
+    without changing behaviour for the canonical two-hash header shape.
+
+    Fenced code blocks are stripped first so example markdown nested inside ``` fences
+    (a PR body that demonstrates the Heavy shape, for instance) is not counted as a
+    structural header. This keeps the shape classifier and Heavy required-header check
+    aligned with `strip_markdown_ceremony`, which already strips fences before measuring.
+    """
+    body_without_fences = FENCED_CODE_BLOCK_PATTERN.sub("", body)
+    all_headers: list[str] = []
+    for each_match in HEADING_LINE_PATTERN.finditer(body_without_fences):
+        header_text = each_match.group(0).strip()
+        all_headers.append(header_text)
+    return all_headers
+
+
+def _compute_pr_body_shape(body: str) -> str:
+    """Classify a PR body as `trivial`, `standard`, or `heavy` from content alone.
+
+    Uses substantive prose chars (post-Markdown-strip) rather than raw length so the
+    classifier and the ceremony-on-Trivial check both measure the same metric against
+    TRIVIAL_BODY_CHAR_THRESHOLD; otherwise a body can be classified Standard by shape
+    while simultaneously being flagged as Trivial-sized by the ceremony check.
+    """
+    substantive_length = _count_substantive_prose_chars(body)
+    header_count = len(_iter_section_headers(body))
+
+    if substantive_length < TRIVIAL_BODY_CHAR_THRESHOLD and header_count == 0:
+        return TRIVIAL_SHAPE
+
+    if substantive_length >= HEAVY_MIN_BODY_CHARS_FOR_CLASSIFICATION:
+        return HEAVY_SHAPE
+
+    return STANDARD_SHAPE
+
+
+def _body_contains_any_header(body: str, all_candidate_headers: frozenset[str]) -> bool:
+    body_headers_lower = {each_header.lower() for each_header in _iter_section_headers(body)}
+    for each_candidate in all_candidate_headers:
+        candidate_lower = each_candidate.lower()
+        for each_present in body_headers_lower:
+            if each_present == candidate_lower:
+                return True
+            if each_present.startswith(candidate_lower):
+                character_after_candidate = each_present[len(candidate_lower)]
+                if not (character_after_candidate.isalnum() or character_after_candidate == "_"):
+                    return True
+    return False
+
+
+def _matches_self_closing_reference(body: str, pr_number: int) -> bool:
+    pattern_source = SELF_REFERENCE_PATTERN_TEMPLATE.format(pr_number=pr_number)
+    compiled_pattern = re.compile(pattern_source, re.IGNORECASE)
+    return compiled_pattern.search(body) is not None
+
+
+def _opens_with_this_pr_phrase(body: str) -> bool:
+    return THIS_PR_OPENING_PATTERN.search(body) is not None

package/hooks/blocking/pr_description_command_parser.py

@@ -0,0 +1,233 @@
+"""Parse gh pr create/edit/comment commands into auditable body content.
+
+Tokenizes the captured shell command and extracts the PR body that should be
+audited, resolving body-file paths and rejecting unauditable shell variables,
+stdin sentinels, and path-traversal targets. Positional PR-number extraction
+lives in pr_description_pr_number.py.
+"""
+
+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,
+    iter_significant_tokens,
+    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
+    BODY_FILE_STDIN_SENTINEL,
+)
+from hooks_constants.setup_project_paths_constants import UTF8_ENCODING  # noqa: E402
+
+
+class PathTraversalError(Exception):
+    pass
+
+
+def _read_body_file_contents(file_path: str) -> str | None:
+    given_path = Path(file_path)
+    allowed_root = Path.cwd().resolve()
+    if given_path.is_symlink():
+        resolved_target = given_path.resolve()
+        try:
+            resolved_target.relative_to(allowed_root)
+        except ValueError:
+            raise PathTraversalError("symlink target resolves outside allowed root")
+    resolved_path = given_path.resolve()
+    if not given_path.is_absolute():
+        try:
+            resolved_path.relative_to(allowed_root)
+        except ValueError:
+            raise PathTraversalError("relative path resolves outside allowed root")
+    try:
+        with open(resolved_path, "r", encoding=UTF8_ENCODING, errors="replace") as body_file:
+            return body_file.read()
+    except (FileNotFoundError, IsADirectoryError, PermissionError, OSError):
+        return None
+
+
+def _resolve_body_file_value(raw_value_token: str) -> str | None:
+    """Return file contents, or None when the body cannot be audited.
+
+    None means body is present but unauditable -- skip enforcement.
+    This covers: stdin sentinel, unresolvable shell variables, and path-traversal-rejected paths.
+    """
+    stripped_value = strip_surrounding_quotes(raw_value_token)
+    if not stripped_value:
+        return None
+    if stripped_value == BODY_FILE_STDIN_SENTINEL:
+        return None
+    if is_unresolvable_shell_value(stripped_value):
+        return None
+    try:
+        return _read_body_file_contents(stripped_value)
+    except PathTraversalError:
+        return None
+
+
+def _resolve_body_string_value(raw_value_token: str) -> str | None:
+    """Return the literal body string, or None when the value is an
+    unresolvable shell variable.
+
+    Distinguishing the two cases lets `pr_description_enforcer.main()` skip enforcement only for
+    unauditable bodies; a literal `--body ""` still returns `""` and flows
+    into `validate_pr_body` so the substantive-prose check blocks it.
+    """
+    stripped_value = strip_surrounding_quotes(raw_value_token)
+    if is_unresolvable_shell_value(stripped_value):
+        return None
+    return stripped_value
+
+
+def _reassemble_split_quoted_value(
+    first_value_token: str, all_remaining_tokens: list[str]
+) -> str | None:
+    extra_tokens_consumed = count_extra_tokens_to_skip_for_split_quoted_value(
+        all_remaining_tokens,
+        first_value_token,
+    )
+    if extra_tokens_consumed is None:
+        return None
+    if extra_tokens_consumed == 0:
+        return first_value_token
+    continuation_tokens = all_remaining_tokens[:extra_tokens_consumed]
+    return " ".join([first_value_token, *continuation_tokens])
+
+
+def _scan_raw_tokens_for_body(all_raw_tokens: list[str]) -> str | None | bool:
+    """Return the body value from a raw token list, or False if no body flag found.
+
+    Returns False when no body/body-file flag is present (caller should continue).
+    Returns None when a body-file flag is present but malformed (no value
+    follows), OR when the body value is an unresolvable shell variable (e.g.
+    `--body "$VAR"`) — in either case the body is unauditable and the caller
+    skips enforcement.
+    Returns str for resolved body string values. An empty string `""` is a
+    literal-empty body (e.g. `--body ""`) and must still flow into
+    `validate_pr_body` so the substantive-prose check blocks it.
+    """
+    token_index = 0
+    while token_index < len(all_raw_tokens):
+        current_token = all_raw_tokens[token_index]
+        remaining_raw = all_raw_tokens[token_index + 1 :]
+        non_body_equals_prefix = match_non_body_value_flag_equals_prefix(current_token)
+        if non_body_equals_prefix is not None:
+            first_value_token = current_token[len(non_body_equals_prefix) :]
+            extra_skip = count_extra_tokens_to_skip_for_split_quoted_value(
+                remaining_raw, first_value_token
+            )
+            token_index += 1 + (extra_skip or 0)
+            continue
+        if current_token in non_body_value_flags:
+            if remaining_raw and not is_flag_shaped_token(remaining_raw[0]):
+                first_value_token = remaining_raw[0]
+                extra_skip = count_extra_tokens_to_skip_for_split_quoted_value(
+                    remaining_raw[1:], first_value_token
+                )
+                token_index += 1 + 1 + (extra_skip or 0)
+                continue
+            token_index += 1
+            continue
+        body_equals_prefix = match_body_flag_equals_prefix(current_token)
+        if body_equals_prefix is not None:
+            first_value_token = current_token[len(body_equals_prefix) :]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw)
+            if full_value_token is None:
+                return None
+            return _resolve_body_string_value(full_value_token)
+        body_file_equals_prefix = match_body_file_equals_prefix(current_token)
+        if body_file_equals_prefix is not None:
+            first_value_token = current_token[len(body_file_equals_prefix) :]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw)
+            if full_value_token is None:
+                return None
+            return _resolve_body_file_value(full_value_token)
+        if current_token in all_body_flags:
+            if not remaining_raw or is_flag_shaped_token(remaining_raw[0]):
+                return None
+            first_value_token = remaining_raw[0]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw[1:])
+            if full_value_token is None:
+                return None
+            return _resolve_body_string_value(full_value_token)
+        if current_token in {body_file_flag, body_file_short_flag}:
+            if not remaining_raw or is_flag_shaped_token(remaining_raw[0]):
+                return None
+            first_value_token = remaining_raw[0]
+            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw[1:])
+            if full_value_token is None:
+                return None
+            return _resolve_body_file_value(full_value_token)
+        token_index += 1
+    return False
+
+
+def extract_body_from_command(
+    command: str,
+    all_pre_tokenized: tuple[str, list[str]] | None = None,
+) -> str | None:
+    """Return the PR body content for validation, or None if unextractable.
+
+    Uses iter_significant_tokens to skip values of non-body value-taking flags
+    so that --body/--body-file embedded in a quoted --title value never false-matches.
+    For space-form body-file flags, scans the raw token list directly because
+    iter_significant_tokens consumes the value token (yielding remaining-after-value).
+
+    If all_pre_tokenized is provided as (logical_line, raw_tokens), reuses those instead
+    of recomputing the logical line and shlex split a second time.
+    """
+    if all_pre_tokenized is not None:
+        logical_line, all_raw_tokens = all_pre_tokenized
+    else:
+        logical_line = get_logical_first_line(command)
+        if not logical_line:
+            return None
+        try:
+            all_raw_tokens = shlex.split(logical_line, posix=False)
+        except ValueError:
+            return None
+    try:
+        all_significant_tokens = list(
+            iter_significant_tokens(command, pre_tokenized=(logical_line, all_raw_tokens))
+        )
+    except ValueError:
+        return None
+
+    significant_token_set = {each_token for each_token, _ in all_significant_tokens}
+    body_flag_found_in_significant = (
+        any(each_token in all_body_flags for each_token in significant_token_set)
+        or any(
+            match_body_flag_equals_prefix(each_token) is not None
+            for each_token in significant_token_set
+        )
+        or any(
+            match_body_file_equals_prefix(each_token) is not None
+            for each_token in significant_token_set
+        )
+        or any(
+            each_token in {body_file_flag, body_file_short_flag}
+            for each_token in significant_token_set
+        )
+    )
+    if not body_flag_found_in_significant:
+        return None
+
+    scan_outcome = _scan_raw_tokens_for_body(all_raw_tokens)
+    if isinstance(scan_outcome, bool):
+        return None
+    return scan_outcome