claude-dev-env 1.72.0 → 1.74.0

package/hooks/blocking/test_code_rules_enforcer_docstring_unguarded_payload.py

@@ -0,0 +1,188 @@
+"""Tests for check_docstring_unguarded_malformed_payload_claim — Category O6 drift.
+
+A function docstring that promises "a malformed payload resolves to None" asserts
+the body catches a bad payload and turns it into a None return. The claim drifts
+when the value construction that dereferences payload fields (``payload["key"]``,
+``float(payload["key"])``) sits OUTSIDE the try/except whose handler returns None:
+a present-but-malformed payload raises KeyError or TypeError from that unguarded
+dereference and propagates rather than resolving to None. This is the deterministic
+slice of Category O6 (docstring prose vs implementation drift) for an
+exception-guard claim.
+"""
+
+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_docstring_unguarded_malformed_payload_claim(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_unguarded_malformed_payload_claim(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/shared/human_actions.py"
+TEST_FILE_PATH = "/project/shared/test_human_actions.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+_UNGUARDED_DEREFERENCE_BODY = (
+    "def read_metrics(self, selector: str) -> object:\n"
+    '    """Read the container geometry over CDP, or None on failure.\n'
+    "\n"
+    "    A missing element, a CDP error, or a malformed payload resolves to None\n"
+    "    so the caller skips the drag.\n"
+    '    """\n'
+    "    try:\n"
+    "        evaluate_payload = self.cdp.run(selector)\n"
+    "        parsed_metrics = json.loads(evaluate_payload)\n"
+    "    except (KeyError, TypeError, ValueError):\n"
+    "        return None\n"
+    '    if not parsed_metrics.get("found"):\n'
+    "        return None\n"
+    "    return Metrics(\n"
+    '        client_width=float(parsed_metrics["client_width"]),\n'
+    '        client_height=float(parsed_metrics["client_height"]),\n'
+    "    )\n"
+)
+
+
+def test_flags_dereference_outside_the_guarded_block() -> None:
+    issues = check_docstring_unguarded_malformed_payload_claim(
+        _UNGUARDED_DEREFERENCE_BODY, PRODUCTION_FILE_PATH
+    )
+    assert len(issues) == 1
+    assert "read_metrics" in issues[0]
+
+
+def test_passes_when_dereference_sits_inside_the_guarded_block() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the container geometry over CDP, or None on failure.\n'
+        "\n"
+        "    A missing element, a CDP error, or a malformed payload resolves to None\n"
+        "    so the caller skips the drag.\n"
+        '    """\n'
+        "    try:\n"
+        "        evaluate_payload = self.cdp.run(selector)\n"
+        "        parsed_metrics = json.loads(evaluate_payload)\n"
+        '        if not parsed_metrics.get("found"):\n'
+        "            return None\n"
+        "        return Metrics(\n"
+        '            client_width=float(parsed_metrics["client_width"]),\n'
+        '            client_height=float(parsed_metrics["client_height"]),\n'
+        "        )\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_docstring_makes_no_malformed_payload_claim() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the container geometry over CDP, or None on failure."""\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        "    return Metrics(\n"
+        '        client_width=float(parsed_metrics["client_width"]),\n'
+        "    )\n"
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_no_subscript_dereference_follows_the_guard() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the geometry over CDP, or None on failure.\n'
+        "\n"
+        "    A malformed payload resolves to None so the caller skips the drag.\n"
+        '    """\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        '    return parsed_metrics.get("found")\n'
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_post_guard_subscript_dereferences_an_unrelated_name() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the geometry over CDP, or None on failure.\n'
+        "\n"
+        "    A malformed payload resolves to None so the caller skips the drag.\n"
+        '    """\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        '        width = float(parsed_metrics["client_width"])\n'
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        "    fallback = cache[selector]\n"
+        "    return Metrics(client_width=width, fallback=fallback)\n"
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def _unguarded_body_with_claim(claim_sentence: str) -> str:
+    return (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the container geometry over CDP, or None on failure.\n'
+        "\n"
+        f"    {claim_sentence}\n"
+        '    """\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        '    return float(parsed_metrics["client_width"])\n'
+    )
+
+
+def test_article_prefixed_claim_phrasings_still_flag_via_articleless_substring() -> None:
+    all_article_prefixed_claims = (
+        "A malformed payload resolves to None so the caller skips the drag.",
+        "A bad payload resolves to None so the caller skips the drag.",
+        "An invalid payload resolves to None so the caller skips the drag.",
+        "A malformed payload yields None so the caller skips the drag.",
+    )
+    for each_claim in all_article_prefixed_claims:
+        issues = check_docstring_unguarded_malformed_payload_claim(
+            _unguarded_body_with_claim(each_claim), PRODUCTION_FILE_PATH
+        )
+        assert len(issues) == 1
+        assert "read_metrics" in issues[0]
+
+
+def test_test_files_are_exempt() -> None:
+    assert (
+        check_docstring_unguarded_malformed_payload_claim(
+            _UNGUARDED_DEREFERENCE_BODY, TEST_FILE_PATH
+        )
+        == []
+    )
+
+
+def test_hook_infrastructure_is_exempt() -> None:
+    assert (
+        check_docstring_unguarded_malformed_payload_claim(
+            _UNGUARDED_DEREFERENCE_BODY, HOOK_INFRASTRUCTURE_PATH
+        )
+        == []
+    )

package/hooks/blocking/test_code_rules_enforcer_module_docstring_roster.py

@@ -0,0 +1,279 @@
+"""Tests for the module-docstring check roster and docstring tuple-enumeration checks.
+
+Both checks catch docstring-prose-vs-implementation drift in a check-registry
+module — a hook module that exposes several public ``check_*`` functions and a
+module-level tuple of literal attribute names. The drift the
+``code_rules_test_assertions.py`` module hit at PR #713 HEAD: a one-line module
+docstring that names four of its five public checks, and a function docstring
+that enumerates three plumbing attributes while the tuple it reads holds four.
+"""
+
+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_module_docstring_names_public_checks(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_module_docstring_names_public_checks(content, file_path)
+
+
+def check_docstring_tuple_enumeration_match(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_tuple_enumeration_match(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/code_rules_test_assertions.py"
+PRODUCTION_FILE_PATH = "/project/src/registry.py"
+TEST_FILE_PATH = "/project/src/test_registry.py"
+
+
+def _registry_module_omitting_a_check() -> str:
+    return (
+        '"""Skip-decorator, existence-only, and constant-equality test-quality checks."""\n'
+        "\n"
+        "def check_skip_decorators(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_existence_check(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_constant_equality(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_behavior_named_mock(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+    )
+
+
+def test_should_flag_module_docstring_omitting_a_public_check() -> None:
+    issues = check_module_docstring_names_public_checks(
+        _registry_module_omitting_a_check(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert any("check_behavior_named_mock" in each for each in issues), (
+        f"Expected the omitted check to flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_module_docstring_naming_every_public_check() -> None:
+    source = (
+        '"""Skip-decorator, existence-check, constant-equality, and behavior-named-mock checks."""\n'
+        "\n"
+        "def check_skip_decorators(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_existence_check(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_constant_equality(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_behavior_named_mock(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+    )
+    issues = check_module_docstring_names_public_checks(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Docstring naming every check must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_module_with_a_single_public_check() -> None:
+    source = (
+        '"""Skip-decorator test-quality check."""\n'
+        "\n"
+        "def check_skip_decorators(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+    )
+    issues = check_module_docstring_names_public_checks(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"A one-check module must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_multi_paragraph_module_docstring() -> None:
+    source = (
+        '"""Skip-decorator and existence-check test-quality checks.\n'
+        "\n"
+        "    The roster grows over time; the audit lane reads the full prose body.\n"
+        '    """\n'
+        "\n"
+        "def check_skip_decorators(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_behavior_named_mock(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+    )
+    issues = check_module_docstring_names_public_checks(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Multi-paragraph docstrings go to the audit lane, got: {issues!r}"
+
+
+def test_should_skip_module_without_docstring() -> None:
+    source = (
+        "def check_skip_decorators(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_behavior_named_mock(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+    )
+    issues = check_module_docstring_names_public_checks(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"No-docstring modules are out of scope, got: {issues!r}"
+
+
+def test_should_skip_private_check_helpers() -> None:
+    source = (
+        '"""Skip-decorator and existence-check test-quality checks."""\n'
+        "\n"
+        "def check_skip_decorators(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_existence_check(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def _check_internal_helper(content: str) -> bool:\n"
+        "    return False\n"
+    )
+    issues = check_module_docstring_names_public_checks(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Private check helpers are not roster surface, got: {issues!r}"
+
+
+def test_should_skip_test_file_for_module_roster() -> None:
+    issues = check_module_docstring_names_public_checks(
+        _registry_module_omitting_a_check(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_handle_module_roster_syntax_error_gracefully() -> None:
+    issues = check_module_docstring_names_public_checks("def broken(\n", HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def _module_with_drifted_tuple_enumeration() -> str:
+    return (
+        '"""Call-args plumbing detection."""\n'
+        "\n"
+        '_CALL_ARGS_PLUMBING_ATTRIBUTES = ("call_args", "call_args_list", "called", "call_count")\n'
+        "\n"
+        "def check_plumbing(content: str, file_path: str) -> list[str]:\n"
+        '    """Advise when a test asserts only on call-args plumbing.\n'
+        "\n"
+        "    A body asserting on call-args plumbing (``call_args``, ``call_args_list``,\n"
+        "    ``.kwargs``) reaches into mock internals rather than observed behavior.\n"
+        '    """\n'
+        "    for each_name in _CALL_ARGS_PLUMBING_ATTRIBUTES:\n"
+        "        if each_name in content:\n"
+        "            return [each_name]\n"
+        "    return []\n"
+    )
+
+
+def test_should_flag_docstring_tuple_enumeration_drift() -> None:
+    issues = check_docstring_tuple_enumeration_match(
+        _module_with_drifted_tuple_enumeration(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert any("check_plumbing" in each for each in issues), (
+        f"Expected the drifted enumeration to flag, got: {issues!r}"
+    )
+    assert any("kwargs" in each for each in issues), (
+        f"Expected the docstring-only token named in the message, got: {issues!r}"
+    )
+    assert any("called" in each for each in issues), (
+        f"Expected a tuple-only member named in the message, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_docstring_tuple_enumeration_match() -> None:
+    source = (
+        '"""Call-args plumbing detection."""\n'
+        "\n"
+        '_CALL_ARGS_PLUMBING_ATTRIBUTES = ("call_args", "call_args_list", "called", "call_count")\n'
+        "\n"
+        "def check_plumbing(content: str, file_path: str) -> list[str]:\n"
+        '    """Advise when a test asserts only on call-args plumbing.\n'
+        "\n"
+        "    A body asserting on call-args plumbing (``call_args``, ``call_args_list``,\n"
+        "    ``called``, ``call_count``) reaches into mock internals.\n"
+        '    """\n'
+        "    for each_name in _CALL_ARGS_PLUMBING_ATTRIBUTES:\n"
+        "        if each_name in content:\n"
+        "            return [each_name]\n"
+        "    return []\n"
+    )
+    issues = check_docstring_tuple_enumeration_match(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Matching enumeration must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_docstring_without_tuple_overlap() -> None:
+    source = (
+        '"""Call-args plumbing detection."""\n'
+        "\n"
+        '_CALL_ARGS_PLUMBING_ATTRIBUTES = ("call_args", "call_args_list", "called", "call_count")\n'
+        "\n"
+        "def check_plumbing(content: str, file_path: str) -> list[str]:\n"
+        '    """Advise when a test asserts only on mock internals.\n'
+        "\n"
+        "    A body reading ``foo``, ``bar``, ``baz`` is unrelated to the tuple.\n"
+        '    """\n'
+        "    for each_name in _CALL_ARGS_PLUMBING_ATTRIBUTES:\n"
+        "        if each_name in content:\n"
+        "            return [each_name]\n"
+        "    return []\n"
+    )
+    issues = check_docstring_tuple_enumeration_match(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"A docstring not naming the tuple must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_when_function_does_not_reference_the_tuple() -> None:
+    source = (
+        '"""Call-args plumbing detection."""\n'
+        "\n"
+        '_CALL_ARGS_PLUMBING_ATTRIBUTES = ("call_args", "call_args_list", "called", "call_count")\n'
+        "\n"
+        "def check_unrelated(content: str, file_path: str) -> list[str]:\n"
+        '    """Advise on ``call_args`` and ``call_args_list`` usage in tests."""\n'
+        "    return [content[:0]]\n"
+    )
+    issues = check_docstring_tuple_enumeration_match(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"A function not reading the tuple must not flag, got: {issues!r}"
+
+
+def test_should_handle_tuple_enumeration_syntax_error_gracefully() -> None:
+    issues = check_docstring_tuple_enumeration_match("def broken(\n", HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_module_roster_drift() -> None:
+    issues = validate_content(
+        _registry_module_omitting_a_check(), HOOK_INFRASTRUCTURE_PATH, old_content=""
+    )
+    matching_issues = [
+        each for each in issues if "check_behavior_named_mock" in each and "docstring" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the module-roster drift, got: {issues!r}"
+    )
+
+
+def test_validate_content_surfaces_tuple_enumeration_drift() -> None:
+    issues = validate_content(
+        _module_with_drifted_tuple_enumeration(), HOOK_INFRASTRUCTURE_PATH, old_content=""
+    )
+    matching_issues = [each for each in issues if "check_plumbing" in each and "enumerat" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the tuple-enumeration drift, got: {issues!r}"
+    )