claude-dev-env 1.79.0 → 1.81.0

package/hooks/blocking/test_code_rules_enforcer_annotations.py

@@ -89,10 +89,28 @@ def test_should_flag_async_function_without_return_annotation() -> None:
     )
 
 
-def test_should_skip_return_check_in_test_files() -> None:
+def test_should_skip_return_check_for_test_file_helper() -> None:
     source = "def fetch(url: str):\n    return url\n"
     issues = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH)
-    assert issues == [], f"Test files must be exempt, got: {issues}"
+    assert issues == [], f"Non-test helper in a test file must be exempt, got: {issues}"
+
+
+def test_should_flag_test_function_missing_return_annotation() -> None:
+    source = "def test_loads():\n    assert True\n"
+    issues = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH)
+    assert any("test_loads" in each_issue for each_issue in issues), (
+        f"Pytest test function must require a return annotation, got: {issues}"
+    )
+
+
+def test_should_scope_test_function_return_annotation_to_changed_lines() -> None:
+    source = "def helper():\n    return 1\n\n\ndef test_uses_it():\n    assert helper()\n"
+    unchanged = code_rules_enforcer.check_return_annotations(source, TEST_FILE_PATH, {2})
+    assert unchanged == []
+    on_definition = code_rules_enforcer.check_return_annotations(
+        source, TEST_FILE_PATH, {5}
+    )
+    assert any("test_uses_it" in each_issue for each_issue in on_definition)
 
 
 def test_should_flag_unannotated_known_fixture_in_test_file() -> None:

package/hooks/blocking/test_code_rules_enforcer_banned_identifier.py

@@ -95,10 +95,18 @@ def test_should_not_flag_name_containing_banned_substring() -> None:
     assert issues == []
 
 
-def test_should_skip_test_files() -> None:
+def test_should_scope_test_file_banned_identifier_to_changed_lines() -> None:
+    content = "def test_thing():\n    result = compute()\n    assert result\n"
+    unchanged_only = check_banned_identifiers(content, TEST_FILE_PATH, {1, 3})
+    assert unchanged_only == []
+    on_changed_line = check_banned_identifiers(content, TEST_FILE_PATH, {2})
+    assert any("result" in each_issue for each_issue in on_changed_line)
+
+
+def test_should_flag_newly_written_test_file_banned_identifier() -> None:
     content = "def test_thing():\n    result = compute()\n    assert result\n"
     issues = check_banned_identifiers(content, TEST_FILE_PATH)
-    assert issues == []
+    assert any("'result'" in each_issue for each_issue in issues)
 
 
 def test_should_skip_hook_infrastructure() -> None:

package/hooks/blocking/test_code_rules_enforcer_banned_import_alias.py

@@ -117,11 +117,15 @@ def test_should_flag_btn_assignment() -> None:
     )
 
 
-def test_should_not_flag_import_alias_in_test_file() -> None:
+def test_should_scope_import_alias_in_test_file_to_changed_lines() -> None:
     content = "from config import rebase_constants as rc\n"
-    issues = check_banned_identifiers(content, TEST_FILE_PATH)
-    assert issues == [], (
-        f"Test files are exempt from banned-identifier checks, got: {issues}"
+    unchanged_only = check_banned_identifiers(content, TEST_FILE_PATH, {2})
+    assert unchanged_only == [], (
+        f"A banned alias on an untouched line must not block, got: {unchanged_only}"
+    )
+    on_changed_line = check_banned_identifiers(content, TEST_FILE_PATH, {1})
+    assert any("'rc'" in each_issue for each_issue in on_changed_line), (
+        f"A newly written banned alias in a test file must flag, got: {on_changed_line}"
     )
 
 

package/hooks/blocking/test_code_rules_enforcer_dispatch_wiring.py

@@ -10,8 +10,12 @@ orphan CSS class slip past the gate again.
 This module reads ``validate_content``'s source and asserts every ``check_*``
 attribute on the enforcer module appears in it. A check that is intentionally
 not wired must be listed in ``KNOWN_UNDISPATCHED_CHECKS`` with a reason in this
-docstring; no such checks exist today. The companion ``test_code_rules_enforcer_
-cap_meta.py`` guards the payload-cap convention; this module guards the wiring.
+docstring. ``check_unanchored_command_dispatch`` is listed there: it guards a
+``hooks/blocking`` command classifier, and the whole ``validate_content`` verdict
+stays off hook-infrastructure files, so the enforcer dispatches it from
+``_hook_infrastructure_blocking_issues`` instead. The companion
+``test_code_rules_enforcer_cap_meta.py`` guards the payload-cap convention; this
+module guards the wiring.
 """
 
 from __future__ import annotations
@@ -34,7 +38,9 @@ assert _hook_specification.loader is not None
 _hook_module = importlib.util.module_from_spec(_hook_specification)
 _hook_specification.loader.exec_module(_hook_module)
 
-KNOWN_UNDISPATCHED_CHECKS: frozenset[str] = frozenset()
+KNOWN_UNDISPATCHED_CHECKS: frozenset[str] = frozenset(
+    {"check_unanchored_command_dispatch"}
+)
 
 
 def _all_check_function_names() -> list[str]:

package/hooks/blocking/test_code_rules_enforcer_docstring_type_checking_gate.py

@@ -0,0 +1,164 @@
+"""Tests for check_docstring_names_absent_type_checking_gate — Category O6.
+
+A module or function docstring that names a ``TYPE_CHECKING`` gate-detection step,
+or a ``type-checking-gate`` helper family, drifts once no identifier in the body
+handles TYPE_CHECKING: the prose points a reader at machinery the module does not
+hold. This is the deterministic slice of Category O6 (docstring prose versus
+implementation drift) for a TYPE_CHECKING gate claim. The check covers hook
+infrastructure, where the import-scan gates that carry this drift class live.
+"""
+
+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_type_checking_gate(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_names_absent_type_checking_gate(content, file_path)
+
+
+PRODUCTION_HOOK_PATH = "/home/user/.claude/hooks/blocking/code_rules_unused_imports.py"
+TEST_FILE_PATH = "/home/user/.claude/hooks/blocking/test_code_rules_unused_imports.py"
+MYPY_GATE_PRODUCTION_PATH = "/home/user/project/scripts/run_mypy_gate.py"
+
+
+def test_flags_module_docstring_naming_type_checking_gate_helpers() -> None:
+    content = (
+        '"""Unused module-level import check and its import-range and '
+        'type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Flag unused imports."""\n'
+        "    return []\n"
+    )
+    issues = check_type_checking_gate(content, PRODUCTION_HOOK_PATH)
+    assert len(issues) == 1
+    assert issues[0].startswith("Line 1:")
+    assert "type-checking-gate" in issues[0]
+
+
+def test_flags_function_docstring_naming_type_checking_gate_detection() -> None:
+    content = (
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused_module_level_imports(content: str) -> list[str]:\n"
+        '    """Flag module-level imports never referenced.\n'
+        "\n"
+        "    When ``full_file_content`` is provided, the ``__all__`` /\n"
+        "    ``TYPE_CHECKING`` gate detection and reference scanning run against\n"
+        "    ``full_file_content``.\n"
+        '    """\n'
+        "    return []\n"
+    )
+    issues = check_type_checking_gate(content, PRODUCTION_HOOK_PATH)
+    assert len(issues) == 1
+    assert "type_checking gate" in issues[0]
+
+
+def test_flags_both_module_and_function_docstrings_on_the_real_drift() -> None:
+    content = (
+        '"""Unused module-level import check and its import-range and '
+        'type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused_module_level_imports(content: str) -> list[str]:\n"
+        '    """Flag module-level imports never referenced.\n'
+        "\n"
+        "    The ``__all__`` / ``TYPE_CHECKING`` gate detection and reference\n"
+        "    scanning run against ``full_file_content``.\n"
+        '    """\n'
+        "    return []\n"
+    )
+    issues = check_type_checking_gate(content, PRODUCTION_HOOK_PATH)
+    assert len(issues) == 2
+
+
+def test_passes_when_code_declares_a_type_checking_gate_helper() -> None:
+    content = (
+        '"""Unused module-level import check and its type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def _module_body_declares_type_checking_gate(tree: ast.Module) -> bool:\n"
+        '    """Return True when the module guards imports behind TYPE_CHECKING."""\n'
+        "    return False\n"
+    )
+    assert check_type_checking_gate(content, PRODUCTION_HOOK_PATH) == []
+
+
+def test_passes_when_body_names_type_checking_guard() -> None:
+    content = (
+        "import ast\n"
+        "from typing import TYPE_CHECKING\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Skip imports the ``TYPE_CHECKING`` gate detection guards."""\n'
+        "    if TYPE_CHECKING:\n"
+        "        return []\n"
+        "    return []\n"
+    )
+    assert check_type_checking_gate(content, PRODUCTION_HOOK_PATH) == []
+
+
+def test_passes_when_no_docstring_names_the_gate() -> None:
+    content = (
+        '"""Unused module-level import check and its import-range helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Flag module-level imports never referenced."""\n'
+        "    return []\n"
+    )
+    assert check_type_checking_gate(content, PRODUCTION_HOOK_PATH) == []
+
+
+def test_passes_on_mypy_static_type_checker_gate_docstring() -> None:
+    content = (
+        "\"\"\"Run the project's type-checking gate and report failures.\"\"\"\n"
+        "\n"
+        "import subprocess\n"
+        "\n"
+        "\n"
+        "def run_gate() -> int:\n"
+        '    return subprocess.run(["mypy", "hooks"]).returncode\n'
+    )
+    assert check_type_checking_gate(content, MYPY_GATE_PRODUCTION_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    content = (
+        '"""Unused module-level import check and its type-checking-gate helpers."""\n'
+        "\n"
+        "import ast\n"
+        "\n"
+        "\n"
+        "def check_unused(content: str) -> list[str]:\n"
+        '    """Flag unused imports."""\n'
+        "    return []\n"
+    )
+    assert check_type_checking_gate(content, TEST_FILE_PATH) == []

package/hooks/blocking/test_code_rules_enforcer_js_returns_object.py

@@ -0,0 +1,72 @@
+"""Enforcer-dispatch tests for the JS returns-object schema-less branch check.
+
+These drive ``validate_content`` end-to-end on a ``.mjs`` payload, so they prove
+the check is wired into the JavaScript branch of the enforcer, not just callable
+in isolation. The drift: a ``function`` whose JSDoc ``@returns {Promise<object>}``
+promises a structured object while one branch returns the agent helper with an
+options object that omits ``schema`` and so resolves to a transcript string.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+
+
+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()
+
+_MJS_PATH = "skills/autoconverge/workflow/converge.mjs"
+
+
+def _mixed_schema_mjs() -> str:
+    return (
+        "/**\n"
+        " * Spawn a git-utility agent.\n"
+        " * @returns {Promise<object>} the structured output\n"
+        " */\n"
+        "function runGitTask(task, head) {\n"
+        "  if (task === 'resolve-head') {\n"
+        "    return convergeAgent(`head ${x}`, { label: 'g', schema: HEAD_SCHEMA, agentType: 'Explore' })\n"
+        "  }\n"
+        "  return convergeAgent(`fetch ${x}`, { label: 'g', agentType: 'Explore' })\n"
+        "}\n"
+    )
+
+
+def _all_schema_mjs() -> str:
+    return _mixed_schema_mjs().replace(
+        "{ label: 'g', agentType: 'Explore' })",
+        "{ label: 'g', schema: FETCH_SCHEMA, agentType: 'Explore' })",
+    )
+
+
+def _has_returns_object_finding(all_issues: list[str]) -> bool:
+    return any("runGitTask" in each_issue and "@returns" in each_issue for each_issue in all_issues)
+
+
+def test_enforcer_reports_schema_less_branch_under_returns_object() -> None:
+    drift_source = _mixed_schema_mjs()
+    all_issues = code_rules_enforcer.validate_content(drift_source, _MJS_PATH, drift_source)
+    assert _has_returns_object_finding(all_issues)
+
+
+def test_enforcer_accepts_every_branch_with_a_schema() -> None:
+    clean_source = _all_schema_mjs()
+    all_issues = code_rules_enforcer.validate_content(clean_source, _MJS_PATH, clean_source)
+    assert not _has_returns_object_finding(all_issues)

package/hooks/blocking/test_code_rules_enforcer_unused_imports.py

@@ -5,9 +5,12 @@ ALL_REPOSITORY_ROOT_MARKER_FILENAMES, VENV_DIRECTORY_NAME and other
 imports that survived into a PR without ever being referenced.
 
 The detector is intentionally narrow: it only flags `from X import Y`
-or `import X` where Y/X is never referenced in the file body, the file
-does not declare `__all__`, and the file does not use TYPE_CHECKING
-conditional imports. The narrow scope keeps false positives low.
+or `import X` where Y/X is never referenced in the file body and the
+file does not declare `__all__`. A `TYPE_CHECKING` guard block no longer
+exempts the whole file — its guarded imports live nested inside the
+`if TYPE_CHECKING:` node so they are never flag candidates, while a
+genuinely dead top-level runtime import in the same file is still
+flagged. The narrow scope keeps false positives low.
 """
 
 from __future__ import annotations
@@ -102,7 +105,7 @@ def test_should_skip_file_with_dunder_all_annotated_assignment() -> None:
     )
 
 
-def test_should_skip_file_using_type_checking_block() -> None:
+def test_should_flag_dead_top_level_import_in_type_checking_file() -> None:
     source = (
         "from typing import TYPE_CHECKING\n"
         "from hooks_constants.constants import UNUSED_NAME\n"
@@ -114,20 +117,101 @@ def test_should_skip_file_using_type_checking_block() -> None:
         "    return None\n"
     )
     issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        "A dead top-level runtime import must be flagged even when the file "
+        f"also declares a TYPE_CHECKING block, got: {issues}"
+    )
+    assert not any("OtherName" in each_issue for each_issue in issues), (
+        "A TYPE_CHECKING-guarded import is nested inside the if block and is "
+        f"never a flag candidate, got: {issues}"
+    )
+
+
+def test_should_not_flag_standard_type_checking_idiom() -> None:
+    source = (
+        "from typing import TYPE_CHECKING\n"
+        "from hooks_constants.constants import RUNTIME_NAME\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from somewhere import TypeOnly\n"
+        "\n"
+        "def run(node: TypeOnly) -> None:\n"
+        "    RUNTIME_NAME()\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
     assert issues == [], (
-        f"TYPE_CHECKING-using files have annotation-only imports — skip, got: {issues}"
+        "The standard TYPE_CHECKING idiom — TYPE_CHECKING referenced by the "
+        "guard, the runtime import used in the body, and the guarded import "
+        f"used in an annotation — must produce no findings, got: {issues}"
     )
 
 
-def test_should_skip_test_files() -> None:
+def test_should_flag_dead_import_beside_type_checking_string_annotation() -> None:
     source = (
-        "from hooks_constants.constants import UNUSED_NAME\n"
+        "from typing import TYPE_CHECKING\n"
+        "from shared_utils.config import portal_specific_timeouts\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from shared_utils.base import BaseAutomation\n"
+        "\n"
+        'async def run(automation: "BaseAutomation") -> None:\n'
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
+    assert any("portal_specific_timeouts" in each_issue for each_issue in issues), (
+        "A dead top-level import in a module that guards its annotation-only "
+        f"import under TYPE_CHECKING must still be flagged, got: {issues}"
+    )
+    assert not any("BaseAutomation" in each_issue for each_issue in issues), (
+        "The TYPE_CHECKING-guarded import used in a string annotation must not "
+        f"be flagged, got: {issues}"
+    )
+
+
+def test_should_flag_dead_import_in_workflow_handler_file() -> None:
+    workflow_handler_path = (
+        "shared_utils/web_automation/samsung_portal/workflow/binary/delete_handlers.py"
+    )
+    source = (
+        "from typing import TYPE_CHECKING\n"
+        "from shared_utils.config import portal_specific_timeouts\n"
+        "\n"
+        "if TYPE_CHECKING:\n"
+        "    from shared_utils.base import BaseAutomation\n"
+        "\n"
+        'async def run(automation: "BaseAutomation") -> None:\n'
+        "    return None\n"
+    )
+    issues = check_unused_module_level_imports(source, workflow_handler_path)
+    assert any("portal_specific_timeouts" in each_issue for each_issue in issues), (
+        "A handler file under a workflow/ directory is not a state/module "
+        "registry; a dead import in it must be flagged, not exempted by the "
+        f"workflow path, got: {issues}"
+    )
+
+
+def test_should_flag_unused_import_in_test_file() -> None:
+    source = (
+        "import asyncio\n"
         "\n"
         "def test_thing() -> None:\n"
         "    assert True\n"
     )
     issues = check_unused_module_level_imports(source, TEST_FILE_PATH)
-    assert issues == [], f"Test files exempt, got: {issues}"
+    assert any("asyncio" in each_issue for each_issue in issues), (
+        f"Unused import in a test file must be flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_used_import_in_test_file() -> None:
+    source = (
+        "import asyncio\n"
+        "\n"
+        "def test_thing() -> None:\n"
+        "    asyncio.run(main())\n"
+    )
+    issues = check_unused_module_level_imports(source, TEST_FILE_PATH)
+    assert issues == [], f"Used import in a test file must not be flagged, got: {issues}"
 
 
 def test_should_handle_syntax_error_gracefully() -> None:
@@ -364,7 +448,7 @@ def test_should_skip_when_full_file_declares_dunder_all() -> None:
     )
 
 
-def test_should_skip_when_full_file_uses_type_checking_gate() -> None:
+def test_should_flag_dead_fragment_import_when_full_file_uses_type_checking() -> None:
     fragment = "from hooks_constants.constants import NEW_NAME\n"
     full_file = (
         "from typing import TYPE_CHECKING\n"
@@ -379,9 +463,9 @@ def test_should_skip_when_full_file_uses_type_checking_gate() -> None:
     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}"
+    assert any("NEW_NAME" in each_issue for each_issue in issues), (
+        "A TYPE_CHECKING block in the post-edit file must not exempt a dead "
+        f"import added by the edit fragment, got: {issues}"
     )
 
 
@@ -472,7 +556,7 @@ def test_should_flag_import_when_only_shadowed_local_name_is_loaded() -> None:
     )
 
 
-def test_should_skip_when_type_checking_uses_imported_alias() -> None:
+def test_should_not_flag_guarded_import_under_imported_type_checking_alias() -> None:
     source = (
         "from typing import TYPE_CHECKING as IS_TYPE_CHECKING\n"
         "from hooks_constants.constants import UNUSED_NAME\n"
@@ -484,12 +568,17 @@ def test_should_skip_when_type_checking_uses_imported_alias() -> None:
         "    return None\n"
     )
     issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
-    assert issues == [], (
-        f"TYPE_CHECKING imported aliases must skip annotation-only files, got: {issues}"
+    assert not any("OtherName" in each_issue for each_issue in issues), (
+        "An import guarded under an aliased TYPE_CHECKING is nested in the if "
+        f"block and is never a flag candidate, got: {issues}"
+    )
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        "A dead top-level import beside an aliased TYPE_CHECKING guard is still "
+        f"flagged, got: {issues}"
     )
 
 
-def test_should_skip_when_type_checking_uses_module_alias() -> None:
+def test_should_not_flag_guarded_import_under_module_type_checking_alias() -> None:
     source = (
         "import typing as t\n"
         "from hooks_constants.constants import UNUSED_NAME\n"
@@ -501,8 +590,13 @@ def test_should_skip_when_type_checking_uses_module_alias() -> None:
         "    return None\n"
     )
     issues = check_unused_module_level_imports(source, PRODUCTION_FILE_PATH)
-    assert issues == [], (
-        f"TYPE_CHECKING module aliases must skip annotation-only files, got: {issues}"
+    assert not any("OtherName" in each_issue for each_issue in issues), (
+        "An import guarded under a module-qualified TYPE_CHECKING is nested in "
+        f"the if block and is never a flag candidate, got: {issues}"
+    )
+    assert any("UNUSED_NAME" in each_issue for each_issue in issues), (
+        "A dead top-level import beside a module-qualified TYPE_CHECKING guard "
+        f"is still flagged, got: {issues}"
     )