claude-dev-env 2.4.0 → 2.5.0

package/hooks/validators/ruff_integration.py

@@ -1,5 +1,6 @@
 """Ruff integration for fast Python linting."""
 
+import os
 import subprocess
 import sys
 from dataclasses import dataclass
@@ -16,13 +17,25 @@ except ModuleNotFoundError:
     from pyproject_config_discovery import find_pyproject_configuring_tool
 
 try:
+    from hooks_constants.blocking_check_limits import RUFF_STDIN_ENCODING
     from hooks_constants.mypy_integration_constants import PYTHON_SOURCE_SUFFIX
     from hooks_constants.pyproject_config_discovery_constants import RUFF_TOOL_TABLE_NAME
+    from hooks_constants.ruff_integration_constants import (
+        FORCE_COLOR_ENVIRONMENT_VARIABLE_NAME,
+        NO_COLOR_ENABLED_VALUE,
+        NO_COLOR_ENVIRONMENT_VARIABLE_NAME,
+    )
 except ModuleNotFoundError:
     if _hooks_directory not in sys.path:
         sys.path.insert(0, _hooks_directory)
+    from hooks_constants.blocking_check_limits import RUFF_STDIN_ENCODING
     from hooks_constants.mypy_integration_constants import PYTHON_SOURCE_SUFFIX
     from hooks_constants.pyproject_config_discovery_constants import RUFF_TOOL_TABLE_NAME
+    from hooks_constants.ruff_integration_constants import (
+        FORCE_COLOR_ENVIRONMENT_VARIABLE_NAME,
+        NO_COLOR_ENABLED_VALUE,
+        NO_COLOR_ENVIRONMENT_VARIABLE_NAME,
+    )
 
 
 @dataclass
@@ -46,6 +59,19 @@ def check_ruff_available() -> bool:
         return False
 
 
+def _ruff_subprocess_environment() -> dict[str, str]:
+    """Return an environment that forces plain, non-ANSI ruff diagnostics.
+
+    The PreToolUse gate parses ``path:line:col:`` prefixes. ANSI color codes
+    wrap those fields when FORCE_COLOR is set, so line numbers no longer parse
+    and baseline scoping fail-closes every ruff finding as new.
+    """
+    ruff_environment = os.environ.copy()
+    ruff_environment[NO_COLOR_ENVIRONMENT_VARIABLE_NAME] = NO_COLOR_ENABLED_VALUE
+    ruff_environment.pop(FORCE_COLOR_ENVIRONMENT_VARIABLE_NAME, None)
+    return ruff_environment
+
+
 def find_pyproject_with_ruff_config(starting_file: Path) -> Path | None:
     """Walk up from a starting file to a pyproject.toml that configures ruff.
 
@@ -108,9 +134,14 @@ def _config_relative_stdin_filename(target_path: Path, config_directory: Path) -
         The config-relative POSIX path when the target sits under the config
         directory, else the target's basename.
     """
+    try:
+        return target_path.relative_to(config_directory).as_posix()
+    except ValueError:
+        pass
     resolved_target = target_path.resolve()
+    resolved_config_directory = config_directory.resolve()
     try:
-        return resolved_target.relative_to(config_directory).as_posix()
+        return resolved_target.relative_to(resolved_config_directory).as_posix()
     except ValueError:
         return resolved_target.name
 
@@ -151,14 +182,25 @@ def _staged_ruff_command(resolved_pyproject: Path, stdin_filename: str) -> list[
 def _staged_ruff_result(
     resolved_pyproject: Path, stdin_filename: str, staged_content: str
 ) -> RuffResult:
-    """Pipe *staged_content* to ruff from the config directory and wrap the result."""
+    """Pipe *staged_content* to ruff from the config directory and wrap the result.
+
+    ``encoding`` pins the stdin encode to UTF-8, which ruff requires, regardless
+    of the host locale codec. ``errors="replace"`` keeps the stdout/stderr decode
+    tolerant: a stray non-UTF-8 byte in ruff's output becomes the replacement
+    character rather than raising, which under strict decoding drops the whole
+    stream on Windows and raises out of ``subprocess.run`` on POSIX. ``replace``
+    is chosen over ``surrogateescape`` so the decoded text never plants a lone
+    surrogate that would raise at a later strict re-encode.
+    """
     result = subprocess.run(
         _staged_ruff_command(resolved_pyproject, stdin_filename),
         check=False,
         capture_output=True,
-        text=True,
+        encoding=RUFF_STDIN_ENCODING,
+        errors="replace",
         input=staged_content,
         cwd=str(resolved_pyproject.parent),
+        env=_ruff_subprocess_environment(),
     )
     return RuffResult(
         passed=result.returncode == 0,
@@ -204,6 +246,7 @@ def _run_native_ruff_check(
         check=False,
         capture_output=True,
         text=True,
+        env=_ruff_subprocess_environment(),
     )
     return RuffResult(
         passed=result.returncode == 0,
@@ -250,12 +293,12 @@ def _parse_fixed_count(fix_output: str) -> int:
     return 0
 
 
-def run_ruff_fix(files: list[Path]) -> RuffResult:
+def run_ruff_fix(all_files: list[Path]) -> RuffResult:
     """Run ruff with --fix to auto-fix violations."""
     if not check_ruff_available():
         return RuffResult(passed=True, output="Ruff not installed", fixed_count=0)
     py_files = [
-        str(each_file) for each_file in files if each_file.suffix == PYTHON_SOURCE_SUFFIX
+        str(each_file) for each_file in all_files if each_file.suffix == PYTHON_SOURCE_SUFFIX
     ]
     if not py_files:
         return RuffResult(passed=True, output="No Python files", fixed_count=0)
@@ -264,6 +307,7 @@ def run_ruff_fix(files: list[Path]) -> RuffResult:
         check=False,
         capture_output=True,
         text=True,
+        env=_ruff_subprocess_environment(),
     )
     return RuffResult(
         passed=result.returncode == 0,

package/hooks/validators/run_all_validators.py

@@ -19,6 +19,11 @@ from datetime import datetime
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Tuple
 
+from .config.directory_exemption_constants import (
+    ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES,
+    ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS,
+    ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES,
+)
 from .health_check import get_system_health, get_validator_version, print_health_report
 from .mypy_integration import check_mypy_available, run_mypy_check
 from .output_formatter import OutputFormatter, OutputMode, ValidatorResultDict
@@ -763,29 +768,221 @@ def run_file_scoped_validators(
     ]
 
 
+def _escapes_temporary_root(path_part: str) -> bool:
+    """Return True when a path part would climb out of or re-anchor the temp root.
+
+    ::
+
+        ok:   "scripts"  -> False (stays inside)
+        flag: ".."       -> True  (climbs a level)
+        flag: "/etc"     -> True  (absolute, re-anchors the join)
+
+    A ``..`` component escapes upward and an absolute or anchored component
+    re-roots the join away from the temporary directory. Both are dropped so a
+    staged file cannot land outside the ephemeral root.
+
+    Args:
+        path_part: A single path component drawn from the destination path.
+
+    Returns:
+        True when the component must be dropped to keep staging contained.
+    """
+    if path_part == os.pardir:
+        return True
+    part_as_path = Path(path_part)
+    return part_as_path.is_absolute() or bool(part_as_path.anchor)
+
+
+def _all_system_temporary_roots() -> tuple[Path, ...]:
+    """Return resolved roots that count as system temporary directories.
+
+    ::
+
+        gettempdir() plus TEMP / TMP / TMPDIR / RUNNER_TEMP when set.
+
+    GitHub Actions puts pytest basetemp under ``RUNNER_TEMP``
+    (``/home/runner/work/_temp``) while ``tempfile.gettempdir()`` is ``/tmp``.
+    Both must count so pytest-shaped ``test_*`` parents disable substring
+    exemption matching during staging.
+    """
+    all_candidate_roots: list[str] = [tempfile.gettempdir()]
+    for each_environment_name in ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES:
+        environment_value = os.environ.get(each_environment_name)
+        if environment_value:
+            all_candidate_roots.append(environment_value)
+    all_resolved_roots: list[Path] = []
+    for each_candidate in all_candidate_roots:
+        try:
+            all_resolved_roots.append(Path(each_candidate).resolve())
+        except OSError:
+            continue
+    return tuple(all_resolved_roots)
+
+
+def _is_absolute_path_under_system_temporary_directory(file_path: str) -> bool:
+    """Return True when *file_path* is absolute and resolves under an OS temp root.
+
+    ::
+
+        ok:   "C:/Users/.../Temp/pytest-of-x/test_foo0/a.py" -> True
+        ok:   "/home/runner/work/_temp/pytest-basetemp/.../a.py" when RUNNER_TEMP
+        flag: "packages/demo/test_helpers/worker.py"         -> False (relative)
+        flag: "C:/repo/pkg/test_helpers/worker.py"           -> False (project)
+
+    Absolute paths under system temporary directories often carry pytest
+    ``tmp_path`` segments named ``test_*``. Those segments must not be treated
+    as project exemption signals, or a production file staged from a pytest
+    path would inherit a false test-file exemption.
+
+    Args:
+        file_path: Destination path the write or edit targets.
+
+    Returns:
+        True when *file_path* is absolute and lives under ``tempfile.gettempdir()``
+        or a known temporary-root environment variable (``TEMP``, ``TMP``,
+        ``TMPDIR``, ``RUNNER_TEMP``).
+    """
+    destination_path = Path(file_path)
+    if not destination_path.is_absolute():
+        return False
+    try:
+        resolved_destination = destination_path.resolve()
+    except OSError:
+        return False
+    return any(
+        resolved_destination.is_relative_to(each_temporary_root)
+        for each_temporary_root in _all_system_temporary_roots()
+    )
+
+
+def _directory_segment_signals_exemption(
+    segment_lower: str, *, is_substring_match_enabled: bool
+) -> bool:
+    """Return True when a directory segment carries a path-exemption signal.
+
+    ::
+
+        ok:   "test_helpers" (substring on)  -> True  (contains the ``test_`` fragment)
+        ok:   "scripts"                      -> True  (exact CLI-marker segment name)
+        flag: "latest"                       -> False (neither exact name nor a fragment)
+        flag: "test_edit_foo0" (substring off) -> False (pytest-shaped; exact-only mode)
+
+    A segment is kept during staging when its name exactly matches an exemption
+    directory name. When *is_substring_match_enabled* is True, a separator-free
+    substring pattern that ``is_test_file`` matches anywhere in a path also
+    counts — that is what preserves ``pkg/test_helpers/``. Substring matching is
+    disabled for absolute paths under the system temporary directory so pytest
+    ``tmp_path`` parents named ``test_*`` do not falsely trip test exemptions.
+
+    Args:
+        segment_lower: One lowercased directory component of the target path.
+        is_substring_match_enabled: When False, only exact exemption names count.
+
+    Returns:
+        True when staging must keep this segment to reproduce the exemption.
+    """
+    if segment_lower in ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES:
+        return True
+    if not is_substring_match_enabled:
+        return False
+    return any(
+        each_pattern in segment_lower
+        for each_pattern in ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS
+    )
+
+
+def _temporary_path_preserving_directory_signal(
+    temporary_directory: Path, file_path: str
+) -> Path:
+    """Build a temp path that keeps exemption directory tails and the basename.
+
+    Directory-name exemptions (``/scripts/``, ``/tests/``) and separator-free
+    path fragments (``test_`` inside ``test_helpers``) match substrings of the
+    real file path. Staging under a flat temp basename drops those segments.
+    Mirroring the first exemption-signaling directory through the basename
+    restores that signal. Substring fragment matching is skipped for absolute
+    paths under the system temporary directory so pytest ``tmp_path`` parents
+    that contain ``test_`` do not falsely trip test-file exemptions; exact
+    exemption directory names (``config``, ``scripts``, ``tests``, ...) still
+    anchor staging on those absolute temp paths.
+
+    Args:
+        temporary_directory: Root of the ephemeral staging tree.
+        file_path: Real destination path the write or edit targets.
+
+    Returns:
+        Path under *temporary_directory* ending in the exemption directory tail
+        (when present) and the real basename.
+    """
+    destination_path = Path(file_path)
+    path_parts = destination_path.parts
+    if destination_path.anchor:
+        path_parts = path_parts[1:]
+    if not path_parts:
+        path_parts = (destination_path.name,)
+
+    is_substring_match_enabled = not _is_absolute_path_under_system_temporary_directory(
+        file_path
+    )
+    start_index = len(path_parts) - 1
+    for each_index, each_part in enumerate(path_parts[:-1]):
+        part_lower = each_part.lower()
+        if not _directory_segment_signals_exemption(
+            part_lower, is_substring_match_enabled=is_substring_match_enabled
+        ):
+            continue
+        start_index = each_index
+        break
+
+    selected_parts = path_parts[start_index:]
+    contained_parts = tuple(
+        each_part for each_part in selected_parts if not _escapes_temporary_root(each_part)
+    )
+    if not contained_parts:
+        contained_parts = (destination_path.name,)
+    temporary_file = temporary_directory.joinpath(*contained_parts)
+    if not temporary_file.resolve().is_relative_to(temporary_directory.resolve()):
+        temporary_file = temporary_directory / destination_path.name
+    temporary_file.parent.mkdir(parents=True, exist_ok=True)
+    return temporary_file
+
+
 def validate_proposed_file(
-    file_path: str, proposed_content: str
+    file_path: str,
+    proposed_content: str,
+    config_source_path: Optional[Path] = None,
 ) -> List[ValidatorResult]:
     """Validate *proposed_content* as if written to *file_path*.
 
-    Writes the content to a temporary file that carries the target's basename so
-    suffix-based and test-name-based validator filtering matches the real path,
-    then runs the file-scoped validators against it. Ruff and mypy resolve their
-    config by walking up from *file_path*, so the staged copy is graded under the
-    project config the real path sits in rather than the temp directory's.
+    Writes the content to a temporary file that preserves the exemption-relevant
+    directory tail and basename so directory-based exemptions, suffix-based
+    filtering, and test-name-based filtering match the real path, then runs the
+    file-scoped validators against it. Ruff and mypy resolve their config by
+    walking up from the config source path, so the staged copy is graded under
+    the project config the real path sits in rather than the temp directory's.
 
     Args:
         file_path: The destination path the write or edit targets.
         proposed_content: The reconstructed post-edit content of that file.
+        config_source_path: Path ruff and mypy resolve their config from;
+            defaults to *file_path* when the caller passes nothing.
 
     Returns:
         One ValidatorResult per file-scoped validator.
     """
-    base_name = Path(file_path).name
     with tempfile.TemporaryDirectory() as temporary_directory:
-        temporary_file = Path(temporary_directory) / base_name
+        temporary_file = _temporary_path_preserving_directory_signal(
+            Path(temporary_directory), file_path
+        )
         temporary_file.write_text(proposed_content, encoding="utf-8")
-        return run_file_scoped_validators([temporary_file], Path(file_path))
+        resolved_config_source_path = (
+            config_source_path
+            if config_source_path is not None
+            else Path(file_path)
+        )
+        return run_file_scoped_validators(
+            [temporary_file], config_source_path=resolved_config_source_path
+        )
 
 
 def _validator_summaries(results: List[ValidatorResult]) -> str:

package/hooks/validators/test_directory_exemption_constants.py

@@ -0,0 +1,185 @@
+"""Tests for directory-exemption segment derivation.
+
+Proves segment names come from authoritative path-exemption patterns and CLI
+markers rather than hand-copied directory-name literals.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from hooks_constants.code_rules_enforcer_constants import ALL_CLI_FILE_PATH_MARKERS
+from hooks_constants.code_rules_path_utils_constants import ALL_CONFIG_DIRECTORY_NAMES
+from validators.config.directory_exemption_constants import (
+    ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES,
+    ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS,
+    ALL_DIRECTORY_SEGMENTS_FROM_PATH_PATTERNS,
+    all_directory_segments_in_path_pattern,
+    directory_segment_names_from_path_patterns,
+    is_filename_like_path_segment,
+    substring_patterns_from_path_patterns,
+)
+from validators.exempt_paths import (
+    HOOK_INFRASTRUCTURE_PATTERNS,
+    MIGRATION_PATH_PATTERNS,
+    TEST_PATH_PATTERNS,
+    WORKFLOW_REGISTRY_PATTERNS,
+)
+from validators.run_all_validators import _temporary_path_preserving_directory_signal
+
+ALL_KNOWN_DIRECTORY_EXEMPTION_SEGMENTS = frozenset(
+    {"scripts", "tests", "migrations", "workflow", "hooks"}
+)
+ALL_SYNTHETIC_DIRECTORY_PATTERNS = frozenset(
+    {"/foo/", "\\bar\\", "/baz.py", "plain", "/.hidden/qux/"}
+)
+ALL_EXPECTED_SYNTHETIC_SEGMENTS = frozenset({"foo", "bar", ".hidden", "qux"})
+
+
+def test_is_filename_like_path_segment_detects_extensions() -> None:
+    assert is_filename_like_path_segment("states.py") is True
+    assert is_filename_like_path_segment("cli.py") is True
+    assert is_filename_like_path_segment("tests") is False
+    assert is_filename_like_path_segment(".claude") is False
+
+
+def test_all_directory_segments_in_path_pattern_keeps_directory_tokens_only() -> None:
+    assert all_directory_segments_in_path_pattern("/.claude/hooks/") == [
+        ".claude",
+        "hooks",
+    ]
+    assert all_directory_segments_in_path_pattern("\\tests\\") == ["tests"]
+    assert all_directory_segments_in_path_pattern("/tests.py") == []
+    assert all_directory_segments_in_path_pattern("conftest") == []
+    assert all_directory_segments_in_path_pattern("_tab.py") == []
+
+
+def test_directory_segment_names_from_path_patterns_extracts_new_directory_token() -> None:
+    all_segment_names = directory_segment_names_from_path_patterns(
+        ALL_SYNTHETIC_DIRECTORY_PATTERNS
+    )
+    assert all_segment_names == ALL_EXPECTED_SYNTHETIC_SEGMENTS
+
+
+def test_derived_segments_cover_authoritative_directory_patterns() -> None:
+    all_authoritative_patterns = (
+        set(TEST_PATH_PATTERNS)
+        | set(WORKFLOW_REGISTRY_PATTERNS)
+        | set(MIGRATION_PATH_PATTERNS)
+        | set(HOOK_INFRASTRUCTURE_PATTERNS)
+        | set(ALL_CLI_FILE_PATH_MARKERS)
+    )
+    all_expected_segments = directory_segment_names_from_path_patterns(
+        all_authoritative_patterns
+    )
+    assert all_expected_segments == ALL_DIRECTORY_SEGMENTS_FROM_PATH_PATTERNS
+    assert all_expected_segments <= ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES
+    assert ALL_CONFIG_DIRECTORY_NAMES <= ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES
+    assert ALL_KNOWN_DIRECTORY_EXEMPTION_SEGMENTS <= ALL_DIRECTORY_EXEMPTION_SEGMENT_NAMES
+
+
+def test_temporary_path_preserves_scripts_directory_segment(tmp_path: Path) -> None:
+    staged_path = _temporary_path_preserving_directory_signal(
+        tmp_path, "packages/demo/scripts/run_job.py"
+    )
+    assert staged_path == tmp_path / "scripts" / "run_job.py"
+
+
+def test_temporary_path_preserves_claude_hooks_parent_and_child(tmp_path: Path) -> None:
+    staged_hooks_path = _temporary_path_preserving_directory_signal(
+        tmp_path, "home/.claude/hooks/blocking/gate.py"
+    )
+    assert staged_hooks_path == (
+        tmp_path / ".claude" / "hooks" / "blocking" / "gate.py"
+    )
+
+
+def test_temporary_path_preserves_tests_directory_segment(tmp_path: Path) -> None:
+    staged_path = _temporary_path_preserving_directory_signal(
+        tmp_path, "packages/demo/tests/helper_functions.py"
+    )
+    assert staged_path == tmp_path / "tests" / "helper_functions.py"
+
+
+def test_temporary_path_preserves_substring_test_helpers_directory(
+    tmp_path: Path,
+) -> None:
+    staged_path = _temporary_path_preserving_directory_signal(
+        tmp_path, "packages/demo/test_helpers/worker.py"
+    )
+    assert staged_path == tmp_path / "test_helpers" / "worker.py"
+
+
+def test_temporary_path_preserves_absolute_project_test_helpers_directory(
+    tmp_path: Path,
+) -> None:
+    absolute_helpers_path = "C:/workspace/pkg/test_helpers/worker.py"
+    staged_path = _temporary_path_preserving_directory_signal(
+        tmp_path, absolute_helpers_path
+    )
+    assert staged_path == tmp_path / "test_helpers" / "worker.py"
+
+
+def test_absolute_system_temp_pytest_shaped_path_stages_flat_basename(
+    tmp_path: Path,
+) -> None:
+    pytest_shaped_target = (
+        tmp_path / "test_edit_introducing_new_viol0" / "legacy_module.py"
+    )
+    staging_root = tmp_path / "staging_root"
+    staging_root.mkdir()
+    staged_path = _temporary_path_preserving_directory_signal(
+        staging_root, str(pytest_shaped_target)
+    )
+    assert staged_path == staging_root / "legacy_module.py"
+
+
+def test_runner_temp_pytest_shaped_path_stages_flat_basename_when_gettempdir_differs(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """GHA basetemp lives under RUNNER_TEMP while gettempdir is often /tmp."""
+    runner_temp_root = tmp_path / "runner_temp"
+    os_gettemp = tmp_path / "os_gettemp"
+    runner_temp_root.mkdir()
+    os_gettemp.mkdir()
+    monkeypatch.setenv("RUNNER_TEMP", str(runner_temp_root))
+    monkeypatch.setattr(
+        "validators.run_all_validators.tempfile.gettempdir",
+        lambda: str(os_gettemp),
+    )
+    pytest_shaped_target = (
+        runner_temp_root
+        / "pytest-basetemp-pkg"
+        / "test_edit_introducing_new_viol0"
+        / "legacy_module.py"
+    )
+    staging_root = tmp_path / "staging_root"
+    staging_root.mkdir()
+    staged_path = _temporary_path_preserving_directory_signal(
+        staging_root, str(pytest_shaped_target)
+    )
+    assert staged_path == staging_root / "legacy_module.py"
+
+
+def test_substring_patterns_from_path_patterns_skips_directory_tokens() -> None:
+    all_substring_patterns = substring_patterns_from_path_patterns(
+        {"test_", "/tests/", "conftest", "\\tests\\"}
+    )
+    assert all_substring_patterns == frozenset({"test_", "conftest"})
+
+
+def test_directory_exemption_substring_patterns_are_non_empty_and_separator_free() -> None:
+    assert ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS
+    for each_pattern in ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS:
+        assert "/" not in each_pattern
+        assert "\\" not in each_pattern
+
+
+def test_directory_exemption_substring_patterns_include_test_fragments() -> None:
+    assert "test_" in ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS
+    assert "_test." in ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS
+    assert ".spec." in ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS
+    assert "conftest" in ALL_DIRECTORY_EXEMPTION_SUBSTRING_PATTERNS