fix: symlink loop safety, remove unused fields, release 0.4.0

Author: igors93

.github/workflows/publish.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Git tag to publish, for example v0.3.1"
+        description: "Git tag to publish, for example v0.4.0"
         required: true
         type: string
 
@@ -18,7 +18,7 @@ env:
 
 jobs:
   build:
-    name: Test and build package
+    name: Quality checks, tests, and build
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -38,6 +38,15 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
 
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Pyright
+        run: pyright
+
       - name: Run tests
         run: pytest
 
@@ -68,6 +77,9 @@ jobs:
       - name: Check package metadata
         run: python -m twine check dist/*
 
+      - name: Verify py.typed is in wheel
+        run: python -m zipfile -l dist/*.whl | grep py.typed
+
       - name: Upload package distributions
         uses: actions/upload-artifact@v4
         with:

CHANGELOG.md

@@ -9,61 +9,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 No unreleased changes.
 
-## [0.3.1] — 2026-06-05
+## [0.4.0] — 2026-06-05
 
 ### Fixed
 
-- SQLite cache files are now correctly excluded when the scan root is accessed through a symbolic link. Path comparison now uses `resolve(strict=False)` on both sides so symlinked and real paths map to the same canonical key.
-- `-wal`, `-shm`, and `-journal` SQLite auxiliary files are excluded alongside the main cache database.
+- Root symbolic links are rejected when symbolic link traversal is disabled (`follow_symlinks=False`), including directory and file symlinks used as the scan root.
+- SQLite cache database and all auxiliary files (`-wal`, `-shm`, `-journal`) are excluded from scans.
+- Cache exclusion works correctly when the scan root is accessed through a symbolic link, using `resolve(strict=False)` on both sides of the comparison.
+- Internal path comparison during cache exclusion no longer raises `OSError` or `RuntimeError` on symlink loops or broken symlinks.
 - PyPI publishing workflow (`publish.yml`) rewritten as valid YAML — the previous file contained Markdown code fences that made it unparseable by GitHub Actions.
+- Public type annotations in `ScanOptions`, `ScanEvent`, and `ScanProgress` now resolve correctly on all supported Python versions via `get_type_hints()`.
 
 ### Changed
 
+- Cancelled CLI scans return exit status `3`. Exit code `3` takes priority over `--fail-on-duplicates`.
 - Minimum supported Python version raised from 3.9 to 3.10. The codebase uses `X | Y` union syntax broadly; requiring 3.10 makes this consistent and allows `get_type_hints()` to resolve annotations correctly at runtime.
-- `ProgressPhase` values corrected to `"discovery"`, `"hashing"`, and `"done"` — the `"grouping"` phase mentioned in the previous changelog was never emitted.
+- `ProgressPhase` values restricted to the phases actually emitted: `"discovery"`, `"hashing"`, and `"done"`.
+
+### Removed
+
+- `ScanEvent.from_cache` and `ScanEvent.bytes_read` fields removed. These fields were added in 0.3.0 but were never populated — they always remained at their default values (`False` and `0`). Removing them eliminates misleading API surface.
 
 ### Tooling
 
-- CI restructured into three jobs: `quality` (Ruff lint + format check + Pyright), `tests` (matrix across Ubuntu/Windows/macOS and Python 3.10–3.13), and `package` (build, Twine check, `py.typed` verification, wheel smoke test).
+- CI restructured into three jobs: `quality` (Ruff lint + format check + Pyright on Ubuntu), `tests` (matrix across Ubuntu, Windows, and macOS with Python 3.10–3.13), and `package` (build, Twine check, `py.typed` verification, wheel smoke test).
+- Publishing workflow (`publish.yml`) now runs Ruff, Pyright, and full quality checks before building, so manual releases cannot skip linting.
 - `pyyaml` added to development dependencies to enable workflow YAML validation in tests.
-- New regression tests: symlink policy (directory and file roots, broken symlinks), cache exclusion through symlinked roots, WAL/SHM/journal exclusion, typing contract, cancellation exit codes, version consistency, `py.typed` marker, workflow YAML validation.
+- Regression tests added: symlink policy, cache exclusion (including symlinked roots, symlink loops, broken symlinks), typing contracts, cancellation exit codes, version consistency, `py.typed` marker, workflow YAML validation.
 
 ## [0.3.0] — 2026-06-04
 
 ### Added
 
 - `DupeFinder` class — integration-ready scan engine with typed events, cancellation, and optional hash cache.
 - `ScanEvent` frozen dataclass — typed events emitted during each scan phase (`scan_started`, `file_discovered`, `file_hashed`, `duplicate_group_found`, `issue`, `scan_completed`, `scan_cancelled`).
-- `ScanProgress` frozen dataclass — simplified progress snapshots delivered to the new `on_progress` callback. Fields: `root`, `phase` (`"discovery"`, `"hashing"`, `"done"`), `scanned_files`, `hashed_files`, `total_candidates`, `duplicate_groups`, `elapsed_seconds`, `cancelled`.
+- `ScanEvent.from_cache` and `ScanEvent.bytes_read` fields (reserved; removed in 0.4.0).
+- `ScanProgress` frozen dataclass — simplified progress snapshots delivered to the new `on_progress` callback. Fields: `root`, `phase`, `scanned_files`, `hashed_files`, `total_candidates`, `duplicate_groups`, `elapsed_seconds`, `cancelled`.
 - `DupeFinder.on_progress` parameter — optional callback that receives a `ScanProgress` snapshot after each file discovered or hashed, and once more at the end with `phase="done"`.
 - `ScanOptions.max_files` — stop file discovery after N files.
 - `ScanOptions.max_depth` — limit directory recursion depth (`0` = root only).
 - `ScanOptions.timeout_seconds` — automatically cancel scan after N seconds.
 - `ScanReport.cancelled` — `True` when the scan was cancelled early.
 - `ScanReport.elapsed_seconds` — wall-clock scan duration.
-- `ScanReport.total_bytes_read` — total bytes read during hashing (always populated; zero when no files were hashed).
-- `ScanReport.to_dict()` and `ScanReport.to_json()` — convenience methods for serialization.
-- `DuplicateGroup.to_dict()` — serialize a single group to a plain dictionary.
-- `ScanIssue.to_dict()` — serialize a single issue to a plain dictionary.
+- `ScanReport.total_bytes_read` — total bytes read during hashing.
+- `ScanReport.to_dict()` and `ScanReport.to_json()` — convenience serialization methods.
+- `DuplicateGroup.to_dict()` and `ScanIssue.to_dict()` — serialize to plain dictionary.
 - `HashCache` protocol — interface for pluggable hash caches.
 - `SQLiteHashCache` — SQLite-backed persistent hash cache; entries validated by file size and mtime.
-- `ScanEvent.from_cache` and `ScanEvent.bytes_read` fields.
-- `grouping.candidate_files()` — public helper that filters files sharing a size with at least one other file.
-- `grouping.groups_from_hash_map()` — public helper that builds and sorts `DuplicateGroup` objects from a `(size, digest) → paths` mapping.
-- `_ScanCancelled` internal exception in `errors.py` — raised between chunks when `should_cancel` returns `True`; caught at the engine boundary.
-- `hash_file()` accepts `should_cancel` and `on_bytes_read` keyword-only callbacks.
-- `hash_files()` accepts `should_cancel` and `on_bytes_read` and forwards them to `hash_file()`.
-- `SCHEMA_VERSION = "1.1"` constant; `schema_version` and `total_bytes_read` fields in all JSON/dict output.
+- `grouping.candidate_files()` and `grouping.groups_from_hash_map()` — public helpers.
+- `_ScanCancelled` internal exception in `errors.py`.
+- `hash_file()` and `hash_files()` accept `should_cancel` and `on_bytes_read` callbacks.
+- `SCHEMA_VERSION = "1.1"` constant; `schema_version` and `total_bytes_read` in all JSON/dict output.
 - CLI flags: `--max-files`, `--max-depth`, `--timeout`, `--cache`, `--progress`.
 - `--progress` flag prints live discovery/hashing progress to stderr.
-- Cancelled CLI scans exit with status code `3`.
 
 ### Fixed
 
 - Engine now emits `type="issue"` events for all issues collected during discovery and hashing.
-- Cache error handling now catches `sqlite3.Error` in addition to `OSError`.
+- Cache error handling catches `sqlite3.Error` in addition to `OSError`.
 - CLI cache creation moved inside the `try` block so errors on cache open are caught and reported cleanly with exit code 1.
-- Engine no longer duplicates the size-grouping and hash-grouping logic from `grouping.py`.
+- Engine no longer duplicates size-grouping and hash-grouping logic from `grouping.py`.
 
 ### Changed
 
@@ -89,7 +94,7 @@ No unreleased changes.
 - Unit tests for all modules using only the Python standard library.
 - Zero runtime dependencies — standard library only.
 
-[Unreleased]: https://github.com/igors93/dupefinder/compare/v0.3.1...HEAD
-[0.3.1]: https://github.com/igors93/dupefinder/compare/v0.3.0...v0.3.1
+[Unreleased]: https://github.com/igors93/dupefinder/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/igors93/dupefinder/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/igors93/dupefinder/compare/v0.1.0...v0.3.0
 [0.1.0]: https://github.com/igors93/dupefinder/releases/tag/v0.1.0

README.md

@@ -194,10 +194,15 @@ Run `dupefinder --help` to see all options.
 
 | Code | Meaning |
 |------|---------|
-| `0` | Scan completed normally, no errors |
-| `1` | Scan failed (invalid path, permission error with `--strict`, etc.) |
-| `2` | Scan completed and duplicates were found (only with `--fail-on-duplicates`) |
-| `3` | Scan was cancelled (timeout or signal) |
+| `0` | Scan completed. Non-fatal issues may still be present in the report. |
+| `1` | Scan failed because of an invalid option, invalid path, cache error, or strict-mode error. |
+| `2` | Scan completed and duplicates were found while `--fail-on-duplicates` was enabled. |
+| `3` | Scan was cancelled or stopped by the configured timeout. |
+
+Notes:
+- `--strict` turns otherwise non-fatal file access errors into exit code `1`.
+- JSON output can contain an `issues` list even when the exit code is `0`.
+- Exit code `3` takes priority over `--fail-on-duplicates`.
 
 ## CLI reference
 
@@ -236,7 +241,7 @@ Run `dupefinder --help` to see all options.
 | `DuplicateGroup` | One group of files with identical content |
 | `FileInfo` | Path and size of a single file |
 | `ScanIssue` | A non-fatal error recorded during a scan |
-| `SQLiteHashCache` | SQLite-backed hash cache for repeated scans |
+| `SQLiteHashCache` | SQLite-backed hash cache — import from `dupefinder.cache` |
 
 ### JSON schema
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dupefinder"
-version = "0.3.1"
+version = "0.4.0"
 description = "A simple, safe, zero-dependency duplicate file finder for Python."
 readme = "README.md"
 requires-python = ">=3.10"

src/dupefinder/__init__.py

@@ -5,7 +5,7 @@
 from dupefinder.events import ScanEvent, ScanProgress
 from dupefinder.models import DuplicateGroup, FileInfo, ScanIssue, ScanOptions, ScanReport
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 
 __all__ = [
     "find_duplicates",

src/dupefinder/events.py

@@ -35,8 +35,6 @@ class ScanEvent:
     message: str | None = None
     issue: ScanIssue | None = None
     group: DuplicateGroup | None = None
-    from_cache: bool = False
-    bytes_read: int = 0
 
 
 @dataclass(frozen=True)

src/dupefinder/scanner.py

@@ -95,7 +95,10 @@ def _walk_directory(
 def _is_excluded(path: Path, excluded_paths: frozenset[Path]) -> bool:
     if not excluded_paths:
         return False
-    return normalize_internal_path(path) in excluded_paths
+    try:
+        return normalize_internal_path(path) in excluded_paths
+    except (OSError, RuntimeError):
+        return False
 
 
 def _handle_scan_error(

tests/test_hardening.py

@@ -252,6 +252,48 @@ def test_cache_excluded_through_symlinked_root(self) -> None:
             self.assertEqual(report.scanned_files, 2)
             self.assertEqual(report.total_groups, 1)
 
+    def test_circular_symlink_inside_root_does_not_crash_with_cache(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "a.txt").write_text("same", encoding="utf-8")
+            (root / "b.txt").write_text("same", encoding="utf-8")
+            loop = root / "loop"
+            try:
+                loop.symlink_to(loop)
+            except (OSError, NotImplementedError) as exc:
+                self.skipTest(f"Symlinks unavailable: {exc}")
+            cache_path = root / "cache.sqlite"
+
+            with SQLiteHashCache(cache_path) as cache:
+                report = DupeFinder(
+                    options=ScanOptions(ignore_hidden=False),
+                    cache=cache,
+                ).scan(root)
+
+            self.assertFalse(report.cancelled)
+            self.assertEqual(report.scanned_files, 2)
+
+    def test_broken_symlink_inside_root_does_not_crash_with_cache(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "a.txt").write_text("same", encoding="utf-8")
+            (root / "b.txt").write_text("same", encoding="utf-8")
+            broken = root / "broken"
+            try:
+                broken.symlink_to(root / "nonexistent_target")
+            except (OSError, NotImplementedError) as exc:
+                self.skipTest(f"Symlinks unavailable: {exc}")
+            cache_path = root / "cache.sqlite"
+
+            with SQLiteHashCache(cache_path) as cache:
+                report = DupeFinder(
+                    options=ScanOptions(ignore_hidden=False),
+                    cache=cache,
+                ).scan(root)
+
+            self.assertFalse(report.cancelled)
+            self.assertEqual(report.scanned_files, 2)
+
 
 class CancellationExitCodeTests(unittest.TestCase):
     def _make_report(self, **kwargs: object) -> ScanReport:

tests/test_models.py

@@ -131,7 +131,7 @@ def test_to_dict_contains_expected_keys(self):
     def test_to_dict_values_are_correct(self):
         issue = self._make_issue()
         result = issue.to_dict()
-        self.assertEqual(result["path"], "/some/file.txt")
+        self.assertEqual(result["path"], str(Path("/some/file.txt")))
         self.assertEqual(result["message"], "Permission denied")
         self.assertEqual(result["phase"], "scan")
 

tests/test_packaging.py

@@ -7,10 +7,11 @@
 import unittest
 from pathlib import Path
 
+ROOT = Path(__file__).parent.parent
+
 
 def _read_pyproject_version() -> str:
-    pyproject = Path(__file__).parent.parent / "pyproject.toml"
-    content = pyproject.read_text(encoding="utf-8")
+    content = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
     match = re.search(r'^version\s*=\s*"([^"]+)"', content, re.MULTILINE)
     if match is None:
         raise AssertionError("version not found in pyproject.toml")
@@ -42,11 +43,11 @@ def test_version_is_non_empty(self) -> None:
 
 class PyTypedTests(unittest.TestCase):
     def test_py_typed_marker_exists(self) -> None:
-        src = Path(__file__).parent.parent / "src" / "dupefinder" / "py.typed"
+        src = ROOT / "src" / "dupefinder" / "py.typed"
         self.assertTrue(src.exists(), f"py.typed not found at {src}")
 
     def test_py_typed_is_empty(self) -> None:
-        src = Path(__file__).parent.parent / "src" / "dupefinder" / "py.typed"
+        src = ROOT / "src" / "dupefinder" / "py.typed"
         if src.exists():
             self.assertEqual(src.read_text(), "", "py.typed should be an empty marker file")
 
@@ -65,6 +66,11 @@ def test_public_api_is_importable(self) -> None:
         self.assertTrue(callable(DupeFinder))
         self.assertTrue(callable(ScanOptions))
 
+    def test_sqlite_hash_cache_importable_from_module(self) -> None:
+        from dupefinder.cache import SQLiteHashCache
+
+        self.assertTrue(callable(SQLiteHashCache))
+
     def test_python_version_meets_minimum(self) -> None:
         self.assertGreaterEqual(
             sys.version_info[:2],
@@ -73,5 +79,74 @@ def test_python_version_meets_minimum(self) -> None:
         )
 
 
+class READMEDocumentationTests(unittest.TestCase):
+    _readme: str = ""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls._readme = (ROOT / "README.md").read_text(encoding="utf-8")
+
+    def test_readme_documents_exit_code_zero(self) -> None:
+        self.assertIn("| `0`", self._readme, "README must document exit code 0")
+
+    def test_readme_documents_exit_code_one(self) -> None:
+        self.assertIn("| `1`", self._readme, "README must document exit code 1")
+
+    def test_readme_documents_exit_code_two(self) -> None:
+        self.assertIn("| `2`", self._readme, "README must document exit code 2")
+
+    def test_readme_documents_exit_code_three(self) -> None:
+        self.assertIn("| `3`", self._readme, "README must document exit code 3")
+
+    def test_readme_notes_exit_code_3_priority(self) -> None:
+        self.assertIn(
+            "priority",
+            self._readme.lower(),
+            "README must clarify that exit code 3 takes priority over --fail-on-duplicates",
+        )
+
+
+class ChangelogStructureTests(unittest.TestCase):
+    _changelog: str = ""
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls._changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8")
+
+    def test_changelog_has_unreleased_section_first(self) -> None:
+        lines = self._changelog.splitlines()
+        headers = [line.strip() for line in lines if line.startswith("## ")]
+        self.assertTrue(headers, "No ## sections found in CHANGELOG")
+        self.assertIn("[Unreleased]", headers[0], "First ## section must be [Unreleased]")
+
+    def test_changelog_current_version_exists(self) -> None:
+        import dupefinder
+
+        self.assertIn(
+            dupefinder.__version__,
+            self._changelog,
+            f"CHANGELOG must contain a section for version {dupefinder.__version__}",
+        )
+
+    def test_changelog_exit_code_3_not_in_030_section(self) -> None:
+        # Exit code 3 was added after v0.3.0; it must not be listed under [0.3.0].
+        changelog = self._changelog
+        idx_030 = changelog.find("## [0.3.0]")
+        idx_010 = changelog.find("## [0.1.0]")
+        if idx_030 == -1 or idx_010 == -1:
+            return
+        section_030 = changelog[idx_030:idx_010]
+        self.assertNotIn(
+            "exit status `3`",
+            section_030,
+            "Exit code 3 must not be listed under [0.3.0]; it was introduced later",
+        )
+        self.assertNotIn(
+            "exit code `3`",
+            section_030,
+            "Exit code 3 must not be listed under [0.3.0]; it was introduced later",
+        )
+
+
 if __name__ == "__main__":
     unittest.main()