claude-dev-env 1.50.0 → 1.50.1

package/hooks/blocking/_gh_body_arg_utils.py

@@ -1,4 +1,4 @@
-"""Shared gh body-arg parsing utilities for blocking hooks."""
+"""Shared shell-token and gh body-arg parsing utilities for blocking hooks."""
 
 from __future__ import annotations
 
@@ -55,6 +55,63 @@ _all_equals_prefixes_for_skip: tuple[str, ...] = tuple(
 bash_continuation_marker: str = "\\"
 powershell_continuation_marker: str = "`"
 
+shell_variable_sigil: str = "$"
+all_quote_characters: frozenset[str] = frozenset({'"', "'"})
+minimum_meaningful_token_length: int = 2
+
+non_body_value_flags: frozenset[str] = all_value_flags - {body_file_flag, body_file_short_flag}
+
+_non_body_value_flag_equals_prefixes: tuple[str, ...] = tuple(
+    sorted((f"{each_flag}=" for each_flag in non_body_value_flags), key=len, reverse=True)
+)
+
+
+def is_flag_shaped_token(token: str) -> bool:
+    """Report whether a token is flag-shaped for body/PR-number extraction.
+
+    Treats any token whose second character is "-" as flag-shaped, so bare
+    "--" and "--<digit>" tokens both count as flags. `_is_flag_shaped` applies
+    a stricter rule for token-stream scanning.
+    """
+    if len(token) < minimum_meaningful_token_length:
+        return False
+    if not token.startswith("-"):
+        return False
+    return token[1] == "-" or token[1].isalpha()
+
+
+def strip_surrounding_quotes(token: str) -> str:
+    if len(token) < minimum_meaningful_token_length:
+        return token
+    first_character = token[0]
+    last_character = token[-1]
+    if first_character in all_quote_characters and first_character == last_character:
+        return token[1:-1]
+    return token
+
+
+def is_unresolvable_shell_value(token: str) -> bool:
+    return token.startswith(shell_variable_sigil)
+
+
+def _match_prefix(token: str, all_prefixes: tuple[str, ...]) -> str | None:
+    for each_prefix in all_prefixes:
+        if token.startswith(each_prefix):
+            return each_prefix
+    return None
+
+
+def match_body_flag_equals_prefix(token: str) -> str | None:
+    return _match_prefix(token, all_body_flag_prefixes)
+
+
+def match_body_file_equals_prefix(token: str) -> str | None:
+    return _match_prefix(token, (body_file_flag_prefix, body_file_short_flag_prefix))
+
+
+def match_non_body_value_flag_equals_prefix(token: str) -> str | None:
+    return _match_prefix(token, _non_body_value_flag_equals_prefixes)
+
 
 def _count_trailing_run(text: str, marker_character: str) -> int:
     trailing_run_length = 0
@@ -91,7 +148,13 @@ def get_logical_first_line(command: str) -> str:
 
 
 def _is_flag_shaped(token: str) -> bool:
-    if len(token) < 2:
+    """Report whether a token is flag-shaped for token-stream scanning.
+
+    Requires an alphabetic character after "--", so bare "--" and "--<digit>"
+    tokens are not flag-shaped. `is_flag_shaped_token` applies a looser rule
+    for body/PR-number extraction.
+    """
+    if len(token) < minimum_meaningful_token_length:
         return False
     if not token.startswith("-"):
         return False
@@ -102,7 +165,7 @@ def _is_flag_shaped(token: str) -> bool:
 
 
 def _quoted_value_starts_split(value_token: str) -> bool:
-    if len(value_token) < 2:
+    if len(value_token) < minimum_meaningful_token_length:
         return False
     first_character = value_token[0]
     if first_character not in {'"', "'"}:
@@ -129,13 +192,6 @@ def count_extra_tokens_to_skip_for_split_quoted_value(
     return None
 
 
-def _match_equals_prefix_for_skip(token: str) -> str | None:
-    for each_prefix in _all_equals_prefixes_for_skip:
-        if token.startswith(each_prefix):
-            return each_prefix
-    return None
-
-
 def iter_significant_tokens(
     command: str,
     pre_tokenized: tuple[str, list[str]] | None = None,
@@ -175,7 +231,7 @@ def iter_significant_tokens(
     while token_index < len(all_tokens):
         current_token = all_tokens[token_index]
         remaining_tokens = all_tokens[token_index + 1:]
-        matched_equals_prefix = _match_equals_prefix_for_skip(current_token)
+        matched_equals_prefix = _match_prefix(current_token, _all_equals_prefixes_for_skip)
         if matched_equals_prefix is not None:
             value_token = current_token[len(matched_equals_prefix):]
             split_value_extra_tokens = count_extra_tokens_to_skip_for_split_quoted_value(

package/hooks/blocking/_md_to_html_blocker_test_support.py

@@ -0,0 +1,65 @@
+"""Shared subprocess-invocation helpers for the md_to_html_blocker test suites.
+
+Subprocess CWD is rooted in a per-session sandbox created lazily so that
+relative-path test cases canonicalize outside any `.claude-plugin/` ancestor,
+outside the OS temp directory, and outside the exempt home-relative
+subdirectories. The sandbox is a real repo root (it carries a `.git` marker) so
+relative `README.md` / `CHANGELOG.md` writes exercise the repo-root exemption
+path. This keeps the suites independent of where pytest itself is run.
+"""
+
+import functools
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "md_to_html_blocker.py")
+
+
+def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+def _force_rmtree(target_path: str) -> None:
+    handler_kw = (
+        {"onexc": _strip_read_only_and_retry}
+        if sys.version_info >= (3, 12)
+        else {"onerror": _strip_read_only_and_retry}
+    )
+    try:
+        shutil.rmtree(target_path, **handler_kw)
+    except OSError:
+        pass
+
+
+@functools.lru_cache(maxsize=1)
+def _get_sandbox_parent_directory() -> str:
+    sandbox_parent = tempfile.mkdtemp(prefix="pytest_md_blocker_", dir=str(Path.home()))
+    git_marker_path = os.path.join(sandbox_parent, ".git")
+    Path(git_marker_path).touch()
+    return sandbox_parent
+
+
+class _RunHook:
+    def __call__(self, tool_name: str, tool_input: dict) -> subprocess.CompletedProcess:
+        payload = json.dumps({"tool_name": tool_name, "tool_input": tool_input})
+        return subprocess.run(
+            [sys.executable, HOOK_SCRIPT_PATH],
+            input=payload,
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=_get_sandbox_parent_directory(),
+        )
+
+
+_run_hook = _RunHook()

package/hooks/blocking/code_rules_enforcer.py

@@ -1723,7 +1723,7 @@ def _is_init_file(file_path: str) -> bool:
     return file_path.replace("\\", "/").rsplit("/", 1)[-1] == "__init__.py"
 
 
-def _statement_is_module_docstring(statement_node: ast.stmt) -> bool:
+def _statement_is_docstring(statement_node: ast.stmt) -> bool:
     return (
         isinstance(statement_node, ast.Expr)
         and isinstance(statement_node.value, ast.Constant)
@@ -1778,7 +1778,7 @@ def check_thin_wrapper_files(content: str, file_path: str) -> list[str]:
 
     statements_after_docstring = (
         body_statements[1:]
-        if _statement_is_module_docstring(body_statements[0])
+        if _statement_is_docstring(body_statements[0])
         else body_statements
     )
     if not statements_after_docstring:
@@ -1937,11 +1937,7 @@ def _function_body_line_count(
     if not function_node.body:
         return 0
     first_body_index = 0
-    if (
-        isinstance(function_node.body[0], ast.Expr)
-        and isinstance(function_node.body[0].value, ast.Constant)
-        and isinstance(function_node.body[0].value.value, str)
-    ):
+    if _statement_is_docstring(function_node.body[0]):
         if len(function_node.body) == 1:
             return 0
         first_body_index = 1
@@ -2355,7 +2351,7 @@ def _statement_is_raise_not_implemented(statement_node: ast.stmt) -> bool:
 
 def _function_body_is_stub(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     body_statements = list(function_node.body)
-    if body_statements and _statement_is_module_docstring(body_statements[0]):
+    if body_statements and _statement_is_docstring(body_statements[0]):
         body_statements = body_statements[1:]
     if len(body_statements) != 1:
         return False
@@ -5630,6 +5626,37 @@ def _function_definition_line_span(
     return end_lineno - function_node.lineno + 1
 
 
+def _definition_docstring_line_span(
+    definition_node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
+) -> int:
+    """Return the source-line count of the definition's leading docstring.
+
+    The Google Python Style Guide pairs a small-function preference that
+    targets executable complexity (§3.18) with a requirement for complete
+    docstrings on public functions and classes (§3.8). Counting those
+    docstring lines toward the function-length gate would penalize the very
+    documentation §3.8 mandates, so the gate measures executable span and
+    excludes leading docstring statements.
+
+    Args:
+        definition_node: The function, method, or class definition node to
+            inspect.
+
+    Returns:
+        The number of source lines the leading docstring statement occupies,
+        or zero when the definition body is empty or does not open with a
+        string literal.
+    """
+    definition_body = definition_node.body
+    if not definition_body:
+        return 0
+    first_statement = definition_body[0]
+    if _statement_is_docstring(first_statement):
+        docstring_end = getattr(first_statement, "end_lineno", None) or first_statement.lineno
+        return docstring_end - first_statement.lineno + 1
+    return 0
+
+
 def changed_line_numbers(prior_content: str, post_edit_content: str) -> set[int]:
     """Return the post-edit line numbers an edit added or replaced.
 
@@ -5716,18 +5743,23 @@ def check_function_length(
     all_changed_lines: set[int] | None = None,
     defer_scope_to_caller: bool = False,
 ) -> list[str]:
-    """Flag functions whose definition span exceeds cognitive-load thresholds.
-
-    Function definition spans (signature line through last body statement,
-    inclusive) at or above ``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60
-    lines) appear in the returned issues list and block the write at the
-    gate. The threshold rests on the small-function guidance in Robert C.
-    Martin, *Clean Code* Ch. 3 ("Functions") and the Google Python Style
-    Guide's ~40-line function review hint
-    (https://google.github.io/styleguide/pyguide.html); this gate blocks on
-    body growth that pushes a function past that span. It does not derive
-    from CODE_RULES §6.5, which governs advisory file-length signals and
-    argues against hard numeric blocks.
+    """Flag functions whose executable span exceeds cognitive-load thresholds.
+
+    Function executable spans — the definition 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, per
+    ``_definition_docstring_line_span`` summed over the nested definitions —
+    at or above
+    ``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60 lines) appear in the returned
+    issues list and block the write at the gate. The threshold rests on the
+    small-function guidance in Robert C. Martin, *Clean Code* Ch. 3
+    ("Functions") and the Google Python Style Guide's ~40-line function review
+    hint (https://google.github.io/styleguide/pyguide.html) — a measure of
+    executable complexity, paired with the Guide's complete-docstring mandate
+    for public APIs, so documentation lines never count against the gate; this
+    gate blocks on body growth that pushes a function past that span. It does
+    not derive from CODE_RULES §6.5, which governs advisory file-length
+    signals and argues against hard numeric blocks.
 
     The issue message carries ``Function NAME (defined at line X) is Y lines``
     precisely so the gate's ``function_length_span_range`` can recover the
@@ -5776,7 +5808,17 @@ def check_function_length(
         if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
             continue
         line_span = _function_definition_line_span(each_node)
-        if line_span >= FUNCTION_LENGTH_BLOCKING_THRESHOLD:
+        if line_span < FUNCTION_LENGTH_BLOCKING_THRESHOLD:
+            continue
+        docstring_line_total = sum(
+            _definition_docstring_line_span(each_definition)
+            for each_definition in ast.walk(each_node)
+            if isinstance(
+                each_definition, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+            )
+        )
+        executable_line_span = line_span - docstring_line_total
+        if executable_line_span >= FUNCTION_LENGTH_BLOCKING_THRESHOLD:
             span_range = range(each_node.lineno, each_node.lineno + line_span)
             message = (
                 f"Function {each_node.name!r} (defined at line {each_node.lineno}) "

package/hooks/blocking/conftest.py

@@ -0,0 +1,30 @@
+"""Session-scoped cleanup fixture for the md_to_html_blocker test suites.
+
+The md_to_html_blocker suites share one lazily-created sandbox parent
+directory under the home directory. This fixture tears that sandbox down once
+the session ends so the suites leave no residue regardless of which split file
+pytest collects first.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+
+if str(_BLOCKING_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIRECTORY))
+
+from _md_to_html_blocker_test_support import (  # noqa: E402
+    _force_rmtree,
+    _get_sandbox_parent_directory,
+)
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _cleanup_sandbox_parent_directory():
+    yield
+    if _get_sandbox_parent_directory.cache_info().currsize:
+        _force_rmtree(_get_sandbox_parent_directory())
+        _get_sandbox_parent_directory.cache_clear()

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