claude-dev-env 1.58.0 → 1.60.0

package/hooks/blocking/test_code_rules_enforcer_zero_payload_alias.py

@@ -0,0 +1,415 @@
+"""Tests for check_zero_payload_function_alias — flag pass-through function aliases.
+
+CODE_RULES §9.5 discourages indirection without payload. A function whose entire
+body (after an optional docstring) is a single `return other_function(...)` that
+forwards its own parameters unchanged to another function defined in the same
+module is a second name for one behavior. Callers should invoke the real function
+directly. This check operates at function granularity, complementing the
+module-level thin-wrapper check.
+
+Hook infrastructure is NOT exempt: pass-through aliases inside hook modules are
+the original motivating case. Test files and config files remain exempt because
+re-binding aliases are legitimate scaffolding there.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_zero_payload_function_alias(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_zero_payload_function_alias(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/src/detection.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/detection.py"
+TEST_FILE_PATH = "/project/src/test_detection.py"
+CONFIG_FILE_PATH = "/project/config/detection.py"
+
+
+def test_should_flag_pass_through_alias_forwarding_same_parameters() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_bare_index_segments(content: str) -> set[str]:\n"
+        "    return find_bare_path_segments(content)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert any("find_bare_index_segments" in each for each in issues), (
+        f"Expected pass-through alias flag, got: {issues!r}"
+    )
+
+
+def test_should_flag_alias_inside_hook_infrastructure() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_bare_index_segments(content: str) -> set[str]:\n"
+        "    return find_bare_path_segments(content)\n"
+    )
+    issues = check_zero_payload_function_alias(source, HOOK_INFRASTRUCTURE_PATH)
+    assert any("find_bare_index_segments" in each for each in issues), (
+        f"Hook infrastructure is the motivating case and must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_alias_with_docstring_before_return() -> None:
+    source = (
+        "def compute_total(amount: int) -> int:\n"
+        "    return amount * 2\n"
+        "\n"
+        "def calculate_total(amount: int) -> int:\n"
+        '    """Forward to compute_total."""\n'
+        "    return compute_total(amount)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert any("calculate_total" in each for each in issues), (
+        f"A docstring before the single return must not hide the alias, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_that_transforms_arguments() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_stripped_segments(content: str) -> set[str]:\n"
+        "    return find_bare_path_segments(content.strip())\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Transformed argument adds payload and must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_that_reorders_arguments() -> None:
+    source = (
+        "def divide(numerator: int, denominator: int) -> float:\n"
+        "    return numerator / denominator\n"
+        "\n"
+        "def inverse_divide(denominator: int, numerator: int) -> float:\n"
+        "    return divide(numerator, denominator)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Reordered arguments change behavior and must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_call_to_external_function() -> None:
+    source = (
+        "from other_module import real_helper\n"
+        "\n"
+        "def public_helper(value: int) -> int:\n"
+        "    return real_helper(value)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A boundary wrapper around an imported function is not a same-module alias, "
+        f"got: {issues!r}"
+    )
+
+
+def test_should_not_flag_method_call() -> None:
+    source = (
+        "def normalize(text: str) -> str:\n"
+        "    return text.strip()\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A call to a method on a parameter is real work, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_with_multiple_statements() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_logged_segments(content: str) -> set[str]:\n"
+        "    all_segments = find_bare_path_segments(content)\n"
+        "    return all_segments\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A body with an intermediate binding is not a single pass-through, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_that_drops_keyword_only_parameter() -> None:
+    source = (
+        "def target(first: int) -> int:\n"
+        "    return first\n"
+        "\n"
+        "def alias(first: int, *, second: int) -> int:\n"
+        "    return target(first)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Dropping a keyword-only parameter changes behavior, not a pure alias, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_that_drops_var_positional_parameter() -> None:
+    source = (
+        "def target(first: int) -> int:\n"
+        "    return first\n"
+        "\n"
+        "def alias(first: int, *rest: int) -> int:\n"
+        "    return target(first)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Dropping *args changes behavior, not a pure alias, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_that_drops_var_keyword_parameter() -> None:
+    source = (
+        "def target(first: int) -> int:\n"
+        "    return first\n"
+        "\n"
+        "def alias(first: int, **rest: int) -> int:\n"
+        "    return target(first)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Dropping **kwargs changes behavior, not a pure alias, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_bare_index_segments(content: str) -> set[str]:\n"
+        "    return find_bare_path_segments(content)\n"
+    )
+    issues = check_zero_payload_function_alias(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_config_file() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_bare_index_segments(content: str) -> set[str]:\n"
+        "    return find_bare_path_segments(content)\n"
+    )
+    issues = check_zero_payload_function_alias(source, CONFIG_FILE_PATH)
+    assert issues == [], f"config/ files exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_zero_payload_function_alias("def broken(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_should_not_flag_empty_file() -> None:
+    issues = check_zero_payload_function_alias("", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Empty file must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_recursive_self_call() -> None:
+    source = (
+        "def walk(node: int) -> int:\n"
+        "    return walk(node)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A self-call is recursion, not a zero-payload alias, got: {issues!r}"
+    )
+
+
+def test_should_flag_through_validate_content_for_hook_file() -> None:
+    source = (
+        "def find_bare_path_segments(content: str) -> set[str]:\n"
+        "    return {part for part in content.split() if part}\n"
+        "\n"
+        "def find_bare_index_segments(content: str) -> set[str]:\n"
+        "    return find_bare_path_segments(content)\n"
+    )
+    issues = code_rules_enforcer.validate_content(source, HOOK_INFRASTRUCTURE_PATH)
+    assert any("find_bare_index_segments" in each for each in issues), (
+        f"validate_content must surface the alias for hook files, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_property_decorated_forwarder() -> None:
+    source = (
+        "def compute_total(amount: int) -> int:\n"
+        "    return amount * 2\n"
+        "\n"
+        "class Cart:\n"
+        "    @property\n"
+        "    def total(self, amount: int) -> int:\n"
+        "        return compute_total(amount)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A @property forwarder gains attribute semantics, not a zero-payload alias, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_lru_cache_decorated_forwarder() -> None:
+    source = (
+        "import functools\n"
+        "\n"
+        "def lookup(key: int) -> int:\n"
+        "    return key\n"
+        "\n"
+        "@functools.lru_cache\n"
+        "def cached_lookup(key: int) -> int:\n"
+        "    return lookup(key)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"An @lru_cache forwarder adds memoization the target lacks, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_forwarder_that_adds_a_default_value() -> None:
+    source = (
+        "def target(first: int, second: int) -> int:\n"
+        "    return first + second\n"
+        "\n"
+        "def alias(first: int, second: int = 5) -> int:\n"
+        "    return target(first, second)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A default value makes a call shape valid that the target rejects, got: {issues!r}"
+    )
+
+
+def test_should_flag_async_pass_through_alias() -> None:
+    source = (
+        "async def real(value: int) -> int:\n"
+        "    return value\n"
+        "\n"
+        "async def alias(value: int) -> int:\n"
+        "    return real(value)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert any("alias" in each for each in issues), (
+        f"An async pass-through alias must be flagged like its sync twin, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_sync_alias_to_async_target() -> None:
+    source = (
+        "async def target(first: int) -> int:\n"
+        "    return first\n"
+        "\n"
+        "def alias(first: int) -> int:\n"
+        "    return target(first)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A sync alias to an async target returns a coroutine, changing the contract, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_async_alias_to_sync_target() -> None:
+    source = (
+        "def target(first: int) -> int:\n"
+        "    return first\n"
+        "\n"
+        "async def alias(first: int) -> int:\n"
+        "    return target(first)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"An async alias to a sync target changes the awaitability contract, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_forwarder_whose_name_is_a_string_dispatch_target() -> None:
+    source = (
+        "from typing import Literal\n"
+        "\n"
+        "TransformName = Literal[\"verbatim\", \"near_verbatim\"]\n"
+        "\n"
+        "def strip_anthropic_refs(text: str) -> str:\n"
+        "    return text.replace(\"Anthropic\", \"\")\n"
+        "\n"
+        "def near_verbatim(text: str) -> str:\n"
+        "    return strip_anthropic_refs(text)\n"
+        "\n"
+        "def apply_transform(name: TransformName, text: str) -> str:\n"
+        "    if name == \"near_verbatim\":\n"
+        "        return near_verbatim(text)\n"
+        "    return text\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "A forwarder dispatched by its own name through a string literal must stay, "
+        f"got: {issues!r}"
+    )
+
+
+def test_should_not_flag_forwarder_calling_keyword_only_target_positionally() -> None:
+    source = (
+        "def target(first: int, *, second: int) -> int:\n"
+        "    return first + second\n"
+        "\n"
+        "def alias(first: int, second: int) -> int:\n"
+        "    return target(first, second)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "The target rejects the forwarded positional call (second is keyword-only), "
+        f"so the alias is not interchangeable with a direct call, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_forwarder_whose_arity_mismatches_redefined_target() -> None:
+    source = (
+        "def target(first: int) -> int:\n"
+        "    return first\n"
+        "\n"
+        "def alias(first: int) -> int:\n"
+        "    return target(first)\n"
+        "\n"
+        "def target(first: int, second: int) -> int:\n"
+        "    return first + second\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        "The live target needs two positional arguments but the forwarder passes one, "
+        f"so the forwarded call is invalid against the live target, got: {issues!r}"
+    )
+
+
+def test_should_flag_forwarder_calling_default_bearing_target_positionally() -> None:
+    source = (
+        "def target(first: int, second: int = 5) -> int:\n"
+        "    return first + second\n"
+        "\n"
+        "def alias(first: int, second: int) -> int:\n"
+        "    return target(first, second)\n"
+    )
+    issues = check_zero_payload_function_alias(source, PRODUCTION_FILE_PATH)
+    assert any("alias" in each for each in issues), (
+        "The target accepts the forwarded positional call, so the alias is a true "
+        f"pass-through and must be flagged, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_zero_payload_alias_hook_routing.py

@@ -0,0 +1,156 @@
+"""Entry-point tests proving the zero-payload-alias check guards hook-infrastructure files.
+
+A pass-through alias inside a hook module is the motivating case for the
+zero-payload-alias check, so the deny must fire on the same PreToolUse path a
+live Write into ``packages/claude-dev-env/hooks/blocking`` would take — not only
+through ``validate_content``, which hook files never reach at PreToolUse. These
+tests drive the real ``main()`` stdin entry point and the pre-check CLI with a
+hook-infrastructure target.
+
+Each test builds a temporary tree whose tail mirrors a production hook directory
+(``packages/claude-dev-env/hooks/blocking``) so ``is_hook_infrastructure`` matches
+the target path the same way it would for the real directory.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import pathlib
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterator
+from types import SimpleNamespace
+
+import pytest
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).resolve().parent
+_HOOKS_PARENT = _HOOK_DIRECTORY.parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+if str(_HOOKS_PARENT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_PARENT))
+
+from code_rules_enforcer import main  # noqa: E402
+
+code_rules_enforcer = SimpleNamespace(main=main, sys=sys)
+
+_ENFORCER_SCRIPT_PATH = _HOOK_DIRECTORY / "code_rules_enforcer.py"
+
+PASS_THROUGH_ALIAS_SOURCE = (
+    "def find_bare_path_segments(content: str) -> set[str]:\n"
+    "    return {part for part in content.split() if part}\n"
+    "\n"
+    "def find_bare_index_segments(content: str) -> set[str]:\n"
+    "    return find_bare_path_segments(content)\n"
+)
+
+_HOOK_INFRASTRUCTURE_TAIL = pathlib.Path("packages") / "claude-dev-env" / "hooks" / "blocking"
+
+
+@pytest.fixture
+def hook_blocking_dir() -> Iterator[pathlib.Path]:
+    base_directory = pathlib.Path(tempfile.mkdtemp())
+    blocking_directory = base_directory / _HOOK_INFRASTRUCTURE_TAIL
+    blocking_directory.mkdir(parents=True)
+    try:
+        yield blocking_directory
+    finally:
+        shutil.rmtree(base_directory, ignore_errors=False)
+
+
+def _run_main_with_write_payload(
+    file_path: str,
+    content: str,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> str:
+    """Drive ``main()`` through its stdin entry point for a Write and return stdout.
+
+    Args:
+        file_path: The on-disk path the Write targets.
+        content: The whole-file body the Write would create.
+        monkeypatch: The fixture used to redirect ``sys.stdin``.
+        capsys: The fixture used to capture the deny payload on stdout.
+
+    Returns:
+        The captured stdout, which holds the deny payload when violations fire.
+    """
+    write_payload = json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": file_path, "content": content},
+        }
+    )
+    monkeypatch.setattr(code_rules_enforcer.sys, "stdin", io.StringIO(write_payload))
+    with contextlib.suppress(SystemExit):
+        code_rules_enforcer.main([])
+    return capsys.readouterr().out
+
+
+def test_write_of_pass_through_alias_into_hook_directory_denies(
+    hook_blocking_dir: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A Write that introduces a pass-through alias into a hook file is denied.
+
+    The target lives under a hook-infrastructure path the full code-rules suite
+    exempts, so this proves the zero-payload-alias check still fires on the exact
+    directory its docstring names as the motivating case — at the PreToolUse Write
+    point, not only through ``validate_content``."""
+    new_file = hook_blocking_dir / "new_blocker.py"
+    stdout = _run_main_with_write_payload(
+        str(new_file), PASS_THROUGH_ALIAS_SOURCE, monkeypatch, capsys
+    )
+    assert stdout != "", (
+        "A pass-through alias written into a hook-infrastructure file must produce "
+        "a deny payload, got empty stdout"
+    )
+    deny_payload = json.loads(stdout)
+    decision = deny_payload["hookSpecificOutput"]["permissionDecision"]
+    reason = deny_payload["hookSpecificOutput"]["permissionDecisionReason"]
+    assert decision == "deny", f"expected deny, got: {decision!r}"
+    assert "find_bare_index_segments" in reason, (
+        f"the deny reason must name the pass-through alias, got: {reason!r}"
+    )
+
+
+def test_precheck_of_pass_through_alias_at_hook_target_exits_nonzero(
+    hook_blocking_dir: pathlib.Path,
+    tmp_path_factory: pytest.TempPathFactory,
+) -> None:
+    """The pre-check CLI flags a pass-through alias judged at a hook-infrastructure target.
+
+    Driving the real ``--check`` argv path proves the gate's pre-check mode also
+    routes a hook ``.py`` target through the zero-payload-alias check rather than
+    exiting clean on the blanket hook-infrastructure exemption."""
+    staging_directory = tmp_path_factory.mktemp("staging")
+    candidate_file = staging_directory / "candidate.py"
+    candidate_file.write_text(PASS_THROUGH_ALIAS_SOURCE, encoding="utf-8")
+    target_path = str(hook_blocking_dir / "new_blocker.py")
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(_ENFORCER_SCRIPT_PATH),
+            "--check",
+            str(candidate_file),
+            "--as",
+            target_path,
+        ],
+        input="",
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert completed.returncode == 1, (
+        "a pass-through alias at a hook target must exit nonzero, got: "
+        f"{completed.returncode}, stdout: {completed.stdout!r}, "
+        f"stderr: {completed.stderr!r}"
+    )
+    assert "find_bare_index_segments" in completed.stdout, (
+        f"the pre-check must name the pass-through alias, got: {completed.stdout!r}"
+    )