claude-dev-env 1.38.0 → 1.38.1

package/hooks/blocking/code_rules_enforcer.py

@@ -2580,7 +2580,30 @@ def _collect_load_names_outside_import_ranges(
     return referenced_names
 
 
-def check_unused_module_level_imports(content: str, file_path: str) -> list[str]:
+def _module_declares_dunder_all(tree: ast.Module) -> bool:
+    """Return True when the module body assigns or annotates ``__all__``."""
+    return any(
+        (
+            isinstance(each_node, ast.Assign)
+            and any(
+                isinstance(each_target, ast.Name) and each_target.id == "__all__"
+                for each_target in each_node.targets
+            )
+        )
+        or (
+            isinstance(each_node, ast.AnnAssign)
+            and isinstance(each_node.target, ast.Name)
+            and each_node.target.id == "__all__"
+        )
+        for each_node in tree.body
+    )
+
+
+def check_unused_module_level_imports(
+    content: str,
+    file_path: str,
+    full_file_content: str | None = None,
+) -> list[str]:
     """Flag module-level imports that are never referenced in the rest of the file.
 
     References are detected from AST ``Name`` / ``Attribute`` loads outside import
@@ -2589,42 +2612,39 @@ def check_unused_module_level_imports(content: str, file_path: str) -> list[str]
     whose module body includes ``if TYPE_CHECKING:`` (or
     ``typing[._extensions].TYPE_CHECKING``) are skipped. Suppression honors bare
     ``# noqa`` or an explicit ``F401`` code in the noqa list only.
+
+    When ``full_file_content`` is provided, ``content`` is treated as an Edit
+    fragment containing the imports being added or replaced, while the
+    ``__all__`` / ``TYPE_CHECKING`` gate detection and reference scanning run
+    against ``full_file_content`` (the post-edit file as it will look once the
+    Edit applies). This prevents false-positive flags on imports added in the
+    same Edit as their consumers.
     """
     if is_test_file(file_path):
         return []
     if is_workflow_registry_file(file_path) or is_migration_file(file_path):
         return []
     try:
-        tree = ast.parse(content)
+        fragment_tree = ast.parse(content)
     except SyntaxError:
         return []
-    file_declares_dunder_all = any(
-        (
-            isinstance(each_node, ast.Assign)
-            and any(
-                isinstance(each_target, ast.Name) and each_target.id == "__all__"
-                for each_target in each_node.targets
-            )
-        )
-        or (
-            isinstance(each_node, ast.AnnAssign)
-            and isinstance(each_node.target, ast.Name)
-            and each_node.target.id == "__all__"
-        )
-        for each_node in tree.body
-    )
-    if file_declares_dunder_all:
+    reference_source = full_file_content if full_file_content is not None else content
+    try:
+        reference_tree = ast.parse(reference_source)
+    except SyntaxError:
+        return []
+    if _module_declares_dunder_all(reference_tree):
         return []
-    if _module_body_declares_type_checking_gate(tree):
+    if _module_body_declares_type_checking_gate(reference_tree):
         return []
-    content_lines = content.splitlines()
-    import_line_ranges = _import_statement_line_ranges(tree)
+    fragment_lines = content.splitlines()
+    reference_import_ranges = _import_statement_line_ranges(reference_tree)
     referenced_names = _collect_load_names_outside_import_ranges(
-        tree,
-        import_line_ranges,
+        reference_tree,
+        reference_import_ranges,
     )
     import_bindings: list[tuple[str, int, int | None]] = []
-    for each_node in tree.body:
+    for each_node in fragment_tree.body:
         if isinstance(each_node, (ast.Import, ast.ImportFrom)):
             if isinstance(each_node, ast.ImportFrom) and each_node.module == "__future__":
                 continue
@@ -2632,14 +2652,14 @@ def check_unused_module_level_imports(content: str, file_path: str) -> list[str]
                 import_bindings.append(each_binding)
     issues: list[str] = []
     for each_name, each_line_number, each_from_keyword_line in import_bindings:
-        if 1 <= each_line_number <= len(content_lines):
-            if line_suppresses_unused_import_via_noqa(content_lines[each_line_number - 1]):
+        if 1 <= each_line_number <= len(fragment_lines):
+            if line_suppresses_unused_import_via_noqa(fragment_lines[each_line_number - 1]):
                 continue
         if each_from_keyword_line is not None and 1 <= each_from_keyword_line <= len(
-            content_lines
+            fragment_lines
         ):
             if line_suppresses_unused_import_via_noqa(
-                content_lines[each_from_keyword_line - 1]
+                fragment_lines[each_from_keyword_line - 1]
             ):
                 continue
         if each_name in referenced_names:
@@ -2904,14 +2924,25 @@ def check_return_annotations(content: str, file_path: str) -> list[str]:
     return issues
 
 
-def validate_content(content: str, file_path: str, old_content: str = "") -> list[str]:
+def validate_content(
+    content: str,
+    file_path: str,
+    old_content: str = "",
+    full_file_content: str | None = None,
+) -> list[str]:
     """Run all applicable validators on content.
 
     Args:
-        content: The new content being written.
+        content: The new content being written. For Edit, this is the
+            ``new_string`` fragment; for Write, the entire new file body.
         file_path: Path to the file.
         old_content: Previous content (old_string for Edit, existing file for Write).
             Used to detect comment additions/removals instead of flagging all comments.
+        full_file_content: For Edit operations, the reconstructed post-edit
+            content of the entire file (existing file with ``old_string`` replaced
+            by ``new_string``). Whole-file checks such as the unused-import
+            scanner use this to evaluate references across the file rather than
+            just within the inserted fragment.
     """
     extension = get_file_extension(file_path)
     all_issues = []
@@ -2938,7 +2969,9 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_stuttering_collection_prefix(content, file_path))
         all_issues.extend(check_hardcoded_user_paths(content, file_path))
         all_issues.extend(check_sys_path_insert_deduplication_guard(content, file_path))
-        all_issues.extend(check_unused_module_level_imports(content, file_path))
+        all_issues.extend(
+            check_unused_module_level_imports(content, file_path, full_file_content)
+        )
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_return_annotations(content, file_path))
@@ -2959,6 +2992,30 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
     return all_issues
 
 
+def _reconstruct_post_edit_file_content(
+    file_path: str, old_string: str, new_string: str,
+) -> str | None:
+    """Return the file content as it will look after the Edit applies, or None.
+
+    Reads ``file_path`` from disk and replaces the first occurrence of
+    ``old_string`` with ``new_string``, mirroring how the Edit tool itself
+    applies a single replacement. Returns None when the file cannot be read,
+    ``old_string`` is empty, or ``old_string`` is not present in the existing
+    file (which means the Edit will fail or has already been applied — neither
+    case yields a well-defined post-edit view).
+    """
+    if not old_string:
+        return None
+    try:
+        with open(file_path, "r", encoding="utf-8") as existing_file:
+            existing_content = existing_file.read()
+    except (FileNotFoundError, OSError, UnicodeDecodeError):
+        return None
+    if old_string not in existing_content:
+        return None
+    return existing_content.replace(old_string, new_string, 1)
+
+
 def main() -> None:
     try:
         input_data = json.load(sys.stdin)
@@ -2980,9 +3037,13 @@ def main() -> None:
         sys.exit(0)
 
     old_content = ""
+    full_file_content_after_edit: str | None = None
     if tool_name == "Edit":
         content = tool_input.get("new_string", "")
         old_content = tool_input.get("old_string", "")
+        full_file_content_after_edit = _reconstruct_post_edit_file_content(
+            file_path, old_content, content,
+        )
     else:
         content = tool_input.get("content", "") or tool_input.get("new_string", "")
         try:
@@ -2997,7 +3058,7 @@ def main() -> None:
     if not content:
         sys.exit(0)
 
-    issues = validate_content(content, file_path, old_content)
+    issues = validate_content(content, file_path, old_content, full_file_content_after_edit)
 
     if issues:
         issue_list = "; ".join(issues[:10])

package/hooks/blocking/test_code_rules_enforcer_unused_imports.py

@@ -30,6 +30,7 @@ assert _hook_spec.loader is not None
 _hook_module = importlib.util.module_from_spec(_hook_spec)
 _hook_spec.loader.exec_module(_hook_module)
 check_unused_module_level_imports = _hook_module.check_unused_module_level_imports
+_reconstruct_post_edit_file_content = _hook_module._reconstruct_post_edit_file_content
 
 
 PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
@@ -297,6 +298,163 @@ def test_should_skip_when_noqa_is_bare() -> None:
     assert issues == [], f"Bare noqa must suppress unused import, got: {issues}"
 
 
+def test_should_not_flag_imports_referenced_only_in_full_file_content() -> None:
+    fragment = "from config.constants import NEW_NAME\n"
+    full_file = (
+        "from config.constants import NEW_NAME\n"
+        "\n"
+        "def existing_function() -> str:\n"
+        "    return NEW_NAME\n"
+    )
+    issues = check_unused_module_level_imports(
+        fragment, PRODUCTION_FILE_PATH, full_file_content=full_file,
+    )
+    assert issues == [], (
+        f"When the post-edit file references the import, it must not flag, got: {issues}"
+    )
+
+
+def test_should_flag_imports_unused_in_full_file_content() -> None:
+    fragment = "from config.constants import TRULY_UNUSED\n"
+    full_file = (
+        "from config.constants import TRULY_UNUSED\n"
+        "\n"
+        "def existing_function() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(
+        fragment, PRODUCTION_FILE_PATH, full_file_content=full_file,
+    )
+    assert any("TRULY_UNUSED" in each_issue for each_issue in issues), (
+        f"Imports unused in the post-edit file must still flag, got: {issues}"
+    )
+
+
+def test_should_only_flag_imports_in_fragment_not_full_file() -> None:
+    fragment = "from config.constants import FRAGMENT_IMPORT\n"
+    full_file = (
+        "from config.other import PRE_EXISTING_UNUSED\n"
+        "from config.constants import FRAGMENT_IMPORT\n"
+        "\n"
+        "def existing_function() -> str:\n"
+        "    return FRAGMENT_IMPORT\n"
+    )
+    issues = check_unused_module_level_imports(
+        fragment, PRODUCTION_FILE_PATH, full_file_content=full_file,
+    )
+    assert issues == [], (
+        "Pre-existing imports outside the fragment must not be flagged on Edit; "
+        f"got: {issues}"
+    )
+
+
+def test_should_skip_when_full_file_declares_dunder_all() -> None:
+    fragment = "from config.constants import NEW_NAME\n"
+    full_file = (
+        "from config.constants import NEW_NAME\n"
+        "\n"
+        "__all__ = ['NEW_NAME']\n"
+    )
+    issues = check_unused_module_level_imports(
+        fragment, PRODUCTION_FILE_PATH, full_file_content=full_file,
+    )
+    assert issues == [], (
+        "__all__ in the post-edit file must skip the scan even when the fragment "
+        f"itself does not contain __all__, got: {issues}"
+    )
+
+
+def test_should_skip_when_full_file_uses_type_checking_gate() -> None:
+    fragment = "from config.constants import NEW_NAME\n"
+    full_file = (
+        "from typing import TYPE_CHECKING\n"
+        "from config.constants import NEW_NAME\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from somewhere import OtherName\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(
+        fragment, PRODUCTION_FILE_PATH, full_file_content=full_file,
+    )
+    assert issues == [], (
+        "TYPE_CHECKING gate in the post-edit file must skip the scan, "
+        f"got: {issues}"
+    )
+
+
+def test_should_fall_back_to_content_when_full_file_content_is_none() -> None:
+    source = (
+        "from config.constants import VENV_DIRECTORY_NAME\n"
+        "\n"
+        "def run() -> None:\n"
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH, full_file_content=None)
+    assert any("VENV_DIRECTORY_NAME" in each_issue for each_issue in issues), (
+        f"Backward-compat: with full_file_content=None, behavior must match "
+        f"the existing single-argument scan, got: {issues}"
+    )
+
+
+def test_should_fall_back_when_full_file_content_has_syntax_error() -> None:
+    fragment = "from config.constants import NEW_NAME\n"
+    full_file_with_syntax_error = "from config import (\n  not python\n"
+    issues = check_unused_module_level_imports(
+        fragment, PRODUCTION_FILE_PATH, full_file_content=full_file_with_syntax_error,
+    )
+    assert issues == [], (
+        "When the reconstructed post-edit content cannot be parsed, return empty "
+        f"rather than raising, got: {issues}"
+    )
+
+
+def test_reconstruct_post_edit_returns_replaced_content(tmp_path: pathlib.Path) -> None:
+    target_file = tmp_path / "module.py"
+    target_file.write_text("ALPHA = 1\nBETA = 2\n", encoding="utf-8")
+    post_edit = _reconstruct_post_edit_file_content(
+        str(target_file), "BETA = 2", "BETA = 22\nGAMMA = 3",
+    )
+    assert post_edit == "ALPHA = 1\nBETA = 22\nGAMMA = 3\n", (
+        f"Helper must return the file body with the first occurrence replaced, got: {post_edit!r}"
+    )
+
+
+def test_reconstruct_post_edit_returns_none_when_file_missing(tmp_path: pathlib.Path) -> None:
+    missing_file = tmp_path / "does_not_exist.py"
+    post_edit = _reconstruct_post_edit_file_content(
+        str(missing_file), "any_old", "any_new",
+    )
+    assert post_edit is None, (
+        f"Missing file must yield None so the caller treats it as 'no full-file context', got: {post_edit!r}"
+    )
+
+
+def test_reconstruct_post_edit_returns_none_when_old_string_absent(tmp_path: pathlib.Path) -> None:
+    target_file = tmp_path / "module.py"
+    target_file.write_text("ALPHA = 1\n", encoding="utf-8")
+    post_edit = _reconstruct_post_edit_file_content(
+        str(target_file), "ZETA = 9", "OMEGA = 0",
+    )
+    assert post_edit is None, (
+        f"Absent old_string means the Edit will not apply cleanly — return None, got: {post_edit!r}"
+    )
+
+
+def test_reconstruct_post_edit_replaces_only_first_occurrence(tmp_path: pathlib.Path) -> None:
+    target_file = tmp_path / "module.py"
+    target_file.write_text("X = 1\nX = 1\n", encoding="utf-8")
+    post_edit = _reconstruct_post_edit_file_content(
+        str(target_file), "X = 1", "X = 2",
+    )
+    assert post_edit == "X = 2\nX = 1\n", (
+        "Edit replaces only the first occurrence; helper must mirror that, got: "
+        f"{post_edit!r}"
+    )
+
+
 def test_should_flag_import_when_only_shadowed_local_name_is_loaded() -> None:
     source = (
         "import json\n"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.38.0",
+    "version": "1.38.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {