claude-dev-env 1.92.0 → 1.93.0

package/hooks/validators/python_style_checks.py

@@ -3,22 +3,39 @@
 Implements four style checks:
 1. Imports at top of file
 2. No empty lines after decorators
-3. Single empty line between functions
+3. Two empty lines between top-level functions
 4. View functions end with _view suffix
 """
 
 import ast
+import logging
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import List
+from typing import Iterator, List, Optional, Union
+
+try:
+    from hooks_constants.python_style_checks_constants import (
+        EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS,
+        MINIMUM_ARGUMENT_COUNT,
+    )
+except ModuleNotFoundError:
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    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,
+    )
+
+logger = logging.getLogger(__name__)
 
-
-# Constants
 VIEW_SUFFIX = "_view"
 REQUEST_PARAM = "request"
 VIEWS_FILENAME = "views.py"
 
+FunctionNode = Union[ast.FunctionDef, ast.AsyncFunctionDef]
+
 
 @dataclass
 class Violation:
@@ -34,329 +51,367 @@ class Violation:
 
 
 def check_imports_at_top(tree: ast.AST, filename: str) -> List[Violation]:
-    """Check that all imports are at the top of the file.
-
-    Catches two violations:
-    1. Module-level imports after non-import statements
-    2. Imports inside functions/classes (inline imports)
+    """Check that all imports sit at the top of the file.
 
-    Args:
-        tree: AST tree to check
-        filename: Name of file being checked
-
-    Returns:
-        List of violations found
+    Flags module-level imports that follow other statements and imports
+    nested inside function or method bodies.
     """
     violations: List[Violation] = []
+    violations.extend(_check_module_level_import_order(tree, filename))
+    violations.extend(_check_no_inline_imports(tree, filename))
+    return violations
+
 
-    # Check 1: Module-level imports must be at top
-    if isinstance(tree, ast.Module):
-        seen_non_import = False
-        for child in tree.body:
-            if isinstance(child, (ast.Import, ast.ImportFrom)):
-                if seen_non_import:
-                    violations.append(
-                        Violation(
-                            filename,
-                            child.lineno,
-                            "Import statement must be at top of file",
-                        )
-                    )
-            elif isinstance(child, ast.Expr) and isinstance(child.value, ast.Constant):
-                # Allow docstrings at top
-                if isinstance(child.value.value, str):
-                    continue
-                seen_non_import = True
-            else:
-                seen_non_import = True
-
-    # Check 2: No imports inside functions or methods
-    for node in ast.walk(tree):
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            for child in ast.walk(node):
-                if isinstance(child, (ast.Import, ast.ImportFrom)):
-                    violations.append(
-                        Violation(
-                            filename,
-                            child.lineno,
-                            "Import inside function - move to top of file",
-                        )
-                    )
+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."""
+    if not isinstance(tree, ast.Module):
+        return []
+    violations: List[Violation] = []
+    has_seen_non_import = False
+    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):
+            has_seen_non_import = True
     return violations
 
 
-def check_no_empty_line_after_decorators(source: str, filename: str) -> List[Violation]:
-    """Check that decorators have no empty line before function.
+def _check_no_inline_imports(tree: ast.AST, filename: str) -> List[Violation]:
+    """Flag import statements located inside function or method bodies."""
+    violations: List[Violation] = []
+    for each_function_node in _iter_function_definitions(tree):
+        violations.extend(_inline_imports_in(each_function_node, filename))
+    return violations
 
-    Args:
-        source: Source code as string
-        filename: Name of file being checked
 
-    Returns:
-        List of violations found
-    """
+def _inline_imports_in(function_node: FunctionNode, filename: str) -> List[Violation]:
+    """Return violations for imports nested inside a single function."""
     violations: List[Violation] = []
-    lines = source.splitlines()
+    for each_descendant in ast.walk(function_node):
+        if isinstance(each_descendant, (ast.Import, ast.ImportFrom)):
+            violations.append(
+                Violation(
+                    filename,
+                    each_descendant.lineno,
+                    "Import inside function - move to top of file",
+                )
+            )
+    return violations
+
+
+def _iter_function_definitions(tree: ast.AST) -> Iterator[FunctionNode]:
+    """Yield every function and async-function definition in the tree."""
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield each_node
 
+
+def check_no_empty_line_after_decorators(source: str, filename: str) -> List[Violation]:
+    """Check that no empty line separates a decorator from its function."""
+    violations: List[Violation] = []
     try:
         tree = ast.parse(source)
     except SyntaxError:
         return violations
-
-    for node in ast.walk(tree):
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.decorator_list:
-            # Get last decorator line
-            last_decorator_line = max(d.lineno for d in node.decorator_list)
-            function_line = node.lineno
-
-            # Check if there's an empty line between decorator and function
-            if function_line - last_decorator_line > 1:
-                violations.append(
-                    Violation(
-                        filename,
-                        last_decorator_line,
-                        "No empty line allowed between decorator and function",
-                    )
-                )
-
+    for each_function_node in _iter_function_definitions(tree):
+        violation = _decorator_gap_violation(each_function_node, filename)
+        if violation is not None:
+            violations.append(violation)
     return violations
 
 
-def check_single_empty_line_between_functions(
+def _decorator_gap_violation(
+    function_node: FunctionNode, filename: str
+) -> Optional[Violation]:
+    """Return a violation when an empty line separates a decorator from its function."""
+    if not function_node.decorator_list:
+        return None
+    last_decorator_line = max(
+        each_decorator.lineno for each_decorator in function_node.decorator_list
+    )
+    if function_node.lineno - last_decorator_line <= 1:
+        return None
+    return Violation(
+        filename,
+        last_decorator_line,
+        "No empty line allowed between decorator and function",
+    )
+
+
+def check_blank_lines_between_functions(
     source: str, filename: str
 ) -> List[Violation]:
-    """Check that functions have exactly one empty line between them.
-
-    Args:
-        source: Source code as string
-        filename: Name of file being checked
-
-    Returns:
-        List of violations found
-    """
+    """Check that consecutive top-level functions carry the expected blank gap."""
     violations: List[Violation] = []
-    lines = source.splitlines()
+    source_lines = _real_newline_lines(source)
+    top_level_functions = _top_level_functions(source)
+    for each_current_function, each_next_function in zip(
+        top_level_functions, top_level_functions[1:]
+    ):
+        violation = _spacing_violation(
+            each_current_function, each_next_function, source_lines, filename
+        )
+        if violation is not None:
+            violations.append(violation)
+    return violations
 
+
+def _top_level_functions(source: str) -> List[FunctionNode]:
+    """Return the module's top-level function definitions, ordered by line."""
     try:
         tree = ast.parse(source)
     except SyntaxError:
-        return violations
-
-    # Get all top-level function definitions
-    functions = [
-        node for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        return []
+    if not isinstance(tree, ast.Module):
+        return []
+    functions: List[FunctionNode] = [
+        node
+        for node in tree.body
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
     ]
+    functions.sort(key=lambda function_node: function_node.lineno)
+    return functions
 
-    # Filter to only top-level functions (not nested)
-    if isinstance(tree, ast.Module):
-        top_level_functions = [
-            node for node in tree.body if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
-        ]
-    else:
-        top_level_functions = []
-
-    # Sort by line number
-    top_level_functions.sort(key=lambda f: f.lineno)
-
-    # Check spacing between consecutive functions
-    for i in range(len(top_level_functions) - 1):
-        current_func = top_level_functions[i]
-        next_func = top_level_functions[i + 1]
-
-        # Find last line of current function
-        current_end = current_func.end_lineno
-        next_start = next_func.lineno
-
-        if current_end is not None:
-            # Calculate empty lines between functions
-            empty_lines = next_start - current_end - 1
-
-            if empty_lines != 1:
-                violations.append(
-                    Violation(
-                        filename,
-                        current_end,
-                        f"Expected 1 empty line between functions, found {empty_lines}",
-                    )
-                )
 
-    return violations
+def _real_newline_lines(source: str) -> List[str]:
+    """Split source on CR, LF, and CRLF only, keeping each line ending.
 
+    ``str.splitlines`` breaks on form feed and other control characters that
+    Python's line numbering ignores, so its indices drift from ``ast`` line
+    numbers. This splitter keeps line indices aligned with ``ast`` line numbers.
+    """
+    lines: List[str] = []
+    line_start = 0
+    scan_index = 0
+    total_length = len(source)
+    while scan_index < total_length:
+        character = source[scan_index]
+        if character == "\r":
+            scan_index += 1
+            if scan_index < total_length and source[scan_index] == "\n":
+                scan_index += 1
+        elif character == "\n":
+            scan_index += 1
+        else:
+            scan_index += 1
+            continue
+        lines.append(source[line_start:scan_index])
+        line_start = scan_index
+    if line_start < total_length:
+        lines.append(source[line_start:])
+    return lines
 
-def check_view_function_naming(tree: ast.AST, filename: str) -> List[Violation]:
-    """Check that view functions end with _view suffix.
 
-    Only applies to functions in views.py that have 'request' as first parameter.
+def _function_start_line(function_node: FunctionNode) -> int:
+    """Return the first source line of a function, counting its decorators."""
+    if not function_node.decorator_list:
+        return function_node.lineno
+    return min(
+        each_decorator.lineno for each_decorator in function_node.decorator_list
+    )
 
-    Args:
-        tree: AST tree to check
-        filename: Name of file being checked
 
-    Returns:
-        List of violations found
-    """
-    violations: List[Violation] = []
+def _gap_is_blank_only(gap_lines: List[str]) -> bool:
+    """Return True when every line between two functions is blank."""
+    return all(each_line.strip() == "" for each_line in gap_lines)
 
-    # Only check files named views.py
-    if not filename.endswith(VIEWS_FILENAME):
-        return violations
 
-    for node in ast.walk(tree):
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            # Check if first parameter is 'request'
-            if node.args.args and node.args.args[0].arg == REQUEST_PARAM:
-                # Check if function name ends with _view
-                if not node.name.endswith(VIEW_SUFFIX):
-                    violations.append(
-                        Violation(
-                            filename,
-                            node.lineno,
-                            f"View function '{node.name}' must end with '{VIEW_SUFFIX}'",
-                        )
-                    )
+def _spacing_violation(
+    current_function: FunctionNode,
+    next_function: FunctionNode,
+    source_lines: List[str],
+    filename: str,
+) -> Optional[Violation]:
+    """Return a violation when two functions hold the wrong blank-line count.
 
-    return violations
+    A run of purely empty lines is measured; a run holding any other content
+    is skipped, matching the fixer so a flagged file can be normalized.
+    """
+    current_end = current_function.end_lineno
+    if current_end is None:
+        return None
+    next_start = _function_start_line(next_function)
+    gap_lines = source_lines[current_end : next_start - 1]
+    if not _gap_is_blank_only(gap_lines):
+        return None
+    blank_line_count = len(gap_lines)
+    if blank_line_count == EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS:
+        return None
+    return Violation(
+        filename,
+        current_end,
+        f"Expected {EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS} empty lines "
+        f"between functions, found {blank_line_count}",
+    )
 
 
-def fix_empty_lines_after_decorators(source: str) -> str:
-    """Remove empty lines between decorators and function definitions.
+def check_view_function_naming(tree: ast.AST, filename: str) -> List[Violation]:
+    """Check that request-handling functions in views.py end with _view."""
+    if not filename.endswith(VIEWS_FILENAME):
+        return []
+    violations: List[Violation] = []
+    for each_function_node in _iter_function_definitions(tree):
+        if _is_misnamed_view(each_function_node):
+            violations.append(
+                Violation(
+                    filename,
+                    each_function_node.lineno,
+                    f"View function '{each_function_node.name}' must end with '{VIEW_SUFFIX}'",
+                )
+            )
+    return violations
 
-    Args:
-        source: Source code as string
 
-    Returns:
-        Fixed source code
-    """
-    lines = source.splitlines(keepends=True)
-    result_lines: List[str] = []
-    skip_next_blank = False
+def _is_misnamed_view(function_node: FunctionNode) -> bool:
+    """Return True when a request handler is missing the _view suffix."""
+    arguments = function_node.args.args
+    if not arguments:
+        return False
+    if arguments[0].arg != REQUEST_PARAM:
+        return False
+    return not function_node.name.endswith(VIEW_SUFFIX)
 
-    for line in lines:
-        stripped = line.strip()
 
-        if stripped.startswith("@"):
-            skip_next_blank = True
-            result_lines.append(line)
-        elif skip_next_blank and stripped == "":
+def fix_empty_lines_after_decorators(source: str) -> str:
+    """Remove empty lines between decorators and their function definitions."""
+    result_lines: List[str] = []
+    should_skip_next_blank = False
+    for each_line in source.splitlines(keepends=True):
+        stripped = each_line.strip()
+        if should_skip_next_blank and stripped == "":
             continue
-        else:
-            skip_next_blank = False
-            result_lines.append(line)
-
+        should_skip_next_blank = stripped.startswith("@")
+        result_lines.append(each_line)
     return "".join(result_lines)
 
 
-def fix_multiple_blank_lines(source: str) -> str:
-    """Collapse multiple blank lines between functions to single blank line.
-
-    Args:
-        source: Source code as string
+def _blank_line_for_source(source: str) -> str:
+    """Return the blank-line string matching the source newline convention.
 
-    Returns:
-        Fixed source code
+    Every disk reader in this package loads source through
+    Path.read_text(), whose universal-newline translation turns a bare
+    \\r or a \\r\\n pair into \\n before the string reaches this function.
+    A bare \\r never arrives from a file on disk. The \\r\\n branch below
+    serves an in-memory caller that builds a CRLF string directly.
     """
-    lines = source.splitlines(keepends=True)
-    result_lines: List[str] = []
-    blank_count = 0
+    if "\r\n" in source:
+        return "\r\n"
+    return "\n"
 
-    for line in lines:
-        if line.strip() == "":
-            blank_count += 1
-            if blank_count <= 1:
-                result_lines.append(line)
-        else:
-            blank_count = 0
-            result_lines.append(line)
 
-    return "".join(result_lines)
+def _normalized_gap(all_gap_lines: List[str], blank_line: str) -> List[str]:
+    """Return the between-function gap normalized to the expected blank count.
 
+    A gap that is entirely blank becomes exactly the expected number of blank
+    lines. A gap that holds any non-blank line stays untouched so no comment,
+    class, or statement in it is lost.
+    """
+    if not _gap_is_blank_only(all_gap_lines):
+        return all_gap_lines
+    return [blank_line] * EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS
+
+
+def fix_function_spacing(source: str) -> str:
+    """Normalize blank lines between top-level functions to exactly two."""
+    functions = _top_level_functions(source)
+    if len(functions) <= 1:
+        return source
+    source_lines = _real_newline_lines(source)
+    blank_line = _blank_line_for_source(source)
+    previous_end_line = functions[0].end_lineno
+    if previous_end_line is None:
+        return source
+    rebuilt: List[str] = list(source_lines[:previous_end_line])
+    for each_next_function in functions[1:]:
+        next_start_line = _function_start_line(each_next_function)
+        gap_lines = source_lines[previous_end_line : next_start_line - 1]
+        rebuilt.extend(_normalized_gap(gap_lines, blank_line))
+        next_end_line = each_next_function.end_lineno
+        if next_end_line is None:
+            return source
+        rebuilt.extend(source_lines[next_start_line - 1 : next_end_line])
+        previous_end_line = next_end_line
+    rebuilt.extend(source_lines[previous_end_line:])
+    return "".join(rebuilt)
 
-def fix_file(file_path: Path) -> bool:
-    """Apply all safe fixes to a file.
 
-    Args:
-        file_path: Path to file to fix
+def fix_file(file_path: Path) -> bool:
+    """Apply the safe blank-line fixes and report whether the file changed.
 
-    Returns:
-        True if any fixes were applied, False otherwise
+    Reads the file through Path.read_text(), which applies
+    universal-newline translation and normalizes every line ending to
+    \\n before either fix function below inspects the text.
     """
     try:
         original = file_path.read_text(encoding="utf-8")
     except Exception:
         return False
-
-    fixed = original
-    fixed = fix_empty_lines_after_decorators(fixed)
-    fixed = fix_multiple_blank_lines(fixed)
-
-    if fixed != original:
-        file_path.write_text(fixed, encoding="utf-8")
-        return True
-
-    return False
+    decorators_fixed = fix_empty_lines_after_decorators(original)
+    blank_lines_fixed = fix_function_spacing(decorators_fixed)
+    if blank_lines_fixed == original:
+        return False
+    file_path.write_text(blank_lines_fixed, encoding="utf-8")
+    return True
 
 
 def validate_file(file_path: Path) -> List[Violation]:
-    """Validate a Python file with all style checks.
-
-    Args:
-        file_path: Path to Python file to validate
-
-    Returns:
-        List of all violations found
-    """
+    """Validate a Python file against every style check."""
     violations: List[Violation] = []
     filename = str(file_path)
-
     try:
         source = file_path.read_text(encoding="utf-8")
-    except Exception as e:
-        violations.append(Violation(filename, 0, f"Error reading file: {e}"))
+    except Exception as error:
+        violations.append(Violation(filename, 0, f"Error reading file: {error}"))
         return violations
-
     try:
         tree = ast.parse(source)
-    except SyntaxError as e:
+    except SyntaxError as error:
         violations.append(
-            Violation(filename, e.lineno or 0, f"Syntax error: {e.msg}")
+            Violation(filename, error.lineno or 0, f"Syntax error: {error.msg}")
         )
         return violations
-
-    # Run all checks
     violations.extend(check_imports_at_top(tree, filename))
     violations.extend(check_no_empty_line_after_decorators(source, filename))
-    violations.extend(check_single_empty_line_between_functions(source, filename))
+    violations.extend(check_blank_lines_between_functions(source, filename))
     violations.extend(check_view_function_naming(tree, filename))
-
     return violations
 
 
 def main() -> int:
-    """Main entry point for command-line usage.
-
-    Returns:
-        Exit code: 0 if all files pass, 1 if violations found
-    """
-    if len(sys.argv) < 2:
-        print("Usage: python_style_checks.py <file1.py> [file2.py ...]", file=sys.stderr)
+    """Run the style checks over the files named on the command line."""
+    minimum_argument_count = MINIMUM_ARGUMENT_COUNT
+    if len(sys.argv) < minimum_argument_count:
+        logger.error("Usage: %s <file1.py> [file2.py ...]", Path(sys.argv[0]).name)
         return 1
-
     all_violations: List[Violation] = []
-
-    for file_arg in sys.argv[1:]:
-        file_path = Path(file_arg)
+    for each_file_arg in sys.argv[1:]:
+        file_path = Path(each_file_arg)
         if not file_path.exists():
-            print(f"Error: File not found: {file_path}", file=sys.stderr)
+            logger.error("File not found: %s", file_path)
             return 1
-
-        violations = validate_file(file_path)
-        all_violations.extend(violations)
-
-    # Print all violations
-    for violation in all_violations:
-        print(violation)
-
+        all_violations.extend(validate_file(file_path))
+    for each_violation in all_violations:
+        logger.error("%s", each_violation)
     return 1 if all_violations else 0
 
 

package/hooks/validators/run_all_validators.py

@@ -32,6 +32,7 @@ _hooks_directory_on_path = str(hooks_dir.resolve())
 if _hooks_directory_on_path not in sys.path:
     sys.path.insert(0, _hooks_directory_on_path)
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
     apply_edits,
     edits_for_tool,
@@ -807,6 +808,11 @@ def _emit_pre_tool_use_deny(deny_reason: str) -> None:
             "permissionDecisionReason": deny_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="run_all_validators.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
     sys.stdout.write(json.dumps(deny_payload) + "\n")
     sys.stdout.flush()