claude-dev-env 1.72.0 → 1.73.0

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -0,0 +1,135 @@
+"""Constants for the PreToolUse dispatcher that hosts Write/Edit/MultiEdit hooks.
+
+Holds the ordered hosted-hook list with per-hook applicable-tool sets, the
+special exit codes, the deny decision string, and the hook-event name. The
+dispatcher imports these; no literals appear inline in the dispatcher script.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "DENY_DECISION",
+    "ALLOW_DECISION",
+    "HOOK_EVENT_NAME",
+    "BLOCKING_CRASH_EXIT_CODE",
+    "EXIT_CODE_TWO_DENY_REASON",
+    "WRITE_TOOL_NAME",
+    "EDIT_TOOL_NAME",
+    "MULTI_EDIT_TOOL_NAME",
+    "ALL_WRITE_AND_EDIT_TOOL_NAMES",
+    "ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES",
+    "STATE_DESCRIPTION_BLOCKER_MODULE_NAME",
+    "PLAIN_LANGUAGE_BLOCKER_MODULE_NAME",
+    "HostedHookEntry",
+    "ALL_HOSTED_HOOK_ENTRIES",
+]
+
+DENY_DECISION = "deny"
+ALLOW_DECISION = "allow"
+HOOK_EVENT_NAME = "PreToolUse"
+BLOCKING_CRASH_EXIT_CODE = 2
+EXIT_CODE_TWO_DENY_REASON = "[dispatcher] hook denied via exit code 2 — write blocked"
+
+WRITE_TOOL_NAME = "Write"
+EDIT_TOOL_NAME = "Edit"
+MULTI_EDIT_TOOL_NAME = "MultiEdit"
+
+ALL_WRITE_AND_EDIT_TOOL_NAMES: frozenset[str] = frozenset({WRITE_TOOL_NAME, EDIT_TOOL_NAME})
+ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES: frozenset[str] = frozenset(
+    {WRITE_TOOL_NAME, EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME}
+)
+
+
+STATE_DESCRIPTION_BLOCKER_MODULE_NAME = "state_description_blocker"
+PLAIN_LANGUAGE_BLOCKER_MODULE_NAME = "plain_language_blocker"
+
+
+@dataclass(frozen=True)
+class HostedHookEntry:
+    """A single hosted hook with its applicable-tools constraint and blocking flag.
+
+    Attributes:
+        script_relative_path: Hook path relative to the hooks/ directory.
+        applicable_tool_names: Tool names this hook applies to. The dispatcher
+            skips the hook when the payload's tool is not in this set.
+        is_blocking: True when a crash surfaces a blocking signal; False when the
+            hook is advisory and a crash stays silent.
+        native_module_name: The importable module name whose evaluate function
+            the dispatcher calls in-process for this hook, or None when the hook
+            runs via runpy under __main__. The named module exposes a function
+            named NATIVE_EVALUATE_FUNCTION_NAME taking the payload dict and
+            returning a deny-reason string or None.
+    """
+
+    script_relative_path: str
+    applicable_tool_names: frozenset[str]
+    is_blocking: bool = field(default=True)
+    native_module_name: str | None = field(default=None)
+
+
+ALL_HOSTED_HOOK_ENTRIES: tuple[HostedHookEntry, ...] = (
+    HostedHookEntry(
+        script_relative_path="blocking/write_existing_file_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/sensitive_file_protector.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="validation/hook_format_validator.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/code_rules_enforcer.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/tdd_enforcer.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/windows_rmtree_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/state_description_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+        native_module_name=STATE_DESCRIPTION_BLOCKER_MODULE_NAME,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/subprocess_budget_completeness.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/hook_prose_detector_consistency.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/verified_commit_message_accuracy_blocker.py",
+        applicable_tool_names=ALL_WRITE_AND_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/workflow_substitution_slot_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/claude_md_orphan_file_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/pytest_testpaths_orphan_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/open_questions_in_plans_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    ),
+    HostedHookEntry(
+        script_relative_path="blocking/plain_language_blocker.py",
+        applicable_tool_names=ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+        native_module_name=PLAIN_LANGUAGE_BLOCKER_MODULE_NAME,
+    ),
+)

package/hooks/hooks_constants/pytest_testpaths_orphan_blocker_constants.py

@@ -0,0 +1,79 @@
+"""Constants for the pytest unregistered-test-directory blocker.
+
+A package whose ``pyproject.toml`` declares ``[tool.pytest.ini_options]`` with an
+explicit ``testpaths`` list runs only the directories that list names. A
+``test_*.py`` file written into a directory that no ``testpaths`` entry covers is
+collected by no default ``pytest`` run, so the test silently never executes and a
+regression in the code it guards passes the standard suite undetected. This
+module holds the marker filename that anchors a pytest package, the key name
+that identifies an explicit ``testpaths`` allowlist, the test-file basename
+pattern, the package-root entry tokens and glob metacharacters that classify a
+``testpaths`` entry, the directory names the upward search prunes, the search
+budget, and the block-message text the hook emits.
+"""
+
+import re
+
+__all__ = [
+    "PYPROJECT_FILENAME",
+    "TESTPATHS_KEY",
+    "TEST_FILE_BASENAME_PATTERN",
+    "PACKAGE_ROOT_ENTRY",
+    "PACKAGE_ROOT_ENTRY_PREFIX",
+    "GLOB_METACHARACTERS",
+    "ALL_PRUNED_PARENT_DIRECTORY_NAMES",
+    "MAX_PARENT_DIRECTORIES_SEARCHED",
+    "UNREGISTERED_TEST_DIRECTORY_MESSAGE_TEMPLATE",
+    "UNREGISTERED_TEST_DIRECTORY_SYSTEM_MESSAGE",
+    "UNREGISTERED_TEST_DIRECTORY_ADDITIONAL_CONTEXT",
+]
+
+PYPROJECT_FILENAME: str = "pyproject.toml"
+
+TESTPATHS_KEY: str = "testpaths"
+
+TEST_FILE_BASENAME_PATTERN: re.Pattern[str] = re.compile(r"^test_.+\.py$")
+
+PACKAGE_ROOT_ENTRY: str = "."
+
+PACKAGE_ROOT_ENTRY_PREFIX: str = "./"
+
+GLOB_METACHARACTERS: frozenset[str] = frozenset({"*", "?", "["})
+
+ALL_PRUNED_PARENT_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
+MAX_PARENT_DIRECTORIES_SEARCHED: int = 40
+
+UNREGISTERED_TEST_DIRECTORY_MESSAGE_TEMPLATE: str = (
+    "Test file {test_file} lands in a directory that the pytest config at "
+    "{pyproject} does not collect. That pyproject declares an explicit testpaths "
+    "allowlist, and no entry covers {test_directory} (relative to the package "
+    "root). A default `pytest` run from the package root never collects this file, "
+    "so the test silently never runs and a regression it would catch passes the "
+    "suite undetected. Add the directory to the testpaths list in {pyproject} "
+    "(for example `{suggested_entry}`) in the same change that adds the test."
+)
+
+UNREGISTERED_TEST_DIRECTORY_SYSTEM_MESSAGE: str = (
+    "test file lands outside the pytest testpaths allowlist - add its directory to "
+    "testpaths so the default suite collects it"
+)
+
+UNREGISTERED_TEST_DIRECTORY_ADDITIONAL_CONTEXT: str = (
+    "When a package's pyproject.toml declares [tool.pytest.ini_options] with an "
+    "explicit testpaths list, that list is the complete set of directories a "
+    "default pytest run collects. A test_*.py file written into a directory no "
+    "testpaths entry covers is collected by nobody: the default run skips it and "
+    "the regression it guards goes unnoticed. To resolve:\n"
+    "  - add the test file's directory (relative to the package root) to the "
+    "testpaths list in pyproject.toml, or\n"
+    "  - move the test under a directory the testpaths list already covers."
+)

package/hooks/validation/mypy_validator.py

@@ -11,6 +11,7 @@ This catches:
 Works in both WSL and Windows for any Python project with a git root.
 Project root is discovered via CLAUDE_PROJECT_ROOT env var or git rev-parse.
 """
+import hashlib
 import importlib
 import json
 import os
@@ -20,10 +21,29 @@ import sys
 from pathlib import Path
 from types import ModuleType
 
-NOTIFICATION_UTILS_DIRECTORY = os.path.join(
-    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "notification"
+_hooks_directory = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+_notification_utils_directory = os.path.join(_hooks_directory, "notification")
+sys.path.insert(0, _notification_utils_directory)
+
+_validators_directory = os.path.join(_hooks_directory, "validators")
+if _validators_directory not in sys.path:
+    sys.path.insert(0, _validators_directory)
+
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from mypy_integration import find_pyproject_with_mypy_config  # noqa: E402
+
+from hooks_constants.mypy_validator_cache_constants import (  # noqa: E402
+    CACHE_FILE_ENCODING,
+    CONTENT_HASH_CACHE_PASSING_EXIT_CODE,
+    HOOK_STATE_CACHE_DIRECTORY,
+    MYPY_CONFIG_CACHE_FILENAME,
+    MYPY_CONTENT_HASH_CACHE_FILENAME,
+    SESSION_ID_ENVIRONMENT_VARIABLE,
+    UNKNOWN_SESSION_IDENTIFIER,
 )
-sys.path.insert(0, NOTIFICATION_UTILS_DIRECTORY)
 
 
 def load_notification_utils() -> ModuleType | None:
@@ -69,6 +89,85 @@ def is_file_within_project(target_file: str, project_root: Path) -> bool:
         return False
 
 
+_session_config_cache_by_target_directory: dict[str, str | None] = {}
+
+
+def reset_session_config_cache() -> None:
+    """Clear the in-process config-walk cache so the next walk runs fresh.
+
+    The cache is normally seeded once per target directory per session; tests
+    call this between scenarios so a redirected cache directory starts empty.
+    """
+    _session_config_cache_by_target_directory.clear()
+
+
+def resolve_session_identifier() -> str:
+    """Return the current session identifier for keying per-session caches.
+
+    Returns:
+        The ``CLAUDE_CODE_SESSION_ID`` environment value, or a fixed unknown
+        marker when the variable is unset or empty so the cache still has a
+        stable key within a single run.
+    """
+    session_identifier = os.environ.get(SESSION_ID_ENVIRONMENT_VARIABLE, "")
+    return session_identifier or UNKNOWN_SESSION_IDENTIFIER
+
+
+def _session_cache_path(cache_filename: str) -> Path:
+    session_identifier = resolve_session_identifier()
+    return Path(HOOK_STATE_CACHE_DIRECTORY) / session_identifier / cache_filename
+
+
+def _read_cache_file(cache_path: Path) -> dict[str, object]:
+    if not cache_path.is_file():
+        return {}
+    try:
+        raw_text = cache_path.read_text(encoding=CACHE_FILE_ENCODING)
+    except OSError:
+        return {}
+    if not raw_text.strip():
+        return {}
+    try:
+        parsed_cache = json.loads(raw_text)
+    except json.JSONDecodeError:
+        return {}
+    return parsed_cache if isinstance(parsed_cache, dict) else {}
+
+
+def _write_cache_file(cache_path: Path, cache_by_key: dict[str, object]) -> None:
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(
+            json.dumps(cache_by_key), encoding=CACHE_FILE_ENCODING
+        )
+    except OSError:
+        return
+
+
+def _walk_mypy_config(target_file: Path) -> Path | None:
+    discovered_config = find_pyproject_with_mypy_config(target_file)
+    return discovered_config if isinstance(discovered_config, Path) else None
+
+
+def _config_cache_key_for(target_file: Path) -> str:
+    """Return the cache key for one file's config walk.
+
+    The walk climbs the ancestors of the target file's own directory, so its
+    result is determined by that directory, not by the shared project root. Two
+    files in sibling subtrees under one git root each carry their own nearer
+    ``[tool.mypy]`` config; keying the cache by the resolved target directory
+    keeps each file's walk distinct so the first file checked does not seed the
+    second file's config.
+
+    Args:
+        target_file: The Python file mypy will check.
+
+    Returns:
+        The resolved directory of the target file as the config-walk cache key.
+    """
+    return str(target_file.resolve().parent)
+
+
 def discover_mypy_config(target_file: Path) -> Path | None:
     """Return the nearest ancestor ``pyproject.toml`` that configures mypy.
 
@@ -76,28 +175,97 @@ def discover_mypy_config(target_file: Path) -> Path | None:
     is on its invocation path; handing the discovered config to mypy lets a
     check run from the repository root still honor the project's own import
     resolution settings (such as ``ignore_missing_imports``) for a module that
-    imports its siblings by name. Reuses the validators-package walk-up so the
-    discovery logic lives in one place.
+    imports its siblings by name. The discovered config is cached per target
+    directory for the session, in process and in a session cache file, so a
+    later edit of a file in the same directory reuses the result rather than
+    walking ancestors again.
 
     Args:
-        target_file: The Python file mypy will check.
+        target_file: The Python file mypy will check; its directory keys the walk.
 
     Returns:
         The nearest ancestor ``pyproject.toml`` declaring a ``[tool.mypy]``
-        table, or None when none exists above the file or the walk-up helper
-        cannot be imported.
+        table, or None when none exists above the file.
     """
-    validators_directory = os.path.join(
-        os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "validators"
-    )
-    if validators_directory not in sys.path:
-        sys.path.insert(0, validators_directory)
+    cache_key = _config_cache_key_for(target_file)
+    if cache_key in _session_config_cache_by_target_directory:
+        cached_value = _session_config_cache_by_target_directory[cache_key]
+        return Path(cached_value) if cached_value is not None else None
+
+    config_cache_path = _session_cache_path(MYPY_CONFIG_CACHE_FILENAME)
+    persisted_cache = _read_cache_file(config_cache_path)
+    if cache_key in persisted_cache:
+        persisted_value = persisted_cache[cache_key]
+        resolved_persisted = persisted_value if isinstance(persisted_value, str) else None
+        _session_config_cache_by_target_directory[cache_key] = resolved_persisted
+        return Path(resolved_persisted) if resolved_persisted is not None else None
+
+    discovered_config = _walk_mypy_config(target_file)
+    discovered_value = str(discovered_config) if discovered_config is not None else None
+    _session_config_cache_by_target_directory[cache_key] = discovered_value
+    persisted_cache[cache_key] = discovered_value
+    _write_cache_file(config_cache_path, persisted_cache)
+    return discovered_config
+
+
+def _config_signature(mypy_config_file: Path | None) -> bytes:
+    """Return a byte signature of the discovered mypy config's current contents.
+
+    The signature folds the config file's own bytes into the content-hash cache
+    key so a change to the project's ``[tool.mypy]`` settings invalidates a
+    previously recorded passing hash: when the file's bytes are restored to a
+    prior passing version under a tightened config, the composite hash differs
+    and mypy re-runs rather than returning a stale pass. An absent config
+    contributes a fixed empty signature.
+
+    Args:
+        mypy_config_file: The discovered config path, or None when none exists.
+
+    Returns:
+        The config file's bytes, or an empty signature when there is no config
+        or it cannot be read.
+    """
+    if mypy_config_file is None:
+        return b""
     try:
-        integration_module = importlib.import_module("mypy_integration")
-    except ImportError:
+        return mypy_config_file.read_bytes()
+    except OSError:
+        return b""
+
+
+def _composite_content_hash(target_file: str, mypy_config_file: Path | None) -> str | None:
+    """Return a hash over the target file's bytes and its mypy config's bytes.
+
+    Args:
+        target_file: The absolute path of the file to type-check.
+        mypy_config_file: The discovered mypy config path, or None.
+
+    Returns:
+        The combined hash, or None when the target file cannot be read.
+    """
+    try:
+        file_bytes = Path(target_file).read_bytes()
+    except OSError:
         return None
-    discovered_config = integration_module.find_pyproject_with_mypy_config(target_file)
-    return discovered_config if isinstance(discovered_config, Path) else None
+    hasher = hashlib.sha256()
+    hasher.update(file_bytes)
+    hasher.update(_config_signature(mypy_config_file))
+    return hasher.hexdigest()
+
+
+def _read_cached_passing_hash(target_file: str) -> str | None:
+    content_hash_cache = _read_cache_file(
+        _session_cache_path(MYPY_CONTENT_HASH_CACHE_FILENAME)
+    )
+    cached_hash = content_hash_cache.get(target_file)
+    return cached_hash if isinstance(cached_hash, str) else None
+
+
+def _record_passing_hash(target_file: str, content_hash: str) -> None:
+    content_hash_cache_path = _session_cache_path(MYPY_CONTENT_HASH_CACHE_FILENAME)
+    content_hash_cache = _read_cache_file(content_hash_cache_path)
+    content_hash_cache[target_file] = content_hash
+    _write_cache_file(content_hash_cache_path, content_hash_cache)
 
 
 def build_mypy_command(relative_file_path: str, mypy_config_file: Path | None) -> list[str]:
@@ -128,6 +296,28 @@ def build_mypy_command(relative_file_path: str, mypy_config_file: Path | None) -
 def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
     """Run mypy on one file from the project root and return its result.
 
+    The mypy run is skipped when a composite hash over the target file's bytes
+    and its discovered mypy config's bytes matches the hash recorded the last
+    time mypy passed for that file; that recorded skip can only return a pass, so
+    a content change always re-runs mypy and a file edited to introduce a type
+    error still blocks. Folding the config bytes into the hash invalidates the
+    skip when the project's ``[tool.mypy]`` settings change, so a file whose
+    bytes are restored to a prior passing version under a tightened config
+    re-runs rather than returning a stale pass. The discovered config is reused
+    from the per-session cache keyed by the target file's own directory, so two
+    files in sibling subtrees under one project root each resolve their own
+    nearer config.
+
+    The composite hash covers the target file's own bytes and its config's
+    bytes only, so the skip is blind to a cross-file change in a dependency:
+    when a dependency is edited in a way that breaks this file's call site and
+    this file is later rewritten to its prior passing content, the cached pass
+    returns without re-running mypy. The post-write hook already type-checks only
+    the single edited file, so a dependent is never re-checked on the
+    dependency's own edit regardless of the cache; the cache adds only the
+    identical-rewrite-under-unchanged-config skip on top of that existing
+    single-file scope.
+
     Args:
         target_file: The absolute path of the file to type-check.
         project_root: The directory mypy runs from.
@@ -137,6 +327,11 @@ def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
     """
     relative_file_path = os.path.relpath(target_file, project_root)
     mypy_config_file = discover_mypy_config(Path(target_file))
+
+    content_hash = _composite_content_hash(target_file, mypy_config_file)
+    if content_hash is not None and content_hash == _read_cached_passing_hash(target_file):
+        return CONTENT_HASH_CACHE_PASSING_EXIT_CODE, ""
+
     mypy_command = build_mypy_command(relative_file_path, mypy_config_file)
 
     completed_process = subprocess.run(
@@ -152,6 +347,9 @@ def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
     stderr_output = completed_process.stderr.strip()
     combined_output = f"{stdout_output}\n{stderr_output}".strip() if stderr_output else stdout_output
 
+    if completed_process.returncode == CONTENT_HASH_CACHE_PASSING_EXIT_CODE and content_hash is not None:
+        _record_passing_hash(target_file, content_hash)
+
     return completed_process.returncode, combined_output