claude-dev-env 2.30.1 → 2.31.0

package/hooks/validators/fast_save_validators.py

@@ -0,0 +1,332 @@
+"""In-process, Mypy-free validator roster for the Write/Edit save-path gate.
+
+``run_all_validators.py``'s PreToolUse gate calls ``run_fast_save_validators``
+in place of the CLI/full mode's per-check subprocess and its Mypy pass.
+
+::
+
+    save path (this module):    12 checks, in-process, no Mypy, no subprocess
+    CLI / full mode (run_all_validators.main): the same 12 checks, plus Mypy
+        and Ruff, each still its own subprocess -- unchanged by this module
+
+Every check here calls the exact same ``validate_file`` (or check) function
+the CLI mode calls. A save-path finding matches the CLI mode's finding for
+the same validator; only Mypy and the process-per-check overhead are gone.
+"""
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from hooks_constants.mypy_integration_constants import PYTHON_SOURCE_SUFFIX
+
+from .abbreviation_checks import validate_file as validate_abbreviation_file
+from .code_quality_checks import validate_file as validate_code_quality_file
+from .config.fast_save_validator_constants import (
+    ALL_CODE_REFERENCE_FILE_SUFFIXES,
+    ALL_REACT_COMPONENT_FILE_SUFFIXES,
+    NO_CODE_REFERENCE_FILES_MESSAGE,
+    NO_PYTHON_FILES_MESSAGE,
+    NO_REACT_FILES_MESSAGE,
+    NO_TEST_FILES_MESSAGE,
+    NO_VIOLATIONS_FOUND_MESSAGE,
+    VIOLATION_REPORT_LINE_SEPARATOR,
+)
+from .magic_value_checks import validate_file as validate_magic_literal_file
+from .pr_reference_checks import validate_file as validate_pr_reference_file
+from .python_antipattern_checks import validate_file as validate_python_antipattern_file
+from .python_style_checks import validate_file as validate_python_style_file
+from .react_checks import check_no_class_components
+from .security_checks import validate_file as validate_security_file
+from .test_safety_checks import (
+    check_debug_guard_in_dev_scripts,
+    check_no_skip_decorators,
+)
+from .todo_checks import validate_file as validate_todo_file
+from .type_safety_checks import validate_file as validate_type_safety_file
+from .useless_test_checks import validate_file as validate_useless_test_file
+
+FilePredicate = Callable[[Path], bool]
+FileViolationLineCollector = Callable[[Path], "list[str]"]
+_RawFileValidator = Callable[[Path], "Sequence[object]"]
+
+
+def _violation_lines_from(raw_validate_file: _RawFileValidator) -> FileViolationLineCollector:
+    """Wrap a ``validate_file`` returning check-specific Violation objects.
+
+    ::
+
+        wrap(abbreviation_checks.validate_file) -> Callable[[Path], list[str]]
+
+    Each check module defines its own ``Violation``-shaped dataclass with a
+    matching ``__str__``, so formatting through ``str()`` here needs no shared
+    base type across the four differently-typed modules that define one.
+
+    Args:
+        raw_validate_file: A module's own ``validate_file(path) -> [Violation, ...]``.
+
+    Returns:
+        A collector returning each violation's ``str()`` line, not the
+        object itself.
+    """
+
+    def _collect(file_path: Path) -> list[str]:
+        return [str(each_violation) for each_violation in raw_validate_file(file_path)]
+
+    return _collect
+
+
+@dataclass(frozen=True)
+class FastSaveCheckOutcome:
+    """One save-path check's finding.
+
+    The caller wraps this into its own reporting type. This module never
+    imports that type back, so no circular import exists between the two
+    modules.
+    """
+
+    display_name: str
+    checks: str
+    is_clean: bool
+    violation_report: str
+
+
+def _is_python_file(file_path: Path) -> bool:
+    return file_path.suffix == PYTHON_SOURCE_SUFFIX
+
+
+def _is_test_python_file(file_path: Path) -> bool:
+    return "test" in file_path.name.lower() and file_path.suffix == PYTHON_SOURCE_SUFFIX
+
+
+def _is_react_file(file_path: Path) -> bool:
+    return file_path.suffix in ALL_REACT_COMPONENT_FILE_SUFFIXES
+
+
+def _is_code_reference_file(file_path: Path) -> bool:
+    return file_path.suffix in ALL_CODE_REFERENCE_FILE_SUFFIXES
+
+
+def _collect_test_safety_violation_lines(file_path: Path) -> "list[str]":
+    """Adapt test_safety_checks's whole-batch ``main`` into one file at a time."""
+    try:
+        code = file_path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    filepath = str(file_path)
+    all_violations = [
+        *check_no_skip_decorators(code, filepath),
+        *check_debug_guard_in_dev_scripts(code, filepath),
+    ]
+    return [str(each_violation) for each_violation in all_violations]
+
+
+def _collect_react_violation_lines(file_path: Path) -> "list[str]":
+    """Adapt react_checks's whole-batch ``check_no_class_components`` to one file.
+
+    react_checks.Violation carries no ``__str__`` override, so this formats
+    each violation the same way react_checks's own ``main`` prints one.
+    """
+    all_violations = check_no_class_components([str(file_path)])
+    return [
+        f"{each_violation.file}:{each_violation.line}: {each_violation.message}"
+        for each_violation in all_violations
+    ]
+
+
+@dataclass(frozen=True)
+class _FastSaveValidatorSpecification:
+    """One save-path validator: display name, check numbers, and how to run it."""
+
+    display_name: str
+    checks: str
+    applies_to_file: FilePredicate
+    collect_violation_lines: FileViolationLineCollector
+    no_matching_files_message: str
+
+
+def _python_naming_and_syntax_specifications() -> (
+    "list[_FastSaveValidatorSpecification]"
+):
+    """Return the save-path checks for Python naming, style, and constants."""
+    return [
+        _FastSaveValidatorSpecification(
+            "Python Style",
+            "1,2,3,4",
+            _is_python_file,
+            _violation_lines_from(validate_python_style_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "Abbreviations",
+            "5",
+            _is_python_file,
+            _violation_lines_from(validate_abbreviation_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "Magic Values",
+            "7",
+            _is_python_file,
+            _violation_lines_from(validate_magic_literal_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+    ]
+
+
+def _python_quality_and_tracking_specifications() -> (
+    "list[_FastSaveValidatorSpecification]"
+):
+    """Return the save-path checks for Python code quality and TODO tracking."""
+    return [
+        _FastSaveValidatorSpecification(
+            "TODO Tracking",
+            "36",
+            _is_python_file,
+            _violation_lines_from(validate_todo_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "Security",
+            "27,28,29",
+            _is_python_file,
+            _violation_lines_from(validate_security_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "Code Quality",
+            "30,31,32",
+            _is_python_file,
+            _violation_lines_from(validate_code_quality_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+    ]
+
+
+def _python_safety_and_typing_specifications() -> (
+    "list[_FastSaveValidatorSpecification]"
+):
+    """Return the save-path checks for Python anti-patterns and typing."""
+    return [
+        _FastSaveValidatorSpecification(
+            "Python Anti-patterns",
+            "33,34,35",
+            _is_python_file,
+            _violation_lines_from(validate_python_antipattern_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "Type Safety",
+            "39,40",
+            _is_python_file,
+            _violation_lines_from(validate_type_safety_file),
+            NO_PYTHON_FILES_MESSAGE,
+        ),
+    ]
+
+
+def _test_scoped_fast_save_specifications() -> "list[_FastSaveValidatorSpecification]":
+    """Return the save-path checks scoped to a ``test_*.py``-shaped file."""
+    return [
+        _FastSaveValidatorSpecification(
+            "Test Safety",
+            "11,21",
+            _is_test_python_file,
+            _collect_test_safety_violation_lines,
+            NO_TEST_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "Useless Tests",
+            "12",
+            _is_test_python_file,
+            _violation_lines_from(validate_useless_test_file),
+            NO_TEST_FILES_MESSAGE,
+        ),
+    ]
+
+
+def _cross_language_fast_save_specifications() -> (
+    "list[_FastSaveValidatorSpecification]"
+):
+    """Return the save-path checks that read a non-Python or multi-language file."""
+    return [
+        _FastSaveValidatorSpecification(
+            "React",
+            "17",
+            _is_react_file,
+            _collect_react_violation_lines,
+            NO_REACT_FILES_MESSAGE,
+        ),
+        _FastSaveValidatorSpecification(
+            "PR References",
+            "6",
+            _is_code_reference_file,
+            _violation_lines_from(validate_pr_reference_file),
+            NO_CODE_REFERENCE_FILES_MESSAGE,
+        ),
+    ]
+
+
+def _all_fast_save_validator_specifications() -> (
+    "list[_FastSaveValidatorSpecification]"
+):
+    """Return the save-path roster: every non-Mypy, non-Ruff file-scoped check."""
+    return [
+        *_python_naming_and_syntax_specifications(),
+        *_python_quality_and_tracking_specifications(),
+        *_python_safety_and_typing_specifications(),
+        *_test_scoped_fast_save_specifications(),
+        *_cross_language_fast_save_specifications(),
+    ]
+
+
+def _fast_save_outcome(
+    specification: _FastSaveValidatorSpecification,
+    is_clean: bool,
+    violation_report: str,
+) -> FastSaveCheckOutcome:
+    """Build one outcome from a specification's display name and check numbers."""
+    return FastSaveCheckOutcome(
+        display_name=specification.display_name,
+        checks=specification.checks,
+        is_clean=is_clean,
+        violation_report=violation_report,
+    )
+
+
+def _run_specification(
+    specification: _FastSaveValidatorSpecification, files: "list[Path]"
+) -> FastSaveCheckOutcome:
+    """Run one validator's violation collector in-process over its matching files."""
+    matching_files = [
+        each_file for each_file in files if specification.applies_to_file(each_file)
+    ]
+    if not matching_files:
+        return _fast_save_outcome(
+            specification, True, specification.no_matching_files_message
+        )
+    all_violation_lines = [
+        each_line
+        for each_file in matching_files
+        for each_line in specification.collect_violation_lines(each_file)
+    ]
+    if not all_violation_lines:
+        return _fast_save_outcome(specification, True, NO_VIOLATIONS_FOUND_MESSAGE)
+    violation_report = VIOLATION_REPORT_LINE_SEPARATOR.join(all_violation_lines)
+    return _fast_save_outcome(specification, False, violation_report)
+
+
+def run_fast_save_validators(files: "list[Path]") -> "list[FastSaveCheckOutcome]":
+    """Run every save-path validator in-process, skipping Mypy and Ruff.
+
+    Args:
+        files: The files under validation -- one reconstructed file in gate mode.
+
+    Returns:
+        One outcome per in-process validator, in roster order. The caller adds
+        Ruff and never adds Mypy.
+    """
+    return [
+        _run_specification(each_specification, files)
+        for each_specification in _all_fast_save_validator_specifications()
+    ]

package/hooks/validators/hook_timing_harness.py

@@ -13,10 +13,14 @@ count, and reported as p50 and p95 milliseconds.
     post_tool_use_dispatcher   p50=80.1ms    p95=1200.5ms
     session_file_edit_tracker  p50=31.0ms    p95=34.2ms
 
-A target under the OS temp root would return before any validator ran, so this
-harness refuses one. It always runs the whole command line ``hooks.json``
-registers, never a single hosted check module standing in for it, so neither
-shortcut can distort the numbers.
+This harness refuses a target under the OS temp root, and runs the whole
+command line ``hooks.json`` registers.
+
+The payload names the Write tool and carries the target's own current content.
+``code_rules_enforcer`` takes its early return for a write over an existing
+file, so the ``pre_tool_use_dispatcher`` figure covers interpreter start and
+hook dispatch. Time an Edit payload against a real file to measure the
+CODE_RULES checks themselves.
 
 The timed payload carries no ``session_id``, so ``session_file_edit_tracker``
 writes its edit record to the default-session file rather than to a

package/hooks/validators/python_style_checks.py

@@ -14,42 +14,27 @@ from dataclasses import dataclass
 from pathlib import Path
 
 _hooks_directory = str(Path(__file__).resolve().parent.parent)
-
-try:
-    from hooks_constants.python_style_checks_constants import (
-        EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS,
-        MINIMUM_ARGUMENT_COUNT,
-    )
-except ModuleNotFoundError:
-    if _hooks_directory not in sys.path:
-        sys.path.insert(0, _hooks_directory)
-    from hooks_constants.python_style_checks_constants import (
-        EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS,
-        MINIMUM_ARGUMENT_COUNT,
-    )
-
-try:
-    from validators.python_style_helpers import (
-        FunctionNode,
-        blank_line_for_source,
-        function_start_line,
-        gap_is_blank_only,
-        iter_function_definitions,
-        real_newline_lines,
-        top_level_functions,
-    )
-except ModuleNotFoundError:
-    if _hooks_directory not in sys.path:
-        sys.path.insert(0, _hooks_directory)
-    from validators.python_style_helpers import (
-        FunctionNode,
-        blank_line_for_source,
-        function_start_line,
-        gap_is_blank_only,
-        iter_function_definitions,
-        real_newline_lines,
-        top_level_functions,
-    )
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.python_style_checks_constants import (  # noqa: E402
+    EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS,
+    MINIMUM_ARGUMENT_COUNT,
+)
+from validators.python_style_helpers import (  # noqa: E402
+    FunctionNode,
+    blank_line_for_source,
+    function_start_line,
+    gap_is_blank_only,
+    is_docstring_statement,
+    is_import_statement,
+    iter_function_definitions,
+    real_newline_lines,
+    top_level_functions,
+)
+from validators.python_style_import_bootstrap import (  # noqa: E402
+    is_sys_path_bootstrap_prelude,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -83,37 +68,26 @@ def check_imports_at_top(tree: ast.AST, filename: str) -> list[Violation]:
     return violations
 
 
-def _is_import_statement(statement: ast.stmt) -> bool:
-    """Return True when the statement is an import or from-import."""
-    return isinstance(statement, (ast.Import, ast.ImportFrom))
-
-
-def _is_docstring_statement(statement: ast.stmt) -> bool:
-    """Return True when the statement is a string-literal docstring."""
-    if not isinstance(statement, ast.Expr):
-        return False
-    literal = statement.value
-    return isinstance(literal, ast.Constant) and isinstance(literal.value, str)
-
-
 def _check_module_level_import_order(tree: ast.AST, filename: str) -> list[Violation]:
-    """Flag module-level imports that appear after other statements."""
+    """Flag module-level imports after other statements, exempting a sys.path bootstrap run."""
     if not isinstance(tree, ast.Module):
         return []
     violations: list[Violation] = []
     has_seen_non_import = False
+    pending_prelude_statements: list[ast.stmt] = []
     for each_statement in tree.body:
-        is_import = _is_import_statement(each_statement)
-        if is_import and has_seen_non_import:
-            violations.append(
-                Violation(
-                    filename,
-                    each_statement.lineno,
-                    "Import statement must be at top of file",
-                )
-            )
-        if not is_import and not _is_docstring_statement(each_statement):
+        if not is_import_statement(each_statement):
+            if not is_docstring_statement(each_statement):
+                pending_prelude_statements.append(each_statement)
+            continue
+        if pending_prelude_statements and not is_sys_path_bootstrap_prelude(
+            pending_prelude_statements
+        ):
             has_seen_non_import = True
+        pending_prelude_statements = []
+        if has_seen_non_import:
+            message = "Import statement must be at top of file"
+            violations.append(Violation(filename, each_statement.lineno, message))
     return violations
 
 

package/hooks/validators/python_style_helpers.py

@@ -1,8 +1,9 @@
 """Shared source-line and function-discovery helpers for the style checks.
 
 These pure helpers underlie the style checks and the blank-line fixers:
-splitting source into ast-aligned lines, locating function definitions, and
-matching the source newline convention.
+splitting source into ast-aligned lines, locating function definitions,
+classifying a module-level statement, and matching the source newline
+convention.
 """
 
 import ast
@@ -93,3 +94,16 @@ def real_newline_lines(source: str) -> list[str]:
     if line_start < total_length:
         lines.append(source[line_start:])
     return lines
+
+
+def is_import_statement(statement: ast.stmt) -> bool:
+    """Return True when the statement is an import or from-import."""
+    return isinstance(statement, (ast.Import, ast.ImportFrom))
+
+
+def is_docstring_statement(statement: ast.stmt) -> bool:
+    """Return True when the statement is a string-literal docstring."""
+    if not isinstance(statement, ast.Expr):
+        return False
+    literal = statement.value
+    return isinstance(literal, ast.Constant) and isinstance(literal.value, str)

package/hooks/validators/python_style_import_bootstrap.py

@@ -0,0 +1,83 @@
+"""Recognizer for the repo's sys.path bootstrap-guard idiom.
+
+Split out of python_style_checks.py to keep that file under its line cap.
+Tells the import-order check whether a run of module-level statements is that
+idiom rather than ordinary code: `check_sys_path_insert_deduplication_guard`
+(code_rules_paths_syspath.py) requires every `sys.path.insert` call to sit
+behind `if <path> not in sys.path:`, and the import-order check must not
+penalize a file for following that guard.
+"""
+
+import ast
+
+
+def _is_sys_path_insert_expression(expression: ast.expr) -> bool:
+    """Return True for a `sys.path.insert(...)` call expression."""
+    if not isinstance(expression, ast.Call):
+        return False
+    function_reference = expression.func
+    if not isinstance(function_reference, ast.Attribute) or function_reference.attr != "insert":
+        return False
+    receiver = function_reference.value
+    if not isinstance(receiver, ast.Attribute) or receiver.attr != "path":
+        return False
+    receiver_value = receiver.value
+    return isinstance(receiver_value, ast.Name) and receiver_value.id == "sys"
+
+
+def _is_sys_path_bootstrap_guard(statement: ast.stmt) -> bool:
+    """Return True for `if <expr> not in sys.path: sys.path.insert(...)`.
+
+    Only the then-branch is inspected, matching the scope
+    `check_sys_path_insert_deduplication_guard` itself checks.
+    """
+    if not isinstance(statement, ast.If):
+        return False
+    membership_test = statement.test
+    if not isinstance(membership_test, ast.Compare) or len(membership_test.ops) != 1:
+        return False
+    if not isinstance(membership_test.ops[0], ast.NotIn):
+        return False
+    membership_target = membership_test.comparators[0]
+    if not isinstance(membership_target, ast.Attribute) or membership_target.attr != "path":
+        return False
+    if not isinstance(membership_target.value, ast.Name) or membership_target.value.id != "sys":
+        return False
+    return any(
+        isinstance(each_body_statement, ast.Expr)
+        and _is_sys_path_insert_expression(each_body_statement.value)
+        for each_body_statement in statement.body
+    )
+
+
+def _is_plain_assignment_statement(statement: ast.stmt) -> bool:
+    """Return True for a single-target module-level `name = value` assignment."""
+    return (
+        isinstance(statement, ast.Assign)
+        and len(statement.targets) == 1
+        and isinstance(statement.targets[0], ast.Name)
+    )
+
+
+def is_sys_path_bootstrap_prelude(all_pending_statements: list[ast.stmt]) -> bool:
+    """Return True when *all_pending_statements* form the repo's sys.path bootstrap idiom.
+
+    Writing the mandated dedup guard takes a preceding `<path> = ...`
+    assignment and the guarded `if` itself — both ordinary, non-import
+    statements that would otherwise read as ordinary code to an import-order
+    check and flag every import that follows.
+
+    A run of statements between two import blocks is accepted as this
+    bootstrap prelude, rather than as ordinary code, when it contains at
+    least one real guard and every other statement in the same run is a
+    plain assignment — the shape a `path = ...` line or an unrelated
+    same-block constant both take. A bare `sys.path.insert` with no guard,
+    or any def/class/call statement, is not part of this shape and still
+    counts as ordinary code.
+    """
+    if not any(_is_sys_path_bootstrap_guard(each) for each in all_pending_statements):
+        return False
+    return all(
+        _is_sys_path_bootstrap_guard(each) or _is_plain_assignment_statement(each)
+        for each in all_pending_statements
+    )