claude-dev-env 1.59.0 → 1.61.0

package/hooks/blocking/test_code_rules_enforcer_orphan_css_class.py

@@ -0,0 +1,196 @@
+"""Unit tests for the orphan-CSS-class check in code_rules_enforcer hook."""
+
+import importlib.util
+import pathlib
+import sys
+import tempfile
+import textwrap
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "code_rules_orphan_css_class",
+    _HOOK_DIR / "code_rules_orphan_css_class.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+check_orphan_css_classes = hook_module.check_orphan_css_classes
+
+PRODUCTION_FILE_PATH = "packages/app/render/report.py"
+TEST_FILE_PATH = "packages/app/render/test_report.py"
+
+MARKUP_WITH_ORPHAN = (
+    "def render() -> str:\n"
+    '    style = "<style>.card { color: red; }</style>"\n'
+    '    body = \'<div class="card">x</div><div class="ghost">y</div>\'\n'
+    "    return style + body\n"
+)
+
+MARKUP_ALL_DEFINED = (
+    "def render() -> str:\n"
+    '    style = "<style>.card { color: red; } .row { margin: 0; }</style>"\n'
+    '    body = \'<div class="card"><span class="row">x</span></div>\'\n'
+    "    return style + body\n"
+)
+
+
+def test_should_flag_class_with_no_matching_selector() -> None:
+    issues = check_orphan_css_classes(MARKUP_WITH_ORPHAN, PRODUCTION_FILE_PATH)
+    assert any("'ghost'" in each_issue for each_issue in issues), (
+        f"Expected 'ghost' flagged as orphan, got: {issues}"
+    )
+
+
+def test_should_not_flag_class_with_matching_selector() -> None:
+    issues = check_orphan_css_classes(MARKUP_WITH_ORPHAN, PRODUCTION_FILE_PATH)
+    assert not any("'card'" in each_issue for each_issue in issues), (
+        f"'card' has a .card selector and must not flag, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_every_class_is_defined() -> None:
+    issues = check_orphan_css_classes(MARKUP_ALL_DEFINED, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Every class is defined; expected no issues, got: {issues}"
+
+
+def test_should_flag_each_class_in_a_multi_class_attribute() -> None:
+    content = (
+        "def render() -> str:\n"
+        '    style = "<style>.pf { padding: 0; }</style>"\n'
+        "    body = '<div class=\"pf problem\">x</div>'\n"
+        "    return style + body\n"
+    )
+    issues = check_orphan_css_classes(content, PRODUCTION_FILE_PATH)
+    assert any("'problem'" in each_issue for each_issue in issues), (
+        f"Second class 'problem' in the attribute must flag, got: {issues}"
+    )
+    assert not any("'pf'" in each_issue for each_issue in issues), (
+        f"First class 'pf' has a selector and must not flag, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_no_style_block_present() -> None:
+    content = "def render() -> str:\n    return '<div class=\"card\">x</div>'\n"
+    issues = check_orphan_css_classes(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"No <style> source nearby; the stylesheet lives outside the scan, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_no_class_attribute_present() -> None:
+    content = (
+        'def render() -> str:\n    return "<style>.card { color: red; }</style><div>x</div>"\n'
+    )
+    issues = check_orphan_css_classes(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"No class attribute in markup; got: {issues}"
+
+
+def test_should_skip_test_files() -> None:
+    issues = check_orphan_css_classes(MARKUP_WITH_ORPHAN, TEST_FILE_PATH)
+    assert issues == [], f"Test files are exempt; got: {issues}"
+
+
+def test_should_include_line_number_and_class_name() -> None:
+    issues = check_orphan_css_classes(MARKUP_WITH_ORPHAN, PRODUCTION_FILE_PATH)
+    orphan_issue = next(each for each in issues if "'ghost'" in each)
+    assert "Line 3" in orphan_issue, (
+        f"Orphan 'ghost' sits on line 3 of the markup; got: {orphan_issue}"
+    )
+
+
+def test_should_report_each_orphan_class_once() -> None:
+    content = (
+        "def render() -> str:\n"
+        '    style = "<style>.card { color: red; }</style>"\n'
+        "    a = '<div class=\"ghost\">x</div>'\n"
+        "    b = '<div class=\"ghost\">y</div>'\n"
+        "    return style + a + b\n"
+    )
+    issues = check_orphan_css_classes(content, PRODUCTION_FILE_PATH)
+    ghost_issues = [each for each in issues if "'ghost'" in each]
+    assert len(ghost_issues) == 1, f"A repeated orphan class reports once; got: {ghost_issues}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    content = "def broken(\n    this is not python\n"
+    issues = check_orphan_css_classes(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A syntax error yields no issues; got: {issues}"
+
+
+_SIBLING_MARKUP_SOURCE = textwrap.dedent(
+    """\
+    from report_constants import HTML_STYLE_BLOCK
+
+
+    def render() -> str:
+        body = (
+            '<details class="appendix">'
+            '<div class="appendix-body">x</div></details>'
+        )
+        return HTML_STYLE_BLOCK + body
+    """
+)
+
+
+@pytest.fixture
+def production_render_package() -> Iterator[Path]:
+    """Yield a neutrally named package directory for the markup and constants modules.
+
+    pytest's ``tmp_path`` carries the test function name, so any path under it
+    holds a ``test_`` segment that the enforcer's ``is_test_file`` predicate
+    matches and exempts. A package created under the default ``tempfile`` prefix
+    keeps that segment out of the path, so the cross-module orphan-class check
+    runs against the markup module as production code.
+
+    Yields:
+        A freshly created package directory, removed when the test finishes.
+    """
+    with tempfile.TemporaryDirectory() as base_directory:
+        package_directory = Path(base_directory) / "render"
+        package_directory.mkdir()
+        yield package_directory
+
+
+def test_should_resolve_selectors_from_a_sibling_module(
+    production_render_package: Path,
+) -> None:
+    constants_module = production_render_package / "report_constants.py"
+    constants_module.write_text(
+        'HTML_STYLE_BLOCK = "<style>.appendix { margin: 0; }'
+        ' .appendix-body { padding: 0; }</style>"\n',
+        encoding="utf-8",
+    )
+    markup_module = production_render_package / "report.py"
+    markup_module.write_text(_SIBLING_MARKUP_SOURCE, encoding="utf-8")
+    issues = check_orphan_css_classes(_SIBLING_MARKUP_SOURCE, str(markup_module))
+    assert issues == [], (
+        f"A sibling module defines every selector; expected no issues, got: {issues}"
+    )
+
+
+def test_should_flag_orphan_even_when_a_sibling_defines_other_selectors(
+    production_render_package: Path,
+) -> None:
+    constants_module = production_render_package / "report_constants.py"
+    constants_module.write_text(
+        'HTML_STYLE_BLOCK = "<style>.appendix { margin: 0; }</style>"\n',
+        encoding="utf-8",
+    )
+    markup_module = production_render_package / "report.py"
+    markup_module.write_text(_SIBLING_MARKUP_SOURCE, encoding="utf-8")
+    issues = check_orphan_css_classes(_SIBLING_MARKUP_SOURCE, str(markup_module))
+    assert any("'appendix-body'" in each_issue for each_issue in issues), (
+        f"'appendix-body' has no selector in any sibling; must flag, got: {issues}"
+    )
+    assert not any(
+        "'appendix'" in each_issue and "appendix-body" not in each_issue
+        for each_issue in issues
+    ), f"'appendix' is defined in the sibling and must not flag, 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}"
+    )