claude-dev-env 2.31.0 → 2.32.0

package/hooks/validators/test_run_all_validators_reporting.py

@@ -0,0 +1,66 @@
+"""Tests for the run report run_all_validators renders after a full run.
+
+Timing metrics and the version header are the two pieces of that report. They
+moved out of test_run_all_validators.py so the paired file keeps room for the
+gate behavior it exists to pin.
+"""
+
+import pytest
+
+from .run_all_validators import (
+    add_timing,
+    build_json_output,
+    create_timing_metrics,
+    format_timing_report,
+    print_header,
+)
+
+
+class TestTimingMetrics:
+    def test_create_timing_metrics_empty(self) -> None:
+        metrics = create_timing_metrics({})
+        assert metrics.total_seconds == 0.0
+        assert metrics.validator_times == {}
+
+    def test_create_timing_metrics_with_data(self) -> None:
+        timings = {"Validator A": 1.5, "Validator B": 2.0}
+        metrics = create_timing_metrics(timings)
+        assert metrics.total_seconds == 3.5
+        assert metrics.validator_times == timings
+
+    def test_add_timing_returns_new_instance(self) -> None:
+        metrics1 = create_timing_metrics({})
+        metrics2 = add_timing(metrics1, "Test", 1.5)
+
+        assert metrics1.total_seconds == 0.0
+        assert metrics2.total_seconds == 1.5
+        assert "Test" not in metrics1.validator_times
+        assert metrics2.validator_times["Test"] == 1.5
+
+    def test_format_report_includes_all_timings(self) -> None:
+        metrics = create_timing_metrics({"Fast": 0.1, "Slow": 2.5})
+        report = format_timing_report(metrics)
+
+        assert "Fast" in report
+        assert "Slow" in report
+        assert "2.6" in report
+
+
+class TestVersionHeader:
+    def test_print_header_includes_version(self, capsys: pytest.CaptureFixture[str]) -> None:
+        print_header()
+        captured = capsys.readouterr()
+
+        assert "PRE-PUSH VALIDATOR RESULTS" in captured.out
+        assert "(v" in captured.out
+
+    def test_build_json_output_includes_version(self) -> None:
+        json_output = build_json_output(
+            results=[],
+            metrics=create_timing_metrics({}),
+            include_timing=False,
+        )
+
+        assert "version" in json_output
+        assert "timestamp" in json_output
+        assert isinstance(json_output["version"], str)

package/hooks/validators/test_run_all_validators_repository_root.py

@@ -0,0 +1,202 @@
+"""Repository-root anchoring tests for the PreToolUse staging walk.
+
+Staging mirrors the destination's exemption-signalling directories through a
+temp path so the save-path checks read the same signals the real path carries.
+The walk must read only the segments the project itself owns. A directory above
+the project root — a home directory named ``tests``, a checkout parked under
+``config`` — belongs to whoever laid out the disk, not to the project, and must
+never lend a production file a test or config exemption.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from .run_all_validators import (
+    _temporary_path_preserving_directory_signal,
+    validate_proposed_file,
+)
+
+pytestmark = pytest.mark.usefixtures("ephemeral_exempt_off")
+
+GIT_MARKER_DIRECTORY_NAME = ".git"
+MAGIC_VALUE_CHECK_NAME = "Magic Values"
+PRODUCTION_CONTENT_WITH_MAGIC_VALUE = "def retry_budget_seconds() -> int:\n    return 3600 * 7\n"
+
+
+def _project_root_under(parent_directory: Path) -> Path:
+    """Create a git-marked project directory under *parent_directory*.
+
+    Args:
+        parent_directory: Directory the project root is created inside.
+
+    Returns:
+        The created project root, holding an empty ``.git`` marker directory.
+    """
+    project_root = parent_directory / "project"
+    (project_root / GIT_MARKER_DIRECTORY_NAME).mkdir(parents=True)
+    return project_root
+
+
+def _staged_relative_path(staging_directory: Path, destination_path: Path) -> str:
+    """Return the posix staged path *destination_path* produces, relative to staging.
+
+    Args:
+        staging_directory: Root of the ephemeral staging tree.
+        destination_path: Real destination the write or edit targets.
+
+    Returns:
+        The staged path relative to *staging_directory*, in posix form.
+    """
+    staged_path = _temporary_path_preserving_directory_signal(
+        staging_directory, str(destination_path)
+    )
+    return staged_path.relative_to(staging_directory).as_posix()
+
+
+def _failed_check_names(destination_path: Path, proposed_content: str) -> list[str]:
+    """Return the names of every save-path check that fails for a destination.
+
+    Args:
+        destination_path: Real destination the write or edit targets.
+        proposed_content: Post-edit content the write would leave on disk.
+
+    Returns:
+        The failing check names, in roster order.
+    """
+    return [
+        each_result.name
+        for each_result in validate_proposed_file(str(destination_path), proposed_content)
+        if not each_result.passed
+    ]
+
+
+def test_should_drop_tests_directory_above_the_project_root(tmp_path: Path) -> None:
+    """A home directory named ``tests`` lends no test exemption to project code."""
+    parent_named_tests = tmp_path / "tests"
+    project_root = _project_root_under(parent_named_tests)
+    staging_directory = tmp_path / "staging"
+    staging_directory.mkdir()
+
+    staged_relative = _staged_relative_path(staging_directory, project_root / "src" / "worker.py")
+
+    assert staged_relative == "worker.py", (
+        f"a tests directory above the project must not stage into the path, got {staged_relative}"
+    )
+
+
+def test_should_drop_config_directory_above_the_project_root(tmp_path: Path) -> None:
+    """A checkout parked under ``config`` lends no config exemption to project code."""
+    parent_named_config = tmp_path / "config"
+    project_root = _project_root_under(parent_named_config)
+    staging_directory = tmp_path / "staging"
+    staging_directory.mkdir()
+
+    staged_relative = _staged_relative_path(staging_directory, project_root / "src" / "worker.py")
+
+    assert staged_relative == "worker.py", (
+        f"a config directory above the project must not stage into the path, got {staged_relative}"
+    )
+
+
+def test_should_report_magic_value_for_production_file_under_a_tests_parent(
+    tmp_path: Path,
+) -> None:
+    """The magic-value check grades project code under a ``tests`` parent directory."""
+    project_root = _project_root_under(tmp_path / "tests")
+
+    all_failed_names = _failed_check_names(
+        project_root / "src" / "worker.py", PRODUCTION_CONTENT_WITH_MAGIC_VALUE
+    )
+
+    assert MAGIC_VALUE_CHECK_NAME in all_failed_names, (
+        f"production code under a tests parent must still be graded, got {all_failed_names}"
+    )
+
+
+def test_should_report_magic_value_for_production_file_under_a_config_parent(
+    tmp_path: Path,
+) -> None:
+    """The magic-value check grades project code under a ``config`` parent directory."""
+    project_root = _project_root_under(tmp_path / "config")
+
+    all_failed_names = _failed_check_names(
+        project_root / "src" / "worker.py", PRODUCTION_CONTENT_WITH_MAGIC_VALUE
+    )
+
+    assert MAGIC_VALUE_CHECK_NAME in all_failed_names, (
+        f"production code under a config parent must still be graded, got {all_failed_names}"
+    )
+
+
+def test_should_keep_test_helpers_directory_inside_the_project(tmp_path: Path) -> None:
+    """A ``test_helpers`` package inside the project keeps its test exemption."""
+    project_root = _project_root_under(tmp_path / "tests")
+    staging_directory = tmp_path / "staging"
+    staging_directory.mkdir()
+
+    staged_relative = _staged_relative_path(
+        staging_directory, project_root / "pkg" / "test_helpers" / "worker.py"
+    )
+
+    assert staged_relative == "test_helpers/worker.py", (
+        f"an in-project test_helpers directory must stage into the path, got {staged_relative}"
+    )
+
+
+def test_should_keep_scripts_directory_inside_the_project(tmp_path: Path) -> None:
+    """A ``scripts`` directory inside the project keeps its CLI-marker signal."""
+    project_root = _project_root_under(tmp_path / "tests")
+    staging_directory = tmp_path / "staging"
+    staging_directory.mkdir()
+
+    staged_relative = _staged_relative_path(
+        staging_directory, project_root / "scripts" / "deploy.py"
+    )
+
+    assert staged_relative == "scripts/deploy.py", (
+        f"an in-project scripts directory must stage into the path, got {staged_relative}"
+    )
+
+
+def test_should_keep_tests_directory_inside_the_project(tmp_path: Path) -> None:
+    """A genuine ``tests`` directory inside the project keeps its test exemption."""
+    project_root = _project_root_under(tmp_path / "config")
+    staging_directory = tmp_path / "staging"
+    staging_directory.mkdir()
+
+    staged_relative = _staged_relative_path(
+        staging_directory, project_root / "tests" / "helpers" / "data.py"
+    )
+
+    assert staged_relative == "tests/helpers/data.py", (
+        f"an in-project tests directory must stage into the path, got {staged_relative}"
+    )
+
+
+def test_should_keep_config_directory_inside_the_project(tmp_path: Path) -> None:
+    """A ``config`` directory inside the project keeps its magic-value exemption."""
+    project_root = _project_root_under(tmp_path / "tests")
+
+    all_failed_names = _failed_check_names(
+        project_root / "config" / "timing.py", PRODUCTION_CONTENT_WITH_MAGIC_VALUE
+    )
+
+    assert MAGIC_VALUE_CHECK_NAME not in all_failed_names, (
+        f"an in-project config module must stay magic-value exempt, got {all_failed_names}"
+    )
+
+
+def test_should_walk_every_segment_for_a_target_with_no_project_root(
+    tmp_path: Path,
+) -> None:
+    """An install-tree target outside every project keeps the whole-path walk."""
+    install_target = tmp_path / ".claude" / "hooks" / "blocking" / "gate.py"
+    staging_directory = tmp_path / "staging"
+    staging_directory.mkdir()
+
+    staged_relative = _staged_relative_path(staging_directory, install_target)
+
+    assert staged_relative == ".claude/hooks/blocking/gate.py", (
+        f"a target with no project root must keep its exemption tail, got {staged_relative}"
+    )

package/hooks/validators/test_validator_base.py

@@ -1,8 +1,11 @@
-"""Tests for shared validator base types."""
+"""Tests for shared validator base types and its shared read and parse."""
+
+import ast
+from pathlib import Path
 
 import pytest
 
-from .validator_base import Violation
+from .validator_base import Violation, source_text, syntax_tree
 
 
 class TestViolation:
@@ -24,3 +27,49 @@ class TestViolation:
         violation = Violation(file="test.py", line=42, message="Test message")
         violation_set = {violation}
         assert violation in violation_set
+
+def test_source_text_reads_the_file_once_for_repeated_callers(tmp_path: Path) -> None:
+    """Two callers asking for the same unchanged file cause one read."""
+    target = tmp_path / "module.py"
+    target.write_text("value = 1\n", encoding="utf-8")
+    first = source_text(target)
+    second = source_text(target)
+    assert first == second == "value = 1\n"
+    assert source_text.__module__ == "validators.validator_base"
+
+
+def test_source_text_reads_again_after_the_file_changes(tmp_path: Path) -> None:
+    """An edited file is read again rather than served from the cache.
+
+    The cache key carries the modification time and the size, so a rewrite
+    between two calls reaches disk a second time.
+    """
+    target = tmp_path / "module.py"
+    target.write_text("value = 1\n", encoding="utf-8")
+    assert source_text(target) == "value = 1\n"
+    target.write_text("value = 2\nvalue = 3\n", encoding="utf-8")
+    assert source_text(target) == "value = 2\nvalue = 3\n"
+
+
+def test_source_text_raises_for_a_missing_file(tmp_path: Path) -> None:
+    """A caller's own error handling still sees the read failure."""
+    with pytest.raises(OSError):
+        source_text(tmp_path / "absent.py")
+
+
+def test_syntax_tree_returns_the_same_tree_for_the_same_source() -> None:
+    """One parse serves every caller asking about the same text."""
+    source = "def handler() -> int:\n    return 1\n"
+    assert syntax_tree(source) is syntax_tree(source)
+
+
+def test_syntax_tree_parses_what_ast_parse_parses() -> None:
+    """The shared parse agrees with a direct ast.parse of the same text."""
+    source = "value = 1\n"
+    assert ast.dump(syntax_tree(source)) == ast.dump(ast.parse(source))
+
+
+def test_syntax_tree_raises_syntax_error_for_unparseable_source() -> None:
+    """A caller's own SyntaxError branch still fires."""
+    with pytest.raises(SyntaxError):
+        syntax_tree("def broken(:\n")

package/hooks/validators/todo_checks.py

@@ -8,7 +8,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from .validator_base import Violation
+from .validator_base import Violation, source_text
 
 
 TODO_PATTERN = re.compile(r"#\s*(TODO|FIXME)\b(?!.*#\d+)", re.IGNORECASE)
@@ -34,7 +34,7 @@ def check_untracked_todos(source: str, filename: str) -> List[Violation]:
 def validate_file(file_path: Path) -> List[Violation]:
     filename = str(file_path)
     try:
-        source = file_path.read_text(encoding="utf-8")
+        source = source_text(file_path)
     except Exception as error:
         return [Violation(filename, 0, f"Error reading file: {error}")]
 

package/hooks/validators/type_safety_checks.py

@@ -10,7 +10,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from .validator_base import Violation
+from .validator_base import Violation, source_text, syntax_tree
 
 
 def check_missing_type_hints(tree: ast.AST, filename: str) -> List[Violation]:
@@ -66,8 +66,8 @@ def validate_file(file_path: Path) -> List[Violation]:
     filename = str(file_path)
 
     try:
-        source = file_path.read_text(encoding="utf-8")
-        tree = ast.parse(source)
+        source = source_text(file_path)
+        tree = syntax_tree(source)
     except Exception as error:
         return [Violation(filename, 0, f"Error: {error}")]
 

package/hooks/validators/useless_test_checks.py

@@ -9,7 +9,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from .validator_base import Violation
+from .validator_base import Violation, source_text, syntax_tree
 
 
 def check_useless_tests(tree: ast.AST, filename: str) -> List[Violation]:
@@ -66,8 +66,8 @@ def validate_file(file_path: Path) -> List[Violation]:
         return []
 
     try:
-        source = file_path.read_text(encoding="utf-8")
-        tree = ast.parse(source)
+        source = source_text(file_path)
+        tree = syntax_tree(source)
     except Exception as error:
         return [Violation(filename, 0, f"Error: {error}")]
 

package/hooks/validators/validator_base.py

@@ -1,9 +1,15 @@
 """Base classes for validators.
 
-Provides shared dataclasses used across all validator modules.
+Provides shared dataclasses used across all validator modules, and the one
+read and the one parse each of those modules shares for a given file.
 """
 
+import ast
 from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+from .config.validator_base_constants import SOURCE_CACHE_ENTRIES, SOURCE_ENCODING
 
 
 @dataclass(frozen=True)
@@ -17,3 +23,69 @@ class Violation:
     def __str__(self) -> str:
         """Format as file:line: message."""
         return f"{self.file}:{self.line}: {self.message}"
+
+
+@dataclass(frozen=True)
+class ValidatorResult:
+    """Result from running a validator."""
+
+    name: str
+    checks: str
+    passed: bool
+    output: str
+    skipped: bool = False
+
+
+@lru_cache(maxsize=SOURCE_CACHE_ENTRIES)
+def _source_text_for_stat(
+    file_path_text: str, modified_nanoseconds: int, size_in_bytes: int
+) -> str:
+    """Read one file, keyed on the stat that identifies this version of it."""
+    return Path(file_path_text).read_text(encoding=SOURCE_ENCODING)
+
+
+def source_text(file_path: Path) -> str:
+    """Return the file's text, reading it once however many checks ask.
+
+    Every check the save-path gate runs reads the same file. The gate hands
+    each of them one freshly written target, so the read is repeated work.
+    The cache key carries the modification time and size, so an edited file
+    is read again.
+
+    That key has one blind spot: a rewrite that leaves the size unchanged
+    inside a single modification-time tick is served from the cache. A hook
+    process handles one payload, so it cannot happen there; a long CLI pass
+    over many files is where a reader needs to know.
+
+    Raises whatever ``read_text`` raises, so a caller's own error handling
+    is unchanged.
+
+    Args:
+        file_path: The file to read.
+
+    Returns:
+        The file's decoded text.
+    """
+    file_status = file_path.stat()
+    return _source_text_for_stat(
+        str(file_path), file_status.st_mtime_ns, file_status.st_size
+    )
+
+
+@lru_cache(maxsize=SOURCE_CACHE_ENTRIES)
+def syntax_tree(source: str) -> ast.Module:
+    """Return the parsed tree for source, parsing it once however many checks ask.
+
+    No check mutates the tree; each one walks it. So one parse serves all of
+    them, and the tree is shared rather than copied.
+
+    Raises ``SyntaxError`` exactly as ``ast.parse`` does, so a caller's own
+    error handling is unchanged.
+
+    Args:
+        source: The file's text.
+
+    Returns:
+        The parsed module.
+    """
+    return ast.parse(source)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.31.0",
+    "version": "2.32.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/shell-invocation.md

@@ -18,4 +18,4 @@ When a script file's literal body needs `$(...)`, author it with the Write tool,
 
 ## Enforcement
 
-`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes.
+`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes. A quoted heredoc body is dropped for the same reason: the opener forms that quote or escape the delimiter tell bash to expand nothing down to the terminator, so a backtick there is text the file receives. A bare delimiter expands its body and keeps its scan.

package/rules/testing.md

@@ -26,3 +26,7 @@ Tests exercise real behavior, real data, and production code paths. A test that
 ## The File-Level TDD Gate Reads Content
 
 `tdd_enforcer.py` records each candidate test's content hash at every sighting and compares that hash on the next write. A first sighting requires content that differs from HEAD.
+
+## The Gate Reads a Recorded Failing Run First
+
+`hooks/observability/test_failure_recorder.py` runs on every Bash call and records a single unchained pytest run that names a real test file path and reports a failing exit status. It stores the command, that exit status, and the path in the same content-hash store the gate reads. The gate consults that record before its freshness fallback, and honours it while the candidate's content still matches what failed. `content_hash_store.py`'s module docstring holds the full contract.

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -8,6 +8,15 @@ here rather than inline in the modules.
 
 from __future__ import annotations
 
+# The installed tree's own shape is shared with every other reader of it.
+from dev_env_scripts_constants.shared_tree_constants import (  # noqa: F401
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    PROCESS_TREE_DIRECTORY_NAME,
+    PROCESS_TREE_KILL_MODULE_FILENAME,
+    SCRIPTS_DIRECTORY_NAME,
+    SHARED_PACKAGE_DIRECTORY_NAME,
+)
+
 GROK_BINARY_NAME: str = "grok"
 """Executable name resolved on PATH for the headless grok tier."""
 
@@ -56,6 +65,16 @@ DEFAULT_PING_TIMEOUT_SECONDS: int = 120
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds Claude config."""
 
+"""Environment variable naming the managed Claude config root."""
+
+"""Filename of the shared process-tree kill helper."""
+
+"""Directory name of the shared install tree under the managed root."""
+
+"""Directory name of the process-tree helper package under ``_shared``."""
+
+"""Directory name holding Python helpers under a process-tree package."""
+
 MANIFEST_FILENAME: str = ".claude-dev-env-manifest.json"
 """Install manifest written by ``claude-dev-env`` into the user Claude home."""
 

package/scripts/dev_env_scripts_constants/shared_tree_constants.py

@@ -0,0 +1,17 @@
+"""Constants for resolving directories inside the installed shared tree.
+
+These name the shape of the installed tree itself, not any one worker or
+skill that reads it, so every caller of shared_tree_paths shares them.
+"""
+
+from __future__ import annotations
+
+CLAUDE_CONFIG_DIR_ENV_VAR: str = "CLAUDE_CONFIG_DIR"
+
+SHARED_PACKAGE_DIRECTORY_NAME: str = "_shared"
+
+SCRIPTS_DIRECTORY_NAME: str = "scripts"
+
+PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
+
+PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"

package/scripts/grok_headless_runner.py

@@ -25,24 +25,14 @@ Import ``run_headless_worker`` for the outcome object::
 
 from __future__ import annotations
 
+import os
 import subprocess
 import sys
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
 
-_shared_process_tree_scripts_directory = (
-    Path(__file__).resolve().parents[1] / "_shared" / "process-tree" / "scripts"
-)
-if str(_shared_process_tree_scripts_directory) not in sys.path:
-    sys.path.insert(0, str(_shared_process_tree_scripts_directory))
-
-from process_tree_kill import (  # noqa: E402
-    should_start_new_session,
-    terminate_process_tree,
-)
-
-from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
+from dev_env_scripts_constants.grok_worker_constants import (
     AGENT_FLAG,
     ALL_AUTH_FAILURE_SIGNATURES,
     ALL_USAGE_LIMIT_SIGNATURES,
@@ -81,6 +71,19 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     UTF8_ENCODING,
     WORKER_SPEC_TIMEOUT_KEY,
 )
+from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+
+_shared_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
+    __file__,
+    all_environment=os.environ,
+)
+if str(_shared_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_process_tree_scripts_directory))
+
+from process_tree_kill import (  # noqa: E402
+    should_start_new_session,
+    terminate_process_tree,
+)
 
 runner_popen = subprocess.Popen