claude-dev-env 1.35.0 → 1.36.1

package/hooks/blocking/test_code_rules_enforcer_constant_equality.py

@@ -110,3 +110,43 @@ def test_should_not_flag_non_test_function() -> None:
     assert issues == [], f"Expected no issues for non-test function, got: {issues}"
 
 
+def test_should_flag_literal_on_left_with_constant_on_right() -> None:
+    source = (
+        'CACHE_DIR = "cache"\n'
+        "\n"
+        "def test_cache_dir_right() -> None:\n"
+        '    assert "cache" == CACHE_DIR\n'
+    )
+    issues = code_rules_enforcer.check_constant_equality_tests(source, TEST_FILE_PATH)
+    assert any("constant" in issue.lower() for issue in issues), (
+        f"Expected 'cache' == CACHE_DIR flagged equally — equality is commutative, got: {issues}"
+    )
+
+
+def test_should_flag_numeric_literal_on_left_with_constant_on_right() -> None:
+    source = (
+        "MAX_SIZE = 100\n"
+        "\n"
+        "def test_max_size_right() -> None:\n"
+        "    assert 100 == MAX_SIZE\n"
+    )
+    issues = code_rules_enforcer.check_constant_equality_tests(source, TEST_FILE_PATH)
+    assert any("constant" in issue.lower() for issue in issues), (
+        f"Expected 100 == MAX_SIZE flagged equally, got: {issues}"
+    )
+
+
+def test_should_not_flag_two_upper_snake_constants_compared() -> None:
+    source = (
+        "EXPECTED = 5\n"
+        "ACTUAL = 5\n"
+        "\n"
+        "def test_two_constants() -> None:\n"
+        "    assert EXPECTED == ACTUAL\n"
+    )
+    issues = code_rules_enforcer.check_constant_equality_tests(source, TEST_FILE_PATH)
+    assert issues == [], (
+        f"Two-constant comparison is not constant-vs-literal, must not flag, got: {issues}"
+    )
+
+

package/hooks/blocking/test_code_rules_enforcer_hardcoded_user_path.py

@@ -0,0 +1,291 @@
+"""Tests for hardcoded user path detection.
+
+Bot reviewers on PR #257 flagged 6+ instances of 'C:/Users/jon/' embedded
+in production source code, which breaks portability across machines.
+The new rule flags any string literal in production code that names a
+specific user's home directory.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+
+_hook_spec = importlib.util.spec_from_file_location(
+    "code_rules_enforcer",
+    _HOOK_DIRECTORY / "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_hardcoded_user_paths = _hook_module.check_hardcoded_user_paths
+HARDCODED_USER_PATH_PATTERN = _hook_module.HARDCODED_USER_PATH_PATTERN
+
+
+PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
+TEST_FILE_PATH = "packages/app/tests/test_loader.py"
+CONFIG_FILE_PATH = "packages/app/config/paths.py"
+HOOK_INFRASTRUCTURE_FILE_PATH = "/repo/packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py"
+
+
+def test_should_match_user_directory_without_consuming_following_separator() -> None:
+    windows = HARDCODED_USER_PATH_PATTERN.search("C:/Users/jon/more")
+    macos = HARDCODED_USER_PATH_PATTERN.search("/Users/bob/more")
+    linux = HARDCODED_USER_PATH_PATTERN.search("/home/alice/more")
+    assert windows is not None and windows.group(0) == "C:/Users/jon"
+    assert macos is not None and macos.group(0) == "/Users/bob"
+    assert linux is not None and linux.group(0) == "/home/alice"
+
+
+def test_should_flag_windows_user_path_with_forward_slashes() -> None:
+    source = 'def find() -> str:\n    return "C:/Users/jon/notes.md"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("C:/Users/jon" in each_issue for each_issue in issues), (
+        f"Expected Windows user path flagged, got: {issues}"
+    )
+
+
+def test_should_flag_windows_user_path_when_users_segment_is_not_title_case() -> None:
+    source = 'def find() -> str:\n    return "c:/users/jon/notes.md"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("users" in each_issue.lower() for each_issue in issues), (
+        f"Expected Windows user path flagged (case-insensitive Users segment), got: {issues}"
+    )
+
+
+def test_should_flag_windows_user_path_with_backslashes() -> None:
+    source = 'def find() -> str:\n    return "C:\\\\Users\\\\jon\\\\notes.md"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("Users" in each_issue for each_issue in issues), (
+        f"Expected Windows backslash user path flagged, got: {issues}"
+    )
+
+
+def test_should_flag_unix_home_path() -> None:
+    source = 'def find() -> str:\n    return "/home/alice/notes.md"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("/home/alice" in each_issue for each_issue in issues), (
+        f"Expected Unix home path flagged, got: {issues}"
+    )
+
+
+def test_should_flag_macos_user_path() -> None:
+    source = 'def find() -> str:\n    return "/Users/bob/Documents/data.json"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("/Users/bob" in each_issue for each_issue in issues), (
+        f"Expected macOS user path flagged, got: {issues}"
+    )
+
+
+def test_should_flag_macos_user_path_when_home_is_entire_path() -> None:
+    source = 'def find() -> str:\n    return "/Users/bob"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("/Users/bob" in each_issue for each_issue in issues), (
+        f"Expected macOS user home literal flagged without trailing slash, got: {issues}"
+    )
+
+
+def test_should_not_flag_tilde_home_alias() -> None:
+    source = 'def find() -> str:\n    return "~/notes.md"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Tilde alias is portable, must not flag, got: {issues}"
+
+
+def test_should_not_flag_users_directory_without_specific_user() -> None:
+    source = 'def root_dir() -> str:\n    return "C:/Users"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Generic /Users root with no specific user has no portability cost, got: {issues}"
+    )
+
+
+def test_should_skip_test_files() -> None:
+    source = 'def test_path() -> None:\n    fixture = "C:/Users/jon/scratch.txt"\n'
+    issues = check_hardcoded_user_paths(source, TEST_FILE_PATH)
+    assert issues == [], (
+        f"Test files exempt — fixtures often need real paths, got: {issues}"
+    )
+
+
+def test_should_skip_config_files() -> None:
+    source = 'DEFAULT_PATH = "C:/Users/jon/notes.md"\n'
+    issues = check_hardcoded_user_paths(source, CONFIG_FILE_PATH)
+    assert issues == [], (
+        f"Config files exempt — that is the right place for paths, got: {issues}"
+    )
+
+
+def test_should_include_line_number_in_issue() -> None:
+    source = '\n\ndef find() -> str:\n    return "C:/Users/jon/notes.md"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("Line 4" in each_issue for each_issue in issues), (
+        f"Expected line 4 reference, got: {issues}"
+    )
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    source = "def broken(\n    not python\n"
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Parse failure must return empty, got: {issues}"
+
+
+def test_should_suggest_path_home_or_expanduser_in_message() -> None:
+    source = 'def find() -> str:\n    return "/home/alice/x"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any(
+        "Path.home" in each_issue or "expanduser" in each_issue for each_issue in issues
+    ), (
+        f"Error message should suggest Path.home() or os.path.expanduser('~'), got: {issues}"
+    )
+
+def test_should_flag_standalone_home_segment_for_symmetry_with_macos() -> None:
+    source = 'def route() -> str:\n    return "/home/dashboard"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("/home/dashboard" in each_issue for each_issue in issues), (
+        f"Linux '/home/<segment>' is structurally indistinguishable from a real"
+        f" home directory and must flag for symmetry with macOS, got: {issues}"
+    )
+
+
+def test_should_not_flag_standalone_users_segment_without_trailing_path() -> None:
+    source = 'def system_path() -> str:\n    return "/Users/Shared"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"'/Users/Shared' without trailing path component is not navigating into a user home, got: {issues}"
+    )
+
+
+def test_should_skip_hook_infrastructure_files() -> None:
+    source = (
+        'HARDCODED_USER_PATH_PATTERN = "/Users/[^/]+|/home/[^/]+"\n'
+        'def find() -> str:\n'
+        '    return "C:/Users/jon/notes.md"\n'
+    )
+    issues = check_hardcoded_user_paths(source, HOOK_INFRASTRUCTURE_FILE_PATH)
+    assert issues == [], (
+        f"Hook infrastructure files exempt — the enforcer itself encodes user-path"
+        f" patterns and would otherwise self-block, got: {issues}"
+    )
+
+
+def test_should_not_flag_docstring_mentioning_user_path() -> None:
+    source = (
+        'def load_data() -> None:\n'
+        '    """Reads from /home/alice/data for testing."""\n'
+        '    pass\n'
+    )
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Docstrings are allowed to mention paths, got: {issues}"
+    )
+
+
+def test_should_flag_linux_home_path_when_home_is_entire_path() -> None:
+    source = 'def find() -> str:\n    return "/home/alice"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert any("/home/alice" in each_issue for each_issue in issues), (
+        f"Expected Linux home literal flagged without trailing slash, got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_public_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "C:/Users/Public/Documents"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'C:/Users/Public' is a system shared folder, not a user home, got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "C:/Users/Shared/data"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'C:/Users/Shared' is a system shared folder, not a user home, got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_all_users_folder() -> None:
+    source = 'def find() -> str:\n    return "C:/Users/All Users/AppData"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'C:/Users/All Users' is a legacy shared folder, not a user home, got: {issues}"
+    )
+
+
+def test_should_not_flag_macos_public_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "/Users/Public/Documents"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"macOS '/Users/Public' is a default shared folder on every macOS install,"
+        f" not a user home — symmetry with the Windows exclusion, got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_lowercase_public_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "c:/users/public/Documents"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'c:/users/public' is the same shared folder regardless of case,"
+        f" the exclusion list must be case-insensitive, got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_lowercase_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "c:/users/shared/data"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'c:/users/shared' is a system shared folder regardless of case,"
+        f" got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_lowercase_all_users_folder() -> None:
+    source = 'def find() -> str:\n    return "c:/users/all users/AppData"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'c:/users/all users' is a legacy shared folder regardless of case,"
+        f" got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_mixed_case_public_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "C:/Users/PuBlIc/Documents"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'C:/Users/PuBlIc' is the same shared folder in any casing,"
+        f" got: {issues}"
+    )
+
+
+def test_should_not_flag_windows_uppercase_public_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "C:/Users/PUBLIC/Documents"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Windows 'C:/Users/PUBLIC' is the same shared folder in any casing,"
+        f" got: {issues}"
+    )
+
+
+def test_should_not_flag_macos_lowercase_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "/Users/shared/data"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"macOS '/Users/shared' is a system shared folder regardless of case,"
+        f" got: {issues}"
+    )
+
+
+def test_should_not_flag_macos_lowercase_public_shared_folder() -> None:
+    source = 'def find() -> str:\n    return "/Users/public/Documents"\n'
+    issues = check_hardcoded_user_paths(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"macOS '/Users/public' is a default shared folder regardless of case,"
+        f" got: {issues}"
+    )

package/hooks/blocking/test_code_rules_enforcer_loop_variable_naming.py

@@ -56,16 +56,100 @@ def test_should_flag_bare_each_without_subject() -> None:
     )
 
 
-def test_should_not_flag_tuple_unpacking_targets() -> None:
+def test_should_flag_tuple_unpacking_targets_lacking_each_prefix() -> None:
     source = (
         "def consume() -> None:\n"
-        "    for key, value in {}.items():\n"
+        "    for accessed_field, access_line in []:\n"
         "        return None\n"
     )
     issues = code_rules_enforcer.check_loop_variable_naming(
         source, PRODUCTION_FILE_PATH
     )
-    assert issues == [], f"Tuple-unpack targets exempt, got: {issues}"
+    assert any("accessed_field" in each_issue for each_issue in issues), (
+        f"Expected 'accessed_field' tuple-unpack target flagged, got: {issues}"
+    )
+    assert any("access_line" in each_issue for each_issue in issues), (
+        f"Expected 'access_line' tuple-unpack target flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_tuple_unpacking_when_all_targets_have_each_prefix() -> None:
+    source = (
+        "def consume() -> None:\n"
+        "    for each_key, each_value in {}.items():\n"
+        "        return None\n"
+    )
+    issues = code_rules_enforcer.check_loop_variable_naming(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Tuple-unpack with each_ prefix on all targets must pass, got: {issues}"
+    )
+
+
+def test_should_exempt_underscore_inside_tuple_unpacking() -> None:
+    source = (
+        "def consume() -> None:\n"
+        "    for _, each_position in []:\n"
+        "        return None\n"
+    )
+    issues = code_rules_enforcer.check_loop_variable_naming(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"'_' must remain exempt inside tuple unpacking, got: {issues}"
+    )
+
+
+def test_should_flag_partially_compliant_tuple_unpacking() -> None:
+    source = (
+        "def consume() -> None:\n"
+        "    for each_key, raw_value in {}.items():\n"
+        "        return None\n"
+    )
+    issues = code_rules_enforcer.check_loop_variable_naming(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("raw_value" in each_issue for each_issue in issues), (
+        f"Mixed-compliance tuple unpack must flag the offender, got: {issues}"
+    )
+    assert not any("each_key" in each_issue for each_issue in issues), (
+        f"each_key compliant target must not be flagged, got: {issues}"
+    )
+
+
+def test_should_flag_nested_tuple_unpacking_targets() -> None:
+    source = (
+        "def consume() -> None:\n"
+        "    for outer_label, (inner_first, inner_second) in []:\n"
+        "        return None\n"
+    )
+    issues = code_rules_enforcer.check_loop_variable_naming(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("inner_first" in each_issue for each_issue in issues), (
+        f"Nested tuple-unpack targets must be inspected, got: {issues}"
+    )
+    assert any("inner_second" in each_issue for each_issue in issues), (
+        f"Nested tuple-unpack targets must be inspected, got: {issues}"
+    )
+
+
+def test_should_flag_starred_tuple_unpacking_target() -> None:
+    source = (
+        "def consume() -> None:\n"
+        "    for first, *rest in []:\n"
+        "        return None\n"
+    )
+    issues = code_rules_enforcer.check_loop_variable_naming(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("first" in each_issue for each_issue in issues), (
+        f"First tuple-unpack target must be flagged, got: {issues}"
+    )
+    assert any("rest" in each_issue for each_issue in issues), (
+        f"Starred tuple-unpack target must be flagged, got: {issues}"
+    )
 
 
 def test_should_not_flag_list_comprehension_target() -> None:

package/hooks/blocking/test_code_rules_enforcer_naming_pattern.py

@@ -161,3 +161,52 @@ def test_validate_content_invokes_boolean_naming_check() -> None:
     assert matching_issues, (
         f"expected validate_content to surface the boolean-naming issue, got {issues!r}"
     )
+
+
+def test_should_flag_substring_is_when_not_at_prefix_position() -> None:
+    source = "def f() -> None:\n    left_is_upper_snake = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_name(issues, "left_is_upper_snake", 2)
+    assert len(issues) == 1, (
+        f"'is_' in middle position must not satisfy the prefix rule, got: {issues}"
+    )
+
+
+def test_should_flag_substring_has_when_not_at_prefix_position() -> None:
+    source = "def f() -> None:\n    user_has_permission = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_name(issues, "user_has_permission", 2)
+    assert len(issues) == 1, (
+        f"'has_' in middle position must not satisfy the prefix rule, got: {issues}"
+    )
+
+
+def test_should_flag_substring_should_when_not_at_prefix_position() -> None:
+    source = "def f() -> None:\n    user_should_retry = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_name(issues, "user_should_retry", 2)
+    assert len(issues) == 1
+
+
+def test_should_flag_substring_can_when_not_at_prefix_position() -> None:
+    source = "def f() -> None:\n    user_can_edit = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_name(issues, "user_can_edit", 2)
+    assert len(issues) == 1
+
+
+def test_should_flag_right_is_literal_substring_match() -> None:
+    source = "def f() -> None:\n    right_is_literal = False\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_name(issues, "right_is_literal", 2)
+    assert len(issues) == 1, (
+        f"PR #232 finding: substring 'is_' in 'right_is_literal' must be flagged, got: {issues}"
+    )
+
+
+def test_should_allow_is_prefix_at_start_when_compound_word_follows() -> None:
+    source = "def f() -> None:\n    is_left_upper_snake = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"is_left_upper_snake has prefix at position 0, must pass, got: {issues}"
+    )

package/hooks/blocking/test_code_rules_enforcer_sys_path_insert.py

@@ -0,0 +1,157 @@
+"""Tests for sys.path.insert dedup-guard rule.
+
+Bot reviewers on PR #289 flagged grant_project_claude_permissions.py:13
+and revoke_project_claude_permissions.py for unconditionally calling
+sys.path.insert(0, X) without checking whether X was already present.
+The convention in the rest of the repo is to guard the call with
+`if str(X) not in sys.path:` (or equivalent) to avoid pushing the
+same path repeatedly when modules get reloaded.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import pathlib
+import sys
+
+
+_HOOK_DIRECTORY = pathlib.Path(__file__).parent
+if str(_HOOK_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIRECTORY))
+
+_hook_spec = importlib.util.spec_from_file_location(
+    "code_rules_enforcer",
+    _HOOK_DIRECTORY / "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_sys_path_insert_deduplication_guard = _hook_module.check_sys_path_insert_deduplication_guard
+
+
+PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
+TEST_FILE_PATH = "packages/app/tests/test_loader.py"
+
+
+def test_should_flag_unguarded_module_level_insert() -> None:
+    source = (
+        "import sys\n"
+        "from pathlib import Path\n"
+        "REPOSITORY_ROOT = Path(__file__).resolve().parent\n"
+        "sys.path.insert(0, str(REPOSITORY_ROOT))\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert any("sys.path.insert" in each_issue for each_issue in issues), (
+        f"Expected unguarded sys.path.insert flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_preceded_by_membership_guard() -> None:
+    source = (
+        "import sys\n"
+        "from pathlib import Path\n"
+        "REPOSITORY_ROOT = str(Path(__file__).resolve().parent)\n"
+        "if REPOSITORY_ROOT not in sys.path:\n"
+        "    sys.path.insert(0, REPOSITORY_ROOT)\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Guarded insert (if X not in sys.path) must not be flagged, got: {issues}"
+    )
+
+
+def test_should_flag_unguarded_function_local_insert() -> None:
+    source = (
+        "import sys\ndef configure() -> None:\n    sys.path.insert(0, '/some/path')\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert any("sys.path.insert" in each_issue for each_issue in issues), (
+        f"Function-local unguarded insert must be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_function_local_when_guarded() -> None:
+    source = (
+        "import sys\n"
+        "def configure() -> None:\n"
+        "    target = '/some/path'\n"
+        "    if target not in sys.path:\n"
+        "        sys.path.insert(0, target)\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Guarded function-local insert must pass, got: {issues}"
+
+
+def test_should_not_flag_sys_path_append_or_extend() -> None:
+    source = (
+        "import sys\nsys.path.append('/some/path')\nsys.path.extend(['/a', '/b'])\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"This rule targets sys.path.insert specifically, append/extend exempt, got: {issues}"
+    )
+
+
+def test_should_skip_test_files() -> None:
+    source = "import sys\nsys.path.insert(0, '/some/path')\n"
+    issues = check_sys_path_insert_deduplication_guard(source, TEST_FILE_PATH)
+    assert issues == [], (
+        f"Test files exempt — fixtures often manipulate sys.path, got: {issues}"
+    )
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    source = "import sys\nsys.path.insert(\n    not python\n"
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Parse failure must return empty, got: {issues}"
+
+
+def test_should_recognize_str_call_around_path_in_guard() -> None:
+    source = (
+        "import sys\n"
+        "from pathlib import Path\n"
+        "ROOT = Path('/x')\n"
+        "if str(ROOT) not in sys.path:\n"
+        "    sys.path.insert(0, str(ROOT))\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"str(ROOT) wrapped in both guard and insert must not flag, got: {issues}"
+    )
+
+
+def test_should_include_line_number_in_issue() -> None:
+    source = "import sys\n\n\nsys.path.insert(0, '/x')\n"
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert any("Line 4" in each_issue for each_issue in issues), (
+        f"Expected line 4 reference, got: {issues}"
+    )
+
+
+def test_should_flag_inverted_membership_guard_inserting_in_then_branch() -> None:
+    source = (
+        "import sys\n"
+        "TARGET = '/some/path'\n"
+        "if TARGET in sys.path:\n"
+        "    sys.path.insert(0, TARGET)\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert any("sys.path.insert" in each_issue for each_issue in issues), (
+        "`if X in sys.path: sys.path.insert(0, X)` inserts a duplicate when X "
+        f"is already present; only `not in` guards then-branch inserts. Got: {issues}"
+    )
+
+
+def test_should_flag_inverted_membership_guard_with_str_wrapper() -> None:
+    source = (
+        "import sys\n"
+        "from pathlib import Path\n"
+        "ROOT = Path('/x')\n"
+        "if str(ROOT) in sys.path:\n"
+        "    sys.path.insert(0, str(ROOT))\n"
+    )
+    issues = check_sys_path_insert_deduplication_guard(source, PRODUCTION_FILE_PATH)
+    assert any("sys.path.insert" in each_issue for each_issue in issues), (
+        f"Inverted membership guard with str() wrapper must still flag, got: {issues}"
+    )