crackerjack 0.30.3__py3-none-any.whl → 0.31.4__py3-none-any.whl

crackerjack/code_cleaner.py

@@ -1,980 +1,670 @@
-import asyncio
-import re
-import subprocess
+import ast
 import typing as t
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from contextlib import suppress
-from functools import lru_cache
+from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
+from typing import Protocol
 
-import aiofiles
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from rich.console import Console
 
-from .errors import ErrorCode, ExecutionError, handle_error
+from .errors import ErrorCode, ExecutionError
 
 
-class CodeCleaner(BaseModel, arbitrary_types_allowed=True):
-    console: Console
+class CleaningStepResult(Enum):
+    SUCCESS = "success"
+    FAILED = "failed"
+    SKIPPED = "skipped"
 
-    def _analyze_workload_characteristics(self, files: list[Path]) -> dict[str, t.Any]:
-        if not files:
-            return {
-                "total_files": 0,
-                "total_size": 0,
-                "avg_file_size": 0,
-                "complexity": "low",
-            }
-        total_size = 0
-        large_files = 0
-        for file_path in files:
-            try:
-                size = file_path.stat().st_size
-                total_size += size
-                if size > 50_000:
-                    large_files += 1
-            except (OSError, PermissionError):
-                continue
-        avg_file_size = total_size / len(files) if files else 0
-        large_file_ratio = large_files / len(files) if files else 0
-        if len(files) > 100 or avg_file_size > 20_000 or large_file_ratio > 0.3:
-            complexity = "high"
-        elif len(files) > 50 or avg_file_size > 10_000 or large_file_ratio > 0.1:
-            complexity = "medium"
-        else:
-            complexity = "low"
-
-        return {
-            "total_files": len(files),
-            "total_size": total_size,
-            "avg_file_size": avg_file_size,
-            "large_files": large_files,
-            "large_file_ratio": large_file_ratio,
-            "complexity": complexity,
-        }
 
-    def _calculate_optimal_workers(self, workload: dict[str, t.Any]) -> int:
-        import os
+@dataclass
+class CleaningResult:
+    file_path: Path
+    success: bool
+    steps_completed: list[str]
+    steps_failed: list[str]
+    warnings: list[str]
+    original_size: int
+    cleaned_size: int
 
-        cpu_count = os.cpu_count() or 4
-        if workload["complexity"] == "high":
-            max_workers = min(cpu_count // 2, 3)
-        elif workload["complexity"] == "medium":
-            max_workers = min(cpu_count, 6)
-        else:
-            max_workers = min(cpu_count + 2, 8)
 
-        return min(max_workers, workload["total_files"])
+class FileProcessorProtocol(Protocol):
+    def read_file_safely(self, file_path: Path) -> str: ...
+    def write_file_safely(self, file_path: Path, content: str) -> None: ...
+    def backup_file(self, file_path: Path) -> Path: ...
 
-    def clean_files(self, pkg_dir: Path | None) -> None:
-        if pkg_dir is None:
-            return
-        python_files = [
-            file_path
-            for file_path in pkg_dir.rglob("*.py")
-            if not str(file_path.parent).startswith("__")
-        ]
-        if not python_files:
-            return
-        workload = self._analyze_workload_characteristics(python_files)
-        max_workers = self._calculate_optimal_workers(workload)
-        if len(python_files) > 10:
-            self.console.print(
-                f"[dim]Cleaning {workload['total_files']} files "
-                f"({workload['complexity']} complexity) with {max_workers} workers[/dim]"
-            )
-        with ThreadPoolExecutor(max_workers=max_workers) as executor:
-            future_to_file = {
-                executor.submit(self.clean_file, file_path): file_path
-                for file_path in python_files
-            }
-            for future in as_completed(future_to_file):
-                file_path = future_to_file[future]
+
+class CleaningStepProtocol(Protocol):
+    def __call__(self, code: str, file_path: Path) -> str: ...
+
+    @property
+    def name(self) -> str: ...
+
+
+class ErrorHandlerProtocol(Protocol):
+    def handle_file_error(
+        self,
+        file_path: Path,
+        error: Exception,
+        step: str,
+    ) -> None: ...
+    def log_cleaning_result(self, result: CleaningResult) -> None: ...
+
+
+class FileProcessor(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    console: Console
+    logger: t.Any = None
+
+    def model_post_init(self, _: t.Any) -> None:
+        if self.logger is None:
+            import logging
+
+            self.logger = logging.getLogger("crackerjack.code_cleaner.file_processor")
+
+    def read_file_safely(self, file_path: Path) -> str:
+        try:
+            return file_path.read_text(encoding="utf - 8")
+        except UnicodeDecodeError:
+            for encoding in ("latin1", "cp1252"):
                 try:
-                    future.result()
-                except Exception as e:
-                    self.console.print(
-                        f"[bold bright_red]❌ Error cleaning {file_path}: {e}[/bold bright_red]"
+                    content = file_path.read_text(encoding=encoding)
+                    self.logger.warning(
+                        f"File {file_path} read with {encoding} encoding",
                     )
-        self._cleanup_cache_directories(pkg_dir)
-
-    def _cleanup_cache_directories(self, pkg_dir: Path) -> None:
-        with suppress(PermissionError, OSError):
-            pycache_dir = pkg_dir / "__pycache__"
-            if pycache_dir.exists():
-                for cache_file in pycache_dir.iterdir():
-                    with suppress(PermissionError, OSError):
-                        cache_file.unlink()
-                pycache_dir.rmdir()
-            parent_pycache = pkg_dir.parent / "__pycache__"
-            if parent_pycache.exists():
-                for cache_file in parent_pycache.iterdir():
-                    with suppress(PermissionError, OSError):
-                        cache_file.unlink()
-                parent_pycache.rmdir()
-
-    def clean_file(self, file_path: Path) -> None:
-        try:
-            code = file_path.read_text(encoding="utf-8")
-            original_code = code
-            cleaning_failed = False
-            try:
-                code = self.remove_line_comments_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove line comments from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_docstrings_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove docstrings from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_extra_whitespace_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove extra whitespace from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.reformat_code(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to reformat {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            file_path.write_text(code, encoding="utf-8")
-            if cleaning_failed:
-                self.console.print(
-                    f"[bold yellow]⚡ Partially cleaned:[/bold yellow] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-            else:
-                self.console.print(
-                    f"[bold green]✨ Cleaned:[/bold green] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-        except PermissionError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Permission denied)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Permission denied while cleaning {file_path}",
-                    error_code=ErrorCode.PERMISSION_ERROR,
-                    details=str(e),
-                    recovery=f"Check file permissions for {file_path} and ensure you have write access",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except OSError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (File system error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"File system error while cleaning {file_path}",
-                    error_code=ErrorCode.FILE_WRITE_ERROR,
-                    details=str(e),
-                    recovery=f"Check that {file_path} exists and is not being used by another process",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except UnicodeDecodeError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Encoding error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Encoding error while reading {file_path}",
-                    error_code=ErrorCode.FILE_READ_ERROR,
-                    details=str(e),
-                    recovery=f"File {file_path} contains non-UTF-8 characters. Please check the file encoding.",
-                ),
-                console=self.console,
-                exit_on_error=False,
+                    return content
+                except UnicodeDecodeError:
+                    continue
+            raise ExecutionError(
+                message=f"Could not decode file {file_path}",
+                error_code=ErrorCode.FILE_READ_ERROR,
             )
         except Exception as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Unexpected error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Unexpected error while cleaning {file_path}",
-                    error_code=ErrorCode.UNEXPECTED_ERROR,
-                    details=str(e),
-                    recovery="This is an unexpected error. Please report this issue with the file content if possible.",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
+            raise ExecutionError(
+                message=f"Failed to read file {file_path}: {e}",
+                error_code=ErrorCode.FILE_READ_ERROR,
+            ) from e
 
-    def _initialize_docstring_state(self) -> dict[str, t.Any]:
-        return {
-            "in_docstring": False,
-            "delimiter": None,
-            "waiting": False,
-            "function_indent": 0,
-            "removed_docstring": False,
-            "in_multiline_def": False,
-        }
+    def write_file_safely(self, file_path: Path, content: str) -> None:
+        try:
+            file_path.write_text(content, encoding="utf - 8")
+        except Exception as e:
+            raise ExecutionError(
+                message=f"Failed to write file {file_path}: {e}",
+                error_code=ErrorCode.FILE_WRITE_ERROR,
+            ) from e
 
-    def _handle_function_definition(
-        self, line: str, stripped: str, state: dict[str, t.Any]
-    ) -> bool:
-        if self._is_function_or_class_definition(stripped):
-            state["waiting"] = True
-            state["function_indent"] = len(line) - len(line.lstrip())
-            state["removed_docstring"] = False
-            state["in_multiline_def"] = not stripped.endswith(":")
-            return True
-        return False
-
-    def _handle_multiline_definition(
-        self, line: str, stripped: str, state: dict[str, t.Any]
-    ) -> bool:
-        if state["in_multiline_def"]:
-            if stripped.endswith(":"):
-                state["in_multiline_def"] = False
-            return True
-        return False
-
-    def _handle_waiting_docstring(
-        self, lines: list[str], i: int, stripped: str, state: dict[str, t.Any]
-    ) -> tuple[bool, str | None]:
-        if state["waiting"] and stripped:
-            if self._handle_docstring_start(stripped, state):
-                pass_line = None
-                if not state["in_docstring"]:
-                    function_indent: int = state["function_indent"]
-                    if self._needs_pass_statement(lines, i + 1, function_indent):
-                        pass_line = " " * (function_indent + 4) + "pass"
-                state["removed_docstring"] = True
-                return True, pass_line
-            else:
-                state["waiting"] = False
-        return False, None
-
-    def _handle_docstring_content(
-        self, lines: list[str], i: int, stripped: str, state: dict[str, t.Any]
-    ) -> tuple[bool, str | None]:
-        if state["in_docstring"]:
-            if self._handle_docstring_end(stripped, state):
-                pass_line = None
-                function_indent: int = state["function_indent"]
-                if self._needs_pass_statement(lines, i + 1, function_indent):
-                    pass_line = " " * (function_indent + 4) + "pass"
-                state["removed_docstring"] = False
-                return True, pass_line
-            else:
-                return True, None
-        return False, None
-
-    def _process_line(
-        self, lines: list[str], i: int, line: str, state: dict[str, t.Any]
-    ) -> tuple[bool, str | None]:
-        stripped = line.strip()
-        if self._handle_function_definition(line, stripped, state):
-            return True, line
-        if self._handle_multiline_definition(line, stripped, state):
-            return True, line
-        handled, pass_line = self._handle_waiting_docstring(lines, i, stripped, state)
-        if handled:
-            return True, pass_line
-        handled, pass_line = self._handle_docstring_content(lines, i, stripped, state)
-        if handled:
-            return True, pass_line
-        if state["removed_docstring"] and stripped:
-            state["removed_docstring"] = False
-        return False, line
-
-    def remove_docstrings(self, code: str) -> str:
-        lines = code.split("\n")
-        cleaned_lines: list[str] = []
-        docstring_state = self._initialize_docstring_state()
-        for i, line in enumerate(lines):
-            handled, result_line = self._process_line(lines, i, line, docstring_state)
-            if handled:
-                if result_line is not None:
-                    cleaned_lines.append(result_line)
-            else:
-                cleaned_lines.append(line)
-        return "\n".join(cleaned_lines)
+    def backup_file(self, file_path: Path) -> Path:
+        backup_path = file_path.with_suffix(f"{file_path.suffix}.backup")
+        try:
+            backup_path.write_bytes(file_path.read_bytes())
+            return backup_path
+        except Exception as e:
+            raise ExecutionError(
+                message=f"Failed to create backup for {file_path}: {e}",
+                error_code=ErrorCode.FILE_WRITE_ERROR,
+            ) from e
 
-    def _is_function_or_class_definition(self, stripped_line: str) -> bool:
-        return stripped_line.startswith(("def ", "class ", "async def "))
 
-    def _handle_docstring_start(self, stripped: str, state: dict[str, t.Any]) -> bool:
-        if not stripped.startswith(('"""', "'''", '"', "'")):
-            return False
-        if stripped.startswith(('"""', "'''")):
-            delimiter = stripped[:3]
-        else:
-            delimiter = stripped[0]
-        state["delimiter"] = delimiter
-        if self._is_single_line_docstring(stripped, delimiter):
-            state["waiting"] = False
-            return True
+class CleaningErrorHandler(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    console: Console
+    logger: t.Any = None
+
+    def model_post_init(self, _: t.Any) -> None:
+        if self.logger is None:
+            import logging
+
+            self.logger = logging.getLogger("crackerjack.code_cleaner.error_handler")
+
+    def handle_file_error(self, file_path: Path, error: Exception, step: str) -> None:
+        self.console.print(
+            f"[bold bright_yellow]⚠️ Warning: {step} failed for {file_path}: {error}[/bold bright_yellow]",
+        )
+
+        self.logger.warning(
+            "Cleaning step failed",
+            extra={
+                "file_path": str(file_path),
+                "step": step,
+                "error": str(error),
+                "error_type": type(error).__name__,
+            },
+        )
+
+    def log_cleaning_result(self, result: CleaningResult) -> None:
+        if result.success:
+            self.console.print(
+                f"[green]✅ Cleaned {result.file_path}[/green] "
+                f"({result.original_size} → {result.cleaned_size} bytes)",
+            )
         else:
-            state["in_docstring"] = True
-            state["waiting"] = False
-            return True
-
-    def _is_single_line_docstring(self, stripped: str, delimiter: str) -> bool:
-        return stripped.endswith(delimiter) and len(stripped) > len(delimiter)
-
-    def _handle_docstring_end(self, stripped: str, state: dict[str, t.Any]) -> bool:
-        if state["delimiter"] and stripped.endswith(state["delimiter"]):
-            state["in_docstring"] = False
-            state["delimiter"] = None
-            return True
-        return False
-
-    def _needs_pass_statement(
-        self, lines: list[str], start_index: int, function_indent: int
-    ) -> bool:
-        for i in range(start_index, len(lines)):
-            line = lines[i]
-            stripped = line.strip()
-            if not stripped:
-                continue
-            line_indent = len(line) - len(line.lstrip())
-            if line_indent <= function_indent:
-                return True
-            if line_indent > function_indent:
-                return False
-        return True
-
-    def remove_line_comments(self, code: str) -> str:
-        lines = code.split("\n")
-        cleaned_lines: list[str] = []
-        for line in lines:
-            if not line.strip():
-                cleaned_lines.append(line)
-                continue
-            cleaned_line = self._process_line_for_comments(line)
-            if cleaned_line or not line.strip():
-                cleaned_lines.append(cleaned_line or line)
-        return "\n".join(cleaned_lines)
-
-    def _process_line_for_comments(self, line: str) -> str:
-        result: list[str] = []
-        string_state = {"in_string": None}
-        for i, char in enumerate(line):
-            if self._handle_string_character(char, i, line, string_state, result):
-                continue
-            elif self._handle_comment_character(char, i, line, string_state, result):
-                break
-            else:
-                result.append(char)
-        return "".join(result).rstrip()
+            self.console.print(
+                f"[red]❌ Failed to clean {result.file_path}[/red] "
+                f"({len(result.steps_failed)} steps failed)",
+            )
 
-    def _handle_string_character(
-        self,
-        char: str,
-        index: int,
-        line: str,
-        string_state: dict[str, t.Any],
-        result: list[str],
-    ) -> bool:
-        if char not in ("'", '"'):
-            return False
-        if index > 0 and line[index - 1] == "\\":
-            return False
-        if string_state["in_string"] is None:
-            string_state["in_string"] = char
-        elif string_state["in_string"] == char:
-            string_state["in_string"] = None
-        result.append(char)
-        return True
-
-    def _handle_comment_character(
-        self,
-        char: str,
-        index: int,
-        line: str,
-        string_state: dict[str, t.Any],
-        result: list[str],
-    ) -> bool:
-        if char != "#" or string_state["in_string"] is not None:
-            return False
-        comment = line[index:].strip()
-        if self._is_special_comment_line(comment):
-            result.append(line[index:])
-        return True
-
-    def _is_special_comment_line(self, comment: str) -> bool:
-        special_comment_pattern = (
-            r"^#\s*(?:type:\s*ignore(?:\[.*?\])?|noqa|nosec|pragma:\s*no\s*cover"
-            r"|pylint:\s*disable|mypy:\s*ignore)"
+        if result.warnings:
+            for warning in result.warnings:
+                self.console.print(f"[yellow]⚠️ {warning}[/yellow]")
+
+        self.logger.info(
+            "File cleaning completed",
+            extra={
+                "file_path": str(result.file_path),
+                "success": result.success,
+                "steps_completed": result.steps_completed,
+                "steps_failed": result.steps_failed,
+                "original_size": result.original_size,
+                "cleaned_size": result.cleaned_size,
+            },
         )
-        return bool(re.match(special_comment_pattern, comment))
-
-    def remove_extra_whitespace(self, code: str) -> str:
-        lines = code.split("\n")
-        cleaned_lines: list[str] = []
-        function_tracker = {"in_function": False, "function_indent": 0}
-        import_tracker = {"in_imports": False, "last_import_type": None}
-        for i, line in enumerate(lines):
-            line = line.rstrip()
-            stripped_line = line.lstrip()
-            self._update_function_state(line, stripped_line, function_tracker)
-            self._update_import_state(line, stripped_line, import_tracker)
-            if not line:
-                if self._should_skip_empty_line(
-                    i, lines, cleaned_lines, function_tracker, import_tracker
-                ):
-                    continue
-            cleaned_lines.append(line)
-        return "\n".join(self._remove_trailing_empty_lines(cleaned_lines))
 
-    def remove_docstrings_streaming(self, code: str) -> str:
-        if len(code) < 10000:
-            return self.remove_docstrings(code)
 
-        def process_lines():
-            lines = code.split("\n")
-            docstring_state = self._initialize_docstring_state()
-            for i, line in enumerate(lines):
-                handled, result_line = self._process_line(
-                    lines, i, line, docstring_state
-                )
-                if handled:
-                    if result_line is not None:
-                        yield result_line
-                else:
-                    yield line
-
-        return "\n".join(process_lines())
-
-    def remove_line_comments_streaming(self, code: str) -> str:
-        if len(code) < 10000:
-            return self.remove_line_comments(code)
-
-        def process_lines():
-            for line in code.split("\n"):
-                if not line.strip():
-                    yield line
-                    continue
-                cleaned_line = self._process_line_for_comments(line)
-                if cleaned_line or not line.strip():
-                    yield cleaned_line or line
+class CleaningPipeline(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
-        return "\n".join(process_lines())
+    file_processor: t.Any
+    error_handler: t.Any
+    console: Console
+    logger: t.Any = None
 
-    def remove_extra_whitespace_streaming(self, code: str) -> str:
-        if len(code) < 10000:
-            return self.remove_extra_whitespace(code)
+    def model_post_init(self, _: t.Any) -> None:
+        if self.logger is None:
+            import logging
 
-        def process_lines():
-            lines = code.split("\n")
-            function_tracker: dict[str, t.Any] = {
-                "in_function": False,
-                "function_indent": 0,
-            }
-            import_tracker: dict[str, t.Any] = {
-                "in_imports": False,
-                "last_import_type": None,
-            }
-            previous_lines: list[str] = []
-            for i, line in enumerate(lines):
-                line = line.rstrip()
-                stripped_line = line.lstrip()
-                self._update_function_state(line, stripped_line, function_tracker)
-                self._update_import_state(line, stripped_line, import_tracker)
-                if not line:
-                    if self._should_skip_empty_line(
-                        i, lines, previous_lines, function_tracker, import_tracker
-                    ):
-                        continue
-                previous_lines.append(line)
-                yield line
-
-        processed_lines = list(process_lines())
-        return "\n".join(self._remove_trailing_empty_lines(processed_lines))
-
-    def _update_function_state(
-        self, line: str, stripped_line: str, function_tracker: dict[str, t.Any]
-    ) -> None:
-        if stripped_line.startswith(("def ", "async def ")):
-            function_tracker["in_function"] = True
-            function_tracker["function_indent"] = len(line) - len(stripped_line)
-        elif self._is_function_end(line, stripped_line, function_tracker):
-            function_tracker["in_function"] = False
-            function_tracker["function_indent"] = 0
-
-    def _update_import_state(
-        self, line: str, stripped_line: str, import_tracker: dict[str, t.Any]
-    ) -> None:
-        if stripped_line.startswith(("import ", "from ")):
-            import_tracker["in_imports"] = True
-            if self._is_stdlib_import(stripped_line):
-                current_type = "stdlib"
-            elif self._is_local_import(stripped_line):
-                current_type = "local"
-            else:
-                current_type = "third_party"
-            import_tracker["last_import_type"] = current_type
-        elif stripped_line and not stripped_line.startswith("#"):
-            import_tracker["in_imports"] = False
-            import_tracker["last_import_type"] = None
-
-    @staticmethod
-    @lru_cache(maxsize=256)
-    def _is_stdlib_module(module: str) -> bool:
-        stdlib_modules = {
-            "os",
-            "sys",
-            "re",
-            "json",
-            "datetime",
-            "time",
-            "pathlib",
-            "typing",
-            "collections",
-            "itertools",
-            "functools",
-            "operator",
-            "math",
-            "random",
-            "uuid",
-            "urllib",
-            "http",
-            "html",
-            "xml",
-            "email",
-            "csv",
-            "sqlite3",
-            "subprocess",
-            "threading",
-            "multiprocessing",
-            "asyncio",
-            "contextlib",
-            "dataclasses",
-            "enum",
-            "abc",
-            "io",
-            "tempfile",
-            "shutil",
-            "glob",
-            "pickle",
-            "copy",
-            "heapq",
-            "bisect",
-            "array",
-            "struct",
-            "zlib",
-            "hashlib",
-            "hmac",
-            "secrets",
-            "base64",
-            "binascii",
-            "codecs",
-            "locale",
-            "platform",
-            "socket",
-            "ssl",
-            "ipaddress",
-            "logging",
-            "warnings",
-            "inspect",
-            "ast",
-            "dis",
-            "tokenize",
-            "keyword",
-            "linecache",
-            "traceback",
-            "weakref",
-            "gc",
-            "ctypes",
-            "unittest",
-            "doctest",
-            "pdb",
-            "profile",
-            "cProfile",
-            "timeit",
-            "trace",
-            "calendar",
-            "decimal",
-            "fractions",
-            "statistics",
-            "tomllib",
-        }
-        return module in stdlib_modules
+            self.logger = logging.getLogger("crackerjack.code_cleaner.pipeline")
 
-    def _is_stdlib_import(self, stripped_line: str) -> bool:
+    def clean_file(
+        self,
+        file_path: Path,
+        cleaning_steps: list[CleaningStepProtocol],
+    ) -> CleaningResult:
+        self.logger.info(f"Starting clean_file for {file_path}")
         try:
-            if stripped_line.startswith("from "):
-                module = stripped_line.split()[1].split(".")[0]
+            original_code = self.file_processor.read_file_safely(file_path)
+            original_size = len(original_code.encode("utf - 8"))
+
+            result = self._apply_cleaning_pipeline(
+                original_code,
+                file_path,
+                cleaning_steps,
+            )
+
+            if result.success and result.cleaned_code != original_code:
+                self.file_processor.write_file_safely(file_path, result.cleaned_code)
+                cleaned_size = len(result.cleaned_code.encode("utf - 8"))
             else:
-                module = stripped_line.split()[1].split(".")[0]
-        except IndexError:
-            return False
-        return CodeCleaner._is_stdlib_module(module)
-
-    def _is_local_import(self, stripped_line: str) -> bool:
-        return stripped_line.startswith("from .") or " . " in stripped_line
-
-    def _is_function_end(
-        self, line: str, stripped_line: str, function_tracker: dict[str, t.Any]
-    ) -> bool:
-        return (
-            function_tracker["in_function"]
-            and bool(line)
-            and (len(line) - len(stripped_line) <= function_tracker["function_indent"])
-            and (not stripped_line.startswith(("@", "#")))
-        )
+                cleaned_size = original_size
+
+            cleaning_result = CleaningResult(
+                file_path=file_path,
+                success=result.success,
+                steps_completed=result.steps_completed,
+                steps_failed=result.steps_failed,
+                warnings=result.warnings,
+                original_size=original_size,
+                cleaned_size=cleaned_size,
+            )
 
-    def _should_skip_empty_line(
-        self,
-        line_idx: int,
-        lines: list[str],
-        cleaned_lines: list[str],
-        function_tracker: dict[str, t.Any],
-        import_tracker: dict[str, t.Any],
-    ) -> bool:
-        if line_idx > 0 and cleaned_lines and (not cleaned_lines[-1]):
-            return True
-
-        if self._is_import_section_separator(line_idx, lines, import_tracker):
-            return False
-
-        if function_tracker["in_function"]:
-            return self._should_skip_function_empty_line(line_idx, lines)
-        return False
-
-    def _is_import_section_separator(
-        self, line_idx: int, lines: list[str], import_tracker: dict[str, t.Any]
-    ) -> bool:
-        if not import_tracker["in_imports"]:
-            return False
-
-        next_line_idx = line_idx + 1
-        while next_line_idx < len(lines) and not lines[next_line_idx].strip():
-            next_line_idx += 1
-
-        if next_line_idx >= len(lines):
-            return False
-
-        next_line = lines[next_line_idx].strip()
-        if not next_line.startswith(("import ", "from ")):
-            return False
-
-        if self._is_stdlib_import(next_line):
-            next_type = "stdlib"
-        elif self._is_local_import(next_line):
-            next_type = "local"
-        else:
-            next_type = "third_party"
-
-        return import_tracker["last_import_type"] != next_type
-
-    def _should_skip_function_empty_line(self, line_idx: int, lines: list[str]) -> bool:
-        next_line_idx = line_idx + 1
-        if next_line_idx >= len(lines):
-            return False
-        next_line = lines[next_line_idx].strip()
-        return not self._is_significant_next_line(next_line)
-
-    def _is_significant_next_line(self, next_line: str) -> bool:
-        if next_line.startswith(("return", "class ", "def ", "async def ", "@")):
-            return True
-        if next_line in ("pass", "break", "continue", "raise"):
-            return True
-        return self._is_special_comment(next_line)
-
-    def _is_special_comment(self, line: str) -> bool:
-        if not line.startswith("#"):
-            return False
-        special_patterns = ("type:", "noqa", "nosec", "pragma:", "pylint:", "mypy:")
-        return any(pattern in line for pattern in special_patterns)
-
-    def _remove_trailing_empty_lines(self, lines: list[str]) -> list[str]:
-        while lines and (not lines[-1]):
-            lines.pop()
-        return lines
-
-    def reformat_code(self, code: str) -> str:
-        try:
-            import tempfile
+            self.error_handler.log_cleaning_result(cleaning_result)
+            return cleaning_result
+
+        except Exception as e:
+            self.error_handler.handle_file_error(file_path, e, "file_processing")
+            return CleaningResult(
+                file_path=file_path,
+                success=False,
+                steps_completed=[],
+                steps_failed=["file_processing"],
+                warnings=[],
+                original_size=0,
+                cleaned_size=0,
+            )
 
-            with tempfile.NamedTemporaryFile(
-                suffix=".py", mode="w+", delete=False
-            ) as temp:
-                temp_path = Path(temp.name)
-                temp_path.write_text(code)
+    @dataclass
+    class PipelineResult:
+        cleaned_code: str
+        success: bool
+        steps_completed: list[str]
+        steps_failed: list[str]
+        warnings: list[str]
+
+    def _apply_cleaning_pipeline(
+        self,
+        code: str,
+        file_path: Path,
+        cleaning_steps: list[CleaningStepProtocol],
+    ) -> PipelineResult:
+        current_code = code
+        steps_completed: list[str] = []
+        steps_failed: list[str] = []
+        warnings: list[str] = []
+        overall_success = True
+
+        for step in cleaning_steps:
             try:
-                result = subprocess.run(
-                    ["uv", "run", "ruff", "format", str(temp_path)],
-                    check=False,
-                    capture_output=True,
-                    text=True,
+                step_result = step(current_code, file_path)
+                current_code = step_result
+                steps_completed.append(step.name)
+
+                self.logger.debug(
+                    "Cleaning step completed",
+                    extra={"step": step.name, "file_path": str(file_path)},
                 )
-                if result.returncode == 0:
-                    formatted_code = temp_path.read_text()
-                else:
-                    self.console.print(
-                        f"[bold bright_yellow]⚠️  Ruff formatting failed: {result.stderr}[/bold bright_yellow]"
-                    )
-                    handle_error(
-                        ExecutionError(
-                            message="Code formatting failed",
-                            error_code=ErrorCode.FORMATTING_ERROR,
-                            details=result.stderr,
-                            recovery="Check Ruff configuration and formatting rules",
-                        ),
-                        console=self.console,
-                        exit_on_error=False,
-                    )
-                    formatted_code = code
+
             except Exception as e:
-                self.console.print(
-                    f"[bold bright_red]❌ Error running Ruff: {e}[/bold bright_red]"
-                )
-                handle_error(
-                    ExecutionError(
-                        message="Error running Ruff",
-                        error_code=ErrorCode.FORMATTING_ERROR,
-                        details=str(e),
-                        recovery="Verify Ruff is installed and configured correctly",
-                    ),
-                    console=self.console,
-                    exit_on_error=False,
+                self.error_handler.handle_file_error(file_path, e, step.name)
+                steps_failed.append(step.name)
+                warnings.append(f"{step.name} failed: {e}")
+
+                self.logger.warning(
+                    "Cleaning step failed, continuing with original code",
+                    extra={
+                        "step": step.name,
+                        "file_path": str(file_path),
+                        "error": str(e),
+                    },
                 )
-                formatted_code = code
-            finally:
-                with suppress(FileNotFoundError):
-                    temp_path.unlink()
-            return formatted_code
-        except Exception as e:
-            self.console.print(
-                f"[bold bright_red]❌ Error during reformatting: {e}[/bold bright_red]"
+
+        if steps_failed:
+            success_ratio = len(steps_completed) / (
+                len(steps_completed) + len(steps_failed)
             )
-            handle_error(
-                ExecutionError(
-                    message="Error during reformatting",
-                    error_code=ErrorCode.FORMATTING_ERROR,
-                    details=str(e),
-                    recovery="Check file permissions and disk space",
-                ),
+            overall_success = success_ratio >= 0.7
+
+        return self.PipelineResult(
+            cleaned_code=current_code,
+            success=overall_success,
+            steps_completed=steps_completed,
+            steps_failed=steps_failed,
+            warnings=warnings,
+        )
+
+
+class CodeCleaner(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    console: Console
+    file_processor: t.Any = None
+    error_handler: t.Any = None
+    pipeline: t.Any = None
+    logger: t.Any = None
+
+    def model_post_init(self, _: t.Any) -> None:
+        if self.logger is None:
+            import logging
+
+            self.logger = logging.getLogger("crackerjack.code_cleaner")
+
+        if self.file_processor is None:
+            self.file_processor = FileProcessor(console=self.console)
+
+        if self.error_handler is None:
+            self.error_handler = CleaningErrorHandler(console=self.console)
+
+        if self.pipeline is None:
+            self.pipeline = CleaningPipeline(
+                file_processor=self.file_processor,
+                error_handler=self.error_handler,
                 console=self.console,
             )
-            return code
 
-    async def clean_files_async(self, pkg_dir: Path | None) -> None:
-        if pkg_dir is None:
-            return
-        python_files = [
-            file_path
-            for file_path in pkg_dir.rglob("*.py")
-            if not str(file_path.parent).startswith("__")
+    def clean_file(self, file_path: Path) -> CleaningResult:
+        cleaning_steps = [
+            self._create_line_comment_step(),
+            self._create_docstring_step(),
+            self._create_whitespace_step(),
+            self._create_formatting_step(),
         ]
-        if not python_files:
-            return
-        max_concurrent = min(len(python_files), 8)
-        semaphore = asyncio.Semaphore(max_concurrent)
 
-        async def clean_with_semaphore(file_path: Path) -> None:
-            async with semaphore:
-                await self.clean_file_async(file_path)
+        return self.pipeline.clean_file(file_path, cleaning_steps)
 
-        tasks = [clean_with_semaphore(file_path) for file_path in python_files]
-        await asyncio.gather(*tasks, return_exceptions=True)
+    def clean_files(self, pkg_dir: Path | None = None) -> list[CleaningResult]:
+        if pkg_dir is None:
+            pkg_dir = Path.cwd()
+
+        python_files = list(pkg_dir.rglob(" * .py"))
+        results: list[CleaningResult] = []
+
+        self.logger.info(f"Starting clean_files for {len(python_files)} files")
+        for file_path in python_files:
+            if self.should_process_file(file_path):
+                result = self.clean_file(file_path)
+                results.append(result)
+
+        return results
+
+    def should_process_file(self, file_path: Path) -> bool:
+        ignore_patterns = {
+            "__pycache__",
+            ".git",
+            ".venv",
+            "site - packages",
+            ".pytest_cache",
+            "build",
+            "dist",
+        }
 
-        await self._cleanup_cache_directories_async(pkg_dir)
+        for parent in file_path.parents:
+            if parent.name in ignore_patterns:
+                return False
 
-    async def clean_file_async(self, file_path: Path) -> None:
-        try:
-            async with aiofiles.open(file_path, encoding="utf-8") as f:  # type: ignore[misc]
-                code: str = await f.read()  # type: ignore[misc]
-            original_code: str = code
-            cleaning_failed = False
-            try:
-                code = self.remove_line_comments_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove line comments from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_docstrings_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove docstrings from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = self.remove_extra_whitespace_streaming(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to remove extra whitespace from {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            try:
-                code = await self.reformat_code_async(code)
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_yellow]⚠️  Warning: Failed to reformat {file_path}: {e}[/bold bright_yellow]"
-                )
-                code = original_code
-                cleaning_failed = True
-            async with aiofiles.open(file_path, "w", encoding="utf-8") as f:  # type: ignore[misc]
-                await f.write(code)  # type: ignore[misc]
-            if cleaning_failed:
-                self.console.print(
-                    f"[bold yellow]⚡ Partially cleaned:[/bold yellow] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-            else:
-                self.console.print(
-                    f"[bold green]✨ Cleaned:[/bold green] [dim bright_white]{file_path}[/dim bright_white]"
-                )
-        except PermissionError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Permission denied)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Permission denied while cleaning {file_path}",
-                    error_code=ErrorCode.PERMISSION_ERROR,
-                    details=str(e),
-                    recovery=f"Check file permissions for {file_path} and ensure you have write access",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except OSError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (File system error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"File system error while cleaning {file_path}",
-                    error_code=ErrorCode.FILE_WRITE_ERROR,
-                    details=str(e),
-                    recovery=f"Check that {file_path} exists and is not being used by another process",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except UnicodeDecodeError as e:
-            self.console.print(
-                f"[red]Failed to clean: {file_path} (Encoding error)[/red]"
-            )
-            handle_error(
-                ExecutionError(
-                    message=f"Encoding error while cleaning {file_path}",
-                    error_code=ErrorCode.FILE_READ_ERROR,
-                    details=str(e),
-                    recovery=f"Check the file encoding of {file_path} - it may not be UTF-8",
-                ),
-                console=self.console,
-                exit_on_error=False,
-            )
-        except Exception as e:
-            self.console.print(f"[red]Unexpected error cleaning {file_path}: {e}[/red]")
-            handle_error(
-                ExecutionError(
-                    message=f"Unexpected error while cleaning {file_path}",
-                    error_code=ErrorCode.UNEXPECTED_ERROR,
-                    details=str(e),
-                    recovery="Please report this issue with the full error details",
-                ),
-                console=self.console,
-                exit_on_error=False,
+        return not (file_path.name.startswith(".") or file_path.suffix != ".py")
+
+    def _create_line_comment_step(self) -> CleaningStepProtocol:
+        """Create a step for removing line comments while preserving special comments."""
+        return self._LineCommentStep()
+
+    def _create_docstring_step(self) -> CleaningStepProtocol:
+        """Create a step for removing docstrings."""
+        return self._DocstringStep()
+
+    class _DocstringStep:
+        """Step implementation for removing docstrings."""
+
+        name = "remove_docstrings"
+
+        def _is_docstring_node(self, node: ast.AST) -> bool:
+            body = getattr(node, "body", None)
+            return (
+                hasattr(node, "body")
+                and body is not None
+                and len(body) > 0
+                and isinstance(body[0], ast.Expr)
+                and isinstance(body[0].value, ast.Constant)
+                and isinstance(body[0].value.value, str)
             )
 
-    async def reformat_code_async(self, code: str) -> str:
-        try:
-            import tempfile
-
-            with tempfile.NamedTemporaryFile(
-                suffix=".py", mode="w+", delete=False
-            ) as temp:
-                temp_path = Path(temp.name)
-            async with aiofiles.open(temp_path, "w", encoding="utf-8") as f:  # type: ignore[misc]
-                await f.write(code)  # type: ignore[misc]
+        def _find_docstrings(self, tree: ast.AST) -> list[ast.AST]:
+            docstring_nodes: list[ast.AST] = []
+            finder = self._DocstringFinder(docstring_nodes, self._is_docstring_node)
+            finder.visit(tree)
+            return docstring_nodes
+
+        class _DocstringFinder(ast.NodeVisitor):
+            def __init__(
+                self,
+                docstring_nodes: list[ast.AST],
+                is_docstring_node: t.Callable[[ast.AST], bool],
+            ):
+                self.docstring_nodes = docstring_nodes
+                self.is_docstring_node = is_docstring_node
+
+            def _add_if_docstring(self, node: ast.AST) -> None:
+                if self.is_docstring_node(node) and hasattr(node, "body"):
+                    body: list[ast.stmt] = getattr(node, "body")
+                    self.docstring_nodes.append(body[0])
+                self.generic_visit(node)
+
+            def visit_Module(self, node: ast.Module) -> None:
+                self._add_if_docstring(node)
+
+            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                self._add_if_docstring(node)
+
+            def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+                self._add_if_docstring(node)
+
+            def visit_ClassDef(self, node: ast.ClassDef) -> None:
+                self._add_if_docstring(node)
+
+        def __call__(self, code: str, file_path: Path) -> str:
             try:
-                proc = await asyncio.create_subprocess_exec(
-                    "uv",
-                    "run",
-                    "ruff",
-                    "format",
-                    str(temp_path),
-                    stdout=asyncio.subprocess.PIPE,
-                    stderr=asyncio.subprocess.PIPE,
-                )
-                _, stderr = await proc.communicate()
-                if proc.returncode == 0:
-                    async with aiofiles.open(temp_path, encoding="utf-8") as f:  # type: ignore[misc]
-                        formatted_code = await f.read()  # type: ignore[misc]
-                else:
-                    self.console.print(
-                        f"[bold bright_yellow]⚠️  Warning: Ruff format failed with return code {proc.returncode}[/bold bright_yellow]"
-                    )
-                    if stderr:
-                        self.console.print(f"[dim]Ruff stderr: {stderr.decode()}[/dim]")
-                    formatted_code = code
-            except Exception as e:
-                self.console.print(
-                    f"[bold bright_red]❌ Error running Ruff: {e}[/bold bright_red]"
-                )
-                handle_error(
-                    ExecutionError(
-                        message="Error running Ruff",
-                        error_code=ErrorCode.FORMATTING_ERROR,
-                        details=str(e),
-                        recovery="Verify Ruff is installed and configured correctly",
-                    ),
-                    console=self.console,
-                    exit_on_error=False,
-                )
-                formatted_code = code
-            finally:
-                with suppress(FileNotFoundError):
-                    temp_path.unlink()
+                tree = ast.parse(code, filename=str(file_path))
+            except SyntaxError:
+                return self._regex_fallback_removal(code)
 
-            return formatted_code
-        except Exception as e:
-            self.console.print(
-                f"[bold bright_red]❌ Error during reformatting: {e}[/bold bright_red]"
+            docstring_nodes = self._find_docstrings(tree)
+
+            if not docstring_nodes:
+                return code
+
+            lines = code.split("\n")
+            lines_to_remove: set[int] = set()
+
+            for node in docstring_nodes:
+                # Most AST nodes have lineno and end_lineno attributes
+                start_line = getattr(node, "lineno", 1)
+                end_line = getattr(node, "end_lineno", start_line + 1)
+                lines_to_remove.update(range(start_line, end_line))
+
+            result_lines = [
+                line for i, line in enumerate(lines, 1) if i not in lines_to_remove
+            ]
+
+            result = "\n".join(result_lines)
+            return self._regex_fallback_removal(result)
+
+        def _regex_fallback_removal(self, code: str) -> str:
+            import re
+
+            patterns = [
+                r'^\s*""".*?"""\s*$',
+                r"^\s*'''.*?'''\s*$",
+                r'^\s*""".*?"""\s*$',
+                r"^\s*'''.*?'''\s*$",
+            ]
+            result = code
+            for pattern in patterns:
+                result = re.sub(pattern, "", result, flags=re.MULTILINE | re.DOTALL)
+            return result
+
+    class _LineCommentStep:
+        """Step implementation for removing line comments."""
+
+        name = "remove_line_comments"
+
+        def __call__(self, code: str, file_path: Path) -> str:
+            lines = code.split("\n")
+            # Performance: Use list comprehension instead of generator for small-to-medium files
+            processed_lines = [self._process_line_for_comments(line) for line in lines]
+            return "\n".join(processed_lines)
+
+        def _process_line_for_comments(self, line: str) -> str:
+            """Process a single line to remove comments while preserving strings."""
+            if not line.strip() or self._is_preserved_comment_line(line):
+                return line
+            return self._remove_comment_from_line(line)
+
+        def _is_preserved_comment_line(self, line: str) -> bool:
+            """Check if this comment line should be preserved."""
+            stripped = line.strip()
+            if not stripped.startswith("#"):
+                return False
+            return self._has_preserved_pattern(stripped)
+
+        def _has_preserved_pattern(self, stripped_line: str) -> bool:
+            """Check if line contains preserved comment patterns."""
+            preserved_patterns = ["coding: ", "encoding: ", "type: ", "noqa", "pragma"]
+            return stripped_line.startswith("# !/ ") or any(
+                pattern in stripped_line for pattern in preserved_patterns
             )
-            handle_error(
-                ExecutionError(
-                    message="Error during reformatting",
-                    error_code=ErrorCode.FORMATTING_ERROR,
-                    details=str(e),
-                    recovery="Check file permissions and disk space",
-                ),
-                console=self.console,
-                exit_on_error=False,
+
+        def _remove_comment_from_line(self, line: str) -> str:
+            """Remove comments from a line while preserving string literals."""
+            result: list[str] = []
+            string_state: dict[str, t.Any] = {"in_string": False, "quote_char": None}
+            for i, char in enumerate(line):
+                if self._should_break_at_comment(char, string_state):
+                    break
+                self._update_string_state(char, i, line, string_state)
+                result.append(char)
+            return "".join(result).rstrip()
+
+        def _should_break_at_comment(self, char: str, state: dict[str, t.Any]) -> bool:
+            """Check if we should break at a comment character."""
+            return not state["in_string"] and char == "#"
+
+        def _update_string_state(
+            self,
+            char: str,
+            index: int,
+            line: str,
+            state: dict[str, t.Any],
+        ) -> None:
+            """Update string parsing state based on current character."""
+            if self._is_string_start(char, state):
+                state["in_string"], state["quote_char"] = True, char
+            elif self._is_string_end(char, index, line, state):
+                state["in_string"], state["quote_char"] = False, None
+
+        def _is_string_start(self, char: str, state: dict[str, t.Any]) -> bool:
+            """Check if character starts a string."""
+            return not state["in_string"] and char in ('"', "'")
+
+        def _is_string_end(
+            self,
+            char: str,
+            index: int,
+            line: str,
+            state: dict[str, t.Any],
+        ) -> bool:
+            """Check if character ends a string."""
+            return (
+                state["in_string"]
+                and char == state["quote_char"]
+                and (index == 0 or line[index - 1] != "\\")
             )
-            return code
-
-    async def _cleanup_cache_directories_async(self, pkg_dir: Path) -> None:
-        def cleanup_sync() -> None:
-            with suppress(PermissionError, OSError):
-                pycache_dir = pkg_dir / "__pycache__"
-                if pycache_dir.exists():
-                    for cache_file in pycache_dir.iterdir():
-                        with suppress(PermissionError, OSError):
-                            cache_file.unlink()
-                    pycache_dir.rmdir()
-                parent_pycache = pkg_dir.parent / "__pycache__"
-                if parent_pycache.exists():
-                    for cache_file in parent_pycache.iterdir():
-                        with suppress(PermissionError, OSError):
-                            cache_file.unlink()
-                    parent_pycache.rmdir()
-
-        loop = asyncio.get_event_loop()
-        await loop.run_in_executor(None, cleanup_sync)
+
+    def _create_docstring_finder_class(
+        self,
+        docstring_nodes: list[ast.AST],
+    ) -> type[ast.NodeVisitor]:
+        class DocstringFinder(ast.NodeVisitor):
+            def _is_docstring_node(self, node: ast.AST) -> bool:
+                body = getattr(node, "body", None)
+                return (
+                    hasattr(node, "body")
+                    and body is not None
+                    and len(body) > 0
+                    and isinstance(body[0], ast.Expr)
+                    and isinstance(body[0].value, ast.Constant)
+                    and isinstance(body[0].value.value, str)
+                )
+
+            def _add_if_docstring(self, node: ast.AST) -> None:
+                if self._is_docstring_node(node) and hasattr(node, "body"):
+                    body: list[ast.stmt] = getattr(node, "body")
+                    docstring_nodes.append(body[0])
+                self.generic_visit(node)
+
+            def visit_Module(self, node: ast.Module) -> None:
+                self._add_if_docstring(node)
+
+            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                self._add_if_docstring(node)
+
+            def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+                self._add_if_docstring(node)
+
+            def visit_ClassDef(self, node: ast.ClassDef) -> None:
+                self._add_if_docstring(node)
+
+        return DocstringFinder
+
+    def _create_whitespace_step(self) -> CleaningStepProtocol:
+        class WhitespaceStep:
+            name = "remove_extra_whitespace"
+
+            def __call__(self, code: str, file_path: Path) -> str:
+                import re
+
+                lines = code.split("\n")
+                cleaned_lines: list[str] = []
+
+                empty_line_count = 0
+
+                for line in lines:
+                    cleaned_line = line.rstrip()
+
+                    if not cleaned_line.strip():
+                        empty_line_count += 1
+                        if empty_line_count <= 2:
+                            cleaned_lines.append("")
+                    else:
+                        empty_line_count = 0
+
+                        leading_whitespace = len(cleaned_line) - len(
+                            cleaned_line.lstrip(),
+                        )
+                        content = cleaned_line.lstrip()
+
+                        content = re.sub(r" {2, }", " ", content)
+
+                        cleaned_line = cleaned_line[:leading_whitespace] + content
+                        cleaned_lines.append(cleaned_line)
+
+                while cleaned_lines and not cleaned_lines[-1].strip():
+                    cleaned_lines.pop()
+
+                result = "\n".join(cleaned_lines)
+                if result and not result.endswith("\n"):
+                    result += "\n"
+
+                return result
+
+        return WhitespaceStep()
+
+    def _create_formatting_step(self) -> CleaningStepProtocol:
+        class FormattingStep:
+            name = "format_code"
+
+            def __call__(self, code: str, file_path: Path) -> str:
+                import re
+
+                lines = code.split("\n")
+                formatted_lines: list[str] = []
+
+                for line in lines:
+                    if line.strip():
+                        leading_whitespace = len(line) - len(line.lstrip())
+                        content = line.lstrip()
+
+                        content = re.sub(
+                            r"([ =+ \ -*/%<>!&|^ ])([ ^ =+ \ -*/%<>!&|^ ])",
+                            r"\1 \2",
+                            content,
+                        )
+                        content = re.sub(
+                            r"([ ^ =+ \ -*/%<>!&|^ ])([ =+ \ -*/%<>!&|^ ])",
+                            r"\1 \2",
+                            content,
+                        )
+
+                        content = re.sub(r", ([ ^ \n])", r", \1", content)
+
+                        content = re.sub(r": ([ ^ \n: ])", r": \1", content)
+
+                        content = re.sub(r" {2, }", " ", content)
+
+                        formatted_line = line[:leading_whitespace] + content
+                        formatted_lines.append(formatted_line)
+                    else:
+                        formatted_lines.append(line)
+
+                return "\n".join(formatted_lines)
+
+        return FormattingStep()
+
+    def remove_line_comments(self, code: str, file_path: Path | None = None) -> str:
+        file_path = file_path or Path("temp.py")
+        step = self._create_line_comment_step()
+        return step(code, file_path)
+
+    def remove_docstrings(self, code: str, file_path: Path | None = None) -> str:
+        file_path = file_path or Path("temp.py")
+        step = self._create_docstring_step()
+        return step(code, file_path)
+
+    def remove_extra_whitespace(self, code: str, file_path: Path | None = None) -> str:
+        file_path = file_path or Path("temp.py")
+        step = self._create_whitespace_step()
+        return step(code, file_path)
+
+    def format_code(self, code: str, file_path: Path | None = None) -> str:
+        file_path = file_path or Path("temp.py")
+        step = self._create_formatting_step()
+        return step(code, file_path)