claude-dev-env 1.94.0 → 2.0.0

package/hooks/validators/test_python_style_checks.py

@@ -1,9 +1,6 @@
 """Tests for Python style checks."""
 
 import ast
-import os
-import subprocess
-import sys
 from pathlib import Path
 
 import pytest
@@ -14,8 +11,6 @@ from .python_style_checks import (
     check_imports_at_top,
     check_no_empty_line_after_decorators,
     check_view_function_naming,
-    fix_file,
-    fix_function_spacing,
     validate_file,
 )
 
@@ -138,14 +133,6 @@ def bar() -> None:
     pass
 '''
 
-ONE_BLANK_BEFORE_DECORATED = '''def foo() -> None:
-    pass
-
-@decorator
-def bar() -> None:
-    pass
-'''
-
 COMMENT_BETWEEN_FUNCTIONS = '''def foo() -> None:
     pass
 
@@ -178,8 +165,6 @@ def bar() -> None:
     pass
 '''
 
-FORM_FEED_BETWEEN_FUNCTIONS = "def foo():\n    pass\n\x0c\n\ndef bar():\n    pass\n"
-
 
 class TestImportsAtTop:
     """Test import positioning validation."""
@@ -401,152 +386,3 @@ class TestViolationClass:
         """Violation should format as file:line: message."""
         violation = Violation("test.py", 42, "Test message")
         assert str(violation) == "test.py:42: Test message"
-
-
-class TestAutoFix:
-    """Test auto-fix capabilities."""
-
-    def test_fix_empty_line_after_decorator(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """Auto-fix should remove blank line between decorator and function."""
-        monkeypatch.setenv("HOME", str(tmp_path))
-        monkeypatch.setenv("TMPDIR", str(tmp_path))
-        code = '''@decorator
-
-def foo():
-    pass
-'''
-        expected = '''@decorator
-def foo():
-    pass
-'''
-        temp_path = tmp_path / "decorator_module.py"
-        temp_path.write_text(code, encoding="utf-8")
-        fixed = fix_file(temp_path)
-        assert fixed is True
-        result_text = temp_path.read_text()
-        assert result_text.strip() == expected.strip()
-
-    def test_fix_collapses_three_blank_lines_to_two(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """Auto-fix should collapse three or more blank lines down to two."""
-        monkeypatch.setenv("HOME", str(tmp_path))
-        monkeypatch.setenv("TMPDIR", str(tmp_path))
-        code = '''def foo():
-    pass
-
-
-
-def bar():
-    pass
-'''
-        expected = '''def foo():
-    pass
-
-
-def bar():
-    pass
-'''
-        temp_path = tmp_path / "spacing_module.py"
-        temp_path.write_text(code, encoding="utf-8")
-        fixed = fix_file(temp_path)
-        assert fixed is True
-        result_text = temp_path.read_text()
-        assert result_text.strip() == expected.strip()
-
-    def test_fix_inserts_missing_blank_lines(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """Auto-fix should insert blank lines for under-spaced functions."""
-        monkeypatch.setenv("HOME", str(tmp_path))
-        monkeypatch.setenv("TMPDIR", str(tmp_path))
-        temp_path = tmp_path / "underspaced_module.py"
-        temp_path.write_text(BAD_ONE_LINE_BETWEEN_FUNCTIONS, encoding="utf-8")
-        fixed = fix_file(temp_path)
-        assert fixed is True
-        assert temp_path.read_text() == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
-
-    def test_no_fix_needed_returns_false(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """Auto-fix should return False when the file already uses two blank lines."""
-        monkeypatch.setenv("HOME", str(tmp_path))
-        monkeypatch.setenv("TMPDIR", str(tmp_path))
-        code = '''def foo():
-    pass
-
-
-def bar():
-    pass
-'''
-        temp_path = tmp_path / "clean_module.py"
-        temp_path.write_text(code, encoding="utf-8")
-        fixed = fix_file(temp_path)
-        assert fixed is False
-
-    def test_form_feed_gap_stays_check_clean_after_fix(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """A form feed in a blank gap converges without corrupting the file."""
-        monkeypatch.setenv("HOME", str(tmp_path))
-        monkeypatch.setenv("TMPDIR", str(tmp_path))
-        assert (
-            check_blank_lines_between_functions(FORM_FEED_BETWEEN_FUNCTIONS, "test.py")
-            == []
-        )
-        temp_path = tmp_path / "form_feed_module.py"
-        temp_path.write_text(FORM_FEED_BETWEEN_FUNCTIONS, encoding="utf-8")
-        fix_file(temp_path)
-        fixed_text = temp_path.read_text()
-        assert check_blank_lines_between_functions(fixed_text, "test.py") == []
-        assert fix_file(temp_path) is False
-
-
-class TestFixFunctionSpacing:
-    """Test blank-line normalization between top-level functions."""
-
-    def test_inserts_two_blank_lines_when_adjacent(self) -> None:
-        """Adjacent functions gain exactly two blank lines."""
-        fixed_source = fix_function_spacing(BAD_NO_LINE_BETWEEN_FUNCTIONS)
-        assert fixed_source == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
-
-    def test_inserts_second_blank_line_when_one(self) -> None:
-        """A single blank line grows to exactly two."""
-        fixed_source = fix_function_spacing(BAD_ONE_LINE_BETWEEN_FUNCTIONS)
-        assert fixed_source == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
-
-    def test_collapses_three_blank_lines_to_two(self) -> None:
-        """Three blank lines collapse to exactly two."""
-        fixed_source = fix_function_spacing(BAD_THREE_LINES_BETWEEN_FUNCTIONS)
-        assert fixed_source == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
-
-    def test_normalizes_before_decorated_function(self) -> None:
-        """Blank lines before a decorated function normalize to two."""
-        fixed_source = fix_function_spacing(ONE_BLANK_BEFORE_DECORATED)
-        assert fixed_source == DECORATED_NEXT_TWO_LINES
-
-
-class TestDirectInvocation:
-    """Test running the checker as a standalone script."""
-
-    def test_direct_invocation_resolves_hooks_constants(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """Direct invocation bootstraps hooks_constants without PYTHONPATH."""
-        monkeypatch.setenv("HOME", str(tmp_path))
-        monkeypatch.setenv("TMPDIR", str(tmp_path))
-        script_path = Path(__file__).resolve().parent / "python_style_checks.py"
-        target_path = tmp_path / "clean_sample.py"
-        target_path.write_text(GOOD_IMPORTS, encoding="utf-8")
-        scrubbed_environment = dict(os.environ)
-        scrubbed_environment.pop("PYTHONPATH", None)
-        completed_process = subprocess.run(
-            [sys.executable, "-S", str(script_path), str(target_path)],
-            capture_output=True,
-            text=True,
-            env=scrubbed_environment,
-        )
-        assert "ModuleNotFoundError" not in completed_process.stderr
-        assert completed_process.returncode == 0

package/hooks/validators/test_python_style_checks_decorator_gap.py

@@ -0,0 +1,119 @@
+"""Tests for multi-line decorator gap detection and repair.
+
+These cover the case where a decorator spans several source lines: the
+validator measures the gap from the decorator's last line to the def, and
+the fixer removes any blank line that falls in that gap.
+"""
+
+import ast
+
+from .python_style_checks import (
+    check_no_empty_line_after_decorators,
+    fix_empty_lines_after_decorators,
+)
+
+MULTILINE_DECORATOR_NO_BLANK = """@parametrize(
+    "value",
+    [1, 2, 3],
+)
+def check_values() -> None:
+    pass
+"""
+
+MULTILINE_DECORATOR_WITH_BLANK = """@parametrize(
+    "value",
+    [1, 2, 3],
+)
+
+def check_values() -> None:
+    pass
+"""
+
+SINGLE_DECORATOR_NO_BLANK = """@decorator
+def foo() -> None:
+    pass
+"""
+
+SINGLE_DECORATOR_WITH_BLANK = """@decorator
+
+def foo() -> None:
+    pass
+"""
+
+STACKED_DECORATORS_WITH_INNER_BLANK = """@first
+
+@second
+def foo() -> None:
+    pass
+"""
+
+STACKED_DECORATORS_NO_BLANK = """@first
+@second
+def foo() -> None:
+    pass
+"""
+
+
+class TestMultilineDecoratorValidator:
+    """Validate gap detection for decorators spanning several lines."""
+
+    def test_multiline_decorator_no_blank_valid(self) -> None:
+        """A multi-line decorator directly above its def passes."""
+        violations = check_no_empty_line_after_decorators(MULTILINE_DECORATOR_NO_BLANK, "test.py")
+        assert violations == []
+
+    def test_multiline_decorator_with_blank_fails(self) -> None:
+        """A blank line after a multi-line decorator is flagged."""
+        violations = check_no_empty_line_after_decorators(MULTILINE_DECORATOR_WITH_BLANK, "test.py")
+        assert len(violations) == 1
+        assert "decorator" in violations[0].message.lower()
+
+    def test_single_decorator_no_blank_valid(self) -> None:
+        """A single-line decorator directly above its def passes."""
+        violations = check_no_empty_line_after_decorators(SINGLE_DECORATOR_NO_BLANK, "test.py")
+        assert violations == []
+
+    def test_single_decorator_with_blank_fails(self) -> None:
+        """A blank line after a single-line decorator is flagged."""
+        violations = check_no_empty_line_after_decorators(SINGLE_DECORATOR_WITH_BLANK, "test.py")
+        assert len(violations) == 1
+        assert violations[0].line == 1
+        assert "decorator" in violations[0].message.lower()
+
+
+class TestMultilineDecoratorFixer:
+    """Validate blank-line removal around decorators spanning several lines."""
+
+    def test_fixer_removes_multiline_decorator_gap(self) -> None:
+        """The fixer removes the blank between a multi-line decorator and its def."""
+        fixed_source = fix_empty_lines_after_decorators(MULTILINE_DECORATOR_WITH_BLANK)
+        ast.parse(fixed_source)
+        assert check_no_empty_line_after_decorators(fixed_source, "test.py") == []
+        assert fixed_source == MULTILINE_DECORATOR_NO_BLANK
+
+    def test_fixer_removes_single_decorator_gap(self) -> None:
+        """The fixer removes the blank after a single-line decorator."""
+        fixed_source = fix_empty_lines_after_decorators(SINGLE_DECORATOR_WITH_BLANK)
+        assert fixed_source == SINGLE_DECORATOR_NO_BLANK
+
+    def test_fixer_removes_blank_between_stacked_decorators(self) -> None:
+        """The fixer removes a blank line separating stacked decorators."""
+        fixed_source = fix_empty_lines_after_decorators(STACKED_DECORATORS_WITH_INNER_BLANK)
+        ast.parse(fixed_source)
+        assert fixed_source == STACKED_DECORATORS_NO_BLANK
+
+    def test_fixer_leaves_clean_multiline_decorator_untouched(self) -> None:
+        """A multi-line decorator with no gap survives the fixer unchanged."""
+        fixed_source = fix_empty_lines_after_decorators(MULTILINE_DECORATOR_NO_BLANK)
+        assert fixed_source == MULTILINE_DECORATOR_NO_BLANK
+
+    def test_fixer_is_idempotent(self) -> None:
+        """Applying the fixer twice matches applying it once."""
+        once = fix_empty_lines_after_decorators(MULTILINE_DECORATOR_WITH_BLANK)
+        twice = fix_empty_lines_after_decorators(once)
+        assert twice == once
+
+    def test_fixer_returns_source_unchanged_on_syntax_error(self) -> None:
+        """Unparseable source is returned unchanged rather than corrupted."""
+        broken_source = "@decorator\n\ndef foo(\n"
+        assert fix_empty_lines_after_decorators(broken_source) == broken_source

package/hooks/validators/test_python_style_fixes.py

@@ -0,0 +1,251 @@
+"""Tests for the blank-line auto-fixers and standalone invocation."""
+
+import ast
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from .python_style_checks import (
+    check_blank_lines_between_functions,
+    fix_file,
+    fix_function_spacing,
+)
+
+GOOD_IMPORTS = """import os
+import sys
+
+def foo() -> None:
+    pass
+"""
+
+GOOD_TWO_LINES_BETWEEN_FUNCTIONS = """def foo() -> None:
+    pass
+
+
+def bar() -> None:
+    pass
+"""
+
+BAD_NO_LINE_BETWEEN_FUNCTIONS = """def foo() -> None:
+    pass
+def bar() -> None:
+    pass
+"""
+
+BAD_ONE_LINE_BETWEEN_FUNCTIONS = """def foo() -> None:
+    pass
+
+def bar() -> None:
+    pass
+"""
+
+BAD_THREE_LINES_BETWEEN_FUNCTIONS = """def foo() -> None:
+    pass
+
+
+
+def bar() -> None:
+    pass
+"""
+
+DECORATED_NEXT_TWO_LINES = """def foo() -> None:
+    pass
+
+
+@decorator
+def bar() -> None:
+    pass
+"""
+
+ONE_BLANK_BEFORE_DECORATED = """def foo() -> None:
+    pass
+
+@decorator
+def bar() -> None:
+    pass
+"""
+
+FORM_FEED_BETWEEN_FUNCTIONS = "def foo():\n    pass\n\x0c\n\ndef bar():\n    pass\n"
+
+
+class TestAutoFix:
+    """Test auto-fix capabilities."""
+
+    def test_fix_empty_line_after_decorator(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Auto-fix should remove blank line between decorator and function."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        code = """@decorator
+
+def foo():
+    pass
+"""
+        expected = """@decorator
+def foo():
+    pass
+"""
+        temp_path = tmp_path / "decorator_module.py"
+        temp_path.write_text(code, encoding="utf-8")
+        fixed = fix_file(temp_path)
+        assert fixed is True
+        result_text = temp_path.read_text()
+        assert result_text.strip() == expected.strip()
+
+    def test_fix_collapses_three_blank_lines_to_two(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Auto-fix should collapse three or more blank lines down to two."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        code = """def foo():
+    pass
+
+
+
+def bar():
+    pass
+"""
+        expected = """def foo():
+    pass
+
+
+def bar():
+    pass
+"""
+        temp_path = tmp_path / "spacing_module.py"
+        temp_path.write_text(code, encoding="utf-8")
+        fixed = fix_file(temp_path)
+        assert fixed is True
+        result_text = temp_path.read_text()
+        assert result_text.strip() == expected.strip()
+
+    def test_fix_inserts_missing_blank_lines(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Auto-fix should insert blank lines for under-spaced functions."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        temp_path = tmp_path / "underspaced_module.py"
+        temp_path.write_text(BAD_ONE_LINE_BETWEEN_FUNCTIONS, encoding="utf-8")
+        fixed = fix_file(temp_path)
+        assert fixed is True
+        assert temp_path.read_text() == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
+
+    def test_no_fix_needed_returns_false(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Auto-fix should return False when the file already uses two blank lines."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        code = """def foo():
+    pass
+
+
+def bar():
+    pass
+"""
+        temp_path = tmp_path / "clean_module.py"
+        temp_path.write_text(code, encoding="utf-8")
+        fixed = fix_file(temp_path)
+        assert fixed is False
+
+    def test_form_feed_gap_stays_check_clean_after_fix(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A form feed in a blank gap converges without corrupting the file."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        assert check_blank_lines_between_functions(FORM_FEED_BETWEEN_FUNCTIONS, "test.py") == []
+        temp_path = tmp_path / "form_feed_module.py"
+        temp_path.write_text(FORM_FEED_BETWEEN_FUNCTIONS, encoding="utf-8")
+        fix_file(temp_path)
+        fixed_text = temp_path.read_text()
+        assert check_blank_lines_between_functions(fixed_text, "test.py") == []
+        assert fix_file(temp_path) is False
+
+
+class TestFixFunctionSpacing:
+    """Test blank-line normalization between top-level functions."""
+
+    def test_inserts_two_blank_lines_when_adjacent(self) -> None:
+        """Adjacent functions gain exactly two blank lines."""
+        fixed_source = fix_function_spacing(BAD_NO_LINE_BETWEEN_FUNCTIONS)
+        assert fixed_source == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
+
+    def test_inserts_second_blank_line_when_one(self) -> None:
+        """A single blank line grows to exactly two."""
+        fixed_source = fix_function_spacing(BAD_ONE_LINE_BETWEEN_FUNCTIONS)
+        assert fixed_source == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
+
+    def test_collapses_three_blank_lines_to_two(self) -> None:
+        """Three blank lines collapse to exactly two."""
+        fixed_source = fix_function_spacing(BAD_THREE_LINES_BETWEEN_FUNCTIONS)
+        assert fixed_source == GOOD_TWO_LINES_BETWEEN_FUNCTIONS
+
+    def test_normalizes_before_decorated_function(self) -> None:
+        """Blank lines before a decorated function normalize to two."""
+        fixed_source = fix_function_spacing(ONE_BLANK_BEFORE_DECORATED)
+        assert fixed_source == DECORATED_NEXT_TWO_LINES
+
+
+class TestDirectInvocation:
+    """Test running the checker as a standalone script."""
+
+    def test_direct_invocation_resolves_hooks_constants(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Direct invocation bootstraps hooks_constants without PYTHONPATH."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        script_path = Path(__file__).resolve().parent / "python_style_checks.py"
+        target_path = tmp_path / "clean_sample.py"
+        target_path.write_text(GOOD_IMPORTS, encoding="utf-8")
+        scrubbed_environment = dict(os.environ)
+        scrubbed_environment.pop("PYTHONPATH", None)
+        completed_process = subprocess.run(
+            [sys.executable, "-S", str(script_path), str(target_path)],
+            capture_output=True,
+            text=True,
+            env=scrubbed_environment,
+            check=False,
+        )
+        assert "ModuleNotFoundError" not in completed_process.stderr
+        assert completed_process.returncode == 0
+
+    def test_direct_invocation_with_hooks_constants_resolvable_off_path(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """First import succeeds while the validators package stays off sys.path."""
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("TMPDIR", str(tmp_path))
+        synthetic_constants_root = tmp_path / "synthetic_root"
+        constants_package = synthetic_constants_root / "hooks_constants"
+        constants_package.mkdir(parents=True)
+        (constants_package / "__init__.py").write_text("", encoding="utf-8")
+        (constants_package / "python_style_checks_constants.py").write_text(
+            "EXPECTED_BLANK_LINES_BETWEEN_FUNCTIONS = 2\nMINIMUM_ARGUMENT_COUNT = 1\n",
+            encoding="utf-8",
+        )
+        script_path = Path(__file__).resolve().parent / "python_style_checks.py"
+        target_path = tmp_path / "clean_sample.py"
+        target_path.write_text(GOOD_IMPORTS, encoding="utf-8")
+        isolated_environment = dict(os.environ)
+        isolated_environment["PYTHONPATH"] = str(synthetic_constants_root)
+        completed_process = subprocess.run(
+            [sys.executable, str(script_path), str(target_path)],
+            capture_output=True,
+            text=True,
+            env=isolated_environment,
+            check=False,
+        )
+        assert "NameError" not in completed_process.stderr
+        assert completed_process.returncode == 0
+
+    def test_ast_module_import_available(self) -> None:
+        """The ast module the checker depends on parses a trivial module."""
+        assert ast.parse("x = 1").body

package/hooks/validators/test_python_style_helpers.py

@@ -0,0 +1,125 @@
+"""Tests for the shared source-line and function-discovery helpers."""
+
+import ast
+
+from .python_style_helpers import (
+    blank_line_for_source,
+    function_start_line,
+    gap_is_blank_only,
+    iter_function_definitions,
+    real_newline_lines,
+    top_level_functions,
+)
+
+TWO_FUNCTIONS = """def foo() -> None:
+    pass
+
+
+def bar() -> None:
+    pass
+"""
+
+DECORATED_FUNCTION = """@decorator
+def decorated() -> None:
+    pass
+"""
+
+CRLF_SOURCE = "def foo() -> None:\r\n    pass\r\n"
+
+
+class TestIterFunctionDefinitions:
+    """Discovery of every function definition in a tree."""
+
+    def test_yields_each_function(self) -> None:
+        """Every top-level function is yielded."""
+        tree = ast.parse(TWO_FUNCTIONS)
+        names = [each.name for each in iter_function_definitions(tree)]
+        assert names == ["foo", "bar"]
+
+    def test_yields_nested_functions(self) -> None:
+        """A nested function is discovered alongside its enclosing function."""
+        tree = ast.parse("def outer() -> None:\n    def inner() -> None:\n        pass\n")
+        names = {each.name for each in iter_function_definitions(tree)}
+        assert names == {"outer", "inner"}
+
+
+class TestTopLevelFunctions:
+    """Ordered listing of a module's top-level functions."""
+
+    def test_returns_functions_in_line_order(self) -> None:
+        """Top-level functions are returned ordered by line."""
+        ordered = top_level_functions(TWO_FUNCTIONS)
+        assert [each.name for each in ordered] == ["foo", "bar"]
+
+    def test_ignores_nested_functions(self) -> None:
+        """A function nested inside another is not top-level."""
+        ordered = top_level_functions(
+            "def outer() -> None:\n    def inner() -> None:\n        pass\n"
+        )
+        assert [each.name for each in ordered] == ["outer"]
+
+    def test_syntax_error_returns_empty(self) -> None:
+        """Unparseable source yields no functions."""
+        assert top_level_functions("def foo(") == []
+
+
+class TestFunctionStartLine:
+    """First source line of a function, counting decorators."""
+
+    def test_undecorated_uses_def_line(self) -> None:
+        """An undecorated function starts on its def line."""
+        function_node = top_level_functions(TWO_FUNCTIONS)[0]
+        assert function_start_line(function_node) == 1
+
+    def test_decorated_uses_first_decorator_line(self) -> None:
+        """A decorated function starts on its first decorator line."""
+        function_node = top_level_functions(DECORATED_FUNCTION)[0]
+        assert function_start_line(function_node) == 1
+
+
+class TestGapIsBlankOnly:
+    """Whether a run of lines between functions is entirely blank."""
+
+    def test_all_blank_lines_true(self) -> None:
+        """A gap of blank lines reports blank-only."""
+        assert gap_is_blank_only(["\n", "   \n", ""]) is True
+
+    def test_non_blank_line_false(self) -> None:
+        """A gap holding any content is not blank-only."""
+        assert gap_is_blank_only(["\n", "# comment\n"]) is False
+
+
+class TestRealNewlineLines:
+    """Line splitting aligned with ast line numbers."""
+
+    def test_splits_on_lf(self) -> None:
+        """LF-separated source splits into its lines with endings kept."""
+        assert real_newline_lines("a\nb\n") == ["a\n", "b\n"]
+
+    def test_splits_on_crlf(self) -> None:
+        """CRLF pairs count as a single line ending."""
+        assert real_newline_lines("a\r\nb\r\n") == ["a\r\n", "b\r\n"]
+
+    def test_form_feed_stays_in_line(self) -> None:
+        """A form feed does not start a new line, matching ast line numbers."""
+        assert real_newline_lines("a\x0cb\n") == ["a\x0cb\n"]
+
+    def test_trailing_partial_line_kept(self) -> None:
+        """A final line with no ending is preserved."""
+        assert real_newline_lines("a\nb") == ["a\n", "b"]
+
+    def test_empty_source_returns_no_lines(self) -> None:
+        """Empty source yields an empty list of lines."""
+        assert real_newline_lines("") == []
+
+
+class TestBlankLineForSource:
+    """Blank-line string matching the source newline convention."""
+
+    def test_lf_source_returns_lf(self) -> None:
+        """LF source yields an LF blank line."""
+        assert blank_line_for_source("a\nb\n") == "\n"
+
+    def test_crlf_source_returns_crlf(self) -> None:
+        """CRLF source yields a CRLF blank line."""
+        assert blank_line_for_source(CRLF_SOURCE) == "\r\n"