filedust 0.2.0__tar.gz → 0.3.1__tar.gz

{filedust-0.2.0 → filedust-0.3.1}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.1
 Name: filedust
-Version: 0.2.0
+Version: 0.3.1
 Summary: Opinionated junk cleaner for dev machines (caches, build artifacts, editor backups).
-Home-page: https://github.com/mdaleo404/filedust
+Home-page: https://github.com/guardutils/filedust
 License: GPL-3.0-or-later
 Author: Marco D'Aleo
 Author-email: marco@marcodaleo.com
@@ -13,16 +13,15 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: argcomplete (>=3.3.0,<4.0.0)
-Requires-Dist: rich (>=13.0.0,<14.0.0)
-Project-URL: Repository, https://github.com/mdaleo404/filedust
+Requires-Dist: argcomplete (>=2)
+Requires-Dist: rich (>=12)
+Project-URL: Repository, https://github.com/guardutils/filedust
 Description-Content-Type: text/markdown
 
-[![License](https://img.shields.io/github/license/mdaleo404/filedust?style=flat)](LICENCE)
-[![Language](https://img.shields.io/github/languages/top/mdaleo404/filedust.svg)](https://github.com/mdaleo404/filedust/)
-![GitHub Release](https://img.shields.io/github/v/release/mdaleo404/filedust?display_name=release&logo=github)
-![PyPI - Version](https://img.shields.io/pypi/v/filedust?logo=pypi)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/mdaleo404/filedust/.github/workflows/lint-and-security.yml)](https://github.com/mdaleo404/filedust/actions)
+[![License](https://img.shields.io/github/license/guardutils/filedust?style=flat)](LICENCE)
+[![Language](https://img.shields.io/github/languages/top/guardutils/filedust.svg)](https://github.com/guardutils/filedust/)
+[![GitHub Release](https://img.shields.io/github/v/release/guardutils/filedust?display_name=release&logo=github)](https://github.com/guardutils/filedust/releases)
+[![PyPI - Version](https://img.shields.io/pypi/v/filedust?logo=pypi)](https://pypi.org/project/filedust/#history)
 [![PyPI downloads](https://img.shields.io/pypi/dm/filedust.svg)](https://pypi.org/project/filedust/)
 
 # filedust
@@ -55,7 +54,11 @@ One interactive prompt at the end of the run (unless -y is used).
 Shows how much disk space can be freed.
 
 ### Safe by design
-Never touches dotfiles, configs, project files, or anything important.
+* It ONLY runs within user's `$HOME`
+
+* Put user in control by reading `~/.filedust.conf`
+
+* Never touches dotfiles, configs, project files, or anything important unless you want.
 
 ## Installation
 
@@ -66,11 +69,17 @@ pip install filedust
 
 ### From this repository
 ```
-git clone https://github.com/mdaleo404/filedust.git
+git clone https://github.com/guardutils/filedust.git
 cd filedust/
 poetry install
 ```
 
+### Custom config
+You can download the example and add your custom rule
+```
+wget -O ~/.filedust.conf https://raw.githubusercontent.com/guardutils/filedust/main/.filedust.conf.example
+```
+
 ### TAB completion
 Add this to your `.bashrc`
 ```

{filedust-0.2.0 → filedust-0.3.1}/README.md

@@ -1,8 +1,7 @@
-[![License](https://img.shields.io/github/license/mdaleo404/filedust?style=flat)](LICENCE)
-[![Language](https://img.shields.io/github/languages/top/mdaleo404/filedust.svg)](https://github.com/mdaleo404/filedust/)
-![GitHub Release](https://img.shields.io/github/v/release/mdaleo404/filedust?display_name=release&logo=github)
-![PyPI - Version](https://img.shields.io/pypi/v/filedust?logo=pypi)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/mdaleo404/filedust/.github/workflows/lint-and-security.yml)](https://github.com/mdaleo404/filedust/actions)
+[![License](https://img.shields.io/github/license/guardutils/filedust?style=flat)](LICENCE)
+[![Language](https://img.shields.io/github/languages/top/guardutils/filedust.svg)](https://github.com/guardutils/filedust/)
+[![GitHub Release](https://img.shields.io/github/v/release/guardutils/filedust?display_name=release&logo=github)](https://github.com/guardutils/filedust/releases)
+[![PyPI - Version](https://img.shields.io/pypi/v/filedust?logo=pypi)](https://pypi.org/project/filedust/#history)
 [![PyPI downloads](https://img.shields.io/pypi/dm/filedust.svg)](https://pypi.org/project/filedust/)
 
 # filedust
@@ -35,7 +34,11 @@ One interactive prompt at the end of the run (unless -y is used).
 Shows how much disk space can be freed.
 
 ### Safe by design
-Never touches dotfiles, configs, project files, or anything important.
+* It ONLY runs within user's `$HOME`
+
+* Put user in control by reading `~/.filedust.conf`
+
+* Never touches dotfiles, configs, project files, or anything important unless you want.
 
 ## Installation
 
@@ -46,11 +49,17 @@ pip install filedust
 
 ### From this repository
 ```
-git clone https://github.com/mdaleo404/filedust.git
+git clone https://github.com/guardutils/filedust.git
 cd filedust/
 poetry install
 ```
 
+### Custom config
+You can download the example and add your custom rule
+```
+wget -O ~/.filedust.conf https://raw.githubusercontent.com/guardutils/filedust/main/.filedust.conf.example
+```
+
 ### TAB completion
 Add this to your `.bashrc`
 ```

{filedust-0.2.0 → filedust-0.3.1}/pyproject.toml

@@ -1,18 +1,18 @@
 [tool.poetry]
 name = "filedust"
-version = "0.2.0"
+version = "0.3.1"
 description = "Opinionated junk cleaner for dev machines (caches, build artifacts, editor backups)."
 authors = ["Marco D'Aleo <marco@marcodaleo.com>"]
 license = "GPL-3.0-or-later"
 readme = "README.md"
-homepage = "https://github.com/mdaleo404/filedust"
-repository = "https://github.com/mdaleo404/filedust"
+homepage = "https://github.com/guardutils/filedust"
+repository = "https://github.com/guardutils/filedust"
 packages = [{ include = "filedust", from = "src" }]
 
 [tool.poetry.dependencies]
 python = ">=3.10,<4.0"
-rich = "^13.0.0"
-argcomplete = "^3.3.0"
+rich = ">=12"
+argcomplete = ">=2"
 
 [tool.poetry.scripts]
 filedust = "filedust.cli:main"

{filedust-0.2.0 → filedust-0.3.1}/src/filedust/cli.py

@@ -12,7 +12,7 @@ from rich.table import Table
 from rich.prompt import Confirm
 from rich import box
 
-from .junk import Finding, iter_junk
+from .junk import Finding, iter_junk, load_user_rules
 
 
 console = Console()
@@ -172,18 +172,34 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     root = Path(args.path).expanduser()
+    home = Path.home().resolve()
+    root_resolved = root.resolve()
+
+    # Ensure root is inside the user's home directory
+    try:
+        root_resolved.relative_to(home)
+    except ValueError:
+        console.print(
+            f"[red]Error:[/] Refusing to operate outside the user's home directory.\n"
+            f"Requested: {root_resolved}\n"
+            f"Allowed:   {home}"
+        )
+        return 1
 
     if not root.exists():
         console.print(f"[red]Error:[/] Path not found: {root}")
         return 1
 
+    print("Looking for junk ...")
+
     if root.resolve() == Path("/"):
         console.print(
             "[yellow]Running filedust on the entire filesystem (/). "
             "This may take a while and may require sudo for deletions.[/]"
         )
 
-    findings = list(iter_junk(root))
+    rules = load_user_rules()
+    findings = list(iter_junk(root, rules=rules))
     total_size = compute_total_size(findings)
 
     if not findings:

filedust-0.3.1/src/filedust/junk.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import os
+import configparser
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Iterable, List
+
+
+class UserRules:
+    def __init__(self):
+        self.include: list[str] = []
+        self.exclude: list[str] = []
+
+
+def load_user_rules() -> UserRules:
+    rules = UserRules()
+    cfg_path = Path.home() / ".filedust.conf"
+
+    if cfg_path.exists():
+        parser = configparser.ConfigParser(allow_no_value=True)
+        parser.read(cfg_path)
+
+        if parser.has_section("include"):
+            rules.include = list(parser["include"].keys())
+
+        if parser.has_section("exclude"):
+            rules.exclude = list(parser["exclude"].keys())
+
+    return rules
+
+
+def matches_any(patterns: list[str], relpath: Path) -> bool:
+    posix = relpath.as_posix()
+    return any(fnmatch(posix, p) for p in patterns)
+
+
+@dataclass
+class Finding:
+    path: Path
+    kind: str  # "file" or "dir"
+    reason: str
+
+
+# Directories that are *typically* safe to delete completely.
+JUNK_DIR_NAMES = {
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".nox",
+    ".tox",
+    ".hypothesis",
+    ".gradle",
+    ".parcel-cache",
+    ".turbo",
+    ".next",
+    ".vite",
+    ".sass-cache",
+    ".sass-cache",
+    "dist",
+}
+
+# File name patterns that are almost always junk / temporary.
+JUNK_FILE_PATTERNS = [
+    "*~",
+    "*.swp",
+    "*.swo",
+    "*.swpx",
+    "*.tmp",
+    "*.temp",
+    "*.bak",
+    "*.orig",
+    "*.rej",
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+]
+
+# VCS / system dirs
+SKIP_DIR_NAMES = {
+    ".cache",
+    "build",
+    ".gnupg",
+    ".git",
+    ".hg",
+    ".svn",
+    ".bzr",
+    ".idea",
+    ".vscode",
+}
+
+
+HOME = Path.home().resolve()
+
+
+def safe_exists(path: Path) -> bool | None:
+    """Return True/False if the path exists, or None if permission denied."""
+    try:
+        return path.exists()
+    except Exception:
+        return None
+
+
+def safe_resolve(path: Path, root: Path) -> Path | None:
+    """
+    Resolve symlinks only if safe.
+    Return resolved path if it stays within root.
+    Return None if:
+      - resolution escapes the root
+      - resolution fails
+      - permission denied
+    """
+    try:
+        resolved = path.resolve(strict=False)  # NEVER strict
+        resolved.relative_to(root)  # ensure containment
+        return resolved
+    except Exception:
+        return None
+
+
+def is_junk_dir_name(name: str) -> bool:
+    return name in JUNK_DIR_NAMES
+
+
+def is_junk_file_name(name: str) -> bool:
+    return any(fnmatch(name, pattern) for pattern in JUNK_FILE_PATTERNS)
+
+
+def iter_junk(root: Path, rules: UserRules | None = None) -> Iterable[Finding]:
+    """
+    Safe, fast junk scanner:
+      - Never follows symlinks.
+      - Broken symlinks are not automatically junk — they follow normal rules.
+      - User include/exclude overrides all.
+      - Built-in junk rules applied only when safe.
+      - SKIP_DIR_NAMES protected unless user includes.
+      - Fully contained in $HOME.
+      - No crashes from PermissionError or unreadable paths.
+    """
+    if rules is None:
+        rules = UserRules()
+
+    root = root.resolve()
+    root_str = str(root)
+
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirpath_p = Path(dirpath)
+
+        # Fast relative path computation
+        if dirpath == root_str:
+            rel_dir = Path(".")
+        else:
+            rel_dir = Path(dirpath[len(root_str) :].lstrip("/"))
+
+        # USER EXCLUDE → skip entire subtree
+        if matches_any(rules.exclude, rel_dir):
+            dirnames[:] = []
+            continue
+
+        pruned = []
+
+        # Handling dirs
+        for d in dirnames:
+            child = dirpath_p / d
+
+            try:
+                st = child.lstat()
+            except Exception:
+                continue  # unreadable
+
+            is_symlink = (st.st_mode & 0o170000) == 0o120000
+
+            if is_symlink:
+                # If broken symlink dir treat as file later via filenames (skip descent)
+                continue
+
+            rel_child = rel_dir / d
+
+            # User exclude wins
+            if matches_any(rules.exclude, rel_child):
+                continue
+
+            # SKIP_DIR_NAMES unless user includes
+            if d in SKIP_DIR_NAMES and not matches_any(
+                rules.include, rel_child
+            ):
+                continue
+
+            pruned.append(d)
+
+        dirnames[:] = pruned
+
+        # Detect JUNK dirs
+        i = 0
+        while i < len(dirnames):
+            name = dirnames[i]
+            rel_child = rel_dir / name
+
+            # User include directory
+            if matches_any(rules.include, rel_child):
+                yield Finding(dirpath_p / name, "dir", "user_include")
+                del dirnames[i]
+                continue
+
+            # Built-in safe junk dirs
+            if is_junk_dir_name(name):
+                yield Finding(dirpath_p / name, "dir", "junk_dir")
+                del dirnames[i]
+                continue
+
+            i += 1
+
+        # Handling files (including symlinks)
+        for fname in filenames:
+            fpath = dirpath_p / fname
+            rel_file = rel_dir / fname
+
+            try:
+                st = fpath.lstat()
+            except Exception:
+                continue
+
+            is_symlink = (st.st_mode & 0o170000) == 0o120000
+
+            # Handling broken symlinks
+            if is_symlink:
+                exists = safe_exists(fpath)
+
+                # Permission denied → skip
+                if exists is None:
+                    continue
+
+                # User exclude wins
+                if matches_any(rules.exclude, rel_file):
+                    continue
+
+                # User include wins
+                if matches_any(rules.include, rel_file):
+                    yield Finding(fpath, "file", "user_include")
+                    continue
+
+                # Broken symlink?
+                if exists is False:
+                    # DO NOT auto-delete — classify like regular file
+                    # Only built-in junk patterns apply
+                    if is_junk_file_name(fname):
+                        yield Finding(fpath, "file", "broken_symlink")
+                    continue
+
+                # Valid symlink — NEVER follow; only user-include counts
+                continue
+
+            # Regular files
+            # User exclude wins
+            if matches_any(rules.exclude, rel_file):
+                continue
+
+            # User include wins
+            if matches_any(rules.include, rel_file):
+                yield Finding(fpath, "file", "user_include")
+                continue
+
+            # Built-in junk patterns (safe ones)
+            if is_junk_file_name(fname):
+                yield Finding(fpath, "file", "junk_file")

filedust-0.2.0/src/filedust/junk.py

@@ -1,106 +0,0 @@
-from __future__ import annotations
-
-import os
-from dataclasses import dataclass
-from fnmatch import fnmatch
-from pathlib import Path
-from typing import Iterable, List
-
-
-@dataclass
-class Finding:
-    path: Path
-    kind: str  # "file" or "dir"
-    reason: str
-
-
-# Directories that are *typically* safe to delete completely.
-JUNK_DIR_NAMES = {
-    "__pycache__",
-    ".pytest_cache",
-    ".mypy_cache",
-    ".ruff_cache",
-    ".nox",
-    ".tox",
-    ".hypothesis",
-    ".cache",
-    ".gradle",
-    ".parcel-cache",
-    ".turbo",
-    ".next",
-    ".vite",
-    ".sass-cache",
-    ".sass-cache",
-    "build",
-    "dist",
-}
-
-# File name patterns that are almost always junk / temporary.
-JUNK_FILE_PATTERNS = [
-    "*~",
-    "*.swp",
-    "*.swo",
-    "*.swpx",
-    "*.tmp",
-    "*.temp",
-    "*.bak",
-    "*.orig",
-    "*.rej",
-    ".DS_Store",
-    "Thumbs.db",
-    "desktop.ini",
-]
-
-# VCS / system dirs
-SKIP_DIR_NAMES = {
-    ".git",
-    ".hg",
-    ".svn",
-    ".bzr",
-    ".idea",
-    ".vscode",
-}
-
-
-def is_junk_dir_name(name: str) -> bool:
-    return name in JUNK_DIR_NAMES
-
-
-def is_junk_file_name(name: str) -> bool:
-    return any(fnmatch(name, pattern) for pattern in JUNK_FILE_PATTERNS)
-
-
-def iter_junk(root: Path) -> Iterable[Finding]:
-    """
-    Walk the tree under `root` and yield junk candidates.
-
-    filedust:
-      - Skips known critical / config directories (SKIP_DIR_NAMES).
-      - Treats known "junk" directory names as removable as a whole.
-      - Treats known junk file patterns as removable.
-    """
-    root = root.resolve()
-
-    for dirpath, dirnames, filenames in os.walk(root):
-        dirpath_p = Path(dirpath)
-
-        # Prune dirs we never touch at all.
-        dirnames[:] = [d for d in dirnames if d not in SKIP_DIR_NAMES]
-
-        # Detect junk directories (and skip walking inside them).
-        i = 0
-        while i < len(dirnames):
-            name = dirnames[i]
-            if is_junk_dir_name(name):
-                junk_dir = dirpath_p / name
-                yield Finding(path=junk_dir, kind="dir", reason="junk_dir")
-                # Remove from walk so we don't descend into it.
-                del dirnames[i]
-                continue
-            i += 1
-
-        # Now process files.
-        for fname in filenames:
-            if is_junk_file_name(fname):
-                fpath = dirpath_p / fname
-                yield Finding(path=fpath, kind="file", reason="junk_file")