claude-dev-env 1.58.0 → 1.60.0

package/hooks/blocking/code_rules_typeddict_stub.py

@@ -26,6 +26,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_STUB_IMPLEMENTATION_ISSUES,
     MAX_THIN_WRAPPER_ISSUES,
     MAX_TYPED_DICT_PAIR_ISSUES,
+    MAX_ZERO_PAYLOAD_ALIAS_ISSUES,
 )
 
 def _pascal_to_snake_case(pascal_name: str) -> str:
@@ -58,6 +59,16 @@ def _collect_module_function_names(parsed_tree: ast.AST) -> set[str]:
     return module_function_names
 
 
+def _collect_module_function_nodes_by_name(
+    parsed_tree: ast.AST,
+) -> dict[str, ast.FunctionDef | ast.AsyncFunctionDef]:
+    function_node_by_name: dict[str, ast.FunctionDef | ast.AsyncFunctionDef] = {}
+    for each_statement in parsed_tree.body:
+        if isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            function_node_by_name[each_statement.name] = each_statement
+    return function_node_by_name
+
+
 def _is_init_file(file_path: str) -> bool:
     return file_path.replace("\\", "/").rsplit("/", 1)[-1] == "__init__.py"
 
@@ -126,6 +137,167 @@ def check_thin_wrapper_files(content: str, file_path: str) -> list[str]:
     return issues[:MAX_THIN_WRAPPER_ISSUES]
 
 
+def _function_parameter_names_in_order(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+    arguments = function_node.args
+    positional_arguments = [*arguments.posonlyargs, *arguments.args]
+    return [each_argument.arg for each_argument in positional_arguments]
+
+
+def _has_only_positional_parameters(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    arguments = function_node.args
+    has_no_parameter_defaults = not arguments.defaults and not arguments.kw_defaults
+    return (
+        not arguments.kwonlyargs
+        and arguments.vararg is None
+        and arguments.kwarg is None
+        and has_no_parameter_defaults
+    )
+
+
+def _single_return_call(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> ast.Call | None:
+    body_statements = function_node.body
+    statements_after_docstring = (
+        body_statements[1:]
+        if body_statements and _statement_is_docstring(body_statements[0])
+        else body_statements
+    )
+    if len(statements_after_docstring) != 1:
+        return None
+    only_statement = statements_after_docstring[0]
+    if not isinstance(only_statement, ast.Return):
+        return None
+    return only_statement.value if isinstance(only_statement.value, ast.Call) else None
+
+
+def _forwards_parameters_unchanged(call_node: ast.Call, all_parameter_names: list[str]) -> bool:
+    if call_node.keywords:
+        return False
+    if len(call_node.args) != len(all_parameter_names):
+        return False
+    for each_argument, each_parameter_name in zip(call_node.args, all_parameter_names):
+        if not isinstance(each_argument, ast.Name) or each_argument.id != each_parameter_name:
+            return False
+    return True
+
+
+def _function_is_async(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return isinstance(function_node, ast.AsyncFunctionDef)
+
+
+def _alias_target_name(call_node: ast.Call, all_sibling_function_names: set[str]) -> str:
+    callee = call_node.func
+    if not isinstance(callee, ast.Name):
+        return ""
+    return callee.id if callee.id in all_sibling_function_names else ""
+
+
+def _module_string_literal_values(parsed_tree: ast.AST) -> set[str]:
+    string_literal_values: set[str] = set()
+    for each_node in ast.walk(parsed_tree):
+        if isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            string_literal_values.add(each_node.value)
+    return string_literal_values
+
+
+def _target_accepts_forwarded_positional_call(
+    target_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    forwarded_argument_count: int,
+) -> bool:
+    arguments = target_node.args
+    if any(default is None for default in arguments.kw_defaults):
+        return False
+    positional_parameters = [*arguments.posonlyargs, *arguments.args]
+    total_positional_count = len(positional_parameters)
+    required_positional_count = total_positional_count - len(arguments.defaults)
+    if arguments.vararg is not None:
+        return forwarded_argument_count >= required_positional_count
+    return required_positional_count <= forwarded_argument_count <= total_positional_count
+
+
+def check_zero_payload_function_alias(content: str, file_path: str) -> list[str]:
+    """Flag a module-level function that only forwards its parameters to a sibling.
+
+    A function whose entire body (after an optional docstring) is a single
+    `return sibling_function(first_param, second_param, ...)` that forwards its
+    own parameters unchanged to another function defined in the same module is a
+    second name for one behavior — indirection without payload, which CODE_RULES
+    discourages. Callers should invoke the sibling directly. Both `def` and
+    `async def` forwarders are inspected.
+
+    A forwarder is left unflagged when any of these makes a direct call to the
+    target not equivalent to the alias: a decorator (caching, `@property`, route
+    registration); a parameter carrying a default value the target rejects; a
+    keyword-only / `*args` / `**kwargs` parameter on the alias; an awaitability
+    mismatch where one of the alias and target is `async def` and the other is
+    not; a forwarded positional call the live target's signature rejects (the
+    target has a keyword-only parameter without a default, or its positional
+    arity does not admit the forwarded argument count); or a name dispatched by a
+    string literal elsewhere in the module, where the named handler must exist for
+    a registry to resolve it.
+
+    Hook infrastructure is intentionally NOT exempt — pass-through aliases inside
+    hook modules are the motivating case. Test files and config files are exempt
+    because re-binding aliases are legitimate scaffolding there.
+
+    Args:
+        content: The source under inspection.
+        file_path: Path to the file, used for the test and config exemptions.
+
+    Returns:
+        One issue string per pass-through alias, capped at
+        MAX_ZERO_PAYLOAD_ALIAS_ISSUES.
+    """
+    if is_test_file(file_path) or is_config_file(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    function_node_by_name = _collect_module_function_nodes_by_name(parsed_tree)
+    all_sibling_function_names = set(function_node_by_name)
+    all_string_literal_values = _module_string_literal_values(parsed_tree)
+    issues: list[str] = []
+    for each_statement in parsed_tree.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if each_statement.decorator_list:
+            continue
+        if each_statement.name in all_string_literal_values:
+            continue
+        if not _has_only_positional_parameters(each_statement):
+            continue
+        call_node = _single_return_call(each_statement)
+        if call_node is None:
+            continue
+        target_name = _alias_target_name(call_node, all_sibling_function_names)
+        if not target_name or target_name == each_statement.name:
+            continue
+        target_node = function_node_by_name[target_name]
+        if _function_is_async(each_statement) != _function_is_async(target_node):
+            continue
+        forwarded_parameter_names = _function_parameter_names_in_order(each_statement)
+        if not _forwards_parameters_unchanged(call_node, forwarded_parameter_names):
+            continue
+        if not _target_accepts_forwarded_positional_call(
+            target_node, len(forwarded_parameter_names)
+        ):
+            continue
+        issues.append(
+            f"Line {each_statement.lineno}: {file_path}: zero-payload alias — "
+            f"{each_statement.name} only forwards its parameters to {target_name}; "
+            f"callers should call {target_name} directly (indirection without payload)"
+        )
+    return issues[:MAX_ZERO_PAYLOAD_ALIAS_ISSUES]
+
+
 def check_typed_dict_encode_decode(content: str, file_path: str) -> list[str]:
     """Flag TypedDict declarations missing companion `_encode_*` / `_decode_*` functions."""
     if (

package/hooks/blocking/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration package for the blocking hooks.
+
+A regular package (not a namespace package) so it resolves ahead of any
+same-named package later on ``sys.path``.
+"""

package/hooks/blocking/config/verified_commit_constants.py

@@ -0,0 +1,106 @@
+"""Constants for the verified-commit gate hook family.
+
+Shared by ``verification_verdict_store.py``, ``verified_commit_gate.py``,
+and ``verifier_verdict_minter.py`` so every tunable lives in one place.
+"""
+
+from __future__ import annotations
+
+GIT_TIMEOUT_SECONDS = 30
+ROOT_KEY_HEX_LENGTH = 16
+VERDICT_JSON_INDENT = 2
+CLAUDE_HOME_DIRECTORY_NAME = ".claude"
+VERDICT_DIRECTORY_NAME = "verification"
+VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN = r"['\"\\/,\s]+"
+VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN = r"(?=['\"]*[\\/,])"
+RELATIVE_VERDICT_DIRECTORY_PATTERN = r"(?:^|(?<=[\s;&|(='\"]))verification[\\/]"
+VERDICT_PATH_GLUE_PATTERN = r"['\"+\\/\s]*[\\/]['\"+\\/\s]*"
+VERDICT_DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?verification[\\/]?['\"]?(?=[\s;&|]|$)"
+VERDICT_PATH_JOINED_VARIABLE_PATTERN = r"\$\{?(\w+)\}?[\\/]|[\\/]\$\{?(\w+)\}?"
+VERDICT_PATH_VARIABLE_ASSIGNMENT_PATTERN = r"(?:^|(?<=[\s;&|(]))%s=(\S+)"
+VERDICT_FILE_RELATIVE_REFERENCE_PATTERN = (
+    rf"(?:^|(?<=[\s;&|(='\"\\/]))verification[\\/][0-9a-f]{{{ROOT_KEY_HEX_LENGTH}}}\.json"
+)
+PATH_OBFUSCATION_PRIMITIVE_PATTERN = (
+    r"chr\s*\(|bytes\.fromhex\s*\(|b64decode\s*\(|codecs\.decode\s*\("
+    r"|(?:bytes|bytearray)\s*\(\s*\[|\[char\[?\]?\]"
+)
+ALL_VERDICT_PATH_SEGMENT_NAMES = (".claude", "verification")
+ALL_VERDICT_PATH_SEGMENT_BODIES = ("claude", "verification")
+HEX_TOKEN_PATTERN = r"(?<![0-9a-fx])([0-9a-f]{6,})(?![0-9a-f])"
+BASE64_TOKEN_PATTERN = r"[A-Za-z0-9+/]{8,}={0,2}"
+CHARACTER_CODE_SEQUENCE_PATTERN = r"\d{1,3}(?:\s*,\s*\d{1,3})+"
+CHR_CALL_CHAIN_PATTERN = r"chr\(\s*\d{1,3}\s*\)(?:\s*\+\s*chr\(\s*\d{1,3}\s*\))+"
+CHR_CALL_CODE_PATTERN = r"chr\(\s*(\d{1,3})\s*\)"
+HEX_DIGITS_PER_BYTE = 2
+FILE_WRITE_PRIMITIVE_PATTERN = (
+    r"\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b|>"
+)
+NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN = (
+    r"\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b"
+)
+WRITE_CALL_REGION_PATTERN = (
+    r"(?:\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b)[^;&|\n]*"
+)
+VERDICT_KEY_ALL_PASS = "all_pass"
+VERDICT_KEY_MANIFEST_SHA256 = "manifest_sha256"
+DOCS_ONLY_EXTENSIONS = frozenset(
+    {".md", ".txt", ".rst", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico"}
+)
+PYTHON_EXTENSION = ".py"
+TEST_FILE_PREFIX = "test_"
+TEST_FILE_SUFFIX = "_test.py"
+CONFTEST_FILE_NAME = "conftest.py"
+MINIMUM_STATUS_FIELD_COUNT = 2
+ALL_FALLBACK_BASE_REFERENCES = ("origin/main", "origin/master")
+ALL_TOOLING_STATE_PREFIXES = (
+    ".claude/verification/",
+    ".claude/worktrees/",
+    ".claude/daemon/",
+    ".claude/teams/",
+    ".claude/sessions/",
+    ".cursor/worktrees/",
+)
+GATED_GIT_SUBCOMMANDS = frozenset({"commit", "push"})
+ALL_GIT_BINARY_NAMES = frozenset({"git", "git.exe"})
+VALUE_TAKING_GIT_OPTIONS = frozenset({"-C", "-c", "--git-dir", "--work-tree", "--namespace"})
+REPO_DIRECTORY_OPTION = "-C"
+WORK_TREE_OPTION = "--work-tree"
+DIRECTORY_CHANGE_VERBS = frozenset({"cd", "pushd", "set-location", "sl"})
+DIRECTORY_CHANGE_PATH_OPTIONS = frozenset({"-path", "-literalpath"})
+DIRECTORY_CHANGE_OPTION_TERMINATOR = "--"
+DIRECTORY_CHANGE_PATTERN_PREFIX = r"(?:^|(?<=[\s;&|(]))(?:"
+DIRECTORY_CHANGE_PATTERN_SUFFIX = r")(?=\s|$)"
+DIRECTORY_CHANGE_OPTION_PREFIX_PATTERN = r"(?:[ \t]+(?:%s)(?=\s|$))*"
+DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?\S*"
+CLAUDE_HOME_TARGET_BOUNDARY_PATTERN = r"[\\/]?['\"]?(?=[\s;&|]|$)"
+VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN = r"[\\/]?['\"]?(?=[\s;&|]|$)"
+COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN = r"[;&|\n][\s]*\S"
+OPTION_WITH_VALUE_STEP = 2
+ALL_GATED_TOOL_NAMES = ("Bash", "PowerShell")
+HASH_PREVIEW_LENGTH = 16
+MINTING_AGENT_TYPE = "code-verifier"
+SPAWN_LOOKUP_ATTEMPT_COUNT = 3
+SPAWN_LOOKUP_RETRY_DELAY_SECONDS = 0.1
+VERDICT_DIRECTORY_GUARD_MESSAGE = (
+    "BLOCKED: [VERDICT_DIRECTORY_GUARD] Shell access to the verification "
+    "verdict directory (~/.claude/verification/) is denied. Only the "
+    "verifier_verdict_minter.py SubagentStop hook writes verdict files; a "
+    "shell write here would forge a passing verdict and defeat the "
+    "verified-commit gate. Spawn the code-verifier agent to earn a verdict "
+    "instead of writing one."
+)
+CORRECTIVE_MESSAGE = (
+    "BLOCKED: [VERIFIED_COMMIT_GATE] This branch surface has no passing "
+    "verification verdict. Spawn the code-verifier agent (Agent tool, "
+    "subagent_type 'code-verifier') with the task texts, the diff scope, "
+    "and recorded baselines; when it finishes with a clean verdict the "
+    "SubagentStop hook mints the verdict and this command will pass. Any "
+    "file change after verification invalidates the verdict, so verify "
+    "last. Exempt automatically: docs/image files, pytest test files, and "
+    "Python files whose docstring- and comment-stripped AST is unchanged "
+    "(comment-only edits in non-Python files are not exempt)."
+)