claude-dev-env 1.95.0 → 2.0.1

package/hooks/blocking/tdd_enforcer_parts/CLAUDE.md

@@ -0,0 +1,30 @@
+# tdd_enforcer_parts
+
+The concern modules `tdd_enforcer.py` wires together to run the TDD gate. Each
+module owns one concern; the entry hook imports them and re-exports their
+surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `path_classification.py` | Classifies a write target (docs, tests, `.claude` trees) the gate skips, and extracts the written text from a Write, Edit, or MultiEdit payload |
+| `content_analysis.py` | Decides whether a payload is constants-only, and whether an Edit or MultiEdit merely removes or reorders imports |
+| `candidate_paths.py` | Resolves the candidate test files whose freshness can satisfy the gate for a production file |
+| `freshness.py` | Checks whether a candidate test was modified within the window and holds a real test function |
+| `git_tracking.py` | Detects a write that restores a git-tracked file absent on disk, so a remove-then-Write rewrite is exempt from the gate |
+| `decisions.py` | Builds the deny reason and writes the allow or deny decision JSON to stdout |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The freshness window, the ancestor-walk limit, the git-tracking command tokens, the source-file extension sets, and the join separator (`tdd_enforcer_constants.py`) |
+| `tests/` | pytest suite with one test module per module above |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/tdd_enforcer_parts/tests/
+```

package/hooks/blocking/tdd_enforcer_parts/__init__.py

@@ -0,0 +1 @@
+"""Decomposed concern modules the ``tdd_enforcer`` entry hook wires together."""

package/hooks/blocking/tdd_enforcer_parts/candidate_paths.py

@@ -0,0 +1,142 @@
+"""Resolve the test files whose freshness can satisfy the gate for a module.
+
+Given a production file, builds every path a matching test could live at: the
+flat sibling ``test_<stem>.py``, the package-mirroring candidates under an
+ancestor ``tests`` directory, and the split test family for ``code_rules_*``
+modules.
+"""
+
+from pathlib import Path
+
+from tdd_enforcer_parts.config.tdd_enforcer_constants import (
+    ALL_JAVASCRIPT_TEST_EXTENSIONS,
+    ALL_REPO_BOUNDARY_SENTINELS,
+    PARENT_WALK_LIMIT,
+    PYTHON_SOURCE_EXTENSION,
+)
+
+
+def _tests_directory_name() -> str:
+    return "tests"
+
+
+def _parent_walk_limit() -> int:
+    return PARENT_WALK_LIMIT
+
+
+def _repo_boundary_sentinels() -> frozenset[str]:
+    return ALL_REPO_BOUNDARY_SENTINELS
+
+
+def _split_module_stem_prefix() -> str:
+    return "code_rules_"
+
+
+def _split_test_family_glob() -> str:
+    return "test_code_rules_enforcer_*.py"
+
+
+def _javascript_test_extensions() -> frozenset[str]:
+    return ALL_JAVASCRIPT_TEST_EXTENSIONS
+
+
+def _is_repo_boundary(candidate_directory: Path) -> bool:
+    for each_sentinel in _repo_boundary_sentinels():
+        if (candidate_directory / each_sentinel).exists():
+            return True
+    return False
+
+
+def _ancestor_tests_directories(start_directory: Path) -> list[tuple[Path, Path]]:
+    """Collect each ancestor's sibling ``tests`` directory up to the repo root.
+
+    Args:
+        start_directory: Directory of the production file under edit.
+
+    Returns:
+        Ordered ``(ancestor, tests_directory)`` pairs, nearer ancestors first.
+    """
+    all_pairs: list[tuple[Path, Path]] = []
+    current_directory = start_directory
+    remaining_steps = _parent_walk_limit()
+    while remaining_steps > 0:
+        remaining_steps -= 1
+        sibling_tests = current_directory / _tests_directory_name()
+        if sibling_tests.is_dir():
+            all_pairs.append((current_directory, sibling_tests))
+        if _is_repo_boundary(current_directory):
+            break
+        if current_directory.parent == current_directory:
+            break
+        current_directory = current_directory.parent
+    return all_pairs
+
+
+def _split_family_candidates(directory: Path, stem: str) -> list[Path]:
+    if not stem.startswith(_split_module_stem_prefix()):
+        return []
+    return sorted(directory.glob(_split_test_family_glob()))
+
+
+def _flat_stem_candidates(directory: Path, stem: str) -> list[Path]:
+    return [directory / f"test_{stem}.py", directory / f"{stem}_test.py"]
+
+
+def _mirrored_nested_candidates(
+    directory: Path, ancestor: Path, tests_directory: Path, stem: str
+) -> list[Path]:
+    all_candidates: list[Path] = []
+    nested_directory = tests_directory
+    for each_relative_part in directory.relative_to(ancestor).parts:
+        nested_directory = nested_directory / each_relative_part
+        all_candidates.append(nested_directory / f"test_{stem}.py")
+    return all_candidates
+
+
+def _nested_tests_candidates(directory: Path, stem: str) -> list[Path]:
+    all_candidates: list[Path] = []
+    for each_ancestor, each_tests_directory in _ancestor_tests_directories(directory):
+        all_candidates.append(each_tests_directory / f"test_{stem}.py")
+        all_candidates.extend(
+            _mirrored_nested_candidates(directory, each_ancestor, each_tests_directory, stem)
+        )
+    return all_candidates
+
+
+def _python_candidate_test_paths(directory: Path, stem: str) -> list[Path]:
+    all_candidates = _flat_stem_candidates(directory, stem)
+    all_candidates.extend(_nested_tests_candidates(directory, stem))
+    all_candidates.extend(_split_family_candidates(directory, stem))
+    return all_candidates
+
+
+def _javascript_candidate_test_paths(directory: Path, stem: str, extension: str) -> list[Path]:
+    return [directory / f"{stem}.test{extension}", directory / f"{stem}.spec{extension}"]
+
+
+def candidate_test_paths_for(production_path: Path) -> list[Path]:
+    """Return the test files that can satisfy the gate for a production file.
+
+    ::
+
+        pkg/orders.py -> pkg/test_orders.py, pkg/orders_test.py,
+                         pkg/tests/test_orders.py (and package mirrors)
+
+    ``code_rules_*`` Python modules also gain the split test family. Plain
+    stem-derived candidates always come first.
+
+    Args:
+        production_path: The production source file being written or edited.
+
+    Returns:
+        Ordered candidate test paths; stem-derived siblings precede any
+        split-family additions.
+    """
+    directory = production_path.parent
+    stem = production_path.stem
+    extension = production_path.suffix.lower()
+    if extension == PYTHON_SOURCE_EXTENSION:
+        return _python_candidate_test_paths(directory, stem)
+    if extension in _javascript_test_extensions():
+        return _javascript_candidate_test_paths(directory, stem, extension)
+    return []

package/hooks/blocking/tdd_enforcer_parts/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration home for the TDD-enforcer parts constants."""

package/hooks/blocking/tdd_enforcer_parts/config/tdd_enforcer_constants.py

@@ -0,0 +1,32 @@
+"""Constants for the TDD-enforcer hook and its decomposed parts modules.
+
+Centralizes the freshness window, the ancestor-walk limit, the git-tracking
+command tokens, the source-file extension sets, and the join separator.
+"""
+
+from __future__ import annotations
+
+FRESHNESS_WINDOW_SECONDS: int = 600
+PARENT_WALK_LIMIT: int = 10
+GIT_LS_FILES_TIMEOUT_SECONDS: int = 10
+GIT_EXECUTABLE_NAME: str = "git"
+GIT_LS_FILES_SUBCOMMAND: str = "ls-files"
+GIT_PATHSPEC_SEPARATOR: str = "--"
+PYTHON_SOURCE_EXTENSION: str = ".py"
+ENTRY_HOOK_FILE_NAME: str = "tdd_enforcer.py"
+NEWLINE_JOIN_SEPARATOR: str = "\n"
+ALL_PRODUCTION_EXTENSIONS: frozenset[str] = frozenset({".py", ".ts", ".tsx", ".js", ".jsx"})
+ALL_SKIP_EXTENSIONS: frozenset[str] = frozenset(
+    {".md", ".json", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".txt"}
+)
+ALL_SKIP_NAME_PATTERNS: frozenset[str] = frozenset(
+    {"test_", "_test.", ".test.", "tests/", "__tests__/", "conftest", "fixture", "mock", "stub"}
+)
+ALL_DIRECTORY_SKIP_COMPONENTS: frozenset[str] = frozenset(
+    {"conftest", "fixture", "fixtures", "mock", "mocks", "stub", "stubs"}
+)
+ALL_DOTCLAUDE_PATH_SEGMENTS: frozenset[str] = frozenset({".claude"})
+ALL_REPO_BOUNDARY_SENTINELS: frozenset[str] = frozenset(
+    {".git", "pyproject.toml", "package.json", "Cargo.toml", "go.mod"}
+)
+ALL_JAVASCRIPT_TEST_EXTENSIONS: frozenset[str] = frozenset({".tsx", ".ts", ".jsx", ".js"})

package/hooks/blocking/tdd_enforcer_parts/content_analysis.py

@@ -0,0 +1,268 @@
+"""Content analysis for the TDD-enforcer constants and import-only exemptions.
+
+Answers two questions about a payload: is the written module only module-level
+constants (no behavior to test), and does an Edit or MultiEdit merely remove or
+reorder imports on a file that already has no behavior worth a fresh test.
+"""
+
+import ast
+from collections import Counter
+
+
+def _constants_only_allowed_node_types() -> tuple[type, ...]:
+    return (ast.Import, ast.ImportFrom, ast.Assign, ast.AnnAssign)
+
+
+def _is_module_docstring_expression(module_level_node: ast.stmt) -> bool:
+    if not isinstance(module_level_node, ast.Expr):
+        return False
+    expression_value = module_level_node.value
+    if not isinstance(expression_value, ast.Constant):
+        return False
+    return isinstance(expression_value.value, str)
+
+
+def _safe_constant_functions() -> frozenset[str]:
+    return frozenset({"Path", "frozenset"})
+
+
+def _safe_constant_attribute_calls() -> frozenset[tuple[str, str]]:
+    return frozenset({("re", "compile")})
+
+
+def _node_is_unsafe_construct(subnode: ast.AST) -> bool:
+    return isinstance(
+        subnode,
+        (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp, ast.Lambda),
+    )
+
+
+def _attribute_call_is_unsafe(function_node: ast.Attribute) -> bool:
+    if not isinstance(function_node.value, ast.Name):
+        return True
+    pair = (function_node.value.id, function_node.attr)
+    return pair not in _safe_constant_attribute_calls()
+
+
+def _call_is_unsafe(call_node: ast.Call) -> bool:
+    function_node = call_node.func
+    if isinstance(function_node, ast.Name):
+        return function_node.id not in _safe_constant_functions()
+    if isinstance(function_node, ast.Attribute):
+        return _attribute_call_is_unsafe(function_node)
+    return True
+
+
+def _rhs_has_unsafe_call(rhs_node: ast.AST) -> bool:
+    """Return True when a constant's value contains a non-allowlisted call.
+
+    Safe calls are value constructors (``Path(...)``, ``re.compile(...)``) that
+    build objects without side effects; any other call or a comprehension reads
+    as import-time behavior.
+
+    Args:
+        rhs_node: The assignment's right-hand-side expression node.
+
+    Returns:
+        True when an unsafe call or comprehension appears anywhere within it.
+    """
+    for each_subnode in ast.walk(rhs_node):
+        if isinstance(each_subnode, ast.Call) and _call_is_unsafe(each_subnode):
+            return True
+        if _node_is_unsafe_construct(each_subnode):
+            return True
+    return False
+
+
+def _assignment_rhs_is_safe(node: ast.stmt) -> bool:
+    right_hand_side = getattr(node, "value", None)
+    if right_hand_side is None:
+        return True
+    return not _rhs_has_unsafe_call(right_hand_side)
+
+
+def _top_level_node_is_constant(node: ast.stmt) -> bool:
+    if isinstance(node, (ast.Assign, ast.AnnAssign)):
+        return _assignment_rhs_is_safe(node)
+    if isinstance(node, _constants_only_allowed_node_types()):
+        return True
+    return _is_module_docstring_expression(node)
+
+
+def _is_constants_only_python_content(content: str) -> bool:
+    """Return whether module source declares only constants, imports, docstring.
+
+    Args:
+        content: Python source text.
+
+    Returns:
+        True when every top-level statement is an import, a safe constant
+        assignment, or the module docstring; False on empty or unparseable
+        content, or any statement that carries behavior.
+    """
+    if not content.strip():
+        return False
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return False
+    if not parsed_tree.body:
+        return False
+    return all(_top_level_node_is_constant(each_node) for each_node in parsed_tree.body)
+
+
+def _apply_edit_to_content(
+    existing_content: str, old_str: str, new_str: str, should_replace_all: bool
+) -> str:
+    if should_replace_all:
+        return existing_content.replace(old_str, new_str)
+    return existing_content.replace(old_str, new_str, 1)
+
+
+def _future_module_name() -> str:
+    return "__future__"
+
+
+def _is_future_import(node: ast.stmt) -> bool:
+    return isinstance(node, ast.ImportFrom) and node.module == _future_module_name()
+
+
+def _is_removable_import(node: ast.stmt) -> bool:
+    if isinstance(node, ast.Import):
+        return True
+    if isinstance(node, ast.ImportFrom):
+        return not _is_future_import(node)
+    return False
+
+
+def _future_import_signatures(content: str) -> list[str] | None:
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return None
+    return [ast.dump(each_node) for each_node in parsed_tree.body if _is_future_import(each_node)]
+
+
+def _top_level_signatures(content: str) -> tuple[list[str], list[str]] | None:
+    """Split top-level statements into removable-import and other signatures.
+
+    ``from __future__`` imports and every non-import statement land in the
+    second list, so editing a future import reads as a behavior edit rather than
+    a removable-import edit. Signatures omit line and column attributes.
+
+    Args:
+        content: Python source text.
+
+    Returns:
+        A pair ``(import_signatures, other_signatures)`` in source order, or
+        None when the content does not parse.
+    """
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return None
+    import_signatures: list[str] = []
+    non_import_signatures: list[str] = []
+    for each_node in parsed_tree.body:
+        if _is_removable_import(each_node):
+            import_signatures.append(ast.dump(each_node))
+        else:
+            non_import_signatures.append(ast.dump(each_node))
+    return import_signatures, non_import_signatures
+
+
+def _post_edit_content_for_edit(existing_content: str, tool_input: dict) -> str | None:
+    old_str = tool_input.get("old_string", "") or ""
+    new_str = tool_input.get("new_string", "") or ""
+    if not old_str:
+        return None
+    should_replace_all = bool(tool_input.get("replace_all", False))
+    return _apply_edit_to_content(existing_content, old_str, new_str, should_replace_all)
+
+
+def _post_edit_content_for_multiedit(existing_content: str, tool_input: dict) -> str | None:
+    all_edits = tool_input.get("edits", []) or []
+    post_edit_content = existing_content
+    for each_edit in all_edits:
+        if not isinstance(each_edit, dict):
+            return None
+        each_old = each_edit.get("old_string", "") or ""
+        each_new = each_edit.get("new_string", "") or ""
+        if not each_old:
+            return None
+        should_replace_all = bool(each_edit.get("replace_all", False))
+        post_edit_content = _apply_edit_to_content(
+            post_edit_content, each_old, each_new, should_replace_all
+        )
+    return post_edit_content
+
+
+def _compute_post_edit_content(
+    existing_content: str, tool_name: str, tool_input: dict
+) -> str | None:
+    if tool_name == "Edit":
+        return _post_edit_content_for_edit(existing_content, tool_input)
+    if tool_name == "MultiEdit":
+        return _post_edit_content_for_multiedit(existing_content, tool_input)
+    return None
+
+
+def _is_post_edit_constants_only(existing_content: str, tool_name: str, tool_input: dict) -> bool:
+    """Return whether an Edit or MultiEdit keeps a constants-only file so.
+
+    Both the existing content and the post-edit result must be constants-only,
+    and the ``from __future__`` imports must be unchanged, so a future-import
+    edit faces the gate rather than slipping through this exemption.
+
+    Args:
+        existing_content: Current file text.
+        tool_name: The intercepted tool (Edit or MultiEdit).
+        tool_input: The intercepted tool's input payload.
+
+    Returns:
+        True when the file was and stays constants-only across the edit.
+    """
+    if not _is_constants_only_python_content(existing_content):
+        return False
+    post_edit_content = _compute_post_edit_content(existing_content, tool_name, tool_input)
+    if post_edit_content is None:
+        return False
+    if _future_import_signatures(existing_content) != _future_import_signatures(post_edit_content):
+        return False
+    return _is_constants_only_python_content(post_edit_content)
+
+
+def _import_signatures_are_reorder_or_removal(
+    all_existing_signatures: tuple[list[str], list[str]],
+    all_post_edit_signatures: tuple[list[str], list[str]],
+) -> bool:
+    existing_imports, existing_rest = all_existing_signatures
+    post_imports, post_rest = all_post_edit_signatures
+    if post_rest != existing_rest or post_imports == existing_imports:
+        return False
+    return Counter(post_imports) <= Counter(existing_imports)
+
+
+def _is_post_edit_import_only(existing_content: str, tool_name: str, tool_input: dict) -> bool:
+    """Return whether an Edit or MultiEdit only removes or reorders imports.
+
+    Args:
+        existing_content: Current file text.
+        tool_name: The intercepted tool (Edit or MultiEdit).
+        tool_input: The intercepted tool's input payload.
+
+    Returns:
+        True when the edit is a pure reordering or removal of imports.
+    """
+    existing_signatures = _top_level_signatures(existing_content)
+    if existing_signatures is None:
+        return False
+    if tool_name == "MultiEdit" and not (tool_input.get("edits") or []):
+        return False
+    post_edit_content = _compute_post_edit_content(existing_content, tool_name, tool_input)
+    if post_edit_content is None:
+        return False
+    post_edit_signatures = _top_level_signatures(post_edit_content)
+    if post_edit_signatures is None:
+        return False
+    return _import_signatures_are_reorder_or_removal(existing_signatures, post_edit_signatures)

package/hooks/blocking/tdd_enforcer_parts/decisions.py

@@ -0,0 +1,92 @@
+"""Build and emit the gate's allow and deny decisions.
+
+Writes the PreToolUse decision JSON to stdout and, on a deny, records the block
+and attaches the short user-facing notice.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from tdd_enforcer_parts.config.tdd_enforcer_constants import (
+    ENTRY_HOOK_FILE_NAME,
+    FRESHNESS_WINDOW_SECONDS,
+    NEWLINE_JOIN_SEPARATOR,
+)
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.messages import USER_FACING_TDD_NOTICE
+
+
+def _entry_hook_path() -> Path:
+    """Return the entry hook file that wires the gate's exemption rules together.
+
+    The exemption logic the deny message points at lives in the entry hook
+    beside this parts package, not in this emit-only module::
+
+        tdd_enforcer_parts/decisions.py  ->  parent  ->  blocking/
+        blocking/tdd_enforcer.py         <-  the named exemption home
+
+    So the guidance names the entry hook, letting a reader land on the module
+    that actually decides exemptions.
+    """
+    return Path(__file__).resolve().parent.parent / ENTRY_HOOK_FILE_NAME
+
+
+def build_deny_reason(production_path: Path, all_candidates: list[Path]) -> str:
+    """Return the verbose deny message naming the candidate test files.
+
+    Args:
+        production_path: The production file the write targets.
+        all_candidates: Candidate test paths the gate looked for.
+
+    Returns:
+        The multi-line reason shown when no fresh test satisfies the gate.
+    """
+    candidate_lines = NEWLINE_JOIN_SEPARATOR.join(f"  - {each_path}" for each_path in all_candidates)
+    hook_source_path = _entry_hook_path()
+    return (
+        f"[TDD] Blocking write to production file: {production_path}\n"
+        f"No matching test file exists, or it has not been modified within the last "
+        f"{FRESHNESS_WINDOW_SECONDS} seconds.\n"
+        f"Expected one of:\n{candidate_lines}\n"
+        f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n\n"
+        f"If this file legitimately does not need a test (for example, a module containing only "
+        f"module-level constants with no behavior), that is a hook enhancement, not a bypass. "
+        f"Propose an exemption rule in {hook_source_path} so every similar file benefits "
+        f"automatically. Do not add escape-hatch markers to production files."
+    )
+
+
+def emit_allow() -> None:
+    """Write the allow decision to stdout."""
+    allow_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        }
+    }
+    sys.stdout.write(json.dumps(allow_payload))
+
+
+def emit_deny(reason: str) -> None:
+    """Write the deny decision to stdout and record the block.
+
+    Args:
+        reason: The verbose deny reason shown to the agent.
+    """
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        },
+        "suppressOutput": True,
+        "systemMessage": USER_FACING_TDD_NOTICE,
+    }
+    log_hook_block(
+        calling_hook_name="tdd_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=reason,
+    )
+    sys.stdout.write(json.dumps(deny_payload))

package/hooks/blocking/tdd_enforcer_parts/freshness.py

@@ -0,0 +1,80 @@
+"""Freshness check for the candidate test files the gate resolves.
+
+A candidate satisfies the gate when it was modified inside the freshness window
+and holds a real test function, so a stale test or a same-named file with no
+test evidence does not open the gate.
+"""
+
+import re
+import time
+from pathlib import Path
+
+from tdd_enforcer_parts.config.tdd_enforcer_constants import FRESHNESS_WINDOW_SECONDS
+
+
+def _freshness_seconds() -> int:
+    return FRESHNESS_WINDOW_SECONDS
+
+
+def _test_file_encoding() -> str:
+    return "utf-8"
+
+
+def _test_function_patterns() -> tuple[re.Pattern[str], ...]:
+    return (
+        re.compile(r"\bdef\s+test_"),
+        re.compile(r"\b(?:it|test|describe)\s*\("),
+    )
+
+
+def _safe_mtime(candidate_path: Path) -> float | None:
+    try:
+        return candidate_path.stat().st_mtime
+    except (FileNotFoundError, OSError):
+        return None
+
+
+def _read_candidate_text(candidate_path: Path) -> str | None:
+    try:
+        with candidate_path.open("r", encoding=_test_file_encoding(), errors="ignore") as each_file:
+            return each_file.read()
+    except (FileNotFoundError, OSError):
+        return None
+
+
+def _contains_test_evidence(candidate_path: Path) -> bool:
+    test_file_content = _read_candidate_text(candidate_path)
+    if test_file_content is None:
+        return False
+    return any(
+        each_pattern.search(test_file_content) for each_pattern in _test_function_patterns()
+    )
+
+
+def _candidate_is_fresh_test(
+    candidate_path: Path, current_time: float, freshness_seconds: int
+) -> bool:
+    candidate_mtime = _safe_mtime(candidate_path)
+    if candidate_mtime is None:
+        return False
+    if current_time - candidate_mtime > freshness_seconds:
+        return False
+    return _contains_test_evidence(candidate_path)
+
+
+def has_fresh_test(all_candidates: list[Path], freshness_seconds: int) -> bool:
+    """Return whether any candidate is a recently modified real test file.
+
+    Args:
+        all_candidates: Candidate test paths for the production file.
+        freshness_seconds: Maximum age, in seconds, a test may have.
+
+    Returns:
+        True when at least one candidate was modified within the window and
+        holds a test function.
+    """
+    current_time = time.time()
+    return any(
+        _candidate_is_fresh_test(each_candidate, current_time, freshness_seconds)
+        for each_candidate in all_candidates
+    )