claude-dev-env 1.95.0 → 2.0.0

package/hooks/blocking/tdd_enforcer_parts/git_tracking.py

@@ -0,0 +1,63 @@
+"""Detect a write that restores a tracked-but-absent production file.
+
+::
+
+    remove orders.py (git-tracked) -> Write orders.py  -> restore (allow)
+    Write brand_new.py (untracked, absent)             -> new code (gate)
+
+A full rewrite happens as remove-then-Write, so the file is absent on disk
+between the two steps. Restoring committed code is not new production code, so
+the gate exempts a Write whose target is absent yet tracked in git.
+"""
+
+import subprocess
+from pathlib import Path
+
+from tdd_enforcer_parts.config.tdd_enforcer_constants import (
+    GIT_EXECUTABLE_NAME,
+    GIT_LS_FILES_SUBCOMMAND,
+    GIT_LS_FILES_TIMEOUT_SECONDS,
+    GIT_PATHSPEC_SEPARATOR,
+)
+
+
+def _git_ls_files_command(file_name: str) -> list[str]:
+    return [GIT_EXECUTABLE_NAME, GIT_LS_FILES_SUBCOMMAND, GIT_PATHSPEC_SEPARATOR, file_name]
+
+
+def _git_tracks_path(path: Path) -> bool:
+    parent_directory = path.parent
+    if not parent_directory.is_dir():
+        return False
+    try:
+        completed = subprocess.run(
+            _git_ls_files_command(path.name),
+            cwd=str(parent_directory),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=GIT_LS_FILES_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return completed.returncode == 0 and bool(completed.stdout.strip())
+
+
+def is_absent_but_tracked(path: Path) -> bool:
+    """Return whether a write target is absent on disk yet tracked in git.
+
+    ::
+
+        path missing on disk + git ls-files finds it -> True  (restore)
+        path present, or git does not track it       -> False
+
+    Args:
+        path: The write target.
+
+    Returns:
+        True only when the path does not exist but git tracks it, marking the
+        write a restore of committed code rather than new production code.
+    """
+    if path.exists():
+        return False
+    return _git_tracks_path(path)

package/hooks/blocking/tdd_enforcer_parts/path_classification.py

@@ -0,0 +1,119 @@
+"""Path and payload classification for the TDD-enforcer gate.
+
+Decides which write targets the gate skips silently (docs, tests, files inside a
+``.claude`` tree) and pulls the written text out of a Write, Edit, or MultiEdit
+payload so the gate can inspect it.
+"""
+
+from tdd_enforcer_parts.config.tdd_enforcer_constants import (
+    ALL_DIRECTORY_SKIP_COMPONENTS,
+    ALL_DOTCLAUDE_PATH_SEGMENTS,
+    ALL_PRODUCTION_EXTENSIONS,
+    ALL_SKIP_EXTENSIONS,
+    ALL_SKIP_NAME_PATTERNS,
+    NEWLINE_JOIN_SEPARATOR,
+)
+
+
+def production_extensions() -> frozenset[str]:
+    """Return the source-file extensions the gate treats as production code."""
+    return ALL_PRODUCTION_EXTENSIONS
+
+
+def skip_extensions() -> frozenset[str]:
+    """Return the config and documentation extensions the gate skips."""
+    return ALL_SKIP_EXTENSIONS
+
+
+def _skip_patterns() -> frozenset[str]:
+    return ALL_SKIP_NAME_PATTERNS
+
+
+def _dotclaude_path_segments() -> frozenset[str]:
+    return ALL_DOTCLAUDE_PATH_SEGMENTS
+
+
+def _directory_skip_components() -> frozenset[str]:
+    return ALL_DIRECTORY_SKIP_COMPONENTS
+
+
+def _is_inside_dotclaude_segment(file_path_string: str) -> bool:
+    """Return whether any path segment is exactly a ``.claude`` directory.
+
+    Args:
+        file_path_string: The write target path, in either separator style.
+
+    Returns:
+        True when a ``.claude`` directory sits on the path, so the gate leaves
+        agent-config edits alone.
+    """
+    normalized_path = file_path_string.replace("\\", "/")
+    dotclaude_segments = _dotclaude_path_segments()
+    for each_segment in normalized_path.split("/"):
+        if each_segment and each_segment in dotclaude_segments:
+            return True
+    return False
+
+
+def _path_has_skip_directory_component(path_with_forward_slashes: str) -> bool:
+    all_components = [each_part for each_part in path_with_forward_slashes.split("/") if each_part]
+    directory_components = all_components[:-1]
+    skip_directory_components = _directory_skip_components()
+    return any(each in skip_directory_components for each in directory_components)
+
+
+def _skip_pattern_matches(pattern: str, name_lower: str, path_with_forward_slashes: str) -> bool:
+    if pattern.endswith("/"):
+        return pattern in path_with_forward_slashes
+    return pattern in name_lower
+
+
+def _name_or_path_matches_skip_pattern(name_lower: str, path_with_forward_slashes: str) -> bool:
+    for each_pattern in _skip_patterns():
+        if _skip_pattern_matches(each_pattern, name_lower, path_with_forward_slashes):
+            return True
+    return False
+
+
+def _matches_any_skip_pattern(name_lower: str, path_with_forward_slashes: str) -> bool:
+    """Return whether a path names a test, fixture, mock, or stub file.
+
+    Args:
+        name_lower: The lower-cased file name.
+        path_with_forward_slashes: The lower-cased path with forward slashes.
+
+    Returns:
+        True when a skip directory component or a skip name pattern matches.
+    """
+    if _path_has_skip_directory_component(path_with_forward_slashes):
+        return True
+    return _name_or_path_matches_skip_pattern(name_lower, path_with_forward_slashes)
+
+
+def _multiedit_new_strings(all_edits: list) -> list[str]:
+    all_new_strings: list[str] = []
+    for each_edit in all_edits:
+        if isinstance(each_edit, dict):
+            all_new_strings.append(each_edit.get("new_string", "") or "")
+    return all_new_strings
+
+
+def _extract_written_content(tool_name: str, tool_input: dict) -> str:
+    """Return the text a Write, Edit, or MultiEdit payload would introduce.
+
+    Args:
+        tool_name: The intercepted tool name.
+        tool_input: The intercepted tool's input payload.
+
+    Returns:
+        The written content for Write, the replacement for Edit, the joined
+        replacements for MultiEdit, or an empty string for any other tool.
+    """
+    if tool_name == "Write":
+        return tool_input.get("content", "") or ""
+    if tool_name == "Edit":
+        return tool_input.get("new_string", "") or ""
+    if tool_name == "MultiEdit":
+        all_edits = tool_input.get("edits", []) or []
+        return NEWLINE_JOIN_SEPARATOR.join(_multiedit_new_strings(all_edits))
+    return ""

package/hooks/blocking/tdd_enforcer_parts/tests/conftest.py

@@ -0,0 +1,10 @@
+"""Put the blocking and hooks directories on sys.path for the parts tests."""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parents[2])
+_hooks_directory = str(Path(__file__).resolve().parents[3])
+for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+    if each_bootstrap_directory not in sys.path:
+        sys.path.insert(0, each_bootstrap_directory)

package/hooks/blocking/tdd_enforcer_parts/tests/test_candidate_paths.py

@@ -0,0 +1,31 @@
+"""Behavioral tests for the candidate_paths parts module."""
+
+from pathlib import Path
+
+from tdd_enforcer_parts import candidate_paths
+
+
+def test_candidate_paths_offers_flat_stem_candidates_first(tmp_path: Path) -> None:
+    (tmp_path / ".git").mkdir()
+    all_candidates = candidate_paths.candidate_test_paths_for(tmp_path / "orders.py")
+    assert all_candidates[0] == tmp_path / "test_orders.py"
+    assert all_candidates[1] == tmp_path / "orders_test.py"
+
+
+def test_candidate_paths_returns_empty_for_unknown_extension(tmp_path: Path) -> None:
+    assert candidate_paths.candidate_test_paths_for(tmp_path / "data.rs") == []
+
+
+def test_candidate_paths_offers_javascript_test_siblings(tmp_path: Path) -> None:
+    all_candidates = candidate_paths.candidate_test_paths_for(tmp_path / "Button.tsx")
+    assert tmp_path / "Button.test.tsx" in all_candidates
+
+
+def test_ancestor_tests_directories_finds_sibling_tests(tmp_path: Path) -> None:
+    (tmp_path / ".git").mkdir()
+    package = tmp_path / "pkg"
+    package.mkdir()
+    (package / "tests").mkdir()
+    all_pairs = candidate_paths._ancestor_tests_directories(package)
+    all_tests_directories = [each_tests_directory for _, each_tests_directory in all_pairs]
+    assert package / "tests" in all_tests_directories

package/hooks/blocking/tdd_enforcer_parts/tests/test_content_analysis.py

@@ -0,0 +1,30 @@
+"""Behavioral tests for the content_analysis parts module."""
+
+from tdd_enforcer_parts import content_analysis
+
+
+def test_constants_only_accepts_module_docstring_and_assignment() -> None:
+    content = '"""doc."""\nMAX_ORDERS = 3\n'
+    assert content_analysis._is_constants_only_python_content(content) is True
+
+
+def test_constants_only_rejects_function_definition() -> None:
+    assert content_analysis._is_constants_only_python_content("def f():\n    return 1\n") is False
+
+
+def test_post_edit_import_only_allows_import_removal() -> None:
+    existing = "import os\n\ndef run(): return 1\n"
+    tool_input = {"old_string": "import os\n", "new_string": ""}
+    assert content_analysis._is_post_edit_import_only(existing, "Edit", tool_input) is True
+
+
+def test_post_edit_import_only_blocks_import_swap() -> None:
+    existing = "import os\n\ndef run(): return 1\n"
+    tool_input = {"old_string": "import os", "new_string": "import sys"}
+    assert content_analysis._is_post_edit_import_only(existing, "Edit", tool_input) is False
+
+
+def test_post_edit_constants_only_allows_constant_value_change() -> None:
+    existing = '"""doc."""\nMAX_ORDERS = 3\n'
+    tool_input = {"old_string": "MAX_ORDERS = 3", "new_string": "MAX_ORDERS = 5"}
+    assert content_analysis._is_post_edit_constants_only(existing, "Edit", tool_input) is True

package/hooks/blocking/tdd_enforcer_parts/tests/test_decisions.py

@@ -0,0 +1,34 @@
+"""Behavioral tests for the decisions parts module."""
+
+import json
+from pathlib import Path
+
+import pytest
+from tdd_enforcer_parts import decisions
+
+
+def test_build_deny_reason_names_candidates_and_production_path() -> None:
+    reason = decisions.build_deny_reason(Path("pkg/orders.py"), [Path("pkg/test_orders.py")])
+    assert "orders.py" in reason
+    assert "test_orders.py" in reason
+    assert "propose" in reason.lower() or "enhancement" in reason.lower()
+
+
+def test_build_deny_reason_points_exemption_guidance_at_entry_hook() -> None:
+    reason = decisions.build_deny_reason(Path("pkg/orders.py"), [])
+    assert "tdd_enforcer.py" in reason
+    assert "decisions.py" not in reason
+
+
+def test_emit_allow_writes_allow_decision(capsys: pytest.CaptureFixture[str]) -> None:
+    decisions.emit_allow()
+    parsed = json.loads(capsys.readouterr().out)
+    assert parsed["hookSpecificOutput"]["permissionDecision"] == "allow"
+
+
+def test_emit_deny_writes_deny_and_system_message(capsys: pytest.CaptureFixture[str]) -> None:
+    decisions.emit_deny("blocked because no fresh test")
+    parsed = json.loads(capsys.readouterr().out)
+    assert parsed["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert parsed["suppressOutput"] is True
+    assert isinstance(parsed["systemMessage"], str)

package/hooks/blocking/tdd_enforcer_parts/tests/test_freshness.py

@@ -0,0 +1,28 @@
+"""Behavioral tests for the freshness parts module."""
+
+import os
+import time
+from pathlib import Path
+
+from tdd_enforcer_parts import freshness
+
+
+def test_has_fresh_test_true_for_recent_test_file(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_x(): pass\n")
+    assert freshness.has_fresh_test([test_file], freshness._freshness_seconds()) is True
+
+
+def test_has_fresh_test_false_for_stale_test_file(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_x(): pass\n")
+    window = freshness._freshness_seconds()
+    stale_timestamp = time.time() - window - 60
+    os.utime(test_file, (stale_timestamp, stale_timestamp))
+    assert freshness.has_fresh_test([test_file], window) is False
+
+
+def test_has_fresh_test_false_when_no_test_evidence(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("x = 1\n")
+    assert freshness.has_fresh_test([test_file], freshness._freshness_seconds()) is False

package/hooks/blocking/tdd_enforcer_parts/tests/test_git_tracking.py

@@ -0,0 +1,48 @@
+"""Behavioral tests for the git_tracking parts module."""
+
+import os
+import subprocess
+from pathlib import Path
+
+from tdd_enforcer_parts import git_tracking
+
+
+def _git(repository_root: Path, *arguments: str) -> None:
+    subprocess.run(
+        ["git", *arguments],
+        cwd=str(repository_root),
+        check=True,
+        capture_output=True,
+        env={**os.environ, "GIT_CONFIG_GLOBAL": os.devnull, "GIT_CONFIG_SYSTEM": os.devnull},
+    )
+
+
+def _init_repository(repository_root: Path) -> None:
+    _git(repository_root, "init", "-q")
+    _git(repository_root, "config", "user.email", "test@example.com")
+    _git(repository_root, "config", "user.name", "Test")
+    _git(repository_root, "config", "commit.gpgsign", "false")
+
+
+def test_absent_but_tracked_true_after_committed_file_removed(tmp_path: Path) -> None:
+    _init_repository(tmp_path)
+    tracked = tmp_path / "service.py"
+    tracked.write_text("def serve(): return 1\n")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-q", "-m", "init")
+    tracked.unlink()
+    assert git_tracking.is_absent_but_tracked(tracked) is True
+
+
+def test_absent_but_tracked_false_for_untracked_absent_file(tmp_path: Path) -> None:
+    _init_repository(tmp_path)
+    assert git_tracking.is_absent_but_tracked(tmp_path / "ghost.py") is False
+
+
+def test_absent_but_tracked_false_when_file_present(tmp_path: Path) -> None:
+    _init_repository(tmp_path)
+    present = tmp_path / "present.py"
+    present.write_text("def here(): return 1\n")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-q", "-m", "init")
+    assert git_tracking.is_absent_but_tracked(present) is False

package/hooks/blocking/tdd_enforcer_parts/tests/test_path_classification.py

@@ -0,0 +1,36 @@
+"""Behavioral tests for the path_classification parts module."""
+
+from tdd_enforcer_parts import path_classification
+
+
+def test_production_extensions_includes_python_and_typescript() -> None:
+    extensions = path_classification.production_extensions()
+    assert ".py" in extensions
+    assert ".tsx" in extensions
+
+
+def test_skip_extensions_includes_markdown_and_json() -> None:
+    extensions = path_classification.skip_extensions()
+    assert ".md" in extensions
+    assert ".json" in extensions
+
+
+def test_is_inside_dotclaude_segment_matches_exact_segment_only() -> None:
+    assert path_classification._is_inside_dotclaude_segment("/home/user/.claude/agent.py") is True
+    assert path_classification._is_inside_dotclaude_segment("/src/my.claude.helpers.py") is False
+
+
+def test_matches_any_skip_pattern_flags_test_file_names() -> None:
+    assert (
+        path_classification._matches_any_skip_pattern("test_orders.py", "pkg/test_orders.py")
+        is True
+    )
+    assert path_classification._matches_any_skip_pattern("orders.py", "pkg/orders.py") is False
+
+
+def test_extract_written_content_reads_write_and_multiedit() -> None:
+    assert path_classification._extract_written_content("Write", {"content": "x"}) == "x"
+    joined = path_classification._extract_written_content(
+        "MultiEdit", {"edits": [{"new_string": "a"}, {"new_string": "b"}]}
+    )
+    assert joined == "a\nb"

package/hooks/blocking/test_inventory_deadlock_resolution.py

@@ -0,0 +1,154 @@
+"""End-to-end tests for the inventory/orphan pending-intent deadlock resolution.
+
+Each test drives the two real hook binaries through their production ``main()``
+stdin path over a temp directory tree whose ``CLAUDE.md`` inventory names two
+sibling files. A shared ``session_id`` and an isolated ``TMPDIR`` make the two
+hooks read one shared intent-records file, so a deny by one hook opens the gate
+for the sibling's second write — in either add order.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+
+INVENTORY_HOOK = "package_inventory_stale_blocker.py"
+ORPHAN_HOOK = "claude_md_orphan_file_blocker.py"
+
+SESSION_ID = "deadlock-session"
+
+INVENTORY_TABLE_HEADER = "# pkg\n\n| File | Purpose |\n|---|---|\n"
+ALPHA_ROW = "| `alpha.py` | Does A |\n"
+BETA_ROW = "| `beta.py` | Does B |\n"
+GAMMA_ROW = "| `gamma.py` | Does G |\n"
+EPSILON_ROW = "| `epsilon.py` | Does E |\n"
+
+BASE_INVENTORY = INVENTORY_TABLE_HEADER + ALPHA_ROW + BETA_ROW
+INVENTORY_WITH_GAMMA = BASE_INVENTORY + GAMMA_ROW
+INVENTORY_WITH_EPSILON = BASE_INVENTORY + EPSILON_ROW
+
+MODULE_BODY = "x = 1\n"
+
+
+def _package_directory(tmp_path: Path) -> Path:
+    """Return a package directory holding a CLAUDE.md table naming two siblings."""
+    package_directory = tmp_path / "pkg"
+    package_directory.mkdir()
+    (package_directory / "CLAUDE.md").write_text(BASE_INVENTORY, encoding="utf-8")
+    (package_directory / "alpha.py").write_text(MODULE_BODY, encoding="utf-8")
+    (package_directory / "beta.py").write_text(MODULE_BODY, encoding="utf-8")
+    return package_directory
+
+
+def _run_hook(
+    hook_filename: str, tool_name: str, tool_input: dict, temp_directory: Path
+) -> subprocess.CompletedProcess:
+    """Run one hook binary over a payload, sharing an isolated intent-records store."""
+    payload = json.dumps(
+        {"tool_name": tool_name, "tool_input": tool_input, "session_id": SESSION_ID}
+    )
+    hook_environment = dict(os.environ)
+    hook_environment["TMPDIR"] = str(temp_directory)
+    return subprocess.run(
+        [sys.executable, str(BLOCKING_DIRECTORY / hook_filename)],
+        input=payload,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=hook_environment,
+    )
+
+
+def _decision(completed: subprocess.CompletedProcess) -> str | None:
+    """Return the permission decision a hook emitted, or None when it allowed."""
+    if not completed.stdout.strip():
+        return None
+    return json.loads(completed.stdout)["hookSpecificOutput"]["permissionDecision"]
+
+
+def _reason(completed: subprocess.CompletedProcess) -> str:
+    """Return the deny reason a hook emitted."""
+    return json.loads(completed.stdout)["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_file_first_order_resolves_after_one_deny(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    new_file = package_directory / "gamma.py"
+    claude_md = package_directory / "CLAUDE.md"
+
+    first_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(first_write) == "deny"
+    assert "gamma.py" in _reason(first_write)
+    assert "recorded" in _reason(first_write)
+
+    row_write = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_GAMMA},
+        tmp_path,
+    )
+    assert _decision(row_write) is None
+
+    claude_md.write_text(INVENTORY_WITH_GAMMA, encoding="utf-8")
+    retry_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(retry_write) is None
+
+
+def test_row_first_order_resolves_after_one_deny(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    new_file = package_directory / "gamma.py"
+    claude_md = package_directory / "CLAUDE.md"
+
+    first_row = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_GAMMA},
+        tmp_path,
+    )
+    assert _decision(first_row) == "deny"
+    assert "gamma.py" in _reason(first_row)
+    assert "recorded" in _reason(first_row)
+
+    file_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(file_write) is None
+
+    new_file.write_text(MODULE_BODY, encoding="utf-8")
+    retry_row = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_GAMMA},
+        tmp_path,
+    )
+    assert _decision(retry_row) is None
+
+
+def test_new_file_with_no_row_attempt_stays_blocked(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    new_file = package_directory / "delta.py"
+    file_write = _run_hook(
+        INVENTORY_HOOK, "Write", {"file_path": str(new_file), "content": MODULE_BODY}, tmp_path
+    )
+    assert _decision(file_write) == "deny"
+    assert "delta.py" in _reason(file_write)
+
+
+def test_row_naming_uncreated_file_stays_blocked(tmp_path: Path) -> None:
+    package_directory = _package_directory(tmp_path)
+    claude_md = package_directory / "CLAUDE.md"
+    row_write = _run_hook(
+        ORPHAN_HOOK,
+        "Write",
+        {"file_path": str(claude_md), "content": INVENTORY_WITH_EPSILON},
+        tmp_path,
+    )
+    assert _decision(row_write) == "deny"
+    assert "epsilon.py" in _reason(row_write)