claude-dev-env 2.31.0 → 2.32.0

package/hooks/observability/test_failure_recorder.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: record a failing single pytest run as TDD-gate evidence.
+
+A file-content edit is not the same claim as a test that ran and failed. The
+content-hash store in ``tdd_enforcer_parts/content_hash_store.py`` already
+tracks whether a candidate test file's content changed; this hook adds a
+stronger form of evidence -- a real RED -- by watching every Bash call finish
+and, for a genuine failing pytest run, recording the command, its real exit
+status, and the test file paths it named into that same store.
+
+::
+
+    pytest test_orders.py                    (exit 1)  -> record test_orders.py
+    pytest test_orders.py -k fulfill          (exit 1)  -> record test_orders.py
+    pytest test_orders.py::test_fulfill       (exit 1)  -> record test_orders.py
+    pytest -q                                 (exit 1)  -> no path named, no record
+    cd repo && pytest test_orders.py          (exit 1)  -> chained, no record
+    pytest test_orders.py | tee run.log       (blocked by piped_pytest_blocker
+                                                first -- this hook never sees it)
+    npm test                                  (exit 1)  -> not pytest, no record
+    pytest test_orders.py                     (exit 0)  -> passed, no record
+
+What this hook matches, and why
+--------------------------------
+
+Only a single, unchained Bash command whose own program is ``pytest`` /
+``py.test``, or a Python interpreter running ``-m pytest``. A chained command
+(``&&``, ``;``, ``|``, ``||``, a newline) is rejected outright: this repo's own
+``piped_pytest_blocker.py`` already tells the caller to "run pytest alone" for
+exactly this reason, and a chain's reported exit status may belong to a
+command other than pytest, or to none of them if an earlier link short-
+circuited before pytest even ran. ``npm test``, ``node --test``, and
+``vitest`` are deliberately not matched: ``npm test`` is a script indirection
+whose real test runner lives in ``package.json``, not on the command line,
+and the other two have no existing, tested classification helper in this
+repository the way pytest does. Extending to them would mean inventing new
+parsing rather than reusing anything proven, which is the over-reach this
+mechanism is built to avoid.
+
+The recognizer here is deliberately its own small, stdlib-only ``shlex``
+check rather than a reuse of ``hooks_constants.pytest_invocation`` /
+``shell_command_pipeline``. Those solve the harder pipe-and-wrapper problem a
+PreToolUse blocker needs, and this repository's own style rule forbids an
+import inside a function body, so importing that larger machinery here would
+mean paying its full transitive import cost on every single Bash call this
+hook sees, pytest or not -- working directly against the point of watching
+every Bash call. The narrower, single-unchained-command scope this hook
+accepts does not need that machinery.
+
+Where the exit status comes from
+---------------------------------
+
+Not from scraping the command's output text for words like "failed" or
+"error". The Bash tool's own PostToolUse ``tool_response`` takes two shapes
+observed directly in this session's own transcript: a dict with ``stdout``/
+``stderr`` keys when the command's reported exit status is 0, and the literal
+string ``"Error: Exit code <N>\\n<output>"`` when it is not. This hook reads
+that harness-authored ``<N>`` directly; it is a real Bash mechanism doing the
+work correctly, not a lookalike that only mimics one.
+
+Where the test paths come from
+--------------------------------
+
+The command's own arguments, not its output. A bare ``pytest`` or ``pytest
+-q`` names no path and is left unrecorded on purpose: recording it against
+every test file pytest might have discovered would satisfy the gate for a
+file this run never demonstrably covered, which is the exact bypass the
+audit calls out. Only a token that is not an option flag and resolves to a
+real file on disk, relative to the command's own ``cwd``, counts.
+
+What stops a bypass
+---------------------
+
+Three things, together:
+
+1. ``content_hash_store.record_test_command_failure`` keys each entry
+   exactly as the gate looks candidates up, so a failure never satisfies a
+   sibling file the same command also happened to run (see
+   ``test_content_hash_store.py::test_recorded_failure_does_not_satisfy_a_different_candidate``).
+2. The gate consults a recorded failure only while the file's *current*
+   content hash still matches what actually failed (see
+   ``test_recorded_failure_does_not_apply_once_content_no_longer_matches``).
+   Editing the test again clears it as evidence.
+3. A record ages out after the same freshness window every other form of
+   evidence uses (see ``test_recorded_failure_expires_after_the_freshness_window``).
+
+The hook never blocks a tool call. A non-Bash tool, a malformed payload, a
+command that does not mention "pytest", a chained command, a command with no
+real path argument, or a failed record each returns quietly.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from pathlib import Path
+
+try:
+    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+    _blocking_directory = str(Path(_hooks_root_directory) / "blocking")
+    for each_bootstrap_directory in (_hooks_root_directory, _blocking_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+    from hooks_constants.gh_pr_author_swap_constants import BASH_TOOL_NAME
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.test_failure_recorder_constants import (
+        ALL_CHAINING_OPERATOR_SUBSTRINGS,
+        ALL_PYTEST_MENTION_SUBSTRINGS,
+        ALL_PYTEST_PROGRAM_BASENAMES,
+        ALL_REDIRECTION_TOKENS,
+        EXIT_CODE_ERROR_PREFIX,
+        MODULE_RUN_FLAG,
+        NODE_ID_FILE_PATH_SEPARATOR,
+        OPTION_TOKEN_PREFIX,
+        PYTEST_MODULE_NAME,
+        PYTHON_INTERPRETER_BASENAME_PATTERN,
+    )
+    from tdd_enforcer_parts import content_hash_store
+except ImportError as import_error:
+    raise ImportError(
+        "test_failure_recorder: cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _mentions_pytest(command: str) -> bool:
+    lowered_command = command.lower()
+    return any(
+        each_substring in lowered_command for each_substring in ALL_PYTEST_MENTION_SUBSTRINGS
+    )
+
+
+def _harness_reported_exit_status(tool_response: object) -> int | None:
+    if not isinstance(tool_response, str) or not tool_response.startswith(EXIT_CODE_ERROR_PREFIX):
+        return None
+    remainder = tool_response[len(EXIT_CODE_ERROR_PREFIX) :]
+    digit_count = 0
+    while digit_count < len(remainder) and remainder[digit_count].isdigit():
+        digit_count += 1
+    return int(remainder[:digit_count]) if digit_count else None
+
+
+def _is_single_unchained_command(command: str) -> bool:
+    return not any(each_operator in command for each_operator in ALL_CHAINING_OPERATOR_SUBSTRINGS)
+
+
+def _runs_pytest_via_module_flag(all_tokens: list[str]) -> bool:
+    if MODULE_RUN_FLAG not in all_tokens:
+        return False
+    flag_index = all_tokens.index(MODULE_RUN_FLAG)
+    return flag_index + 1 < len(all_tokens) and all_tokens[flag_index + 1] == PYTEST_MODULE_NAME
+
+
+def _command_tokens_run_pytest(all_tokens: list[str]) -> bool:
+    if not all_tokens:
+        return False
+    first_basename = Path(all_tokens[0]).name
+    if first_basename in ALL_PYTEST_PROGRAM_BASENAMES:
+        return True
+    if not PYTHON_INTERPRETER_BASENAME_PATTERN.match(first_basename):
+        return False
+    return _runs_pytest_via_module_flag(all_tokens)
+
+
+def _existing_test_file_paths(all_tokens: list[str], cwd: str) -> list[Path]:
+    all_paths: list[Path] = []
+    for each_token in all_tokens:
+        if each_token.startswith(OPTION_TOKEN_PREFIX) or each_token in ALL_REDIRECTION_TOKENS:
+            continue
+        file_path_text = each_token.split(NODE_ID_FILE_PATH_SEPARATOR, 1)[0]
+        candidate_path = Path(cwd, file_path_text) if cwd else Path(file_path_text)
+        if candidate_path.is_file():
+            all_paths.append(candidate_path)
+    return all_paths
+
+
+def _command_tokens(command: str) -> list[str]:
+    try:
+        return shlex.split(command)
+    except ValueError:
+        return []
+
+
+def _record_pytest_failure(hook_payload: dict, command: str) -> None:
+    exit_status = _harness_reported_exit_status(hook_payload.get("tool_response"))
+    if exit_status is None or not _is_single_unchained_command(command):
+        return
+    all_tokens = _command_tokens(command)
+    if not _command_tokens_run_pytest(all_tokens):
+        return
+    cwd = str(hook_payload.get("cwd") or "")
+    all_test_file_paths = _existing_test_file_paths(all_tokens, cwd)
+    if not all_test_file_paths:
+        return
+    session_id = str(hook_payload.get("session_id") or "")
+    content_hash_store.record_test_command_failure(
+        all_test_file_paths, command, exit_status, session_id, cwd
+    )
+
+
+def main() -> None:
+    """Record one failing pytest run's evidence from a PostToolUse Bash payload.
+
+    Reads the payload from stdin. Returns quietly on every branch that is not
+    a genuine, single, unchained, path-naming pytest failure, so a logging
+    problem never surfaces as a blocked or altered tool call.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None or hook_payload.get("tool_name") != BASH_TOOL_NAME:
+        return
+    tool_input = hook_payload.get("tool_input")
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if not isinstance(command, str) or not _mentions_pytest(command):
+        return
+    _record_pytest_failure(hook_payload, command)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/observability/test_pr_description_writer_spawn_tracker.py

@@ -26,6 +26,10 @@ assert _TRACKER_SPEC.loader is not None
 tracker_module = importlib.util.module_from_spec(_TRACKER_SPEC)
 _TRACKER_SPEC.loader.exec_module(tracker_module)
 
+_GATE_CONSTANTS = importlib.import_module(
+    "hooks_constants.pr_description_writer_gate_constants"
+)
+
 _SESSION_ID = "session-abc123"
 _OTHER_SUBAGENT_TYPE = "general-purpose"
 
@@ -65,7 +69,7 @@ def _run_tracker(payload: dict[str, object], temp_directory: Path) -> None:
     """
     with mock.patch("sys.stdin", io.StringIO(json.dumps(payload))):
         with mock.patch.object(
-            tracker_module.tempfile, "gettempdir", return_value=str(temp_directory)
+            _GATE_CONSTANTS.tempfile, "gettempdir", return_value=str(temp_directory)
         ):
             tracker_module.main()
 
@@ -120,7 +124,7 @@ def should_record_twice_without_error(tmp_path: Path) -> None:
 def should_ignore_a_malformed_payload(tmp_path: Path) -> None:
     """Unparseable stdin records nothing and raises nothing."""
     with mock.patch("sys.stdin", io.StringIO("this is not json")):
-        with mock.patch.object(tracker_module.tempfile, "gettempdir", return_value=str(tmp_path)):
+        with mock.patch.object(_GATE_CONSTANTS.tempfile, "gettempdir", return_value=str(tmp_path)):
             tracker_module.main()
     assert list(tmp_path.iterdir()) == []
 

package/hooks/observability/test_test_failure_recorder.py

@@ -0,0 +1,173 @@
+"""Behavior tests for the test_failure_recorder PostToolUse hook.
+
+Drives the hook's main through real stdin payloads shaped like a genuine
+Bash PostToolUse call, then reads the shared content-hash store back to
+confirm what -- if anything -- it recorded. The store's real state file
+under the OS temp directory is read directly, the same way
+test_content_hash_store.py and test_tdd_enforcer.py already do, rather than
+mocking tempfile.gettempdir. ``hooks/conftest.py`` already puts the hooks
+and blocking directories on sys.path for test collection, so this file needs
+no bootstrap of its own before importing content_hash_store.
+"""
+
+import contextlib
+import importlib.util
+import io
+import json
+from pathlib import Path
+from unittest import mock
+
+from tdd_enforcer_parts import content_hash_store
+
+_HOOK_DIRECTORY = Path(__file__).parent
+_hook_spec = importlib.util.spec_from_file_location(
+    "test_failure_recorder_under_test", _HOOK_DIRECTORY / "test_failure_recorder.py"
+)
+assert _hook_spec is not None
+assert _hook_spec.loader is not None
+_hook_module = importlib.util.module_from_spec(_hook_spec)
+_hook_spec.loader.exec_module(_hook_module)
+
+
+def _run_hook_with_payload(payload: dict) -> None:
+    with (
+        mock.patch("sys.stdin", io.StringIO(json.dumps(payload))),
+        contextlib.suppress(SystemExit),
+    ):
+        _hook_module.main()
+
+
+def _recorded_failure_entry(test_file: Path, session_id: str, repository_root: str) -> dict | None:
+    state_file = content_hash_store._state_file_path(session_id, repository_root)
+    if not state_file.exists():
+        return None
+    state = json.loads(state_file.read_text())
+    return state.get(content_hash_store._state_key_for(test_file))
+
+
+def _bash_payload(command: str, tool_response: object, cwd: Path, session_id: str) -> dict:
+    return {
+        "session_id": session_id,
+        "cwd": str(cwd),
+        "tool_name": "Bash",
+        "tool_input": {"command": command},
+        "tool_response": tool_response,
+    }
+
+
+_FAILING_OUTPUT = (
+    "Error: Exit code 1\n"
+    "F                                                                    [100%]\n"
+    "=================================== FAILURES ===================================\n"
+    "FAILED test_orders.py::test_fulfill - AssertionError\n"
+    "1 failed in 0.02s"
+)
+_PASSING_OUTPUT = {"stdout": "1 passed in 0.02s", "stderr": "", "interrupted": False}
+
+
+def test_records_a_failure_for_a_bare_pytest_command_naming_a_real_file(
+    tmp_path: Path,
+) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): assert False\n")
+    session_id = "recorder-session-1"
+
+    _run_hook_with_payload(
+        _bash_payload("pytest test_orders.py", _FAILING_OUTPUT, tmp_path, session_id)
+    )
+
+    entry = _recorded_failure_entry(test_file, session_id, str(tmp_path))
+    assert entry is not None
+    assert entry[content_hash_store.STORED_FAILURE_EXIT_STATUS_KEY] == 1
+    assert entry[content_hash_store.STORED_FAILURE_COMMAND_KEY] == "pytest test_orders.py"
+
+
+def test_does_not_record_for_a_passing_command(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): pass\n")
+    session_id = "recorder-session-2"
+
+    _run_hook_with_payload(
+        _bash_payload("pytest test_orders.py", _PASSING_OUTPUT, tmp_path, session_id)
+    )
+
+    assert _recorded_failure_entry(test_file, session_id, str(tmp_path)) is None
+
+
+def test_does_not_record_for_a_non_pytest_command(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): assert False\n")
+    session_id = "recorder-session-3"
+
+    _run_hook_with_payload(
+        _bash_payload("npm test", "Error: Exit code 1\n1 failing", tmp_path, session_id)
+    )
+
+    assert _recorded_failure_entry(test_file, session_id, str(tmp_path)) is None
+
+
+def test_does_not_record_for_a_chained_command(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): assert False\n")
+    session_id = "recorder-session-4"
+
+    _run_hook_with_payload(
+        _bash_payload("cd /repo && pytest test_orders.py", _FAILING_OUTPUT, tmp_path, session_id)
+    )
+
+    assert _recorded_failure_entry(test_file, session_id, str(tmp_path)) is None
+
+
+def test_does_not_record_for_a_bare_pytest_run_with_no_path_argument(
+    tmp_path: Path,
+) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): assert False\n")
+    session_id = "recorder-session-5"
+
+    _run_hook_with_payload(_bash_payload("pytest -q", _FAILING_OUTPUT, tmp_path, session_id))
+
+    assert _recorded_failure_entry(test_file, session_id, str(tmp_path)) is None
+
+
+def test_records_only_the_named_file_not_an_option_or_expression_token(
+    tmp_path: Path,
+) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): assert False\n")
+    session_id = "recorder-session-6"
+
+    _run_hook_with_payload(
+        _bash_payload("pytest test_orders.py -k fulfill", _FAILING_OUTPUT, tmp_path, session_id)
+    )
+
+    entry = _recorded_failure_entry(test_file, session_id, str(tmp_path))
+    assert entry is not None
+    state_file = content_hash_store._state_file_path(session_id, str(tmp_path))
+    state = json.loads(state_file.read_text())
+    assert len(state) == 1
+
+
+def test_ignores_a_tool_other_than_bash(tmp_path: Path) -> None:
+    test_file = tmp_path / "test_orders.py"
+    test_file.write_text("def test_fulfill(): assert False\n")
+    session_id = "recorder-session-7"
+    payload = _bash_payload("pytest test_orders.py", _FAILING_OUTPUT, tmp_path, session_id)
+    payload["tool_name"] = "Write"
+
+    _run_hook_with_payload(payload)
+
+    assert _recorded_failure_entry(test_file, session_id, str(tmp_path)) is None
+
+
+def test_does_not_record_when_the_named_file_does_not_exist_on_disk(
+    tmp_path: Path,
+) -> None:
+    session_id = "recorder-session-8"
+    missing_file = tmp_path / "test_missing.py"
+
+    _run_hook_with_payload(
+        _bash_payload("pytest test_missing.py", _FAILING_OUTPUT, tmp_path, session_id)
+    )
+
+    assert _recorded_failure_entry(missing_file, session_id, str(tmp_path)) is None

package/hooks/validators/abbreviation_checks.py

@@ -14,7 +14,7 @@ from pathlib import Path
 from typing import List
 
 from .config.abbreviation_checks_constants import ALL_ALLOWED_SINGLE_LETTERS
-from .validator_base import Violation
+from .validator_base import Violation, source_text, syntax_tree
 
 
 def check_single_letter_variables(tree: ast.AST, filename: str) -> List[Violation]:
@@ -39,13 +39,13 @@ 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:
         violations.append(Violation(filename, 0, f"Error reading file: {error}"))
         return violations
 
     try:
-        tree = ast.parse(source)
+        tree = syntax_tree(source)
     except SyntaxError as error:
         violations.append(
             Violation(filename, error.lineno or 0, f"Syntax error: {error.msg}")

package/hooks/validators/code_quality_checks.py

@@ -11,7 +11,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
 
 
 MAX_FUNCTION_LINES = 30
@@ -75,7 +75,7 @@ def check_file_length(file_path: Path) -> List[Violation]:
     filename = str(file_path)
 
     try:
-        lines = file_path.read_text(encoding="utf-8").splitlines()
+        lines = source_text(file_path).splitlines()
     except Exception as error:
         return [Violation(filename, 0, f"Error reading file: {error}")]
 
@@ -98,8 +98,8 @@ def validate_file(file_path: Path) -> List[Violation]:
     violations.extend(check_file_length(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 violations + [Violation(filename, 0, f"Error: {error}")]
 

package/hooks/validators/config/baseline_identity_constants.py

@@ -0,0 +1,12 @@
+"""Patterns and placeholders the baseline gate masks a violation message with.
+
+Config files are exempt from the string-literal magic-value checks, so the
+regex fragments and the placeholder text the scope-agnostic message shape needs
+live here rather than inline in ``run_all_validators.py``.
+"""
+
+QUALIFIED_SCOPE_NAME_SEPARATOR = "."
+WORD_BOUNDARY_PATTERN = r"\b"
+STANDALONE_NUMBER_PATTERN = r"(?<![A-Za-z0-9_])\d+(?![A-Za-z0-9_])"
+SCOPE_NAME_PLACEHOLDER = "<name>"
+SHAPE_NUMBER_PLACEHOLDER = "<number>"

package/hooks/validators/config/directory_exemption_constants.py

@@ -7,7 +7,9 @@ siblings). Exact names come from the authoritative path-exemption pattern sets
 and CLI markers, unioned with the config-directory allowlist. Substring
 patterns come from the separator-free members of those same pattern sets so a
 directory such as ``pkg/test_helpers/`` stages with the same test exemption as
-the real path.
+the real path. Directories pytest generates for its own scratch tree are
+recognized by name and contribute no signal, whatever ``--basetemp`` they sit
+under.
 """
 
 from __future__ import annotations
@@ -27,13 +29,13 @@ from ..exempt_paths import (
 POSIX_DIRECTORY_SEPARATOR = "/"
 WINDOWS_DIRECTORY_SEPARATOR = "\\"
 
-ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
-    {
-        "TEMP",
-        "TMP",
-        "TMPDIR",
-        "RUNNER_TEMP",
-    }
+PYTEST_TEMPORARY_ROOT_NAME_PREFIX = "pytest-"
+DECIMAL_DIGIT_CHARACTERS = "0123456789"
+LOWERCASE_ASCII_LETTER_CHARACTERS = "abcdefghijklmnopqrstuvwxyz"
+UNDERSCORE_CHARACTER = "_"
+PYTEST_SANITIZED_TEST_NAME_LENGTH_LIMIT = 30
+ALL_PYTEST_SANITIZED_TEST_NAME_CHARACTERS: frozenset[str] = frozenset(
+    LOWERCASE_ASCII_LETTER_CHARACTERS + DECIMAL_DIGIT_CHARACTERS + UNDERSCORE_CHARACTER
 )
 
 ALL_AUTHORITATIVE_DIRECTORY_PATH_PATTERN_SETS: tuple[Iterable[str], ...] = (
@@ -68,6 +70,38 @@ def is_filename_like_path_segment(path_segment: str) -> bool:
     return "." in path_segment
 
 
+def is_pytest_scratch_directory_segment(segment_lower: str) -> bool:
+    """Return True when *segment_lower* is a directory pytest itself created.
+
+    ::
+
+        is_pytest_scratch_directory_segment("test_drops_leading_anchor0")  # True
+        is_pytest_scratch_directory_segment("pytest-of-root")  # True
+        is_pytest_scratch_directory_segment("test_helpers")  # False
+
+    ``TempPathFactory`` names its roots ``pytest-of-<user>`` and ``pytest-<n>``, and
+    each per-test directory as a length-capped test-name stem with a number appended.
+    Those generated names carry ``test_`` without naming a real project directory.
+
+    Args:
+        segment_lower: One lowercased directory component of a target path.
+
+    Returns:
+        True when pytest generated the segment rather than the project.
+    """
+    if segment_lower.startswith(PYTEST_TEMPORARY_ROOT_NAME_PREFIX):
+        return True
+    sanitized_test_name = segment_lower.rstrip(DECIMAL_DIGIT_CHARACTERS)
+    if not sanitized_test_name or sanitized_test_name == segment_lower:
+        return False
+    if len(sanitized_test_name) > PYTEST_SANITIZED_TEST_NAME_LENGTH_LIMIT:
+        return False
+    return all(
+        each_character in ALL_PYTEST_SANITIZED_TEST_NAME_CHARACTERS
+        for each_character in sanitized_test_name
+    )
+
+
 def all_directory_segments_in_path_pattern(path_pattern: str) -> list[str]:
     """Return lowercased directory tokens from one path-exemption pattern.
 

package/hooks/validators/config/system_temporary_roots_constants.py

@@ -0,0 +1,15 @@
+"""Constants naming where the system keeps temporary directories."""
+
+from __future__ import annotations
+
+# A run reaches its temp root through any of these, so a walk that stops at
+# that boundary checks all four rather than gettempdir() alone. RUNNER_TEMP
+# is the hosted-CI case: pytest writes there while gettempdir() stays /tmp.
+ALL_SYSTEM_TEMPORARY_ROOT_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
+    {
+        "TEMP",
+        "TMP",
+        "TMPDIR",
+        "RUNNER_TEMP",
+    }
+)

package/hooks/validators/config/validator_base_constants.py

@@ -0,0 +1,9 @@
+"""Constants for the shared source reader and parser in validator_base."""
+
+from __future__ import annotations
+
+# One save validates one file, so a handful of entries covers a run and keeps
+# a long-lived CLI pass from holding every file it ever read.
+SOURCE_CACHE_ENTRIES: int = 8
+
+SOURCE_ENCODING: str = "utf-8"