claude-dev-env 2.31.0 → 2.31.1

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.31.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -56,6 +56,21 @@ DEFAULT_PING_TIMEOUT_SECONDS: int = 120
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds Claude config."""
 
+CLAUDE_CONFIG_DIR_ENV_VAR: str = "CLAUDE_CONFIG_DIR"
+"""Environment variable naming the managed Claude config root."""
+
+PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"
+"""Filename of the shared process-tree kill helper."""
+
+SHARED_PACKAGE_DIRECTORY_NAME: str = "_shared"
+"""Directory name of the shared install tree under the managed root."""
+
+PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
+"""Directory name of the process-tree helper package under ``_shared``."""
+
+SCRIPTS_DIRECTORY_NAME: str = "scripts"
+"""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/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
 

package/scripts/shared_tree_paths.py

@@ -0,0 +1,70 @@
+"""Resolve directories inside the installed shared tree."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+from dev_env_scripts_constants.grok_worker_constants import (
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    PROCESS_TREE_DIRECTORY_NAME,
+    PROCESS_TREE_KILL_MODULE_FILENAME,
+    SCRIPTS_DIRECTORY_NAME,
+    SHARED_PACKAGE_DIRECTORY_NAME,
+)
+
+
+def _process_tree_scripts_directory(from_root: Path) -> Path:
+    return (
+        from_root
+        / SHARED_PACKAGE_DIRECTORY_NAME
+        / PROCESS_TREE_DIRECTORY_NAME
+        / SCRIPTS_DIRECTORY_NAME
+    )
+
+
+def _has_process_tree_kill_module(from_directory: Path) -> bool:
+    return (from_directory / PROCESS_TREE_KILL_MODULE_FILENAME).is_file()
+
+
+def resolve_shared_process_tree_scripts_directory(
+    module_file: str | Path,
+    all_environment: Mapping[str, str],
+) -> Path:
+    """Return the first process-tree scripts directory that holds the kill helper.
+
+    ::
+
+        scripts dir is a junction; the kill helper sits beside the un-resolved parent
+        ok:   Path(module_file).absolute().parent.parent then the _shared scripts dir
+        flag: Path(module_file).resolve().parents[1] walks the junction and misses it
+
+    Tries the un-resolved parent first, then the configured managed root, then
+    the resolved parent. When none hold the helper, return the un-resolved
+    candidate so import failure names a readable path.
+
+    Args:
+        module_file: Path of the importing module (``__file__``).
+        all_environment: Mapping that may hold ``CLAUDE_CONFIG_DIR``.
+
+    Returns:
+        Directory that should hold ``process_tree_kill.py``.
+    """
+    un_resolved_candidate = _process_tree_scripts_directory(
+        Path(module_file).absolute().parent.parent
+    )
+    all_candidates = [un_resolved_candidate]
+    configured_root_text = all_environment.get(
+        CLAUDE_CONFIG_DIR_ENV_VAR, ""
+    ).strip()
+    if configured_root_text:
+        all_candidates.append(
+            _process_tree_scripts_directory(Path(configured_root_text))
+        )
+    all_candidates.append(
+        _process_tree_scripts_directory(Path(module_file).resolve().parents[1])
+    )
+    for each_candidate in all_candidates:
+        if _has_process_tree_kill_module(each_candidate):
+            return each_candidate
+    return un_resolved_candidate

package/scripts/test_shared_tree_paths.py

@@ -0,0 +1,143 @@
+"""Behavioral tests for shared-tree directory resolution."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import shared_tree_paths  # noqa: E402
+from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    PROCESS_TREE_DIRECTORY_NAME,
+    PROCESS_TREE_KILL_MODULE_FILENAME,
+    SCRIPTS_DIRECTORY_NAME,
+    SHARED_PACKAGE_DIRECTORY_NAME,
+)
+
+
+def _create_directory_link(*, from_link: Path, to_target: Path) -> None:
+    if sys.platform.startswith("win32"):
+        importlib.import_module("_winapi").CreateJunction(
+            str(to_target), str(from_link)
+        )
+        return
+    try:
+        os.symlink(to_target, from_link, target_is_directory=True)
+    except OSError:
+        pytest.skip("directory symlink creation is not available")
+
+
+def _build_junction_scripts_layout(tmp_path: Path) -> Path:
+    real_scripts_directory = tmp_path / "real" / SCRIPTS_DIRECTORY_NAME
+    real_scripts_directory.mkdir(parents=True)
+    (real_scripts_directory / "runner.py").write_text("", encoding="utf-8")
+    managed_root = tmp_path / "root"
+    managed_root.mkdir()
+    _create_directory_link(
+        from_link=managed_root / SCRIPTS_DIRECTORY_NAME,
+        to_target=real_scripts_directory,
+    )
+    return managed_root / SCRIPTS_DIRECTORY_NAME / "runner.py"
+
+
+def _write_process_tree_kill_stub(from_root: Path) -> Path:
+    scripts_directory = (
+        from_root
+        / SHARED_PACKAGE_DIRECTORY_NAME
+        / PROCESS_TREE_DIRECTORY_NAME
+        / SCRIPTS_DIRECTORY_NAME
+    )
+    scripts_directory.mkdir(parents=True)
+    (scripts_directory / PROCESS_TREE_KILL_MODULE_FILENAME).write_text(
+        "", encoding="utf-8"
+    )
+    return scripts_directory
+
+
+def test_junction_scripts_dir_finds_shared_tree_on_unresolved_parent(
+    tmp_path: Path,
+) -> None:
+    module_file = _build_junction_scripts_layout(tmp_path)
+    expected_scripts_directory = _write_process_tree_kill_stub(tmp_path / "root")
+    resolved_scripts_directory = (
+        shared_tree_paths.resolve_shared_process_tree_scripts_directory(
+            module_file, all_environment={}
+        )
+    )
+    assert resolved_scripts_directory == expected_scripts_directory
+
+
+def test_resolved_parent_is_used_when_link_side_has_no_shared_tree(
+    tmp_path: Path,
+) -> None:
+    module_file = _build_junction_scripts_layout(tmp_path)
+    expected_scripts_directory = _write_process_tree_kill_stub(tmp_path / "real")
+    resolved_scripts_directory = (
+        shared_tree_paths.resolve_shared_process_tree_scripts_directory(
+            module_file, all_environment={}
+        )
+    )
+    assert resolved_scripts_directory == expected_scripts_directory
+
+
+def test_configured_root_is_used_when_neither_parent_holds_the_module(
+    tmp_path: Path,
+) -> None:
+    module_file = _build_junction_scripts_layout(tmp_path)
+    configured_root = tmp_path / "configured"
+    expected_scripts_directory = _write_process_tree_kill_stub(configured_root)
+    resolved_scripts_directory = (
+        shared_tree_paths.resolve_shared_process_tree_scripts_directory(
+            module_file,
+            all_environment={
+                CLAUDE_CONFIG_DIR_ENV_VAR: str(configured_root)
+            },
+        )
+    )
+    assert resolved_scripts_directory == expected_scripts_directory
+
+
+def test_unresolved_parent_wins_when_configured_root_also_holds_the_module(
+    tmp_path: Path,
+) -> None:
+    module_file = _build_junction_scripts_layout(tmp_path)
+    expected_scripts_directory = _write_process_tree_kill_stub(tmp_path / "root")
+    configured_root = tmp_path / "configured"
+    _write_process_tree_kill_stub(configured_root)
+    resolved_scripts_directory = (
+        shared_tree_paths.resolve_shared_process_tree_scripts_directory(
+            module_file,
+            all_environment={
+                CLAUDE_CONFIG_DIR_ENV_VAR: str(configured_root)
+            },
+        )
+    )
+    assert resolved_scripts_directory == expected_scripts_directory
+
+
+def test_missing_module_returns_unresolved_candidate(tmp_path: Path) -> None:
+    module_file = _build_junction_scripts_layout(tmp_path)
+    expected_scripts_directory = (
+        tmp_path
+        / "root"
+        / SHARED_PACKAGE_DIRECTORY_NAME
+        / PROCESS_TREE_DIRECTORY_NAME
+        / SCRIPTS_DIRECTORY_NAME
+    )
+    resolved_scripts_directory = (
+        shared_tree_paths.resolve_shared_process_tree_scripts_directory(
+            module_file, all_environment={}
+        )
+    )
+    assert resolved_scripts_directory == expected_scripts_directory
+    assert not (
+        expected_scripts_directory / PROCESS_TREE_KILL_MODULE_FILENAME
+    ).is_file()