Merge pull request #13 from smurftyy/feat-9-compress-artifacts

Feat 9 compress artifacts

Author: smurftyy

README.md

@@ -25,7 +25,7 @@ pipx install devklean
 pip install devklean
 ```
 
-Requires Python 3.8+. Runtime dependencies are `send2trash` (used for all deletions) and `tomli` (only on Python < 3.11).
+Requires Python 3.8+. Runtime dependencies are `send2trash` (used for all deletions) and `tomli` (only on Python < 3.11). `zstandard` is an optional dependency, only needed for `compress_format = "zstd"` — see [Compression](#compression).
 
 ## Quick start
 
@@ -70,7 +70,7 @@ devklean clean --dry-run        # show what *would* be deleted; delete nothing
 devklean clean -i               # interactive: pick items in a TUI (Linux/macOS only)
 devklean clean --allow-symlinks # permit deleting symlinked targets (blocked by default)
 devklean clean -y               # skip the y/N prompt (large deletions still require typing DELETE)
-devklean clean --compress       # zip eligible directories before sending them to trash
+devklean clean --compress       # compress eligible directories (gzip) before sending them to trash
 ```
 
 | Flag | Meaning |
@@ -79,7 +79,7 @@ devklean clean --compress       # zip eligible directories before sending them t
 | `-i`, `--interactive` | Choose items in a terminal UI (SPACE select, A all, D none, ENTER confirm, Q quit). **Linux/macOS only** — see [Platform support](#platform-support). |
 | `--allow-symlinks` | Allow deleting symbolic links. Off by default (symlinks are blocked). |
 | `-y`, `--yes` | Skip the standard confirmation. Deletions over the size threshold still require typing `DELETE`. |
-| `--compress` | Zip eligible directories into a sibling archive before trashing them, shrinking their footprint in trash. Off by default — see [Compression](#compression). |
+| `--compress` | Compress eligible directories into a sibling archive before trashing them, shrinking their footprint in trash. Off by default — see [Compression](#compression). |
 
 ### `restore`
 
@@ -95,9 +95,10 @@ devklean restore   # explains how to recover from the Recycle Bin / Trash
 - **macOS** — open Trash in Finder and "Put Back".
 - **Linux** — open Trash in your file manager and restore.
 
-If the item was deleted with `--compress`, what lands in trash is a `.zip`
-archive rather than the original directory — restore the archive from trash,
-then unpack it to the original path yourself. devklean does not decompress
+If the item was deleted with `--compress`, what lands in trash is a `.tar.gz`
+(or `.tar.zst`, if `compress_format = "zstd"`) archive rather than the original
+directory — restore the archive from trash, then extract it to the original
+path yourself, e.g. `tar -xf <name>.tar.gz`. devklean does not decompress
 automatically (yet).
 
 Run `devklean history` to see what was removed and when.
@@ -170,7 +171,9 @@ exclude = ["node_modules", ".git"]
 dry_run = false
 interactive = false
 default_yes = false          # skip the y/N prompt (the large-deletion DELETE gate still applies)
-compress = false             # zip eligible directories before trashing them
+compress = false             # compress eligible directories before trashing them
+compress_min_size = 10485760 # bytes; directories smaller than this are trashed uncompressed (default 10 MiB)
+compress_format = "gzip"     # "gzip" (stdlib, default) or "zstd" (needs the devklean[zstd] extra)
 theme = "default"            # "default" or "mono"
 confirm_threshold = 1073741824   # bytes; deletions >= this require typing DELETE (default 1 GiB)
 path = "."
@@ -193,18 +196,46 @@ Color follows the `theme` setting and is automatically disabled when output is p
 
 Common artifacts (`node_modules`, `.venv`, `.next`, build caches) often compress
 to a fraction of their on-disk size. Pass `--compress` (or set `compress = true`
-in config) and devklean will zip each eligible directory into a sibling
-`<name>.zip` archive and send *that* to trash instead of the raw directory —
-shrinking how much space the deletion actually occupies in trash before it's
-emptied.
-
-- Only applies to directories (not symlinks); files are trashed as-is.
-- The archive path and format are recorded in deletion metadata, so `history`
-  and `doctor` see compressed deletions the same as uncompressed ones.
+in config) and devklean will archive each eligible directory into a sibling
+`.tar.gz` (gzip, the default) before sending *that* to trash instead of the raw
+directory — shrinking how much space the deletion actually occupies in trash
+before it's emptied. `zstd` is available as an opt-in format (see below) for a
+better compression ratio.
+
+Compression is always ordered for safety: devklean compresses to a temp
+archive, verifies it (test-extracts every entry and cross-checks the file
+count and total uncompressed size against the source), and only *after*
+`send2trash` confirms the archive is in the trash does it remove the original
+directory. If compression or verification fails, or `send2trash` itself fails,
+the original directory is left completely untouched and the error is reported
+per-item — nothing is ever partially deleted.
+
+- Only applies to directories (not symlinks) at or above `compress_min_size`
+  (default 10 MiB); smaller directories and files are trashed as-is, since the
+  archive/verify overhead rarely pays for itself below that size.
+- The archive path, format, original size, and compressed size are recorded in
+  deletion metadata, so `history` and `doctor` see compressed deletions the
+  same as uncompressed ones.
 - Off by default, so existing scripts and habits aren't surprised by archives
   appearing in trash.
 - Restoring a compressed item is manual today — see [`restore`](#restore).
 
+### zstd (optional)
+
+```bash
+pip install 'devklean[zstd]'
+```
+
+```toml
+[defaults]
+compress = true
+compress_format = "zstd"
+```
+
+If `compress_format = "zstd"` is set but the `zstandard` package isn't
+installed, devklean logs a warning and falls back to gzip rather than
+crashing.
+
 ## Logs
 
 `devklean` writes detailed structured logs (commands, scanned/deleted paths, sizes, errors) to:

pyproject.toml

@@ -36,12 +36,16 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+zstd = [
+    "zstandard>=0.21",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "ruff>=0.6",
     "mypy>=1.8",
     "build>=1.0",
+    "zstandard>=0.21",
 ]
 
 [project.scripts]

src/devklean/cli/commands/analyze.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from devklean.config.models import AppConfig
+from devklean.scanner.scanner import scan_tree
+from devklean.signatures.analysis import analyze_candidates
+
+if TYPE_CHECKING:
+    from devklean.output.text import TextRenderer
+
+
+def run_analyze(args, renderer: TextRenderer, config: AppConfig) -> int:
+    """Scan for cleanable directories and report a signature-backed analysis.
+
+    Calls ``scan_tree`` directly — the exact discovery function ``clean``/
+    ``scan`` use via ``scan_directory`` — rather than a second walker.
+    ``scan_directory`` isn't reused as-is because its "nothing found" path
+    renders clean/scan's own summary and stops; analyze always wants to
+    render its own report (recognized/unrecognized buckets, structural
+    checks, health score), even over an empty candidate list.
+    """
+    root = os.path.abspath(args.path)
+    if not os.path.isdir(root):
+        renderer.invalid_directory(root)
+        return 1
+
+    scan_report = scan_tree(root, settings=config.scan_settings)
+    if scan_report.permission_errors:
+        renderer.permission_warnings(scan_report.permission_errors)
+
+    analysis = analyze_candidates(root, scan_report.items)
+    renderer.analysis_report(analysis, verbose=getattr(args, "verbose", False))
+    return 0

src/devklean/cli/commands/clean.py

@@ -8,7 +8,7 @@
     confirm_large_deletion,
     exceeds_threshold,
 )
-from devklean.config.models import AppConfig
+from devklean.config.models import DEFAULT_COMPRESS_FORMAT, DEFAULT_COMPRESS_MIN_SIZE, AppConfig
 from devklean.deletion.safety import SafetyValidator
 from devklean.models import CleanableItem
 from devklean.output.base import Renderer
@@ -46,6 +46,8 @@ def run_standard(
     validator: SafetyValidator | None = None,
     *,
     compress: bool = False,
+    compress_min_size: int = DEFAULT_COMPRESS_MIN_SIZE,
+    compress_format: str = DEFAULT_COMPRESS_FORMAT,
     default_yes: bool = False,
     confirm_threshold: int = DEFAULT_LARGE_THRESHOLD,
 ) -> None:
@@ -59,7 +61,14 @@ def run_standard(
         renderer.aborted()
         return
 
-    result = delete_items(found, total_size, validator=validator, compress=compress)
+    result = delete_items(
+        found,
+        total_size,
+        validator=validator,
+        compress=compress,
+        compress_min_size=compress_min_size,
+        compress_format=compress_format,
+    )
     renderer.deletion_result(result)
 
 
@@ -78,6 +87,10 @@ def run_clean(
     default_yes = getattr(args, "yes", False) or getattr(defaults, "default_yes", False)
     confirm_threshold = getattr(defaults, "confirm_threshold", DEFAULT_LARGE_THRESHOLD)
     compress = getattr(args, "compress", False) or getattr(defaults, "compress", False)
+    # Not exposed as CLI flags (per the original issue, --compress itself is
+    # the only opt-in surface); config-only knobs read straight from defaults.
+    compress_min_size = getattr(defaults, "compress_min_size", DEFAULT_COMPRESS_MIN_SIZE)
+    compress_format = getattr(defaults, "compress_format", DEFAULT_COMPRESS_FORMAT)
 
     if args.interactive:
         # Interactive mode relies on curses, which is unavailable on Windows.
@@ -100,6 +113,8 @@ def run_clean(
             args.dry_run,
             validator,
             compress=compress,
+            compress_min_size=compress_min_size,
+            compress_format=compress_format,
             confirm_threshold=confirm_threshold,
         )
     else:
@@ -109,6 +124,8 @@ def run_clean(
             args.dry_run,
             validator,
             compress=compress,
+            compress_min_size=compress_min_size,
+            compress_format=compress_format,
             default_yes=default_yes,
             confirm_threshold=confirm_threshold,
         )

src/devklean/cli/commands/explain.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from devklean.signatures import match_signature
+
+if TYPE_CHECKING:
+    from devklean.output.text import TextRenderer
+
+
+def run_explain(args, renderer: TextRenderer, config) -> int:
+    """Resolve a path against the artifact-signature registry and explain it.
+
+    Every field printed on a match comes straight from the matched
+    ``ArtifactSignature`` — nothing here is generated freeform. On no match,
+    no risk/confidence verdict is given at all; guessing about an unrecognized
+    path is a hard constraint, not a style choice.
+
+    Text-only by design, like ``doctor``/``restore``: this is a direct lookup
+    report, not a scannable result set, so it never needs the JSON scan/history
+    payload shape.
+    """
+    path = os.path.abspath(args.path)
+    signature = match_signature(path)
+
+    if signature is None:
+        renderer.explain_no_match(path)
+        return 0
+
+    renderer.explain_match(path, signature)
+    return 0

src/devklean/cli/dispatcher.py

@@ -3,8 +3,10 @@
 import sys
 from typing import Callable
 
+from devklean.cli.commands.analyze import run_analyze
 from devklean.cli.commands.clean import run_clean
 from devklean.cli.commands.doctor import run_doctor
+from devklean.cli.commands.explain import run_explain
 from devklean.cli.commands.history import run_history
 from devklean.cli.commands.restore import run_restore
 from devklean.cli.commands.scan import run_scan
@@ -23,6 +25,8 @@
     "history": run_history,
     "doctor": run_doctor,
     "restore": run_restore,
+    "explain": run_explain,
+    "analyze": run_analyze,
 }
 
 

src/devklean/cli/parser.py

@@ -5,9 +5,22 @@
 from devklean._version import __version__
 
 COMMAND_NAMES = frozenset(
-    {"scan", "clean", "history", "doctor", "stats", "restore", "config", "plugins"}
+    {
+        "scan",
+        "clean",
+        "history",
+        "doctor",
+        "stats",
+        "restore",
+        "explain",
+        "analyze",
+        "config",
+        "plugins",
+    }
+)
+IMPLEMENTED_COMMANDS = frozenset(
+    {"scan", "clean", "history", "doctor", "restore", "explain", "analyze"}
 )
-IMPLEMENTED_COMMANDS = frozenset({"scan", "clean", "history", "doctor", "restore"})
 RESERVED_COMMANDS = frozenset({"stats", "config", "plugins"})
 GLOBAL_OPTIONS = frozenset({"-h", "--help", "--version"})
 
@@ -84,6 +97,26 @@ def _add_subparsers(parser: argparse.ArgumentParser) -> None:
         "restore", help="Show how to recover deleted items from your system trash"
     )
 
+    explain_parser = subparsers.add_parser(
+        "explain",
+        help="Explain what a directory is, using the artifact-signature registry",
+    )
+    explain_parser.add_argument(
+        "path",
+        help="Path to a directory to look up in the signature registry",
+    )
+
+    analyze_parser = subparsers.add_parser(
+        "analyze",
+        help="Analyze cleanable directories using the artifact-signature registry",
+    )
+    _add_path_argument(analyze_parser)
+    analyze_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show the workspace-health formula and its raw inputs",
+    )
+
     history_parser = subparsers.add_parser(
         "history",
         help="Show previous cleanup operations",

src/devklean/config/manager.py

@@ -21,6 +21,8 @@
     "dry_run",
     "interactive",
     "compress",
+    "compress_min_size",
+    "compress_format",
     "path",
     "default_yes",
     "theme",
@@ -153,6 +155,8 @@ def _merge_defaults(self, layers: list[dict[str, Any]]) -> DefaultsConfig:
             "dry_run": base.dry_run,
             "interactive": base.interactive,
             "compress": base.compress,
+            "compress_min_size": base.compress_min_size,
+            "compress_format": base.compress_format,
             "path": base.path,
             "default_yes": base.default_yes,
             "theme": base.theme,
@@ -167,6 +171,13 @@ def _merge_defaults(self, layers: list[dict[str, Any]]) -> DefaultsConfig:
                     merged[key] = bool(section[key])
             if "compress" in section:
                 merged["compress"] = bool(section["compress"])
+            if "compress_min_size" in section:
+                try:
+                    merged["compress_min_size"] = int(section["compress_min_size"])
+                except (TypeError, ValueError):
+                    pass
+            if "compress_format" in section:
+                merged["compress_format"] = str(section["compress_format"])
             if "path" in section:
                 merged["path"] = str(section["path"])
             if "theme" in section:

src/devklean/config/models.py

@@ -8,12 +8,25 @@
 # CLI/TUI confirmation flow re-exports this as DEFAULT_LARGE_THRESHOLD.
 DEFAULT_CONFIRM_THRESHOLD = 1024**3  # 1 GiB
 
+# Single source of truth for compress-before-trash defaults; deletion/trash.py
+# imports these rather than defining its own copies, so config and the
+# deletion pipeline can't drift apart on what "the default" is.
+# Below this size, tar/gzip overhead and the extra verify-read pass rarely
+# pay for themselves, so --compress skips the directory and trashes it as-is.
+DEFAULT_COMPRESS_MIN_SIZE = 10 * 1024 * 1024  # 10 MiB
+# "gzip" (stdlib tarfile, always available) or "zstd" (needs the
+# devklean[zstd] extra; silently falls back to gzip with a logged warning
+# when requested but not installed).
+DEFAULT_COMPRESS_FORMAT = "gzip"
+
 
 @dataclass(frozen=True)
 class DefaultsConfig:
     dry_run: bool = False
     interactive: bool = False
     compress: bool = False
+    compress_min_size: int = DEFAULT_COMPRESS_MIN_SIZE
+    compress_format: str = DEFAULT_COMPRESS_FORMAT
     path: str = "."
     default_yes: bool = False
     theme: str = "default"