dupehunt 0.0.1__tar.gz

dupehunt-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lqxnjk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dupehunt-0.0.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: dupehunt
+Version: 0.0.1
+Summary: Fast, dependency-free duplicate file finder with a friendly CLI.
+Project-URL: Homepage, https://github.com/lqxnjk/dupehunt
+Project-URL: Source, https://github.com/lqxnjk/dupehunt
+Author: lqxnjk
+License: MIT
+License-File: LICENSE
+Keywords: cleanup,cli,dedupe,disk-usage,duplicate,duplicates,files,hash
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# dupehunt
+
+Find duplicate files by content hash. Zero dependencies, one command, works on
+Windows, macOS and Linux.
+
+```console
+$ dupehunt ~/Downloads
+3 group(s), 9 file(s), 412.6 MB reclaimable
+
+[1] 180.0 MB x 3  (360.0 MB wasted)
+    /home/me/Downloads/ubuntu.iso
+    /home/me/Downloads/ubuntu (1).iso
+    /home/me/Downloads/backup/ubuntu.iso
+
+[2] 26.3 MB x 2  (26.3 MB wasted)
+    ...
+```
+
+## Install
+
+```console
+pip install dupehunt
+```
+
+## Usage
+
+```console
+dupehunt [paths ...] [options]
+```
+
+| Option | Meaning |
+| --- | --- |
+| `paths` | Files or directories to scan. Default: current directory |
+| `-m, --min-size` | Skip files smaller than this. `1K`, `4M`, `1G` all accepted |
+| `-a, --algo` | `blake2b` (default), `sha256`, `sha1`, `md5` |
+| `-n, --top` | Show only the N largest groups |
+| `--json` | Machine readable output |
+| `--delete` | Delete extra copies, keeping the first path of each group |
+| `--yes` | Required together with `--delete` to actually delete |
+
+### Examples
+
+```console
+# biggest wins only, files above 10 MB
+dupehunt ~/Pictures -m 10M -n 20
+
+# feed the result to another tool
+dupehunt ~/data --json > dupes.json
+
+# preview what a cleanup would remove, without touching anything
+dupehunt ~/data --delete -m 1M
+
+# really delete the extra copies
+dupehunt ~/data --delete --yes -m 1M
+```
+
+`--delete` without `--yes` is always a dry run: it prints the plan and removes
+nothing. Nothing is ever deleted unless both flags are present.
+
+## How it works
+
+Three passes, cheapest first, so a full disk scan stays fast:
+
+1. Group files by exact size. Unique sizes drop out immediately.
+2. Hash the first 8 KiB of each remaining candidate.
+3. Hash the whole file only for candidates that still collide.
+
+Symlinks are never followed, and hard links to an already seen inode are counted
+once, so the same physical data is not reported as duplicates of itself.
+
+## Use as a library
+
+```python
+from pathlib import Path
+from dupehunt import find_duplicates, total_wasted
+
+groups = find_duplicates([Path(".")], n_min_size=1024 * 1024)
+for group in groups:
+    print(group.size, group.wasted, [str(p) for p in group.paths])
+print(total_wasted(groups))
+```
+
+## License
+
+MIT

dupehunt-0.0.1/README.md

@@ -0,0 +1,85 @@
+# dupehunt
+
+Find duplicate files by content hash. Zero dependencies, one command, works on
+Windows, macOS and Linux.
+
+```console
+$ dupehunt ~/Downloads
+3 group(s), 9 file(s), 412.6 MB reclaimable
+
+[1] 180.0 MB x 3  (360.0 MB wasted)
+    /home/me/Downloads/ubuntu.iso
+    /home/me/Downloads/ubuntu (1).iso
+    /home/me/Downloads/backup/ubuntu.iso
+
+[2] 26.3 MB x 2  (26.3 MB wasted)
+    ...
+```
+
+## Install
+
+```console
+pip install dupehunt
+```
+
+## Usage
+
+```console
+dupehunt [paths ...] [options]
+```
+
+| Option | Meaning |
+| --- | --- |
+| `paths` | Files or directories to scan. Default: current directory |
+| `-m, --min-size` | Skip files smaller than this. `1K`, `4M`, `1G` all accepted |
+| `-a, --algo` | `blake2b` (default), `sha256`, `sha1`, `md5` |
+| `-n, --top` | Show only the N largest groups |
+| `--json` | Machine readable output |
+| `--delete` | Delete extra copies, keeping the first path of each group |
+| `--yes` | Required together with `--delete` to actually delete |
+
+### Examples
+
+```console
+# biggest wins only, files above 10 MB
+dupehunt ~/Pictures -m 10M -n 20
+
+# feed the result to another tool
+dupehunt ~/data --json > dupes.json
+
+# preview what a cleanup would remove, without touching anything
+dupehunt ~/data --delete -m 1M
+
+# really delete the extra copies
+dupehunt ~/data --delete --yes -m 1M
+```
+
+`--delete` without `--yes` is always a dry run: it prints the plan and removes
+nothing. Nothing is ever deleted unless both flags are present.
+
+## How it works
+
+Three passes, cheapest first, so a full disk scan stays fast:
+
+1. Group files by exact size. Unique sizes drop out immediately.
+2. Hash the first 8 KiB of each remaining candidate.
+3. Hash the whole file only for candidates that still collide.
+
+Symlinks are never followed, and hard links to an already seen inode are counted
+once, so the same physical data is not reported as duplicates of itself.
+
+## Use as a library
+
+```python
+from pathlib import Path
+from dupehunt import find_duplicates, total_wasted
+
+groups = find_duplicates([Path(".")], n_min_size=1024 * 1024)
+for group in groups:
+    print(group.size, group.wasted, [str(p) for p in group.paths])
+print(total_wasted(groups))
+```
+
+## License
+
+MIT

dupehunt-0.0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dupehunt"
+version = "0.0.1"
+description = "Fast, dependency-free duplicate file finder with a friendly CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "lqxnjk" }]
+keywords = [
+    "duplicate",
+    "duplicates",
+    "dedupe",
+    "files",
+    "hash",
+    "disk-usage",
+    "cleanup",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: System :: Filesystems",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+dupehunt = "dupehunt.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/lqxnjk/dupehunt"
+Source = "https://github.com/lqxnjk/dupehunt"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dupehunt"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/dupehunt",
+    "tests",
+    "README.md",
+    "LICENSE",
+]

dupehunt-0.0.1/src/dupehunt/__init__.py

@@ -0,0 +1,31 @@
+"""
+Author: lqxnjk <lqxnjk@qq.com>
+Created: 2026-10-23 10:06
+Modified: 2026-10-23 10:06
+Python Version: 3.10
+"""
+
+from .cli import __version__, main
+from .core import (
+    SUPPORTED_ALGOS,
+    DuplicateGroup,
+    ScanError,
+    find_duplicates,
+    human_size,
+    iter_files,
+    parse_size,
+    total_wasted,
+)
+
+__all__ = [
+    "SUPPORTED_ALGOS",
+    "DuplicateGroup",
+    "ScanError",
+    "__version__",
+    "find_duplicates",
+    "human_size",
+    "iter_files",
+    "main",
+    "parse_size",
+    "total_wasted",
+]

dupehunt-0.0.1/src/dupehunt/__main__.py

@@ -0,0 +1,13 @@
+"""
+Author: lqxnjk <lqxnjk@qq.com>
+Created: 2026-10-23 10:06
+Modified: 2026-10-23 10:06
+Python Version: 3.10
+"""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

dupehunt-0.0.1/src/dupehunt/cli.py

@@ -0,0 +1,174 @@
+"""
+Author: lqxnjk <lqxnjk@qq.com>
+Created: 2026-10-23 10:06
+Modified: 2026-10-23 10:06
+Python Version: 3.10
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .core import (
+    SUPPORTED_ALGOS,
+    DuplicateGroup,
+    find_duplicates,
+    human_size,
+    parse_size,
+    total_wasted,
+)
+
+__version__ = "0.0.1"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dupehunt",
+        description="Find duplicate files by content hash.",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        default=["."],
+        help="files or directories to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "-m",
+        "--min-size",
+        default="1",
+        help="ignore files smaller than this, e.g. 1K, 4M, 1G (default: 1)",
+    )
+    parser.add_argument(
+        "-a",
+        "--algo",
+        default="blake2b",
+        choices=list(SUPPORTED_ALGOS),
+        help="hash algorithm (default: blake2b, fastest)",
+    )
+    parser.add_argument(
+        "-n",
+        "--top",
+        type=int,
+        default=0,
+        help="show only the N largest groups (0 = all)",
+    )
+    parser.add_argument("--json", action="store_true", help="machine readable output")
+    parser.add_argument(
+        "--delete",
+        action="store_true",
+        help="delete extra copies, keeping the first path in each group (dry run unless --yes)",
+    )
+    parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="confirm deletion; only meaningful together with --delete",
+    )
+    parser.add_argument("--version", action="version", version=f"dupehunt {__version__}")
+    return parser
+
+
+def _render_text(m_groups: Sequence[DuplicateGroup], m_roots: Sequence[str]) -> str:
+    if not m_groups:
+        return "no duplicates found"
+
+    lines = [
+        f"{len(m_groups)} group(s), "
+        f"{sum(len(group.paths) for group in m_groups)} file(s), "
+        f"{human_size(total_wasted(m_groups))} reclaimable",
+        "",
+    ]
+    for index, group in enumerate(m_groups, start=1):
+        lines.append(
+            f"[{index}] {human_size(group.size)} x {len(group.paths)}"
+            f"  ({human_size(group.wasted)} wasted)"
+        )
+        lines.extend(f"    {path}" for path in group.paths)
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def _render_json(m_groups: Sequence[DuplicateGroup], m_roots: Sequence[str]) -> str:
+    payload = {
+        "roots": list(m_roots),
+        "groups": [
+            {
+                "size": group.size,
+                "digest": group.digest,
+                "wasted": group.wasted,
+                "paths": [str(path) for path in group.paths],
+            }
+            for group in m_groups
+        ],
+        "total_wasted": total_wasted(m_groups),
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _delete_extras(m_groups: Sequence[DuplicateGroup], n_confirm: bool) -> int:
+    """Delete every path but the first in each group. Returns the number removed."""
+    targets = [path for group in m_groups for path in group.paths[1:]]
+    if not targets:
+        return 0
+    if not n_confirm:
+        print(
+            f"dry run: {len(targets)} file(s) would be deleted "
+            "(re-run with --delete --yes to apply)",
+            file=sys.stderr,
+        )
+        for path in targets:
+            print(f"  would delete {path}", file=sys.stderr)
+        return 0
+
+    removed = 0
+    for path in targets:
+        try:
+            os.remove(path)
+            removed += 1
+        except OSError as exc:
+            logging.getLogger(__name__).error("failed to delete %s: %s", path, exc)
+    return removed
+
+
+def main(m_argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(m_argv)
+
+    try:
+        min_size = parse_size(args.min_size)
+    except ValueError as exc:
+        parser.error(str(exc))
+        return 2
+
+    roots = [Path(item) for item in args.paths]
+    missing = [root for root in roots if not root.exists()]
+    if missing:
+        for root in missing:
+            print(f"path does not exist: {root}", file=sys.stderr)
+        return 2
+
+    try:
+        groups = find_duplicates(roots, n_min_size=min_size, n_algo=args.algo)
+    except OSError as exc:
+        logging.getLogger(__name__).error("scan failed: %s", exc)
+        return 1
+
+    if args.top > 0:
+        groups = groups[: args.top]
+
+    if args.json:
+        print(_render_json(groups, args.paths))
+    else:
+        print(_render_text(groups, args.paths))
+
+    if args.delete:
+        removed = _delete_extras(groups, n_confirm=args.yes)
+        if removed:
+            print(f"deleted {removed} file(s)", file=sys.stderr)
+
+    return 0

dupehunt-0.0.1/src/dupehunt/core.py

@@ -0,0 +1,189 @@
+"""
+Author: lqxnjk <lqxnjk@qq.com>
+Created: 2026-10-23 10:06
+Modified: 2026-10-23 10:06
+Python Version: 3.10
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Iterator, Sequence
+
+LOGGER = logging.getLogger(__name__)
+
+CHUNK_SIZE = 1 << 20
+QUICK_SIZE = 8192
+SUPPORTED_ALGOS = ("blake2b", "sha256", "sha1", "md5")
+
+
+@dataclass(frozen=True)
+class DuplicateGroup:
+    """A set of two or more files with identical content."""
+
+    size: int
+    digest: str
+    paths: list[Path]
+
+    @property
+    def wasted(self) -> int:
+        """Bytes that would be reclaimed by keeping a single copy."""
+        return self.size * (len(self.paths) - 1)
+
+
+class ScanError(OSError):
+    """Raised when a scan root cannot be read."""
+
+
+def human_size(m_num: int) -> str:
+    """Format a byte count as a short human readable string."""
+    value = float(m_num)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if value < 1024 or unit == "TB":
+            if unit == "B":
+                return f"{int(value)} {unit}"
+            return f"{value:.1f} {unit}"
+        value /= 1024
+    return f"{value:.1f} PB"
+
+
+def parse_size(m_text: str) -> int:
+    """Parse ``"1024"``, ``"10K"``, ``"1.5M"``, ``"2G"`` into bytes."""
+    raw = m_text.strip().upper().rstrip("B")
+    multiplier = 1
+    if raw and raw[-1] in "KMGTP":
+        multiplier = 1024 ** ("KMGTP".index(raw[-1]) + 1)
+        raw = raw[:-1]
+    try:
+        return int(float(raw) * multiplier)
+    except ValueError as exc:
+        raise ValueError(f"invalid size: {m_text!r}") from exc
+
+
+def _hash_file(m_path: Path, m_algo: str, n_limit: int | None = None) -> str:
+    """Hash a file, optionally reading at most ``n_limit`` bytes."""
+    digest = hashlib.new(m_algo)
+    remaining = n_limit
+    with m_path.open("rb") as handle:
+        while True:
+            want = CHUNK_SIZE if remaining is None else min(CHUNK_SIZE, remaining)
+            if want <= 0:
+                break
+            block = handle.read(want)
+            if not block:
+                break
+            digest.update(block)
+            if remaining is not None:
+                remaining -= len(block)
+    return digest.hexdigest()
+
+
+def iter_files(m_roots: Sequence[Path], n_min_size: int = 1) -> Iterator[tuple[Path, int]]:
+    """Yield ``(path, size)`` for regular files under ``m_roots``.
+
+    Symlinks are never followed and hard links to an already seen inode are
+    skipped, so the same physical data is not reported twice. Unreadable
+    entries are logged and skipped instead of aborting the whole scan.
+    """
+    seen_inodes: set[tuple[int, int]] = set()
+    for root in m_roots:
+        if root.is_file():
+            try:
+                stat = root.stat()
+            except OSError as exc:
+                LOGGER.warning("skip unreadable file %s: %s", root, exc)
+                continue
+            if stat.st_size >= n_min_size:
+                yield root, stat.st_size
+            continue
+        if not root.is_dir():
+            raise ScanError(f"not a directory: {root}")
+        stack = [root]
+        while stack:
+            current = stack.pop()
+            try:
+                entries = list(os.scandir(current))
+            except OSError as exc:
+                LOGGER.warning("skip unreadable directory %s: %s", current, exc)
+                continue
+            for entry in entries:
+                try:
+                    if entry.is_dir(follow_symlinks=False):
+                        stack.append(Path(entry.path))
+                        continue
+                    if not entry.is_file(follow_symlinks=False):
+                        continue
+                    stat = entry.stat(follow_symlinks=False)
+                except OSError as exc:
+                    LOGGER.warning("skip unreadable entry %s: %s", entry.path, exc)
+                    continue
+                inode = (stat.st_dev, stat.st_ino)
+                if inode != (0, 0):
+                    if inode in seen_inodes:
+                        LOGGER.debug("skip hard link %s", entry.path)
+                        continue
+                    seen_inodes.add(inode)
+                if stat.st_size >= n_min_size:
+                    yield Path(entry.path), stat.st_size
+
+
+def find_duplicates(
+    m_roots: Sequence[Path],
+    n_min_size: int = 1,
+    n_algo: str = "blake2b",
+) -> list[DuplicateGroup]:
+    """Return duplicate groups sorted by reclaimable space, largest first.
+
+    Three passes keep large scans cheap: group by size, then hash the first
+    few KiB, then hash the whole file only for surviving candidates.
+    """
+    if n_algo not in SUPPORTED_ALGOS:
+        raise ValueError(f"unsupported algorithm: {n_algo!r}")
+
+    by_size: dict[int, list[Path]] = defaultdict(list)
+    for path, size in iter_files(m_roots, n_min_size):
+        by_size[size].append(path)
+
+    candidates = [(size, path) for size, paths in by_size.items() if len(paths) > 1 for path in paths]
+    if not candidates:
+        return []
+
+    by_quick: dict[tuple[int, str], list[Path]] = defaultdict(list)
+    for size, path in candidates:
+        try:
+            quick = _hash_file(path, n_algo, QUICK_SIZE)
+        except OSError as exc:
+            LOGGER.warning("skip unreadable candidate %s: %s", path, exc)
+            continue
+        by_quick[(size, quick)].append(path)
+
+    groups: list[DuplicateGroup] = []
+    for (size, quick), paths in by_quick.items():
+        if len(paths) < 2:
+            continue
+        if size <= QUICK_SIZE:
+            groups.append(DuplicateGroup(size=size, digest=quick, paths=paths))
+            continue
+        by_full: dict[str, list[Path]] = defaultdict(list)
+        for path in paths:
+            try:
+                by_full[_hash_file(path, n_algo)].append(path)
+            except OSError as exc:
+                LOGGER.warning("skip unreadable candidate %s: %s", path, exc)
+                continue
+        for digest, same in by_full.items():
+            if len(same) > 1:
+                groups.append(DuplicateGroup(size=size, digest=digest, paths=same))
+
+    groups.sort(key=lambda group: group.wasted, reverse=True)
+    return groups
+
+
+def total_wasted(m_groups: Iterable[DuplicateGroup]) -> int:
+    """Sum reclaimable bytes across groups."""
+    return sum(group.wasted for group in m_groups)

dupehunt-0.0.1/tests/test_core.py

@@ -0,0 +1,106 @@
+"""
+Author: lqxnjk <lqxnjk@qq.com>
+Created: 2026-10-23 10:06
+Modified: 2026-10-23 10:06
+Python Version: 3.10
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from dupehunt import find_duplicates, human_size, parse_size, total_wasted
+
+
+def _write(path: Path, content: bytes) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(content)
+    return path
+
+
+def test_detects_identical_files(tmp_path: Path) -> None:
+    payload = b"same content" * 100
+    _write(tmp_path / "a.bin", payload)
+    _write(tmp_path / "sub" / "b.bin", payload)
+    _write(tmp_path / "c.bin", b"different")
+    _write(tmp_path / "d.bin", b"also different, longer payload")
+
+    groups = find_duplicates([tmp_path])
+
+    assert len(groups) == 1
+    assert groups[0].size == len(payload)
+    assert {p.name for p in groups[0].paths} == {"a.bin", "b.bin"}
+    assert groups[0].wasted == len(payload)
+
+
+def test_ignores_unique_files(tmp_path: Path) -> None:
+    _write(tmp_path / "a.txt", b"alpha")
+    _write(tmp_path / "b.txt", b"beta!")
+    assert find_duplicates([tmp_path]) == []
+
+
+def test_respects_min_size(tmp_path: Path) -> None:
+    _write(tmp_path / "a.txt", b"tiny")
+    _write(tmp_path / "b.txt", b"tiny")
+    assert find_duplicates([tmp_path], n_min_size=10) == []
+    assert len(find_duplicates([tmp_path], n_min_size=1)) == 1
+
+
+def test_large_file_uses_full_hash(tmp_path: Path) -> None:
+    head = b"x" * 8192
+    _write(tmp_path / "a.bin", head + b"tail-one")
+    _write(tmp_path / "b.bin", head + b"tail-two")
+
+    assert find_duplicates([tmp_path]) == []
+
+
+def test_groups_sorted_by_wasted(tmp_path: Path) -> None:
+    big = b"b" * 5000
+    small = b"s" * 100
+    _write(tmp_path / "big1", big)
+    _write(tmp_path / "big2", big)
+    _write(tmp_path / "small1", small)
+    _write(tmp_path / "small2", small)
+
+    groups = find_duplicates([tmp_path])
+
+    assert [g.size for g in groups] == [5000, 100]
+    assert total_wasted(groups) == 5100
+
+
+def test_accepts_single_file_root(tmp_path: Path) -> None:
+    target = _write(tmp_path / "one.bin", b"payload")
+    assert find_duplicates([target]) == []
+
+
+def test_missing_root_raises(tmp_path: Path) -> None:
+    with pytest.raises(OSError):
+        find_duplicates([tmp_path / "nope"])
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [("1", 1), ("1K", 1024), ("1k", 1024), ("1.5M", 1572864), ("2G", 2 * 1024**3)],
+)
+def test_parse_size(text: str, expected: int) -> None:
+    assert parse_size(text) == expected
+
+
+def test_parse_size_rejects_garbage() -> None:
+    with pytest.raises(ValueError):
+        parse_size("abc")
+
+
+@pytest.mark.parametrize(
+    ("num", "expected"),
+    [(0, "0 B"), (1023, "1023 B"), (1024, "1.0 KB"), (1536, "1.5 KB")],
+)
+def test_human_size(num: int, expected: str) -> None:
+    assert human_size(num) == expected
+
+
+def test_unsupported_algo(tmp_path: Path) -> None:
+    with pytest.raises(ValueError):
+        find_duplicates([tmp_path], n_algo="crc99")