claude-dev-env 2.30.0 → 2.31.0

package/hooks/validation/test_hook_format_validator.py

@@ -41,6 +41,64 @@ def test_simple_pattern_blocks_with_deny_payload(tmp_path: Path) -> None:
     assert hook_specific_output["permissionDecision"] == "deny"
 
 
+def test_write_payload_reads_the_content_field(tmp_path: Path) -> None:
+    """_resolve_content's non-MultiEdit branch reads a Write payload's "content" key."""
+    settings_path = tmp_path / ".claude" / "settings.json"
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": str(settings_path),
+            "content": "python3 ~/.claude/hooks/blocking/my-hook.py",
+        },
+    }
+
+    hook_run = _run_hook(payload)
+
+    assert hook_run.returncode == 0
+    deny_payload = json.loads(hook_run.stdout)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_second_multi_edit_new_string_is_caught(tmp_path: Path) -> None:
+    """A simple-pattern hook command in the second edit of a MultiEdit is denied."""
+    settings_path = tmp_path / ".claude" / "settings.json"
+    payload = {
+        "tool_name": "MultiEdit",
+        "tool_input": {
+            "file_path": str(settings_path),
+            "edits": [
+                {"old_string": "a", "new_string": "b"},
+                {"old_string": "c", "new_string": "python3 ~/.claude/hooks/blocking/my-hook.py"},
+            ],
+        },
+    }
+
+    hook_run = _run_hook(payload)
+
+    assert hook_run.returncode == 0
+    deny_payload = json.loads(hook_run.stdout)
+    assert deny_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_clean_multi_edit_passes(tmp_path: Path) -> None:
+    settings_path = tmp_path / ".claude" / "settings.json"
+    payload = {
+        "tool_name": "MultiEdit",
+        "tool_input": {
+            "file_path": str(settings_path),
+            "edits": [
+                {"old_string": "a", "new_string": "b"},
+                {"old_string": "c", "new_string": "node -e \"require('run-hook-wrapper')\""},
+            ],
+        },
+    }
+
+    hook_run = _run_hook(payload)
+
+    assert hook_run.returncode == 0
+    assert hook_run.stdout.strip() == ""
+
+
 def test_block_logs_pre_tool_use_event(tmp_path: Path) -> None:
     fake_home = tmp_path / "home"
     fake_home.mkdir()

package/hooks/validators/README.md

@@ -2,7 +2,7 @@
 
 AST-based Python style checks for code quality enforcement.
 
-The checks live in `python_style_checks.py`; the shared source-line splitting and function-discovery helpers they build on live in `python_style_helpers.py`. `hook_timing_harness.py` measures real wall-clock time for the Write/Edit hooks `hooks.json` registers, reporting p50 and p95 over a configurable run count.
+The checks live in `python_style_checks.py`; the shared source-line splitting, function-discovery, and statement-classification helpers they build on live in `python_style_helpers.py`. `python_style_import_bootstrap.py` recognizes the repo's sys.path bootstrap-guard idiom so the imports-at-top check does not penalize a file for following it. `hook_timing_harness.py` measures real wall-clock time for the Write/Edit hooks `hooks.json` registers, reporting p50 and p95 over a configurable run count. `fast_save_validators.py` runs the twelve non-Mypy, non-Ruff checks in-process for the Write/Edit save-path gate, with no per-check subprocess.
 
 ## Checks Implemented
 

package/hooks/validators/abbreviation_checks.py

@@ -11,20 +11,18 @@ Detects:
 import ast
 import sys
 from pathlib import Path
-from typing import List, Set
+from typing import List
 
+from .config.abbreviation_checks_constants import ALL_ALLOWED_SINGLE_LETTERS
 from .validator_base import Violation
 
 
-ALLOWED_SINGLE_LETTERS: Set[str] = frozenset({"i", "j", "k", "_"})
-
-
 def check_single_letter_variables(tree: ast.AST, filename: str) -> List[Violation]:
     violations: List[Violation] = []
 
     for node in ast.walk(tree):
         if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
-            if len(node.id) == 1 and node.id not in ALLOWED_SINGLE_LETTERS:
+            if len(node.id) == 1 and node.id not in ALL_ALLOWED_SINGLE_LETTERS:
                 violations.append(
                     Violation(
                         filename,

package/hooks/validators/config/abbreviation_checks_constants.py

@@ -0,0 +1,3 @@
+"""Shared constants for abbreviation_checks.py's single-letter-name check."""
+
+ALL_ALLOWED_SINGLE_LETTERS: frozenset[str] = frozenset({"i", "j", "k", "_"})

package/hooks/validators/config/fast_save_validator_constants.py

@@ -0,0 +1,32 @@
+"""File suffixes and report text the save-path validator roster reuses.
+
+Config files are exempt from the string-literal magic-value checks, so the
+per-language file suffixes and shared report strings live here rather than
+inline in ``fast_save_validators.py``.
+"""
+
+from hooks_constants.mypy_integration_constants import PYTHON_SOURCE_SUFFIX
+
+TYPESCRIPT_SOURCE_SUFFIX = ".ts"
+REACT_TYPESCRIPT_SOURCE_SUFFIX = ".tsx"
+JAVASCRIPT_SOURCE_SUFFIX = ".js"
+REACT_JAVASCRIPT_SOURCE_SUFFIX = ".jsx"
+
+ALL_REACT_COMPONENT_FILE_SUFFIXES: tuple[str, ...] = (
+    REACT_TYPESCRIPT_SOURCE_SUFFIX,
+    REACT_JAVASCRIPT_SOURCE_SUFFIX,
+)
+ALL_CODE_REFERENCE_FILE_SUFFIXES: tuple[str, ...] = (
+    PYTHON_SOURCE_SUFFIX,
+    TYPESCRIPT_SOURCE_SUFFIX,
+    REACT_TYPESCRIPT_SOURCE_SUFFIX,
+    JAVASCRIPT_SOURCE_SUFFIX,
+    REACT_JAVASCRIPT_SOURCE_SUFFIX,
+)
+
+NO_PYTHON_FILES_MESSAGE = "No Python files to check"
+NO_TEST_FILES_MESSAGE = "No test files to check"
+NO_REACT_FILES_MESSAGE = "No React files to check"
+NO_CODE_REFERENCE_FILES_MESSAGE = "No code files to check"
+NO_VIOLATIONS_FOUND_MESSAGE = "All checks passed"
+VIOLATION_REPORT_LINE_SEPARATOR = "\n"

package/hooks/validators/config/hook_timing_harness_constants.py

@@ -9,7 +9,9 @@ P50_FRACTION = 0.50
 P95_FRACTION = 0.95
 DEFAULT_TARGET_RELATIVE_PATH = "hooks/blocking/code_rules_shared.py"
 SUBPROCESS_TIMEOUT_SECONDS = 60.0
-ALL_WRITE_EDIT_MATCHER_PATTERNS = frozenset({"Write|Edit", "Write|Edit|MultiEdit"})
+ALL_WRITE_EDIT_MATCHER_PATTERNS = frozenset(
+    {"Write|Edit", "Write|Edit|MultiEdit", "Write|Edit|MultiEdit|apply_patch"}
+)
 ALL_TIMED_EVENT_NAMES = ("PreToolUse", "PostToolUse")
 RUN_ALL_VALIDATORS_LABEL = "run_all_validators"
 CLAUDE_PLUGIN_ROOT_PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}"

package/hooks/validators/config/test_abbreviation_checks_constants.py

@@ -0,0 +1,11 @@
+"""Tests for the shared abbreviation_checks allow-list constant."""
+
+from .abbreviation_checks_constants import ALL_ALLOWED_SINGLE_LETTERS
+
+
+def test_allowed_single_letters_covers_loop_counters_and_underscore() -> None:
+    assert ALL_ALLOWED_SINGLE_LETTERS == frozenset({"i", "j", "k", "_"})
+
+
+def test_allowed_single_letters_is_immutable() -> None:
+    assert isinstance(ALL_ALLOWED_SINGLE_LETTERS, frozenset)

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)