devklean 1.0.0__py3-none-any.whl

devklean/config/manager.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from devklean.config.models import AppConfig, DefaultsConfig
+from devklean.config.paths import get_config_path
+from devklean.config.targets import merge_targets
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib
+
+PROJECT_CONFIG_NAME = ".devklean.toml"
+
+_KNOWN_TOP_LEVEL = {"defaults", "targets", "ignore", "exclude"}
+_KNOWN_DEFAULTS = {
+    "dry_run",
+    "interactive",
+    "path",
+    "default_yes",
+    "theme",
+    "confirm_threshold",
+}
+
+
+@dataclass(frozen=True)
+class ConfigLoadResult:
+    config: AppConfig
+    warnings: list[str]
+
+
+class ConfigManager:
+    """Load and merge user configuration with built-in defaults.
+
+    Precedence (lowest to highest): built-in defaults < global config file <
+    project ``.devklean.toml`` discovered by walking up from the start dir.
+    Scalar keys take the highest-precedence value; list keys are unioned.
+    """
+
+    def __init__(
+        self,
+        config_path: Path | None = None,
+        project_dir: Path | None = None,
+    ) -> None:
+        self._config_path = config_path if config_path is not None else get_config_path()
+        self._project_dir = project_dir if project_dir is not None else Path.cwd()
+
+    @property
+    def config_path(self) -> Path:
+        return self._config_path
+
+    def load(self) -> AppConfig:
+        return self.load_full().config
+
+    def load_full(self) -> ConfigLoadResult:
+        warnings: list[str] = []
+
+        global_raw = self._read_toml(self._config_path, warnings)
+        _validate(global_raw, str(self._config_path), warnings)
+
+        project_path = self._find_project_config()
+        project_raw: dict[str, Any] = {}
+        if project_path is not None:
+            project_raw = self._read_toml(project_path, warnings)
+            _validate(project_raw, str(project_path), warnings)
+
+        # Layers in increasing precedence.
+        config = self._build_config([global_raw, project_raw])
+        return ConfigLoadResult(config=config, warnings=warnings)
+
+    def apply_defaults(self, args, raw_argv: list[str]) -> None:
+        """Apply configured defaults when the CLI did not override them."""
+        config = getattr(args, "_config", None)
+        if config is None:
+            return
+
+        if getattr(args, "command", None) == "clean":
+            if "--dry-run" not in raw_argv:
+                args.dry_run = config.defaults.dry_run
+            if "-i" not in raw_argv and "--interactive" not in raw_argv:
+                args.interactive = config.defaults.interactive
+
+        if getattr(args, "path", None) == "." and not _explicit_path_provided(raw_argv):
+            args.path = os.path.expanduser(config.defaults.path)
+
+    # --- internals ---
+
+    def _read_toml(self, path: Path, warnings: list[str]) -> dict[str, Any]:
+        if not path.is_file():
+            return {}
+        try:
+            return tomllib.loads(path.read_text(encoding="utf-8"))
+        except (tomllib.TOMLDecodeError, OSError) as exc:
+            warnings.append(f"Could not parse config '{path}': {exc}; ignoring it.")
+            return {}
+
+    def _find_project_config(self) -> Path | None:
+        current = self._project_dir.resolve()
+        for directory in (current, *current.parents):
+            candidate = directory / PROJECT_CONFIG_NAME
+            if candidate.is_file():
+                return candidate
+        return None
+
+    def _build_config(self, layers: list[dict[str, Any]]) -> AppConfig:
+        # Scalars: highest-precedence (last non-empty) layer wins.
+        # Lists: unioned across layers preserving order.
+        defaults = self._merge_defaults(layers)
+
+        exclude_dirs = _union_lists(*[_as_str_list(layer.get("exclude", [])) for layer in layers])
+
+        target_excludes = _union_lists(
+            *[_as_str_list(layer.get("targets", {}).get("exclude", [])) for layer in layers]
+        )
+        custom_targets: dict[str, str] = {}
+        for layer in layers:
+            custom = layer.get("targets", {}).get("custom", {})
+            if isinstance(custom, dict):
+                custom_targets.update({str(k): str(v) for k, v in custom.items()})
+
+        merged_targets = merge_targets(exclude=target_excludes, custom=custom_targets)
+
+        ignored_paths = tuple(
+            _normalize_path(path)
+            for path in _union_lists(
+                *[_as_str_list(layer.get("ignore", {}).get("paths", [])) for layer in layers]
+            )
+        )
+        ignored_directories = tuple(
+            _union_lists(
+                exclude_dirs,
+                *[_as_str_list(layer.get("ignore", {}).get("directories", [])) for layer in layers],
+            )
+        )
+
+        return AppConfig(
+            targets=merged_targets,
+            ignored_paths=ignored_paths,
+            ignored_directories=ignored_directories,
+            defaults=defaults,
+        )
+
+    def _merge_defaults(self, layers: list[dict[str, Any]]) -> DefaultsConfig:
+        base = DefaultsConfig()
+        merged: dict[str, Any] = {
+            "dry_run": base.dry_run,
+            "interactive": base.interactive,
+            "path": base.path,
+            "default_yes": base.default_yes,
+            "theme": base.theme,
+            "confirm_threshold": base.confirm_threshold,
+        }
+        for layer in layers:
+            section = layer.get("defaults", {})
+            if not isinstance(section, dict):
+                continue
+            for key in ("dry_run", "interactive", "default_yes"):
+                if key in section:
+                    merged[key] = bool(section[key])
+            if "path" in section:
+                merged["path"] = str(section["path"])
+            if "theme" in section:
+                merged["theme"] = str(section["theme"])
+            if "confirm_threshold" in section:
+                try:
+                    merged["confirm_threshold"] = int(section["confirm_threshold"])
+                except (TypeError, ValueError):
+                    pass
+        return DefaultsConfig(**merged)
+
+
+def _validate(data: dict[str, Any], source: str, warnings: list[str]) -> None:
+    for key in data:
+        if key not in _KNOWN_TOP_LEVEL:
+            warnings.append(f"Unknown config key '{key}' in '{source}' (ignored).")
+    defaults_section = data.get("defaults", {})
+    if isinstance(defaults_section, dict):
+        for key in defaults_section:
+            if key not in _KNOWN_DEFAULTS:
+                warnings.append(f"Unknown key 'defaults.{key}' in '{source}' (ignored).")
+
+
+def _union_lists(*lists: list[str]) -> list[str]:
+    seen: dict[str, None] = {}
+    for items in lists:
+        for item in items:
+            seen.setdefault(item, None)
+    return list(seen)
+
+
+def _as_str_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value]
+
+
+def _normalize_path(path: str) -> str:
+    return os.path.abspath(os.path.expanduser(path))
+
+
+def _explicit_path_provided(argv: list[str]) -> bool:
+    """Return True when a positional path appears on the command line."""
+    command_names = {
+        "scan",
+        "clean",
+        "history",
+        "doctor",
+        "stats",
+        "restore",
+        "config",
+        "plugins",
+    }
+    index = 1
+    if index < len(argv) and argv[index] in command_names:
+        index += 1
+
+    while index < len(argv):
+        if argv[index].startswith("-"):
+            index += 1
+            continue
+        return True
+    return False

devklean/config/models.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from devklean.config.defaults import DEFAULT_TARGETS
+
+# Single source of truth for the large-deletion confirmation threshold; the
+# CLI/TUI confirmation flow re-exports this as DEFAULT_LARGE_THRESHOLD.
+DEFAULT_CONFIRM_THRESHOLD = 1024**3  # 1 GiB
+
+
+@dataclass(frozen=True)
+class DefaultsConfig:
+    dry_run: bool = False
+    interactive: bool = False
+    path: str = "."
+    default_yes: bool = False
+    theme: str = "default"
+    confirm_threshold: int = DEFAULT_CONFIRM_THRESHOLD
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    targets: dict[str, str]
+    ignored_paths: tuple[str, ...] = ()
+    ignored_directories: tuple[str, ...] = ()
+    defaults: DefaultsConfig = field(default_factory=DefaultsConfig)
+
+    @property
+    def scan_settings(self) -> ScanSettings:
+        return ScanSettings(
+            targets=dict(self.targets),
+            ignored_paths=frozenset(self.ignored_paths),
+            ignored_directories=frozenset(self.ignored_directories),
+        )
+
+
+@dataclass(frozen=True)
+class ScanSettings:
+    """Scan-specific settings derived from application configuration."""
+
+    targets: dict[str, str]
+    ignored_paths: frozenset[str] = field(default_factory=frozenset)
+    ignored_directories: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def defaults(cls) -> ScanSettings:
+        return cls(targets=dict(DEFAULT_TARGETS))

devklean/config/paths.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def get_config_path() -> Path:
+    """Return the platform-appropriate config file path.
+
+    An explicit ``XDG_CONFIG_HOME`` override is honored on every platform; the
+    Windows-native ``APPDATA`` location is only the fallback when it is unset.
+    """
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config:
+        return Path(xdg_config) / "devklean" / "config.toml"
+
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "devklean" / "config.toml"
+        return Path.home() / "AppData" / "Roaming" / "devklean" / "config.toml"
+
+    return Path.home() / ".config" / "devklean" / "config.toml"

devklean/config/targets.py

@@ -0,0 +1,23 @@
+"""Target merge logic for configuration."""
+
+from __future__ import annotations
+
+from devklean.config.defaults import DEFAULT_TARGETS
+
+
+def merge_targets(
+    *,
+    exclude: list[str] | tuple[str, ...] = (),
+    custom: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Merge built-in defaults with user exclusions and custom targets."""
+    merged = dict(DEFAULT_TARGETS)
+
+    for name in exclude:
+        merged.pop(name, None)
+
+    if custom:
+        for name, label in custom.items():
+            merged[str(name)] = str(label)
+
+    return merged

devklean/deletion/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from devklean.deletion.integrity import IntegrityReport, check_integrity
+from devklean.deletion.metadata import MetadataManager
+from devklean.deletion.paths import get_deletion_metadata_dir
+from devklean.deletion.safety import SafetyValidator, SafetyViolation
+from devklean.deletion.trash import delete_items
+
+__all__ = [
+    "IntegrityReport",
+    "MetadataManager",
+    "SafetyValidator",
+    "SafetyViolation",
+    "check_integrity",
+    "delete_items",
+    "get_deletion_metadata_dir",
+]

devklean/deletion/history.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from devklean.deletion.metadata import StoredDeletionMetadata
+
+
+@dataclass(frozen=True)
+class HistoryOperation:
+    """A single cleanup operation aggregated from per-item metadata records."""
+
+    run_id: str | None
+    timestamp: str
+    strategy: str
+    item_count: int
+    reclaimed_size: int
+
+
+def build_history(
+    records: Sequence[StoredDeletionMetadata],
+) -> tuple[HistoryOperation, ...]:
+    """Aggregate per-item deletion records into cleanup operations.
+
+    Records sharing a ``run_id`` are grouped into one operation. Legacy
+    records without a ``run_id`` each become their own single-item operation.
+    Operations are returned newest-first by timestamp.
+    """
+    grouped: dict[str, list[StoredDeletionMetadata]] = {}
+    ungrouped: list[StoredDeletionMetadata] = []
+
+    for stored in records:
+        run_id = stored.record.run_id
+        if run_id is None:
+            ungrouped.append(stored)
+        else:
+            grouped.setdefault(run_id, []).append(stored)
+
+    operations: list[HistoryOperation] = []
+
+    for run_id, group in grouped.items():
+        first = group[0].record
+        operations.append(
+            HistoryOperation(
+                run_id=run_id,
+                timestamp=first.timestamp,
+                strategy=first.strategy,
+                item_count=len(group),
+                reclaimed_size=sum(entry.record.item.size for entry in group),
+            )
+        )
+
+    for stored in ungrouped:
+        record = stored.record
+        operations.append(
+            HistoryOperation(
+                run_id=None,
+                timestamp=record.timestamp,
+                strategy=record.strategy,
+                item_count=1,
+                reclaimed_size=record.item.size,
+            )
+        )
+
+    operations.sort(key=lambda op: op.timestamp, reverse=True)
+    return tuple(operations)

devklean/deletion/integrity.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from devklean.deletion.metadata import (
+    CorruptMetadata,
+    MetadataManager,
+    StoredDeletionMetadata,
+)
+
+
+@dataclass(frozen=True)
+class IntegrityReport:
+    """The outcome of inspecting the metadata store."""
+
+    valid: tuple[StoredDeletionMetadata, ...]
+    corrupt: tuple[CorruptMetadata, ...]
+
+    @property
+    def has_issues(self) -> bool:
+        return bool(self.corrupt)
+
+    @property
+    def healthy(self) -> bool:
+        return not self.has_issues
+
+
+def check_integrity(manager: MetadataManager) -> IntegrityReport:
+    """Inspect the metadata store for corruption.
+
+    Detects malformed JSON, missing fields, and type mismatches on load.
+
+    Orphan detection (records whose trashed item was later emptied from the
+    trash) is no longer possible: items go to the native OS trash via
+    ``send2trash``, which devklean neither owns nor tracks, so there is no trash
+    path to check for existence.
+    """
+    snapshot = manager.load_records()
+    return IntegrityReport(valid=snapshot.records, corrupt=snapshot.corrupt)

devklean/deletion/metadata.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Sequence
+from uuid import uuid4
+
+from devklean.deletion.paths import get_deletion_metadata_dir
+from devklean.models import CleanableItem, DeleteResult
+
+
+@dataclass(frozen=True)
+class DeletionMetadataItem:
+    original_path: str
+    display_name: str
+    size: int
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "original_path": self.original_path,
+            "display_name": self.display_name,
+            "size": self.size,
+        }
+
+
+@dataclass(frozen=True)
+class DeletionMetadataRecord:
+    schema_version: int
+    deletion_id: str
+    run_id: str | None
+    timestamp: str
+    strategy: str
+    item: DeletionMetadataItem
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "schema_version": self.schema_version,
+            "deletion": {
+                "id": self.deletion_id,
+                "run_id": self.run_id,
+                "timestamp": self.timestamp,
+                "strategy": self.strategy,
+            },
+            "item": self.item.to_dict(),
+        }
+
+
+@dataclass(frozen=True)
+class StoredDeletionMetadata:
+    path: Path
+    record: DeletionMetadataRecord
+
+
+@dataclass(frozen=True)
+class CorruptMetadata:
+    """A metadata file that could not be parsed, with the reason why."""
+
+    path: Path
+    reason: str
+
+
+@dataclass(frozen=True)
+class MetadataLoadResult:
+    records: tuple[StoredDeletionMetadata, ...]
+    corrupt: tuple[CorruptMetadata, ...]
+
+    @property
+    def invalid_count(self) -> int:
+        return len(self.corrupt)
+
+
+def _parse_record(data: dict[str, object]) -> DeletionMetadataRecord:
+    deletion = data.get("deletion")
+    item = data.get("item")
+    if not isinstance(deletion, dict) or not isinstance(item, dict):
+        raise ValueError("missing or invalid 'deletion'/'item' section")
+
+    deletion_id = deletion.get("id")
+    run_id = deletion.get("run_id")
+    timestamp = deletion.get("timestamp")
+    strategy = deletion.get("strategy")
+    original_path = item.get("original_path")
+    display_name = item.get("display_name")
+    size = item.get("size")
+
+    # Records predating the schema_version field are treated as v1. Any integer
+    # version is accepted as-is; there are no migrations yet.
+    schema_version = data.get("schema_version", 1)
+
+    if not (
+        isinstance(deletion_id, str)
+        and (run_id is None or isinstance(run_id, str))
+        and isinstance(timestamp, str)
+        and isinstance(strategy, str)
+        and isinstance(original_path, str)
+        and isinstance(display_name, str)
+        and isinstance(size, int)
+        and isinstance(schema_version, int)
+    ):
+        raise ValueError("missing or wrong-typed metadata fields")
+
+    return DeletionMetadataRecord(
+        schema_version=schema_version,
+        deletion_id=deletion_id,
+        run_id=run_id,
+        timestamp=timestamp,
+        strategy=strategy,
+        item=DeletionMetadataItem(
+            original_path=original_path,
+            display_name=display_name,
+            size=size,
+        ),
+    )
+
+
+def _metadata_sort_key(entry: StoredDeletionMetadata) -> str:
+    return entry.record.timestamp
+
+
+class MetadataManager:
+    """Persist deletion metadata in the app data directory."""
+
+    def __init__(self, storage_dir: Path | None = None) -> None:
+        self._storage_dir = storage_dir if storage_dir is not None else get_deletion_metadata_dir()
+
+    @property
+    def storage_dir(self) -> Path:
+        return self._storage_dir
+
+    def load_records(self) -> MetadataLoadResult:
+        if not self._storage_dir.exists():
+            return MetadataLoadResult(records=(), corrupt=())
+
+        records: list[StoredDeletionMetadata] = []
+        corrupt: list[CorruptMetadata] = []
+
+        for path in sorted(self._storage_dir.glob("*.json")):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                if not isinstance(data, dict):
+                    raise ValueError("metadata file is not a JSON object")
+                record = _parse_record(data)
+            except json.JSONDecodeError:
+                corrupt.append(CorruptMetadata(path=path, reason="malformed JSON"))
+                continue
+            except OSError as exc:
+                corrupt.append(CorruptMetadata(path=path, reason=f"unreadable file: {exc}"))
+                continue
+            except (ValueError, TypeError) as exc:
+                corrupt.append(CorruptMetadata(path=path, reason=str(exc)))
+                continue
+
+            records.append(StoredDeletionMetadata(path=path, record=record))
+
+        records.sort(key=_metadata_sort_key, reverse=True)
+        return MetadataLoadResult(records=tuple(records), corrupt=tuple(corrupt))
+
+    def remove_record(self, entry: StoredDeletionMetadata | CorruptMetadata) -> None:
+        """Delete a single metadata file from the store (valid or corrupt)."""
+        entry.path.unlink(missing_ok=True)
+
+    def record_successes(
+        self,
+        items: Sequence[CleanableItem],
+        result: DeleteResult,
+        strategy: str,
+    ) -> None:
+        deleted_paths = set(result.deleted)
+        if not deleted_paths:
+            return
+
+        self._storage_dir.mkdir(parents=True, exist_ok=True)
+
+        run_id = uuid4().hex
+        timestamp = datetime.now(timezone.utc).isoformat()
+
+        for item in items:
+            if item.path not in deleted_paths:
+                continue
+
+            record = DeletionMetadataRecord(
+                schema_version=3,
+                deletion_id=uuid4().hex,
+                run_id=run_id,
+                timestamp=timestamp,
+                strategy=strategy,
+                item=DeletionMetadataItem(
+                    original_path=item.path,
+                    display_name=item.display_label,
+                    size=item.size,
+                ),
+            )
+            stamp = record.timestamp.replace(":", "").replace("+00:00", "Z")
+            filename = f"{stamp}_{record.deletion_id}.json"
+            path = self._storage_dir / filename
+            path.write_text(json.dumps(record.to_dict(), indent=2) + "\n", encoding="utf-8")

devklean/deletion/paths.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def get_deletion_metadata_dir() -> Path:
+    """Return the directory used to persist deletion metadata.
+
+    An explicit ``XDG_DATA_HOME`` override is honored on every platform; the
+    Windows-native ``APPDATA`` location is only the fallback when it is unset.
+    """
+    xdg_data = os.environ.get("XDG_DATA_HOME")
+    if xdg_data:
+        return Path(xdg_data) / "devklean" / "deletions"
+
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "devklean" / "deletions"
+        return Path.home() / "AppData" / "Roaming" / "devklean" / "deletions"
+
+    return Path.home() / ".local" / "share" / "devklean" / "deletions"