claude-dev-env 1.59.0 → 1.60.0

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import stat
+import tempfile
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+import pytest
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location("code_rules_enforcer", ENFORCER_PATH)
+assert specification is not None and specification.loader is not None
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+CONSTANTS_BODY = 'MEDIUM_TERMINAL = "terminal"\nMEDIUM_CODE = "code"\nMEDIUM_TEXT = "text"\n'
+
+
+def _strip_read_only_and_retry(
+    removal_function: Callable[[str], object],
+    target_path: str,
+    _exc_info: BaseException,
+) -> None:
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+@pytest.fixture
+def neutral_root() -> Iterator[Path]:
+    """Yield a temp directory whose path carries no ``test_`` segment.
+
+    The enforcer's ``is_test_file`` keys on the full path string, and pytest's
+    own ``tmp_path`` directory name embeds the test name, which would make every
+    synthetic constants path look like a test file. A neutral ``mkdtemp`` root
+    mirrors how a production constants module path looks.
+    """
+    neutral_directory = Path(tempfile.mkdtemp(prefix="deadconst-")).resolve()
+    try:
+        yield neutral_directory
+    finally:
+        shutil.rmtree(neutral_directory, onexc=_strip_read_only_and_retry)
+
+
+def _check(source: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_module_constants(source, file_path)
+
+
+def _build_constants_package(
+    workflow_directory: Path,
+    constants_body: str,
+    consumer_body: str,
+) -> Path:
+    constants_package = workflow_directory / "report_constants"
+    constants_package.mkdir(parents=True)
+    (constants_package / "__init__.py").write_text("", encoding="utf-8")
+    constants_path = constants_package / "render_report_constants.py"
+    constants_path.write_text(constants_body, encoding="utf-8")
+    (workflow_directory / "render_report.py").write_text(consumer_body, encoding="utf-8")
+    return constants_path
+
+
+def test_flags_constant_imported_by_no_module_in_the_tree(neutral_root: Path) -> None:
+    consumer_body = (
+        "from report_constants.render_report_constants import (\n"
+        "    MEDIUM_CODE,\n"
+        "    MEDIUM_TERMINAL,\n"
+        ")\n"
+        "\n"
+        "def panel_class(medium: str) -> str:\n"
+        "    if medium == MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    return 'code-panel' if medium == MEDIUM_CODE else 'text-panel'\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", CONSTANTS_BODY, consumer_body
+    )
+    issues = _check(CONSTANTS_BODY, str(constants_path))
+    assert any("MEDIUM_TEXT" in each_issue for each_issue in issues), (
+        f"Expected dead MEDIUM_TEXT flagged, got: {issues}"
+    )
+    assert not any(
+        "MEDIUM_TERMINAL" in each_issue or "MEDIUM_CODE" in each_issue for each_issue in issues
+    ), f"Imported constants must not be flagged, got: {issues}"
+
+
+def test_does_not_flag_constant_imported_one_directory_up(neutral_root: Path) -> None:
+    consumer_uses_text = (
+        "from report_constants.render_report_constants import (\n"
+        "    MEDIUM_CODE,\n"
+        "    MEDIUM_TERMINAL,\n"
+        "    MEDIUM_TEXT,\n"
+        ")\n"
+        "\n"
+        "def panel_class(medium: str) -> str:\n"
+        "    if medium == MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    if medium == MEDIUM_TEXT:\n"
+        "        return 'text-panel'\n"
+        "    return 'code-panel' if medium == MEDIUM_CODE else 'text-panel'\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", CONSTANTS_BODY, consumer_uses_text
+    )
+    issues = _check(CONSTANTS_BODY, str(constants_path))
+    assert issues == [], f"No constant is dead when all are imported, got: {issues}"
+
+
+def test_does_not_flag_when_module_declares_dunder_all(neutral_root: Path) -> None:
+    constants_body = CONSTANTS_BODY + '__all__ = ["MEDIUM_TERMINAL"]\n'
+    consumer_body = (
+        "from report_constants.render_report_constants import MEDIUM_TERMINAL\n"
+        "\n"
+        "def label() -> str:\n"
+        "    return MEDIUM_TERMINAL\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", constants_body, consumer_body
+    )
+    issues = _check(constants_body, str(constants_path))
+    assert issues == [], f"__all__ surface suppresses the check, got: {issues}"
+
+
+def test_does_not_run_on_ordinary_production_module(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    workflow_directory.mkdir(parents=True)
+    ordinary_path = workflow_directory / "render_report.py"
+    body = "WIDGET_LIMIT = 5\n\ndef widgets() -> int:\n    return WIDGET_LIMIT\n"
+    ordinary_path.write_text(body, encoding="utf-8")
+    issues = _check(body, str(ordinary_path))
+    assert issues == [], (
+        f"The dead-constant check runs only on dedicated constants modules, got: {issues}"
+    )
+
+
+def test_runs_on_config_directory_module(neutral_root: Path) -> None:
+    package_directory = neutral_root / "app"
+    config_directory = package_directory / "config"
+    config_directory.mkdir(parents=True)
+    constants_body = "TIMEOUT_SECONDS = 30\nUNUSED_THRESHOLD = 99\n"
+    constants_path = config_directory / "timing.py"
+    constants_path.write_text(constants_body, encoding="utf-8")
+    consumer_body = (
+        "from config.timing import TIMEOUT_SECONDS\n"
+        "\n"
+        "def deadline() -> int:\n"
+        "    return TIMEOUT_SECONDS\n"
+    )
+    (package_directory / "service.py").write_text(consumer_body, encoding="utf-8")
+    issues = _check(constants_body, str(constants_path))
+    assert any("UNUSED_THRESHOLD" in each_issue for each_issue in issues), (
+        f"Expected dead UNUSED_THRESHOLD flagged in config module, got: {issues}"
+    )
+    assert not any("TIMEOUT_SECONDS" in each_issue for each_issue in issues), (
+        f"Consumed config constant must not be flagged, got: {issues}"
+    )
+
+
+def test_counts_a_reference_from_a_test_module(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    constants_body = 'ONLY_TESTS_USE_THIS = "x"\n'
+    constants_path = workflow_directory / "render_report_constants.py"
+    workflow_directory.mkdir(parents=True)
+    constants_path.write_text(constants_body, encoding="utf-8")
+    test_body = (
+        "from render_report_constants import ONLY_TESTS_USE_THIS\n"
+        "\n"
+        "def test_value() -> None:\n"
+        "    assert ONLY_TESTS_USE_THIS == 'x'\n"
+    )
+    (workflow_directory / "test_render_report.py").write_text(test_body, encoding="utf-8")
+    issues = _check(constants_body, str(constants_path))
+    assert issues == [], f"A constant used only by a test under the tree stays live, got: {issues}"
+
+
+def test_is_skipped_on_a_constants_test_file(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    workflow_directory.mkdir(parents=True)
+    test_constants_path = workflow_directory / "test_render_report_constants.py"
+    body = 'UNREFERENCED = "y"\n'
+    test_constants_path.write_text(body, encoding="utf-8")
+    issues = _check(body, str(test_constants_path))
+    assert issues == [], f"Test files are exempt, got: {issues}"

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}"
+    )