claude-dev-env 1.80.0 → 1.82.0

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_unused_imports.py

@@ -190,15 +190,28 @@ def test_should_flag_dead_import_in_workflow_handler_file() -> None:
     )
 
 
-def test_should_skip_test_files() -> None:
+def test_should_flag_unused_import_in_test_file() -> None:
     source = (
-        "from hooks_constants.constants import UNUSED_NAME\n"
+        "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:

package/hooks/blocking/test_code_rules_js_conventions.py

@@ -0,0 +1,167 @@
+"""Behavioral tests for the JavaScript boolean-naming and banned-identifier checks."""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+
+from code_rules_js_conventions import (  # noqa: E402
+    check_js_banned_identifiers,
+    check_js_boolean_naming,
+)
+
+CONVERGE_PATH = "packages/claude-dev-env/skills/autoconverge/workflow/converge.mjs"
+
+
+def test_flags_unprefixed_boolean_let_declaration() -> None:
+    content = "let hardeningPrOpened = false\n"
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "hardeningPrOpened" in issues[0]
+    assert "Line 1" in issues[0]
+
+
+def test_flags_unprefixed_boolean_negation_declaration() -> None:
+    content = "const readyState = !pending\n"
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "readyState" in issues[0]
+
+
+def test_flags_pure_negation_declaration() -> None:
+    content = "const ready = !pending;\n"
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "ready" in issues[0]
+
+
+def test_does_not_flag_ternary_negation_string_declaration() -> None:
+    content = 'const label = !isActive ? "on" : "off";\n'
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_ternary_negation_number_declaration() -> None:
+    content = "const count = !arr.length ? 0 : arr.length;\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_negation_logical_and_declaration() -> None:
+    content = "const name = !err && getName();\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_negation_logical_or_declaration() -> None:
+    content = "const port = !custom || 8080;\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_flags_unprefixed_boolean_jsdoc_param() -> None:
+    content = (
+        "/**\n"
+        " * @param {boolean} alreadyOpened whether the PR is open\n"
+        " */\n"
+        "function note(alreadyOpened) { return alreadyOpened }\n"
+    )
+    issues = check_js_boolean_naming(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "alreadyOpened" in issues[0]
+    assert "parameter" in issues[0].lower()
+
+
+def test_accepts_prefixed_boolean_declarations() -> None:
+    content = (
+        "let isReady = true\n"
+        "const hasItems = false\n"
+        "let shouldRetry = !done\n"
+        "var wasOpened = true\n"
+    )
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_accepts_prefixed_boolean_jsdoc_param() -> None:
+    content = (
+        "/**\n"
+        " * @param {boolean} isOpen whether the PR is open\n"
+        " */\n"
+        "function note(isOpen) { return isOpen }\n"
+    )
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_ignores_boolean_declaration_inside_string_literal() -> None:
+    content = 'const label = "let flagged = false"\n'
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_ignores_boolean_declaration_inside_line_comment() -> None:
+    content = "// let flagged = false\nconst isReady = true\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_does_not_flag_falsely_named_non_boolean_declaration() -> None:
+    content = "const counted = falsely()\n"
+    assert check_js_boolean_naming(content, CONVERGE_PATH) == []
+
+
+def test_boolean_naming_scoped_to_changed_lines() -> None:
+    content = "let alreadyRun = false\nconst isReady = true\n"
+    unchanged_only = check_js_boolean_naming(content, CONVERGE_PATH, {2})
+    assert unchanged_only == []
+    changed = check_js_boolean_naming(content, CONVERGE_PATH, {1})
+    assert len(changed) == 1
+    assert "alreadyRun" in changed[0]
+
+
+def test_boolean_naming_defer_scope_returns_all() -> None:
+    content = "let alreadyRun = false\n"
+    deferred = check_js_boolean_naming(content, CONVERGE_PATH, None, True)
+    assert len(deferred) == 1
+
+
+def test_boolean_naming_exempts_test_files() -> None:
+    content = "let alreadyRun = false\n"
+    assert check_js_boolean_naming(content, "workflow/converge.test.mjs") == []
+
+
+def test_flags_banned_identifier_declaration() -> None:
+    content = "let data = fetchThings()\n"
+    issues = check_js_banned_identifiers(content, CONVERGE_PATH)
+    assert len(issues) == 1
+    assert "data" in issues[0]
+    assert "Line 1" in issues[0]
+
+
+def test_accepts_descriptive_identifier_declaration() -> None:
+    content = "let allOrders = fetchThings()\n"
+    assert check_js_banned_identifiers(content, CONVERGE_PATH) == []
+
+
+def test_banned_identifier_message_carries_descriptive_name_guidance() -> None:
+    content = "let data = fetchThings()\n"
+    issues = check_js_banned_identifiers(content, CONVERGE_PATH)
+    assert "use descriptive name (see CODE_RULES Naming section)" in issues[0]
+
+
+def test_flags_each_banned_identifier_name() -> None:
+    content = "const result = compute()\nlet response = call()\nvar ctx = build()\n"
+    issues = check_js_banned_identifiers(content, CONVERGE_PATH)
+    assert len(issues) == 3
+
+
+def test_banned_identifier_ignores_string_literal() -> None:
+    content = 'const label = "let data = 1"\n'
+    assert check_js_banned_identifiers(content, CONVERGE_PATH) == []
+
+
+def test_banned_identifier_scoped_to_changed_lines() -> None:
+    content = "let data = one()\nconst allOrders = two()\n"
+    assert check_js_banned_identifiers(content, CONVERGE_PATH, {2}) == []
+    changed = check_js_banned_identifiers(content, CONVERGE_PATH, {1})
+    assert len(changed) == 1
+
+
+def test_banned_identifier_exempts_test_files() -> None:
+    content = "let data = one()\n"
+    assert check_js_banned_identifiers(content, "workflow/converge.test.mjs") == []