claude-dev-env 1.50.0 → 1.50.2

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_annotations_length.py

@@ -0,0 +1,167 @@
+"""Parameter-annotation, return-annotation, and function-length checks."""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    _collect_annotated_arguments,
+    _definition_docstring_line_span,
+    _function_definition_line_span,
+    _scope_violations_to_changed_lines,
+    is_hook_infrastructure,
+    is_migration_file,
+    is_test_file,
+    is_workflow_registry_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_SELF_AND_CLS_PARAMETER_NAMES,
+    FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX,
+    FUNCTION_LENGTH_BLOCKING_THRESHOLD,
+)
+
+
+def check_parameter_annotations(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_arg in _collect_annotated_arguments(each_node):
+            if each_arg.arg in ALL_SELF_AND_CLS_PARAMETER_NAMES:
+                continue
+            if each_arg.annotation is None:
+                issues.append(
+                    f"Line {each_arg.lineno}: parameter {each_arg.arg!r} on {each_node.name!r} missing type annotation (CODE_RULES §6)"
+                )
+    return issues
+
+
+def check_return_annotations(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if each_node.returns is None:
+            issues.append(
+                f"Line {each_node.lineno}: function {each_node.name!r} missing return type annotation (CODE_RULES §6)"
+            )
+    return issues
+
+
+def check_function_length(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    """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`` 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* Chapter Three ("Functions") and the Google Python Style
+    Guide's ~forty-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 file-length guidance, 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
+    function's full declared span (lines ``X`` through ``X + Y - 1``). The
+    gate classifies the violation blocking when that span intersects the
+    diff's added lines — the body grew this diff — and advisory otherwise — a
+    pre-existing, untouched long function in a file the diff happened to
+    touch. Anchoring to the span rather than a single ``Line N:`` definition
+    line lets body growth on any interior line block correctly even when the
+    ``def`` line itself is untouched.
+
+    Exempt: test files (test bodies are sometimes long by necessity), Django
+    migrations (auto-generated), workflow registries (registry entries), and
+    hook infrastructure.
+
+    Args:
+        content: The Python source to analyze.
+        file_path: The path of the file being checked.
+        all_changed_lines: Post-edit line numbers the current edit touched, or
+            None to treat the whole file as in scope. When provided, a violation
+            blocks only when the function's declared span intersects the changed
+            lines.
+        defer_scope_to_caller: When True, return every violation so the
+            commit/push gate's ``split_violations_by_scope`` can scope by added
+            line and report the in-scope set.
+
+    Returns:
+        Blocking issues. When *defer_scope_to_caller* is True every violation is
+        returned for the gate to scope; otherwise every violation in scope is
+        returned.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_hook_infrastructure(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    all_violations_in_walk_order: list[tuple[range, str]] = []
+    for each_node in ast.walk(parsed_tree):
+        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:
+            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}) "
+                f"is {line_span} lines - {FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX}"
+            )
+            all_violations_in_walk_order.append((span_range, message))
+    return _scope_violations_to_changed_lines(
+        all_violations_in_walk_order,
+        all_changed_lines,
+        defer_scope_to_caller,
+    )