⚡ Bolt: 디렉토리 탐색 중 불필요한 os.lstat() 호출 최적화

.jules/bolt.md

@@ -60,3 +60,6 @@
 ## 2026-06-25 - [Optimize Path.exists() when paired with stat()]
 **Learning:** Checking `Path.exists()` before `Path.stat()` introduces a redundant system call because `exists()` internally uses `stat()`.
 **Action:** Rely on catching the `OSError` from `Path.stat()` to simultaneously check for existence and retrieve file attributes, saving measurable I/O overhead on large filesystems.
+## 2026-06-26 - [Minimize os.lstat() overhead during directory traversal]
+**Learning:** During directory traversal (e.g., using `os.walk`), performing filesystem I/O operations like `os.lstat()` unconditionally on every directory introduces significant overhead, especially on slow network drives or deeply nested structures, even when the results are only needed for specific conditional logic (like exclude patterns).
+**Action:** Always place heavy filesystem operations like `os.lstat()` strictly inside the conditional blocks that actually require their output to avoid taxing the filesystem unnecessarily.

media_shrinker.py

@@ -214,21 +214,22 @@ def find_candidates(
                 dirnames[:] = []
                 continue
 
-        # Prune excluded directories
+        # ⚡ Bolt: Prune excluded directories while minimizing I/O overhead.
+        # Moved os.lstat strictly inside the excluded_exact_strs block to prevent
+        # unnecessary filesystem calls during traversal when no exclusions are specified.
         valid_dirs = []
         for d in dirnames:
             if d.casefold().startswith(excluded_prefixes):
                 continue
 
-            d_path_str = os.path.join(dirpath_str, d)
-
-            try:
-                d_stat = os.lstat(d_path_str)
-                is_symlink = stat.S_ISLNK(d_stat.st_mode)
-            except OSError:
-                continue
-
             if excluded_exact_strs:
+                d_path_str = os.path.join(dirpath_str, d)
+                try:
+                    d_stat = os.lstat(d_path_str)
+                    is_symlink = stat.S_ISLNK(d_stat.st_mode)
+                except OSError:
+                    continue
+
                 if not is_symlink:
                     resolved_d_str = os.path.join(resolved_dir_str, d)
                 else:

tests/test_media_shrinker.py

@@ -196,7 +196,8 @@ def flaky_lstat(path):
             with patch("os.lstat", flaky_lstat):
                 candidates = [
                     p[0].relative_to(root)
-                    for p in find_candidates(root, include_under_limit=True)
+                    # We pass exclude_paths so that directory symlink checks are evaluated
+                    for p in find_candidates(root, include_under_limit=True, exclude_paths=[root / "dummy"])
                 ]
 
             self.assertEqual(candidates, [Path("good.mp3")])