claude-dev-env 1.24.0 → 1.25.1

package/hooks/blocking/test_code_rules_enforcer_any_type_ignore.py

@@ -0,0 +1,116 @@
+"""Unit tests for code-rules-enforcer Any/type-ignore checks."""
+
+import importlib.util
+import pathlib
+import sys
+
+_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_enforcer",
+    _HOOK_DIR / "code-rules-enforcer.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_type_escape_hatches = hook_module.check_type_escape_hatches
+
+PRODUCTION_FILE_PATH = "/project/src/module.py"
+TEST_FILE_PATH = "/project/src/test_module.py"
+
+
+def test_should_flag_any_parameter_annotation() -> None:
+    source = "def foo(x: Any) -> None:\n    pass\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_flag_any_return_annotation() -> None:
+    source = "def foo() -> Any:\n    return None\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_flag_any_variable_annotation() -> None:
+    source = "x: Any = 1\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_flag_any_inside_optional() -> None:
+    source = "from typing import Optional\nx: Optional[Any] = None\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_allow_lowercase_any_as_builtin_call() -> None:
+    source = "items = [1, 2, 3]\nif any(x > 0 for x in items):\n    pass\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert not any("Any" in issue or "any" in issue for issue in issues)
+
+
+def test_should_flag_bare_type_ignore() -> None:
+    source = "x = 1  # type: ignore\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("type: ignore" in issue for issue in issues)
+
+
+def test_should_flag_coded_type_ignore_without_justification() -> None:
+    source = "x = 1  # type: ignore[misc]\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("type: ignore" in issue for issue in issues)
+
+
+def test_should_allow_justified_type_ignore() -> None:
+    source = "x = 1  # type: ignore[misc]  # stubs missing in foo library\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert not any("type: ignore" in issue for issue in issues)
+
+
+def test_should_skip_test_files() -> None:
+    source = "def foo(x: Any) -> Any:\n    y: Any = 1  # type: ignore\n    return y\n"
+    issues = check_type_escape_hatches(source, TEST_FILE_PATH)
+    assert issues == []
+
+
+def test_should_flag_any_on_positional_only_parameter() -> None:
+    source = "def foo(x: Any, /) -> None:\n    pass\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_flag_any_on_vararg() -> None:
+    source = "def foo(*args: Any) -> None:\n    pass\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_flag_any_on_kwarg() -> None:
+    source = "def foo(**kwargs: Any) -> None:\n    pass\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+
+
+def test_should_not_flag_type_ignore_inside_string_literal() -> None:
+    source = 'message = "# type: ignore[misc] in docs"\n'
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert not any("type: ignore" in issue for issue in issues)
+
+
+def test_should_report_any_and_type_ignore_together_without_cap_starvation() -> None:
+    any_lines = "\n".join(f"x{each_index}: Any = {each_index}" for each_index in range(5))
+    type_ignore_line = "y = 1  # type: ignore\n"
+    source = any_lines + "\n" + type_ignore_line
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    assert any("Any" in issue for issue in issues)
+    assert any("type: ignore" in issue for issue in issues)
+
+
+def test_should_emit_unique_line_numbers_for_multiple_any_params_on_one_line() -> None:
+    source = "def foo(x: Any, y: Any, z: Any) -> None:\n    pass\n"
+    issues = check_type_escape_hatches(source, PRODUCTION_FILE_PATH)
+    line_one_issues = [each_issue for each_issue in issues if each_issue.startswith("Line 1:") and "Any" in each_issue]
+    assert len(line_one_issues) <= 1

package/hooks/blocking/test_code_rules_enforcer_banned_identifier.py

@@ -0,0 +1,231 @@
+"""Unit tests for banned-identifier check in code-rules-enforcer hook."""
+
+import importlib.util
+import pathlib
+import sys
+
+_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_enforcer",
+    _HOOK_DIR / "code-rules-enforcer.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_banned_identifiers = hook_module.check_banned_identifiers
+
+PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
+TEST_FILE_PATH = "packages/app/services/test_loader.py"
+
+
+def test_should_flag_result_assignment() -> None:
+    content = "def load():\n    result = compute()\n    return result\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("result" in issue for issue in issues)
+
+
+def test_should_flag_data_assignment() -> None:
+    content = "def fetch():\n    data = read()\n    return data\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("data" in issue for issue in issues)
+
+
+def test_should_flag_output_assignment() -> None:
+    content = "def render():\n    output = build()\n    return output\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("output" in issue for issue in issues)
+
+
+def test_should_flag_response_assignment() -> None:
+    content = "def call():\n    response = send()\n    return response\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("response" in issue for issue in issues)
+
+
+def test_should_flag_value_assignment() -> None:
+    content = "def read():\n    value = lookup()\n    return value\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("value" in issue for issue in issues)
+
+
+def test_should_flag_item_assignment() -> None:
+    content = "def pick():\n    item = first()\n    return item\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("item" in issue for issue in issues)
+
+
+def test_should_flag_temp_assignment() -> None:
+    content = "def swap():\n    temp = holder()\n    return temp\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("temp" in issue for issue in issues)
+
+
+def test_should_flag_annotated_assignment() -> None:
+    content = "def build() -> dict:\n    data: dict = {}\n    return data\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("data" in issue for issue in issues)
+
+
+def test_should_not_flag_descriptive_names() -> None:
+    content = (
+        "def summarize_orders():\n"
+        "    all_users = load_users()\n"
+        "    is_valid = True\n"
+        "    price_by_product = {}\n"
+        "    for each_order in all_users:\n"
+        "        pass\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_not_flag_name_containing_banned_substring() -> None:
+    content = (
+        "def aggregate():\n"
+        "    result_set = fetch()\n"
+        "    data_map = {}\n"
+        "    value_counts = []\n"
+        "    return result_set, data_map, value_counts\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_test_files() -> None:
+    content = "def test_thing():\n    result = compute()\n    assert result\n"
+    issues = check_banned_identifiers(content, TEST_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    hook_path = "/home/user/.claude/hooks/some-hook.py"
+    content = "def run():\n    data = gather()\n    return data\n"
+    issues = check_banned_identifiers(content, hook_path)
+    assert issues == []
+
+
+def test_should_cap_at_three_issues() -> None:
+    content = (
+        "def many_bad():\n"
+        "    result = 1\n"
+        "    data = 2\n"
+        "    output = 3\n"
+        "    response = 4\n"
+        "    value = 5\n"
+        "    return result\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 3
+
+
+def test_should_include_line_number_and_name() -> None:
+    content = "def run():\n    result = 1\n    return result\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "Line 2" in issues[0]
+    assert "'result'" in issues[0]
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    content = "def broken(\n    this is not python\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_flag_tuple_unpacking_target() -> None:
+    content = "def run():\n    result, err = compute()\n    return result, err\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'result'" in issue for issue in issues)
+
+
+def test_should_flag_list_unpacking_target() -> None:
+    content = "def run():\n    [data, meta] = fetch()\n    return data, meta\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'data'" in issue for issue in issues)
+
+
+def test_should_flag_starred_unpacking_target() -> None:
+    content = "def run():\n    head, *data = fetch()\n    return head, data\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'data'" in issue for issue in issues)
+
+
+def test_should_flag_for_loop_target() -> None:
+    content = "def run(orders):\n    for result in orders:\n        pass\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'result'" in issue for issue in issues)
+
+
+def test_should_flag_async_for_loop_target() -> None:
+    content = (
+        "async def run(orders):\n"
+        "    async for data in orders:\n"
+        "        pass\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'data'" in issue for issue in issues)
+
+
+def test_should_flag_list_comprehension_target() -> None:
+    content = "def run(rows):\n    seen = [x for data in rows]\n    return seen\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'data'" in issue for issue in issues)
+
+
+def test_should_flag_dict_comprehension_target() -> None:
+    content = "def run(rows):\n    mapping = {k: v for value in rows}\n    return mapping\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'value'" in issue for issue in issues)
+
+
+def test_should_flag_generator_expression_target() -> None:
+    content = "def run(rows):\n    stream = (x for item in rows)\n    return stream\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'item'" in issue for issue in issues)
+
+
+def test_should_flag_with_as_target() -> None:
+    content = (
+        "def run():\n"
+        "    with open('a') as data:\n"
+        "        return data.read()\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'data'" in issue for issue in issues)
+
+
+def test_should_flag_walrus_target() -> None:
+    content = "def run(source):\n    if (data := source()):\n        return data\n"
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert any("'data'" in issue for issue in issues)
+
+
+def test_should_return_issues_in_source_line_order() -> None:
+    content = (
+        "def outer():\n"
+        "    def inner():\n"
+        "        result = 1\n"
+        "        data = 2\n"
+        "        return result\n"
+        "    output = inner()\n"
+        "    return output\n"
+    )
+    issues = check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 3
+    assert "Line 3" in issues[0]
+    assert "Line 4" in issues[1]
+    assert "Line 6" in issues[2]
+
+
+def test_should_emit_stderr_advisory_on_syntax_error(
+    capsys: "object",
+) -> None:
+    content = "def broken(\n    this is not python\n"
+    check_banned_identifiers(content, PRODUCTION_FILE_PATH)
+    captured = capsys.readouterr()  # type: ignore[attr-defined]
+    assert "banned-identifier check skipped" in captured.err
+    assert PRODUCTION_FILE_PATH in captured.err

package/hooks/blocking/test_code_rules_enforcer_conftest_anchor.py

@@ -0,0 +1,51 @@
+"""Tests ensuring the conftest pattern matches only the canonical filename."""
+
+import importlib.util
+from pathlib import Path
+
+
+ENFORCER_MODULE_NAME = "code_rules_enforcer_under_test"
+ENFORCER_SOURCE_PATH = Path(__file__).parent / "code-rules-enforcer.py"
+
+
+def load_enforcer_module() -> object:
+    module_spec = importlib.util.spec_from_file_location(
+        ENFORCER_MODULE_NAME, ENFORCER_SOURCE_PATH
+    )
+    if module_spec is None or module_spec.loader is None:
+        raise RuntimeError(f"cannot load enforcer from {ENFORCER_SOURCE_PATH}")
+    enforcer_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(enforcer_module)
+    return enforcer_module
+
+
+enforcer = load_enforcer_module()
+is_test_file = enforcer.is_test_file
+
+
+def test_is_test_file_should_match_canonical_conftest_py() -> None:
+    assert is_test_file("C:/proj/tests/conftest.py") is True
+
+
+def test_is_test_file_should_match_nested_conftest_py() -> None:
+    assert is_test_file("C:/proj/subdir/conftest.py") is True
+
+
+def test_is_test_file_should_not_match_conftest_substring_in_filename() -> None:
+    assert is_test_file("C:/proj/my_conftestfile.py") is False
+
+
+def test_is_test_file_should_not_match_conftest_in_directory_name() -> None:
+    assert is_test_file("C:/proj/conftestdata/foo.py") is False
+
+
+def test_is_test_file_should_not_match_prefixed_conftest_py() -> None:
+    assert is_test_file("C:/proj/myconftest.py") is False
+
+
+def test_is_test_file_should_not_match_underscore_prefixed_conftest_py() -> None:
+    assert is_test_file("C:/proj/foo_conftest.py") is False
+
+
+def test_is_test_file_should_match_conftest_py_with_backslash_separators() -> None:
+    assert is_test_file("C:\\proj\\subdir\\conftest.py") is True

package/hooks/blocking/test_code_rules_enforcer_dot_test_pattern.py

@@ -0,0 +1,55 @@
+"""Regression tests for .test.{ts,tsx,js} recognition in code-rules-enforcer."""
+
+import importlib.util
+import pathlib
+
+
+def _load_enforcer_module():
+    enforcer_path = pathlib.Path(__file__).parent / "code-rules-enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", enforcer_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+enforcer = _load_enforcer_module()
+
+
+def test_is_test_file_should_recognize_dot_test_tsx_files():
+    assert enforcer.is_test_file("C:/foo/Button.test.tsx") is True
+
+
+def test_is_test_file_should_recognize_dot_test_ts_files():
+    assert enforcer.is_test_file("C:/foo/Button.test.ts") is True
+
+
+def test_is_test_file_should_recognize_dot_test_js_files():
+    assert enforcer.is_test_file("C:/foo/Button.test.js") is True
+
+
+def test_is_test_file_should_still_recognize_python_test_files():
+    assert enforcer.is_test_file("C:/foo/test_foo.py") is True
+    assert enforcer.is_test_file("C:/foo/foo_test.py") is True
+    assert enforcer.is_test_file("C:/foo/conftest.py") is True
+    assert enforcer.is_test_file("C:/foo/foo.spec.ts") is True
+
+
+def test_is_hook_infrastructure_should_recognize_packages_claude_dev_env_hooks_forward_slash():
+    assert enforcer.is_hook_infrastructure("/repo/packages/claude-dev-env/hooks/blocking/foo.py") is True
+
+
+def test_is_hook_infrastructure_should_recognize_packages_claude_dev_env_hooks_backslash():
+    assert enforcer.is_hook_infrastructure("C:\\repo\\packages\\claude-dev-env\\hooks\\blocking\\foo.py") is True
+
+
+def test_is_hook_infrastructure_should_recognize_packages_claude_dev_env_hooks_validators():
+    assert enforcer.is_hook_infrastructure("/repo/packages/claude-dev-env/hooks/validators/bar.py") is True
+
+
+def test_is_hook_infrastructure_should_still_recognize_dot_claude_hooks():
+    assert enforcer.is_hook_infrastructure("C:/Users/jon/.claude/hooks/blocking/foo.py") is True
+    assert enforcer.is_hook_infrastructure("/home/user/.claude/hooks/blocking/foo.py") is True
+
+
+def test_is_hook_infrastructure_should_not_match_unrelated_package_path():
+    assert enforcer.is_hook_infrastructure("/repo/packages/other-package/src/foo.py") is False

package/hooks/blocking/test_code_rules_enforcer_fstring_scan.py

@@ -0,0 +1,144 @@
+"""Unit tests for code-rules-enforcer f-string structural literal scanner."""
+
+import importlib.util
+import pathlib
+import sys
+
+_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_enforcer",
+    _HOOK_DIR / "code-rules-enforcer.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_fstring_structural_literals = hook_module.check_fstring_structural_literals
+validate_content = hook_module.validate_content
+
+PRODUCTION_FILE_PATH = "packages/claude-dev-env/example.py"
+TEST_FILE_PATH = "packages/claude-dev-env/test_example.py"
+
+
+def test_should_flag_fstring_with_url_path() -> None:
+    content = 'def build_url(user_id):\n    endpoint = f"/api/v1/users/{user_id}"\n    return endpoint\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "expected URL path f-string to be flagged"
+
+
+def test_should_flag_fstring_with_windows_path() -> None:
+    content = 'def build_path(name):\n    location = f"C:\\\\Users\\\\{name}\\\\Documents"\n    return location\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "expected Windows path f-string to be flagged"
+
+
+def test_should_flag_fstring_with_regex_pattern() -> None:
+    content = 'def build_pattern(group):\n    regex = f"\\\\d+{group}\\\\w+"\n    return regex\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "expected regex metacharacter f-string to be flagged"
+
+
+def test_should_not_flag_fstring_with_only_interpolation() -> None:
+    content = 'def render(value):\n    rendered = f"{value}"\n    return rendered\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"pure interpolation should not be flagged, got: {issues}"
+
+
+def test_should_not_flag_fstring_with_trivial_separator() -> None:
+    content = 'def render(x):\n    rendered = f"{x} "\n    return rendered\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"single-space separator should not be flagged, got: {issues}"
+
+
+def test_should_not_flag_true_false_literals() -> None:
+    content = "def toggle():\n    x = True\n    y = False\n    return x, y\n"
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"True/False literals should not be flagged, got: {issues}"
+
+
+def test_should_not_flag_empty_string_literal() -> None:
+    content = 'def blank():\n    x = ""\n    return x\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"empty string literal should not be flagged, got: {issues}"
+
+
+def test_should_skip_test_files() -> None:
+    content = 'def test_thing():\n    url = f"/api/v1/users/{user_id}"\n'
+    issues_via_validate = validate_content(content, TEST_FILE_PATH, "")
+    fstring_issues = [
+        each_issue
+        for each_issue in issues_via_validate
+        if "structural" in each_issue.lower() or "f-string" in each_issue.lower()
+    ]
+    assert fstring_issues == [], (
+        f"test files should be exempt from f-string scanner, got: {fstring_issues}"
+    )
+
+
+def test_should_not_flag_natural_english_with_single_slash() -> None:
+    content = 'def log_mode(mode):\n    message = f"Test name contains online/offline - mode is {mode}"\n    return message\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"natural English with single slash should not be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_common_english_slash_phrases() -> None:
+    for each_phrase in ("and/or", "CI/CD", "PR/MR", "input/output", "read/write"):
+        content = f'def note(x):\n    message = f"{each_phrase} value is {{x}}"\n    return message\n'
+        issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+        assert issues == [], (
+            f"phrase {each_phrase!r} should not be flagged, got: {issues}"
+        )
+
+
+def test_should_flag_fstring_with_apostrophe() -> None:
+    content = 'def greet(name):\n    message = f"it\'s /api/v1/{name}/home"\n    return message\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "f-string containing an apostrophe should still be detected"
+
+
+def test_should_flag_triple_quoted_fstring_with_path() -> None:
+    content = 'def build(x):\n    message = f"""/api/v1/{x}/path/extra"""\n    return message\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "triple-quoted f-string with path should be flagged"
+
+
+def test_should_flag_raw_fstring_rf_prefix() -> None:
+    content = 'def build(x):\n    message = rf"/api/v1/{x}/extra"\n    return message\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "rf-prefixed f-string with path should be flagged"
+
+
+def test_should_flag_raw_fstring_fr_prefix() -> None:
+    content = 'def build(x):\n    message = fr"/api/v1/{x}/extra"\n    return message\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    assert issues, "fr-prefixed f-string with path should be flagged"
+
+
+def test_should_not_leak_escaped_braces_into_flag_message() -> None:
+    content = 'def build(x):\n    message = f"{{/api/{x}/extra/path}}"\n    return message\n'
+    issues = check_fstring_structural_literals(content, PRODUCTION_FILE_PATH)
+    for each_issue in issues:
+        assert "{{" not in each_issue, (
+            f"flag message should not contain escaped brace artifacts, got: {each_issue}"
+        )
+        assert "}}" not in each_issue, (
+            f"flag message should not contain escaped brace artifacts, got: {each_issue}"
+        )
+
+
+def test_should_not_flag_enforcer_hook_itself() -> None:
+    hook_path = _HOOK_DIR / "code-rules-enforcer.py"
+    with open(hook_path, encoding="utf-8") as each_file:
+        enforcer_source = each_file.read()
+    issues = check_fstring_structural_literals(
+        enforcer_source,
+        "packages/claude-dev-env/hooks/blocking/code-rules-enforcer.py",
+    )
+    assert issues == [], (
+        f"the enforcer hook should not flag itself, got: {issues}"
+    )