claude-dev-env 1.93.1 → 1.95.0

package/hooks/validators/python_style_checks.py

@@ -12,7 +12,8 @@ import logging
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterator, List, Optional, Union
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
 
 try:
     from hooks_constants.python_style_checks_constants import (
@@ -20,7 +21,6 @@ try:
         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 (
@@ -28,14 +28,35 @@ except ModuleNotFoundError:
         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,
+    )
+
 logger = logging.getLogger(__name__)
 
 VIEW_SUFFIX = "_view"
 REQUEST_PARAM = "request"
 VIEWS_FILENAME = "views.py"
 
-FunctionNode = Union[ast.FunctionDef, ast.AsyncFunctionDef]
-
 
 @dataclass
 class Violation:
@@ -50,13 +71,13 @@ class Violation:
         return f"{self.file}:{self.line}: {self.message}"
 
 
-def check_imports_at_top(tree: ast.AST, filename: str) -> List[Violation]:
+def check_imports_at_top(tree: ast.AST, filename: str) -> list[Violation]:
     """Check that all imports sit at the top of the file.
 
     Flags module-level imports that follow other statements and imports
     nested inside function or method bodies.
     """
-    violations: List[Violation] = []
+    violations: list[Violation] = []
     violations.extend(_check_module_level_import_order(tree, filename))
     violations.extend(_check_no_inline_imports(tree, filename))
     return violations
@@ -75,11 +96,11 @@ def _is_docstring_statement(statement: ast.stmt) -> bool:
     return isinstance(literal, ast.Constant) and isinstance(literal.value, str)
 
 
-def _check_module_level_import_order(tree: ast.AST, filename: str) -> List[Violation]:
+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] = []
+    violations: list[Violation] = []
     has_seen_non_import = False
     for each_statement in tree.body:
         is_import = _is_import_statement(each_statement)
@@ -96,17 +117,17 @@ def _check_module_level_import_order(tree: ast.AST, filename: str) -> List[Viola
     return violations
 
 
-def _check_no_inline_imports(tree: ast.AST, filename: str) -> List[Violation]:
+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: list[Violation] = []
+    for each_function_node in iter_function_definitions(tree):
         violations.extend(_inline_imports_in(each_function_node, filename))
     return violations
 
 
-def _inline_imports_in(function_node: FunctionNode, filename: str) -> List[Violation]:
+def _inline_imports_in(function_node: FunctionNode, filename: str) -> list[Violation]:
     """Return violations for imports nested inside a single function."""
-    violations: List[Violation] = []
+    violations: list[Violation] = []
     for each_descendant in ast.walk(function_node):
         if isinstance(each_descendant, (ast.Import, ast.ImportFrom)):
             violations.append(
@@ -119,21 +140,14 @@ def _inline_imports_in(function_node: FunctionNode, filename: str) -> List[Viola
     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]:
+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] = []
+    violations: list[Violation] = []
     try:
         tree = ast.parse(source)
     except SyntaxError:
         return violations
-    for each_function_node in _iter_function_definitions(tree):
+    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)
@@ -142,12 +156,13 @@ def check_no_empty_line_after_decorators(source: str, filename: str) -> List[Vio
 
 def _decorator_gap_violation(
     function_node: FunctionNode, filename: str
-) -> Optional[Violation]:
+) -> Violation | None:
     """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
+        each_decorator.end_lineno or each_decorator.lineno
+        for each_decorator in function_node.decorator_list
     )
     if function_node.lineno - last_decorator_line <= 1:
         return None
@@ -158,15 +173,13 @@ def _decorator_gap_violation(
     )
 
 
-def check_blank_lines_between_functions(
-    source: str, filename: str
-) -> List[Violation]:
+def check_blank_lines_between_functions(source: str, filename: str) -> list[Violation]:
     """Check that consecutive top-level functions carry the expected blank gap."""
-    violations: List[Violation] = []
-    source_lines = _real_newline_lines(source)
-    top_level_functions = _top_level_functions(source)
+    violations: list[Violation] = []
+    source_lines = real_newline_lines(source)
+    ordered_functions = top_level_functions(source)
     for each_current_function, each_next_function in zip(
-        top_level_functions, top_level_functions[1:]
+        ordered_functions, ordered_functions[1:], strict=False
     ):
         violation = _spacing_violation(
             each_current_function, each_next_function, source_lines, filename
@@ -176,72 +189,12 @@ def check_blank_lines_between_functions(
     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 []
-    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
-
-
-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 _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
-    )
-
-
-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)
-
-
 def _spacing_violation(
     current_function: FunctionNode,
     next_function: FunctionNode,
-    source_lines: List[str],
+    all_source_lines: list[str],
     filename: str,
-) -> Optional[Violation]:
+) -> Violation | None:
     """Return a violation when two functions hold the wrong blank-line count.
 
     A run of purely empty lines is measured; a run holding any other content
@@ -250,9 +203,9 @@ def _spacing_violation(
     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):
+    next_start = function_start_line(next_function)
+    gap_lines = all_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:
@@ -265,12 +218,12 @@ def _spacing_violation(
     )
 
 
-def check_view_function_naming(tree: ast.AST, filename: str) -> List[Violation]:
+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):
+    violations: list[Violation] = []
+    for each_function_node in iter_function_definitions(tree):
         if _is_misnamed_view(each_function_node):
             violations.append(
                 Violation(
@@ -292,58 +245,84 @@ def _is_misnamed_view(function_node: FunctionNode) -> bool:
     return not function_node.name.endswith(VIEW_SUFFIX)
 
 
+def _decorator_span_line_numbers(all_decorators: list[ast.expr]) -> set[int]:
+    """Return every source line a decorator expression occupies."""
+    occupied_lines: set[int] = set()
+    for each_decorator in all_decorators:
+        end_line = each_decorator.end_lineno or each_decorator.lineno
+        occupied_lines.update(range(each_decorator.lineno, end_line + 1))
+    return occupied_lines
+
+
+def _blank_gap_lines_for_function(
+    function_node: FunctionNode, all_source_lines: list[str]
+) -> set[int]:
+    """Return blank line numbers between one function's decorators and its def."""
+    all_decorators = function_node.decorator_list
+    if not all_decorators:
+        return set()
+    occupied_lines = _decorator_span_line_numbers(all_decorators)
+    first_decorator_line = min(
+        each_decorator.lineno for each_decorator in all_decorators
+    )
+    return {
+        each_line_number
+        for each_line_number in range(first_decorator_line, function_node.lineno)
+        if each_line_number not in occupied_lines
+        and all_source_lines[each_line_number - 1].strip() == ""
+    }
+
+
 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
-        should_skip_next_blank = stripped.startswith("@")
-        result_lines.append(each_line)
-    return "".join(result_lines)
-
-
-def _blank_line_for_source(source: str) -> str:
-    """Return the blank-line string matching the source newline convention.
-
-    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.
+    """Remove empty lines between decorators and their function definitions.
+
+    Blank lines separating stacked decorators, and blank lines between the
+    last line of a multi-line decorator and the def, are both removed.
     """
-    if "\r\n" in source:
-        return "\r\n"
-    return "\n"
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return source
+    source_lines = real_newline_lines(source)
+    blank_line_numbers: set[int] = set()
+    for each_function_node in iter_function_definitions(tree):
+        blank_line_numbers |= _blank_gap_lines_for_function(
+            each_function_node, source_lines
+        )
+    if not blank_line_numbers:
+        return source
+    return "".join(
+        each_line
+        for each_line_number, each_line in enumerate(source_lines, start=1)
+        if each_line_number not in blank_line_numbers
+    )
 
 
-def _normalized_gap(all_gap_lines: List[str], blank_line: str) -> List[str]:
+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):
+    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)
+    functions = top_level_functions(source)
     if len(functions) <= 1:
         return source
-    source_lines = _real_newline_lines(source)
-    blank_line = _blank_line_for_source(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])
+    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)
+        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
@@ -358,9 +337,8 @@ def fix_function_spacing(source: str) -> str:
 def fix_file(file_path: Path) -> bool:
     """Apply the safe blank-line fixes and report whether the file changed.
 
-    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.
+    Path.read_text() normalizes every line ending to \\n before either fix
+    below inspects the text.
     """
     try:
         original = file_path.read_text(encoding="utf-8")
@@ -374,9 +352,9 @@ def fix_file(file_path: Path) -> bool:
     return True
 
 
-def validate_file(file_path: Path) -> List[Violation]:
+def validate_file(file_path: Path) -> list[Violation]:
     """Validate a Python file against every style check."""
-    violations: List[Violation] = []
+    violations: list[Violation] = []
     filename = str(file_path)
     try:
         source = file_path.read_text(encoding="utf-8")
@@ -403,7 +381,7 @@ def main() -> int:
     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] = []
+    all_violations: list[Violation] = []
     for each_file_arg in sys.argv[1:]:
         file_path = Path(each_file_arg)
         if not file_path.exists():

package/hooks/validators/python_style_helpers.py

@@ -0,0 +1,95 @@
+"""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.
+"""
+
+import ast
+from collections.abc import Iterator
+
+FunctionNode = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+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 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 []
+    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
+
+
+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)
+
+
+def gap_is_blank_only(all_gap_lines: list[str]) -> bool:
+    """Return True when every line between two functions is blank."""
+    return all(each_line.strip() == "" for each_line in all_gap_lines)
+
+
+def blank_line_for_source(source: str) -> str:
+    """Return the blank-line string matching the source newline convention.
+
+    Path.read_text() normalizes disk newlines to \\n before this runs, so the
+    CRLF branch serves an in-memory caller that builds a CRLF string directly.
+    """
+    if "\r\n" in source:
+        return "\r\n"
+    return "\n"
+
+
+def _advance_past_newline(source: str, scan_index: int) -> int | None:
+    """Return the index past a CR, LF, or CRLF at scan_index, or None.
+
+    None marks a character that is not a line ending.
+    """
+    character = source[scan_index]
+    if character == "\r":
+        scan_index += 1
+        if scan_index < len(source) and source[scan_index] == "\n":
+            scan_index += 1
+        return scan_index
+    if character == "\n":
+        return scan_index + 1
+    return None
+
+
+def real_newline_lines(source: str) -> list[str]:
+    """Split source on CR, LF, and CRLF only, keeping each line ending.
+
+    Line indices stay aligned with ast line numbers because the split
+    ignores form feed and other control characters ast does not count.
+    """
+    lines: list[str] = []
+    line_start = 0
+    scan_index = 0
+    total_length = len(source)
+    while scan_index < total_length:
+        line_end = _advance_past_newline(source, scan_index)
+        if line_end is None:
+            scan_index += 1
+            continue
+        scan_index = line_end
+        lines.append(source[line_start:scan_index])
+        line_start = scan_index
+    if line_start < total_length:
+        lines.append(source[line_start:])
+    return lines