devklean 1.0.0__py3-none-any.whl

devklean/output/scan_payload.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from devklean.formatting import format_size
+from devklean.models import CleanableItem
+from devklean.output.sorting import items_by_size_desc
+
+SCAN_OUTPUT_VERSION = "1.0"
+
+
+def build_scan_payload(
+    root: str,
+    items: list[CleanableItem],
+    permission_errors: Sequence[str] = (),
+) -> dict:
+    """Build the canonical scan result structure for renderers and tooling."""
+    sorted_items = items_by_size_desc(items)
+    total_size = sum(item.size for item in items)
+
+    return {
+        "version": SCAN_OUTPUT_VERSION,
+        "root": root,
+        "items": [serialize_cleanable_item(item) for item in sorted_items],
+        "permission_errors": list(permission_errors),
+        "summary": {
+            "count": len(sorted_items),
+            "total_size": total_size,
+            "formatted_total_size": format_size(total_size),
+        },
+    }
+
+
+def serialize_cleanable_item(item: CleanableItem) -> dict:
+    return {
+        "path": item.path,
+        "display_name": item.display_label,
+        "size": item.size,
+        "formatted_size": format_size(item.size),
+        "type": item.name,
+    }
+
+
+def build_error_payload(code: str, message: str) -> dict:
+    return {
+        "version": SCAN_OUTPUT_VERSION,
+        "error": {
+            "code": code,
+            "message": message,
+        },
+    }

devklean/output/sorting.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from devklean.models import CleanableItem
+
+
+def items_by_size_desc(items: list[CleanableItem]) -> list[CleanableItem]:
+    """Return items sorted largest-first by size.
+
+    Safe: sort is stable; equal sizes retain relative order. Used by all
+    output paths so sort logic lives in one place without affecting scan order.
+    """
+    return sorted(items, key=lambda item: item.size, reverse=True)

devklean/output/text.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from devklean.deletion.history import HistoryOperation
+from devklean.deletion.integrity import IntegrityReport
+from devklean.formatting import format_size, format_timestamp
+from devklean.models import CleanableItem, DeleteResult
+from devklean.output.console import SYM_ERROR, SYM_SUCCESS, Console
+from devklean.output.sorting import items_by_size_desc
+
+
+class TextRenderer:
+    """Color-gated terminal output with a standardized symbol scheme."""
+
+    def __init__(self, console: Console | None = None) -> None:
+        self._console = console if console is not None else Console()
+
+    def _println(self, text: str = "") -> None:
+        self._console.plain(text)
+
+    def scan_start(self, root: str) -> None:
+        c = self._console
+        banner = f"{c.paint('devklean', 'bold')} {c.paint(f'scanning {root}...', 'detail')}"
+        self._println(f"\n{banner}\n")
+
+    def scan_summary(self, items: list[CleanableItem]) -> int:
+        c = self._console
+        total_size = sum(item.size for item in items)
+
+        self._println(f"{'TYPE':<18} {'SIZE':>8}  {'PATH'}")
+        self._println(c.paint("─" * 70, "detail"))
+
+        for item in items_by_size_desc(items):
+            role = "error" if item.size > 50 * 1024 * 1024 else "warning"
+            self._println(
+                f"{c.paint(f'{item.display_label:<18}', 'detail')} "
+                f"{c.paint(f'{format_size(item.size):>8}', role)}  "
+                f"{c.paint(item.path, 'detail')}"
+            )
+
+        self._println(c.paint("─" * 70, "detail"))
+        total = c.paint(c.paint(f"{format_size(total_size):>8}", "bold"), "error")
+        self._println(f"{'TOTAL':<18} {total}\n")
+
+        return total_size
+
+    def nothing_to_clean(self) -> None:
+        self._console.success("Nothing to clean.")
+        self._println()
+
+    def dry_run_nothing_deleted(self) -> None:
+        self._console.warning("[dry-run] would delete nothing.")
+        self._println()
+
+    def dry_run_selected(self, count: int) -> None:
+        word = "directory" if count == 1 else "directories"
+        self._console.warning(f"[dry-run] would delete {count} {word}; nothing deleted.")
+        self._println()
+
+    def aborted(self) -> None:
+        self._println()
+        self._console.detail("Aborted. Nothing deleted.")
+        self._println()
+
+    def no_items_selected(self) -> None:
+        self._println()
+        self._console.detail("No items selected. Nothing deleted.")
+        self._println()
+
+    def invalid_directory(self, path: str) -> None:
+        self._console.error(f"'{path}' is not a directory.")
+
+    def confirm_prompt(self, count: int, total_size: int = 0) -> str:
+        word = "directory" if count == 1 else "directories"
+        return (
+            f"{self._console.paint('Delete', 'bold')} {count} {word} "
+            f"(~{format_size(total_size)})? "
+            f"{self._console.paint('(y/N)', 'detail')} "
+        )
+
+    def deletion_result(self, result: DeleteResult) -> None:
+        c = self._console
+        self._println()
+        for path in result.deleted:
+            self._println(f"  {c.paint(SYM_SUCCESS, 'success')} {c.paint(path, 'detail')}")
+        for failure in result.failed:
+            self._println(f"  {c.paint(SYM_ERROR, 'error')} {failure.path} — {failure.error}")
+
+        deleted = result.deleted_count
+        word = "directory" if deleted == 1 else "directories"
+        self._println()
+        self._console.success(
+            c.paint(f"Cleaned {deleted} {word}, freed ~{format_size(result.total_size)}.", "bold")
+        )
+        if result.failed_count:
+            self._console.error(f"{result.failed_count} failed.")
+        self._println()
+
+    def permission_warnings(self, paths: Sequence[str]) -> None:
+        if not paths:
+            return
+        count = len(paths)
+        plural = "s" if count != 1 else ""
+        self._console.warning(f"Skipped {count} path{plural} (permission denied):")
+        for path in paths:
+            self._console.detail(f"    {path}")
+
+    def history(
+        self,
+        operations: Sequence[HistoryOperation],
+        invalid_count: int,
+    ) -> None:
+        c = self._console
+        if not operations:
+            c.detail("No cleanup history.")
+            self._print_invalid_note(invalid_count)
+            return
+
+        self._println(f"\n{c.paint('Cleanup history', 'bold')}\n")
+        self._println(f"{'WHEN':<18} {'SIZE':>9}  {'STRATEGY':<10} {'ITEMS':>5}")
+        self._println(c.paint("─" * 48, "detail"))
+
+        for op in operations:
+            self._println(
+                f"{c.paint(f'{format_timestamp(op.timestamp):<18}', 'detail')} "
+                f"{c.paint(f'{format_size(op.reclaimed_size):>9}', 'success')}  "
+                f"{op.strategy:<10} "
+                f"{op.item_count:>5}"
+            )
+        self._println()
+        self._print_invalid_note(invalid_count)
+
+    def _print_invalid_note(self, invalid_count: int) -> None:
+        if invalid_count:
+            plural = "s" if invalid_count != 1 else ""
+            self._console.warning(
+                f"Skipped {invalid_count} corrupt metadata record{plural} "
+                f"— run `devklean doctor` to inspect."
+            )
+
+    # --- doctor ---
+
+    def doctor_healthy(self) -> None:
+        self._console.success("Metadata store is healthy.")
+
+    def doctor_corruption_report(self, report: IntegrityReport) -> None:
+        c = self._console
+        self._println()
+        c.warning(
+            c.paint(f"CORRUPT ({len(report.corrupt)})", "error")
+            + " — unparseable metadata, will be removed on confirmation"
+        )
+        for entry in report.corrupt:
+            c.detail(f"  {SYM_ERROR} {entry.path.name}  — {entry.reason}")
+
+    def doctor_confirm_prompt(self, count: int) -> str:
+        plural = "s" if count != 1 else ""
+        return f"\nRemove {count} corrupt metadata record{plural}? (y/N) "
+
+    def doctor_kept(self) -> None:
+        self._console.detail("Kept all records. Nothing removed.")
+
+    def doctor_removed(self, removed: int) -> None:
+        plural = "s" if removed != 1 else ""
+        self._println()
+        self._console.success(f"Removed {removed} corrupt metadata record{plural}.")
+
+    def doctor_remove_error(self, name: str, error: str) -> None:
+        self._console.error(f"could not remove {name}: {error}")
+
+    # --- restore ---
+
+    def restore_help(self) -> None:
+        c = self._console
+        c.info("devklean moves deleted items to your system trash, not to a devklean-owned store.")
+        self._println()
+        c.detail("To recover something you deleted:")
+        c.detail("  • Windows — open the Recycle Bin and restore the item.")
+        c.detail("  • macOS   — open Trash in Finder and 'Put Back'.")
+        c.detail("  • Linux   — open Trash in your file manager and restore.")
+        self._println()
+        c.detail("Run `devklean history` to see what was removed and when.")

devklean/output/theme.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Palette:
+    """ANSI codes for semantic roles. Empty strings mean 'no color'."""
+
+    green: str
+    red: str
+    yellow: str
+    cyan: str
+    dim: str
+    bold: str
+    reset: str
+
+
+_COLOR_PALETTE = Palette(
+    green="\033[32m",
+    red="\033[31m",
+    yellow="\033[33m",
+    cyan="\033[36m",
+    dim="\033[2m",
+    bold="\033[1m",
+    reset="\033[0m",
+)
+
+_MONO_PALETTE = Palette(green="", red="", yellow="", cyan="", dim="", bold="", reset="")
+
+
+@dataclass(frozen=True)
+class Theme:
+    name: str
+    palette: Palette
+
+
+_THEMES = {
+    "default": Theme(name="default", palette=_COLOR_PALETTE),
+    "mono": Theme(name="mono", palette=_MONO_PALETTE),
+}
+
+
+def get_theme(name: str) -> Theme:
+    """Return the named theme, falling back to 'default' for unknown names."""
+    return _THEMES.get(name, _THEMES["default"])

devklean/scanner/__init__.py

@@ -0,0 +1,17 @@
+from devklean.config.defaults import DEFAULT_TARGETS
+from devklean.scanner.filters import (
+    dir_is_under_ignored_path,
+    normalize_paths,
+    path_is_excluded,
+)
+from devklean.scanner.scanner import ScanResult, get_dir_size, scan_tree
+
+__all__ = [
+    "DEFAULT_TARGETS",
+    "ScanResult",
+    "dir_is_under_ignored_path",
+    "get_dir_size",
+    "normalize_paths",
+    "path_is_excluded",
+    "scan_tree",
+]

devklean/scanner/filters.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+
+
+def normalize_paths(paths: frozenset[str] | set[str] | list[str] | tuple[str, ...]) -> set[str]:
+    if not paths:
+        return set()
+    return {os.path.abspath(os.path.expanduser(path)) for path in paths}
+
+
+def dir_is_under_ignored_path(dirpath: str, ignored_paths: set[str]) -> bool:
+    """Return True when ``dirpath`` is inside an ignored path.
+
+    Safe: callers pass absolute ``dirpath`` values from ``os.walk(abspath(root))``
+    and absolute entries in ``ignored_paths`` from ``normalize_paths``.
+    """
+    for ignored_path in ignored_paths:
+        if dirpath == ignored_path or dirpath.startswith(ignored_path + os.sep):
+            return True
+    return False
+
+
+def path_is_excluded(full_path: str, ignored_paths: set[str]) -> bool:
+    """Return True when ``full_path`` should be excluded from scan results.
+
+    Safe: same absolute-path precondition as ``dir_is_under_ignored_path``.
+    """
+    for ignored_path in ignored_paths:
+        if full_path == ignored_path or full_path.startswith(ignored_path + os.sep):
+            return True
+    return False

devklean/scanner/scanner.py

@@ -0,0 +1,170 @@
+"""Scanner performance notes.
+
+Before (per directory visited during ``os.walk``):
+- Rebuilt ``dirnames`` via list comprehension (new list allocation).
+- Copied ``dirnames`` with ``list()`` for safe removal during iteration.
+- Called ``dirnames.remove`` multiple times (O(n) each).
+- Called ``os.path.abspath`` on every ``dirpath`` and matched path.
+- Ran ignore-path checks even when the ignore list was empty.
+
+After:
+- Single-pass ``dirnames`` filtering via slice assignment (one list built per node).
+- ``root`` normalized once so walk paths stay absolute; filters skip ``abspath``.
+- Ignore-path checks gated on ``has_ignored_paths`` (empty config = no work).
+- Directory-name ignore checks gated on ``has_ignored_directories``.
+- ``active_targets[dirname]`` used directly after membership test (no redundant ``.get``).
+
+Complexity (unchanged asymptotics, improved constants):
+- Walk: still O(N) over filesystem nodes under ``root``.
+- Per node: O(d) directory entries; target/ignore lookups O(1) average.
+- Found-path pruning: O(1) per child via ``found_paths`` set (unchanged).
+
+Sizing and concurrency (qualitative before/after):
+- Sizing: ``get_dir_size`` moved from ``os.walk`` + ``os.path.getsize`` (which
+  re-``stat``s every file) to ``os.scandir`` + ``entry.stat`` (cached stat, one
+  syscall per entry). Symlinked dirs/files are skipped, so no double-counting.
+- Concurrency: target sizing was sequential (each target's subtree walked one
+  after another). It now runs on a bounded ``ThreadPoolExecutor`` — sizing is
+  I/O-bound, so wide trees with many targets see real wall-clock wins. Discovery
+  stays a single deterministic walk; result order is preserved (map keeps input
+  order), so output is identical to the sequential version.
+- Memory: only per-directory totals are retained (never a list of every file),
+  unchanged — large scans stay bounded by the number of matched targets, not
+  the number of files.
+
+All changes preserve behavior: same targets matched, same paths ignored, same
+sizes reported, same traversal boundaries (no recursion into matched targets).
+"""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+
+from devklean.config.models import ScanSettings
+from devklean.models import CleanableItem
+from devklean.scanner.filters import (
+    dir_is_under_ignored_path,
+    normalize_paths,
+    path_is_excluded,
+)
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    """Discovered cleanable items plus paths skipped due to permission errors."""
+
+    items: list[CleanableItem]
+    permission_errors: list[str] = field(default_factory=list)
+
+
+def get_dir_size(path: str) -> int:
+    """Return the combined byte size of all regular files under ``path``.
+
+    Uses ``os.scandir`` with ``entry.stat(follow_symlinks=False)``, which:
+    - avoids the redundant ``stat`` that ``os.path.getsize`` performs after
+      ``os.walk`` (scandir caches the entry's stat where the OS provides it),
+    - never traverses symlinked directories and never counts symlinked files,
+      so symlinks/hardlink aliases are not double-counted,
+    - counts regular files only.
+    """
+    total = 0
+    stack = [path]
+    while stack:
+        current = stack.pop()
+        try:
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            stack.append(entry.path)
+                        elif entry.is_file(follow_symlinks=False):
+                            total += entry.stat(follow_symlinks=False).st_size
+                    except OSError:
+                        pass
+        except OSError:
+            pass
+    return total
+
+
+def scan_tree(root: str, settings: ScanSettings | None = None) -> ScanResult:
+    """Discover cleanable directories, reporting permission-denied paths.
+
+    Permission errors during traversal are collected (via ``os.walk``'s
+    ``onerror`` hook) rather than silently swallowed, so the caller can tell the
+    user which paths were skipped. Scanning continues past them.
+    """
+    active = settings or ScanSettings.defaults()
+
+    # Safe: absolute root => os.walk yields absolute dirpaths; ignored paths
+    # are normalized the same way in ConfigManager / normalize_paths.
+    root = os.path.abspath(root)
+    ignored_paths = normalize_paths(active.ignored_paths)
+    has_ignored_paths = bool(ignored_paths)
+    ignored_directories = active.ignored_directories
+    has_ignored_directories = bool(ignored_directories)
+    active_targets = active.targets
+
+    # Discovery is a single deterministic pass; sizing (the real cost) is
+    # deferred so it can run concurrently afterwards.
+    matched: list[tuple[str, str]] = []  # (child_path, dirname)
+    found_paths: set[str] = set()
+    permission_errors: list[str] = []
+
+    def _on_walk_error(error: OSError) -> None:
+        if isinstance(error, PermissionError):
+            permission_errors.append(error.filename or str(error))
+
+    for dirpath, dirnames, _ in os.walk(
+        root, topdown=True, followlinks=False, onerror=_on_walk_error
+    ):
+        if has_ignored_paths and dir_is_under_ignored_path(dirpath, ignored_paths):
+            dirnames.clear()
+            continue
+
+        kept_dirnames: list[str] = []
+        for dirname in dirnames:
+            if has_ignored_directories and dirname in ignored_directories:
+                continue
+
+            child_path = os.path.join(dirpath, dirname)
+
+            if child_path in found_paths:
+                continue
+
+            if dirname in active_targets:
+                if has_ignored_paths and path_is_excluded(child_path, ignored_paths):
+                    continue
+                matched.append((child_path, dirname))
+                found_paths.add(child_path)
+                continue
+
+            kept_dirnames.append(dirname)
+
+        dirnames[:] = kept_dirnames
+
+    sizes = _compute_sizes_concurrently([path for path, _ in matched])
+    found = [
+        CleanableItem(
+            path=child_path,
+            name=dirname,
+            size=size,
+            display_label=active_targets[dirname],
+        )
+        for (child_path, dirname), size in zip(matched, sizes)
+    ]
+
+    return ScanResult(items=found, permission_errors=permission_errors)
+
+
+def _compute_sizes_concurrently(paths: list[str]) -> list[int]:
+    """Compute directory sizes in parallel (I/O-bound). Order is preserved."""
+    if not paths:
+        return []
+    if len(paths) == 1:
+        return [get_dir_size(paths[0])]
+
+    workers = min(32, (os.cpu_count() or 1) * 5, len(paths))
+    with ThreadPoolExecutor(max_workers=workers) as executor:
+        return list(executor.map(get_dir_size, paths))

devklean/tui.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from devklean.cli.confirmation import (
+    DEFAULT_LARGE_THRESHOLD,
+    confirm_large_deletion,
+    exceeds_threshold,
+)
+from devklean.deletion import SafetyValidator, delete_items
+from devklean.formatting import format_size, truncate
+from devklean.models import CleanableItem
+from devklean.output.base import Renderer
+from devklean.output.sorting import items_by_size_desc
+
+
+def interactive_ui(stdscr, items: list[CleanableItem], dry_run: bool) -> list[int] | None:
+    import curses  # Unix-only; imported lazily so this module loads on Windows.
+
+    curses.curs_set(0)
+    stdscr.keypad(True)
+
+    selected = [False] * len(items)
+    idx = 0
+    top = 0
+
+    while True:
+        stdscr.erase()
+        height, width = stdscr.getmaxyx()
+
+        header = "devklean interactive - SPACE select | A all | D none | ENTER confirm | Q/ESC quit"
+        stdscr.addnstr(0, 0, truncate(header, width), width)
+
+        list_top = 1
+        list_height = max(0, height - 3)
+        footer_y = height - 1
+
+        if len(items) == 0:
+            stdscr.addnstr(
+                list_top,
+                0,
+                "No matching directories found — press Q to exit.",
+                width,
+            )
+        else:
+            if idx < top:
+                top = idx
+            if idx >= top + list_height:
+                top = idx - list_height + 1
+
+            for row in range(list_height):
+                i = top + row
+                if i >= len(items):
+                    break
+                item = items[i]
+                mark = "x" if selected[i] else " "
+                line = f"[{mark}] {item.display_label:<18} {format_size(item.size):>8} {item.path}"
+                line = truncate(line, width)
+                if i == idx:
+                    stdscr.addnstr(list_top + row, 0, line, width, curses.A_REVERSE)
+                else:
+                    stdscr.addnstr(list_top + row, 0, line, width)
+
+        selected_count = sum(1 for s in selected if s)
+        selected_size = sum(items[i].size for i, s in enumerate(selected) if s)
+        footer = f"Selected: {selected_count}/{len(items)}  Total: {format_size(selected_size)}"
+        if dry_run:
+            footer += "  [dry-run: would delete, nothing removed]"
+        stdscr.addnstr(footer_y, 0, truncate(footer, width), width)
+
+        stdscr.refresh()
+
+        key = stdscr.getch()
+        if key in (ord("q"), ord("Q"), 27):
+            return None
+        if key in (curses.KEY_UP,):
+            if idx > 0:
+                idx -= 1
+        elif key in (curses.KEY_DOWN,):
+            if idx < len(items) - 1:
+                idx += 1
+        elif key == ord(" "):
+            if len(items) > 0:
+                selected[idx] = not selected[idx]
+        elif key in (ord("a"), ord("A")):
+            selected = [True] * len(items)
+        elif key in (ord("d"), ord("D")):
+            selected = [False] * len(items)
+        elif key in (curses.KEY_ENTER, 10, 13):
+            return [i for i, s in enumerate(selected) if s]
+
+
+def run_interactive(
+    renderer: Renderer,
+    found: list[CleanableItem],
+    dry_run: bool,
+    validator: SafetyValidator | None = None,
+    *,
+    confirm_threshold: int = DEFAULT_LARGE_THRESHOLD,
+) -> None:
+    import curses  # Unix-only; imported lazily so this module loads on Windows.
+
+    items = items_by_size_desc(found)
+
+    selected_indices = curses.wrapper(interactive_ui, items, dry_run)
+    if selected_indices is None:
+        renderer.aborted()
+        return
+
+    selected = [items[i] for i in selected_indices]
+    if not selected:
+        renderer.no_items_selected()
+        return
+
+    total_size = sum(item.size for item in selected)
+
+    if dry_run:
+        renderer.dry_run_selected(len(selected))
+        return
+
+    # Large selections require an explicit typed confirmation even here.
+    if exceeds_threshold(total_size, confirm_threshold):
+        if not confirm_large_deletion(len(selected), total_size, confirm_threshold):
+            renderer.aborted()
+            return
+
+    result = delete_items(selected, total_size, validator=validator)
+    renderer.deletion_result(result)