claude-dev-env 1.23.1 → 1.25.0

package/hooks/blocking/test_tdd_enforcer.py

@@ -0,0 +1,249 @@
+"""Tests for tdd-enforcer hook (blocking behavior)."""
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+SCRIPT_PATH = Path(__file__).parent / "tdd-enforcer.py"
+
+
+def _load_production_module():
+    module_spec = importlib.util.spec_from_file_location("tdd_enforcer_under_test", SCRIPT_PATH)
+    assert module_spec is not None and module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+_PRODUCTION_MODULE = _load_production_module()
+FRESHNESS_SECONDS = _PRODUCTION_MODULE._freshness_seconds()
+STALE_MTIME_OFFSET_SECONDS = FRESHNESS_SECONDS + 60
+
+
+def _run_hook_with_payload(payload: dict) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def _make_write_payload(file_path: Path, content: str = "") -> dict:
+    return {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(file_path), "content": content},
+    }
+
+
+def _decision_from(completed: subprocess.CompletedProcess[str]) -> str | None:
+    if not completed.stdout:
+        return None
+    parsed = json.loads(completed.stdout)
+    hook_output = parsed.get("hookSpecificOutput", {})
+    return hook_output.get("permissionDecision")
+
+
+def _sandbox(tmp_path: Path) -> Path:
+    isolated_root = tmp_path / "sandbox"
+    isolated_root.mkdir()
+    (isolated_root / ".git").mkdir()
+    return isolated_root
+
+
+def test_should_allow_when_sibling_test_file_exists_and_recent(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    sibling_test.write_text("def test_fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_when_no_test_file_exists(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "deny"
+    parsed = json.loads(completed.stdout)
+    reason = parsed["hookSpecificOutput"]["permissionDecisionReason"]
+    assert "test_orders.py" in reason
+
+
+def test_should_deny_when_test_file_exists_but_is_stale(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    sibling_test.write_text("def test_fulfill(): pass\n")
+    stale_timestamp = time.time() - STALE_MTIME_OFFSET_SECONDS
+    os.utime(sibling_test, (stale_timestamp, stale_timestamp))
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_when_bypass_sentinel_present_in_content(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    content_with_sentinel = "# pragma: no-tdd-gate\ndef fulfill(): pass\n"
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(production_file, content_with_sentinel)
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_skip_markdown_files_entirely(tmp_path: Path) -> None:
+    markdown_file = tmp_path / "notes.md"
+
+    completed = _run_hook_with_payload(_make_write_payload(markdown_file, "# Notes\n"))
+
+    assert completed.returncode == 0
+    assert completed.stdout.strip() == ""
+
+
+def test_should_skip_test_files_entirely(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(test_file, "def test_fulfill(): pass\n")
+    )
+
+    assert completed.returncode == 0
+    assert completed.stdout.strip() == ""
+
+
+def test_should_allow_when_tests_directory_sibling_has_fresh_test(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    package_dir = sandbox / "source"
+    package_dir.mkdir()
+    tests_dir = sandbox / "tests"
+    tests_dir.mkdir()
+    production_file = package_dir / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    matching_test = tests_dir / "test_orders.py"
+    matching_test.write_text("def test_fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_allow_tsx_when_dot_test_sibling_exists(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "Button.tsx"
+    production_file.write_text("export const Button = () => null;\n")
+    sibling_test = sandbox / "Button.test.tsx"
+    sibling_test.write_text("test('renders', () => {});\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_when_test_file_has_no_test_evidence(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    sibling_test.write_text("x = 1\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_edit_when_bypass_sentinel_present_in_new_string(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    payload = {
+        "tool_name": "Edit",
+        "tool_input": {
+            "file_path": str(production_file),
+            "old_string": "pass",
+            "new_string": "# pragma: no-tdd-gate\npass",
+        },
+    }
+
+    completed = _run_hook_with_payload(payload)
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_production_file_inside_directory_containing_skip_substring(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    mockingbird_directory = sandbox / "mockingbird"
+    mockingbird_directory.mkdir()
+    production_file = mockingbird_directory / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_when_test_file_contains_only_production_stem_without_test_function(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    sibling_test.write_text("orders = 'mentioned but no test function'\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_when_large_test_file_has_valid_test_function_past_first_chunk(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+    sibling_test = sandbox / "test_orders.py"
+    padding_byte_count = 250_000
+    padding_comment = "# " + ("x" * padding_byte_count) + "\n"
+    sibling_test.write_text(padding_comment + "def test_fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_directory_skip_components_exactly_matches_pre_fc61a8b_hardcoded_set() -> None:
+    expected_directory_skip_components = frozenset({
+        "conftest", "fixture", "fixtures", "mock", "mocks", "stub", "stubs",
+    })
+
+    actual_directory_skip_components = _PRODUCTION_MODULE._directory_skip_components()
+
+    assert actual_directory_skip_components == expected_directory_skip_components
+
+
+def test_directory_skip_components_excludes_pluralized_conftest() -> None:
+    actual_directory_skip_components = _PRODUCTION_MODULE._directory_skip_components()
+
+    assert "conftests" not in actual_directory_skip_components

package/hooks/validators/exempt_paths.py

@@ -0,0 +1,99 @@
+"""Canonical path-exemption helpers shared between validator hooks.
+
+Single source of truth for CONFIG / TEST / HOOK-INFRASTRUCTURE /
+WORKFLOW-REGISTRY / MIGRATION path pattern sets. Both Pre-Write
+(``code-rules-enforcer.py``) and pre-push (``magic_value_checks.py``)
+scanners must short-circuit on the same file categories; drift between
+the two produced the "inconsistent verdicts" bug this module prevents.
+
+Matching is case-insensitive so paths like ``Config/foo.py`` or
+``src/Tests/test_x.py`` are treated the same on case-preserving
+filesystems (macOS default, Windows NTFS) as on case-sensitive ones.
+"""
+
+from __future__ import annotations
+
+
+CONFIG_PATH_PATTERNS: frozenset[str] = frozenset(
+    {
+        "config/",
+        "config\\",
+        "/config.",
+        "\\config.",
+        "settings.py",
+    }
+)
+
+TEST_PATH_PATTERNS: frozenset[str] = frozenset(
+    {
+        "test_",
+        "_test.",
+        ".spec.",
+        "conftest",
+        "/tests/",
+        "\\tests\\",
+        "/tests.py",
+        "\\tests.py",
+    }
+)
+
+HOOK_INFRASTRUCTURE_PATTERNS: frozenset[str] = frozenset(
+    {
+        "/.claude/hooks/",
+        "\\.claude\\hooks\\",
+        "\\.claude/hooks/",
+    }
+)
+
+WORKFLOW_REGISTRY_PATTERNS: frozenset[str] = frozenset(
+    {
+        "/workflow/",
+        "\\workflow\\",
+        "_tab.py",
+        "/states.py",
+        "\\states.py",
+        "/modules.py",
+        "\\modules.py",
+    }
+)
+
+MIGRATION_PATH_PATTERNS: frozenset[str] = frozenset(
+    {
+        "/migrations/",
+        "\\migrations\\",
+    }
+)
+
+
+def is_config_file(file_path: str) -> bool:
+    path_lower = file_path.lower()
+    return any(pattern in path_lower for pattern in CONFIG_PATH_PATTERNS)
+
+
+def is_test_file(file_path: str) -> bool:
+    path_lower = file_path.lower()
+    return any(pattern in path_lower for pattern in TEST_PATH_PATTERNS)
+
+
+def is_hook_infrastructure(file_path: str) -> bool:
+    path_normalized = file_path.lower().replace("\\", "/")
+    return any(
+        pattern.replace("\\", "/") in path_normalized
+        for pattern in HOOK_INFRASTRUCTURE_PATTERNS
+    )
+
+
+def is_workflow_registry_file(file_path: str) -> bool:
+    path_normalized = file_path.lower().replace("\\", "/")
+    return any(
+        pattern.replace("\\", "/") in path_normalized
+        for pattern in WORKFLOW_REGISTRY_PATTERNS
+    )
+
+
+def is_migration_file(file_path: str) -> bool:
+    path_normalized = file_path.lower().replace("\\", "/")
+    return any(
+        pattern.replace("\\", "/") in path_normalized
+        for pattern in MIGRATION_PATH_PATTERNS
+    )

package/hooks/validators/magic_value_checks.py

@@ -7,56 +7,156 @@ Note: Only checks for magic numbers. Magic string detection is not implemented.
 """
 
 import ast
+import re
 import sys
 from pathlib import Path
-from typing import List, Set
+from typing import Dict, FrozenSet, List, Set, Tuple, Type
 
+from exempt_paths import (
+    is_config_file,
+    is_test_file,
+)
 from validator_base import Violation
 
 
-ALLOWED_NUMBERS: Set[int] = frozenset({-1, 0, 1, 2, 100})
+ALLOWED_NUMBERS: FrozenSet[int] = frozenset({-1, 0, 1})
+
+_UPPER_SNAKE_NAME_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+_CONTAINER_LITERAL_TYPES: Tuple[Type[ast.AST], ...] = (
+    ast.Dict,
+    ast.List,
+    ast.Tuple,
+    ast.Set,
+)
 
 
 def check_magic_values(tree: ast.AST, filename: str) -> List[Violation]:
     violations: List[Violation] = []
-
-    constant_names: Set[str] = set()
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Assign):
-            for target in node.targets:
-                if isinstance(target, ast.Name) and target.id.isupper():
-                    constant_names.add(target.id)
+    negated_literal_ids: Set[int] = set()
+    parent_by_child_id = _build_parent_map(tree)
 
     for node in ast.walk(tree):
-        if isinstance(node, ast.Constant):
-            if isinstance(node.value, int) and node.value not in ALLOWED_NUMBERS:
-                if not _is_in_constant_definition(node, tree):
-                    violations.append(
-                        Violation(
-                            filename,
-                            node.lineno,
-                            f"Magic number {node.value} - use named constant",
-                        )
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+            operand = node.operand
+            if isinstance(operand, ast.UnaryOp):
+                continue
+            if (
+                isinstance(operand, ast.Constant)
+                and isinstance(operand.value, int)
+                and not isinstance(operand.value, bool)
+            ):
+                negated_literal_ids.add(id(operand))
+                outermost_unary = _walk_up_unary_minus(node, parent_by_child_id)
+                negation_depth = _count_unary_minus_depth(outermost_unary)
+                unsigned_value = operand.value
+                signed_value = -unsigned_value if negation_depth % 2 == 1 else unsigned_value
+                if signed_value in ALLOWED_NUMBERS:
+                    continue
+                if _is_in_constant_definition(outermost_unary, parent_by_child_id):
+                    continue
+                violations.append(
+                    Violation(
+                        filename,
+                        node.lineno,
+                        f"Magic number {signed_value} - use named constant",
                     )
+                )
+            continue
+        if isinstance(node, ast.Constant):
+            if not isinstance(node.value, int):
+                continue
+            if isinstance(node.value, bool):
+                continue
+            if id(node) in negated_literal_ids:
+                continue
+            if node.value in ALLOWED_NUMBERS:
+                continue
+            if _is_in_constant_definition(node, parent_by_child_id):
+                continue
+            violations.append(
+                Violation(
+                    filename,
+                    node.lineno,
+                    f"Magic number {node.value} - use named constant",
+                )
+            )
 
     return violations
 
 
-def _is_in_constant_definition(node: ast.Constant, tree: ast.AST) -> bool:
+def _build_parent_map(tree: ast.AST) -> Dict[int, ast.AST]:
+    parent_by_child_id: Dict[int, ast.AST] = {}
     for parent in ast.walk(tree):
-        if isinstance(parent, ast.Assign):
-            for target in parent.targets:
-                if isinstance(target, ast.Name) and target.id.isupper():
-                    if parent.value is node:
-                        return True
+        for child in ast.iter_child_nodes(parent):
+            parent_by_child_id[id(child)] = parent
+    return parent_by_child_id
+
+
+def _walk_up_unary_minus(
+    node: ast.UnaryOp,
+    parent_by_child_id: Dict[int, ast.AST],
+) -> ast.UnaryOp:
+    current: ast.UnaryOp = node
+    while True:
+        parent = parent_by_child_id.get(id(current))
+        if isinstance(parent, ast.UnaryOp) and isinstance(parent.op, ast.USub):
+            current = parent
+            continue
+        return current
+
+
+def _count_unary_minus_depth(node: ast.UnaryOp) -> int:
+    depth = 0
+    current: ast.AST = node
+    while isinstance(current, ast.UnaryOp) and isinstance(current.op, ast.USub):
+        depth += 1
+        current = current.operand
+    return depth
+
+
+def _is_in_constant_definition(
+    node: ast.AST,
+    parent_by_child_id: Dict[int, ast.AST],
+) -> bool:
+    current_node: ast.AST = node
+    while id(current_node) in parent_by_child_id:
+        parent = parent_by_child_id[id(current_node)]
+        if _is_upper_snake_constant_assignment(parent):
+            return True
+        if not isinstance(parent, _CONTAINER_LITERAL_TYPES):
+            return False
+        current_node = parent
     return False
 
 
+def _is_upper_snake_constant_assignment(node: ast.AST) -> bool:
+    if isinstance(node, ast.Assign):
+        for target in node.targets:
+            if isinstance(target, ast.Name) and _is_upper_snake_name(target.id):
+                return True
+        return False
+    if isinstance(node, ast.AnnAssign):
+        target = node.target
+        return isinstance(target, ast.Name) and _is_upper_snake_name(target.id)
+    return False
+
+
+def _is_upper_snake_name(name: str) -> bool:
+    return bool(_UPPER_SNAKE_NAME_PATTERN.match(name))
+
+
+def _is_exempt_path(file_path: str) -> bool:
+    return is_test_file(file_path) or is_config_file(file_path)
+
+
 def validate_file(file_path: Path) -> List[Violation]:
     filename = str(file_path)
+    if _is_exempt_path(filename):
+        return []
     try:
-        source = file_path.read_text(encoding="utf-8")
-        tree = ast.parse(source)
+        source_bytes = file_path.read_bytes()
+        tree = ast.parse(source_bytes)
     except Exception as error:
         return [Violation(filename, 0, f"Error: {error}")]