clutterxp 1.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. clutterxp/__init__.py +4 -0
  2. clutterxp/cli/__init__.py +7 -0
  3. clutterxp/cli/app.py +251 -0
  4. clutterxp/cli/cmd_config.py +250 -0
  5. clutterxp/cli/cmd_doctor.py +449 -0
  6. clutterxp/cli/cmd_duplicates.py +253 -0
  7. clutterxp/cli/cmd_gui.py +22 -0
  8. clutterxp/cli/cmd_history.py +233 -0
  9. clutterxp/cli/cmd_init.py +76 -0
  10. clutterxp/cli/cmd_organize.py +226 -0
  11. clutterxp/cli/cmd_rules.py +540 -0
  12. clutterxp/cli/cmd_scan.py +109 -0
  13. clutterxp/cli/cmd_service.py +130 -0
  14. clutterxp/cli/cmd_undo.py +180 -0
  15. clutterxp/cli/cmd_watch.py +147 -0
  16. clutterxp/cli/errors.py +166 -0
  17. clutterxp/cli/render.py +390 -0
  18. clutterxp/config/__init__.py +40 -0
  19. clutterxp/config/jsonschema.py +12 -0
  20. clutterxp/config/loader.py +212 -0
  21. clutterxp/config/placeholders.py +79 -0
  22. clutterxp/config/runtime.py +30 -0
  23. clutterxp/config/schema.py +166 -0
  24. clutterxp/config/validate.py +226 -0
  25. clutterxp/config/writer.py +248 -0
  26. clutterxp/config.example.yaml +76 -0
  27. clutterxp/duplicates/__init__.py +22 -0
  28. clutterxp/duplicates/detector.py +438 -0
  29. clutterxp/duplicates/hashcache.py +149 -0
  30. clutterxp/duplicates/namenorm.py +45 -0
  31. clutterxp/duplicates/quarantine.py +196 -0
  32. clutterxp/duplicates/report.py +110 -0
  33. clutterxp/gui/__init__.py +1 -0
  34. clutterxp/gui/api.py +494 -0
  35. clutterxp/gui/app.py +205 -0
  36. clutterxp/gui/models_qt.py +544 -0
  37. clutterxp/gui/views/__init__.py +21 -0
  38. clutterxp/gui/views/dashboard.py +253 -0
  39. clutterxp/gui/views/duplicates.py +404 -0
  40. clutterxp/gui/views/folders.py +354 -0
  41. clutterxp/gui/views/history.py +281 -0
  42. clutterxp/gui/views/preview.py +277 -0
  43. clutterxp/gui/views/rules.py +527 -0
  44. clutterxp/gui/views/settings.py +172 -0
  45. clutterxp/gui/workers.py +147 -0
  46. clutterxp/history/__init__.py +23 -0
  47. clutterxp/history/db.py +174 -0
  48. clutterxp/history/pathcodec.py +42 -0
  49. clutterxp/history/recovery.py +318 -0
  50. clutterxp/history/schema.sql +43 -0
  51. clutterxp/history/service.py +493 -0
  52. clutterxp/history/undo.py +373 -0
  53. clutterxp/interfaces.py +164 -0
  54. clutterxp/locking.py +113 -0
  55. clutterxp/logging_setup.py +73 -0
  56. clutterxp/models.py +266 -0
  57. clutterxp/mover/__init__.py +26 -0
  58. clutterxp/mover/collision.py +46 -0
  59. clutterxp/mover/fsops.py +191 -0
  60. clutterxp/mover/safe_move.py +741 -0
  61. clutterxp/organizer.py +388 -0
  62. clutterxp/packaging/clutterxp.service +15 -0
  63. clutterxp/paths.py +112 -0
  64. clutterxp/planner.py +339 -0
  65. clutterxp/py.typed +0 -0
  66. clutterxp/rules/__init__.py +16 -0
  67. clutterxp/rules/engine.py +374 -0
  68. clutterxp/rules/matcher.py +222 -0
  69. clutterxp/rules/template.py +171 -0
  70. clutterxp/rules/tokenizer.py +118 -0
  71. clutterxp/safety.py +111 -0
  72. clutterxp/scanner.py +196 -0
  73. clutterxp/service_install.py +208 -0
  74. clutterxp/units.py +59 -0
  75. clutterxp/watch/__init__.py +37 -0
  76. clutterxp/watch/debounce.py +84 -0
  77. clutterxp/watch/events.py +259 -0
  78. clutterxp/watch/ignore.py +77 -0
  79. clutterxp/watch/service.py +662 -0
  80. clutterxp/watch/settle.py +170 -0
  81. clutterxp-1.1.0.dist-info/METADATA +149 -0
  82. clutterxp-1.1.0.dist-info/RECORD +84 -0
  83. clutterxp-1.1.0.dist-info/WHEEL +4 -0
  84. clutterxp-1.1.0.dist-info/entry_points.txt +6 -0
@@ -0,0 +1,171 @@
1
+ """Destination template expansion and static root calculation.
2
+
3
+ Implements ~ and $VAR expansion, placeholder substitution ({year}, {month},
4
+ {day}, {ext}, {rule}, {mtime:...}), value sanitization, and static root
5
+ containment per docs/02_RULE_ENGINE.md section 7 and safety invariant S13.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import datetime
11
+ import difflib
12
+ import os
13
+ import re
14
+ from pathlib import Path
15
+
16
+ from clutterxp.models import ClutterError, ErrorCode, FileInfo
17
+
18
+ ALLOWED_PLACEHOLDERS = frozenset(["year", "month", "day", "ext", "rule", "mtime"])
19
+
20
+ _ENV_VAR_RE = re.compile(r"\$(?:([A-Za-z_][A-Za-z0-9_]*)|(?:\{([A-Za-z_][A-Za-z0-9_]*)\}))")
21
+ _PLACEHOLDER_RE = re.compile(r"\{([^}]+)\}")
22
+
23
+
24
+ def static_root(template: str) -> str:
25
+ """Returns the path prefix before the first {placeholder}."""
26
+ first_brace = template.find("{")
27
+ if first_brace == -1:
28
+ return template
29
+
30
+ prefix = template[:first_brace]
31
+ last_slash = prefix.rfind("/")
32
+ if last_slash == -1:
33
+ return ""
34
+ if last_slash == 0:
35
+ return "/"
36
+ return prefix[:last_slash]
37
+
38
+
39
+ def _expand_env_and_tilde(text: str, environ: dict[str, str] | None) -> str:
40
+ """Expand ~ and $VAR / ${VAR} in text.
41
+
42
+ Raises ClutterError(code=DEST_INVALID) if any $VAR is unset.
43
+ """
44
+ env = os.environ if environ is None else environ
45
+
46
+ def replace_var(m: re.Match[str]) -> str:
47
+ var_name = m.group(1) or m.group(2)
48
+ if var_name not in env:
49
+ raise ClutterError(
50
+ f"unresolved environment variable: ${var_name}",
51
+ code=ErrorCode.DEST_INVALID,
52
+ )
53
+ return env[var_name]
54
+
55
+ expanded = _ENV_VAR_RE.sub(replace_var, text)
56
+
57
+ # Expand tilde ~
58
+ if expanded == "~" or expanded.startswith("~/"):
59
+ home = env.get("HOME")
60
+ if not home:
61
+ home = str(Path.home())
62
+ expanded = home + expanded[1:]
63
+
64
+ return expanded
65
+
66
+
67
+ def expand(
68
+ template: str,
69
+ file: FileInfo,
70
+ rule_name: str,
71
+ *,
72
+ now_ns: int | None = None, # nanoseconds, default to file mtime
73
+ environ: dict[str, str] | None = None,
74
+ ) -> Path:
75
+ """Expand template to absolute Path.
76
+
77
+ Raises ClutterError(code=DEST_INVALID) if:
78
+ - Substituted value contains '/' or NUL
79
+ - Substituted value is '.' or '..'
80
+ - Unknown placeholder (did-you-mean in message)
81
+ - {mtime:} with '/' in format string
82
+ - Expanded destination escapes static root (S13)
83
+ First expands ~ and $VAR, then {placeholders}.
84
+ Result is os.path.normpath'd (NOT realpath, no symlink resolution).
85
+ """
86
+ # 1. Expand ~ and environment variables
87
+ expanded_template = _expand_env_and_tilde(template, environ)
88
+
89
+ # Calculate static root of the template
90
+ raw_static = static_root(template)
91
+ expanded_static = _expand_env_and_tilde(raw_static, environ)
92
+ norm_static = os.path.normpath(expanded_static)
93
+ static_root_path = Path(norm_static)
94
+
95
+ # 2. Prepare timestamp for time-based placeholders
96
+ timestamp_ns = now_ns if now_ns is not None else file.mtime_ns
97
+ dt = datetime.datetime.fromtimestamp(timestamp_ns / 1_000_000_000)
98
+
99
+ # 3. Substitute {placeholders}
100
+ def replace_placeholder(m: re.Match[str]) -> str:
101
+ content = m.group(1)
102
+ val: str
103
+
104
+ if content.startswith("mtime:"):
105
+ fmt = content[6:]
106
+ if "/" in fmt or "\x00" in fmt:
107
+ raise ClutterError(
108
+ f"strftime format in {{mtime:...}} cannot contain '/' or NUL: {fmt!r}",
109
+ code=ErrorCode.DEST_INVALID,
110
+ )
111
+ try:
112
+ val = dt.strftime(fmt)
113
+ except ValueError as e:
114
+ raise ClutterError(
115
+ f"invalid strftime format {fmt!r}: {e}",
116
+ code=ErrorCode.DEST_INVALID,
117
+ ) from e
118
+ elif content == "mtime":
119
+ val = dt.strftime("%Y%m%d_%H%M%S")
120
+ elif content == "year":
121
+ val = f"{dt.year:04d}"
122
+ elif content == "month":
123
+ val = f"{dt.month:02d}"
124
+ elif content == "day":
125
+ val = f"{dt.day:02d}"
126
+ elif content == "ext":
127
+ val = file.ext.lower() if file.ext else "noext"
128
+ elif content == "rule":
129
+ val = rule_name.replace("/", "").replace("\\", "").replace("\x00", "")
130
+ else:
131
+ close = difflib.get_close_matches(content, list(ALLOWED_PLACEHOLDERS), n=1)
132
+ hint = f" (did you mean '{close[0]}' ?)" if close else ""
133
+ raise ClutterError(
134
+ f"unknown placeholder '{content}'{hint}",
135
+ code=ErrorCode.DEST_INVALID,
136
+ )
137
+
138
+ if "/" in val or "\x00" in val:
139
+ raise ClutterError(
140
+ f"substituted value for '{{{content}}}' contains '/' or NUL: {val!r}",
141
+ code=ErrorCode.DEST_INVALID,
142
+ )
143
+ if val in (".", ".."):
144
+ raise ClutterError(
145
+ f"substituted value for '{{{content}}}' cannot be '.' or '..': {val!r}",
146
+ code=ErrorCode.DEST_INVALID,
147
+ )
148
+
149
+ return val
150
+
151
+ expanded_path_str = _PLACEHOLDER_RE.sub(replace_placeholder, expanded_template)
152
+
153
+ norm_dest = os.path.normpath(expanded_path_str)
154
+ dest_path = Path(norm_dest)
155
+
156
+ if not dest_path.is_absolute():
157
+ raise ClutterError(
158
+ f"expanded destination must be absolute: {dest_path}",
159
+ code=ErrorCode.DEST_INVALID,
160
+ )
161
+
162
+ # 4. Containment check (S13): cannot escape static root
163
+ if static_root_path.is_absolute() and (
164
+ dest_path != static_root_path and static_root_path not in dest_path.parents
165
+ ):
166
+ raise ClutterError(
167
+ f"expanded destination {dest_path} escapes static root {static_root_path}",
168
+ code=ErrorCode.DEST_INVALID,
169
+ )
170
+
171
+ return dest_path
@@ -0,0 +1,118 @@
1
+ """Tokenizer module for ClutterXP rule engine.
2
+
3
+ Implements Unicode NFC normalization, hidden file detection, stem/extension
4
+ splitting, raw tokenization, camelCase splitting, and keyword tokenization
5
+ per docs/02_RULE_ENGINE.md sections 2 and 3.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ import unicodedata
12
+
13
+ _SEPARATOR_RE = re.compile(r"[\W_]+")
14
+ _EXT_RE = re.compile(r"^[A-Za-z0-9_+-]{1,8}$")
15
+
16
+
17
+ def normalize(name: str) -> str:
18
+ """NFC normalize. Pure, never raises."""
19
+ if not isinstance(name, str):
20
+ return ""
21
+ return unicodedata.normalize("NFC", name)
22
+
23
+
24
+ def is_hidden(name: str) -> bool:
25
+ """True if name starts with '.'"""
26
+ return name.startswith(".")
27
+
28
+
29
+ def split_stem(name: str) -> tuple[str, str]:
30
+ """Returns (stem, ext) where ext is the last suffix (after stripping .tar if compound).
31
+
32
+ Extension: 1-8 alphanumeric+_+- chars after a dot that isn't the first char.
33
+ .tar.gz -> stem=base, ext=tar.gz. .bashrc -> stem=.bashrc, ext=''.
34
+ """
35
+ normalized = normalize(name)
36
+ last_dot = normalized.rfind(".")
37
+ if last_dot <= 0:
38
+ return normalized, ""
39
+
40
+ suffix = normalized[last_dot + 1 :]
41
+ if not _EXT_RE.match(suffix):
42
+ return normalized, ""
43
+
44
+ stem = normalized[:last_dot]
45
+ # Compound .tar check: if remaining stem ends with .tar (case-insensitive)
46
+ # and that .tar also has a dot that is not the first character of stem
47
+ if stem.lower().endswith(".tar"):
48
+ tar_dot = stem.rfind(".")
49
+ if tar_dot > 0:
50
+ stem = stem[:tar_dot]
51
+ ext = normalized[tar_dot + 1 :].lower()
52
+ return stem, ext
53
+
54
+ return stem, suffix.lower()
55
+
56
+
57
+ def raw_tokens(stem: str, *, casefold: bool = True) -> list[str]:
58
+ """Split on [\\W_]+, casefold, drop empty. Pure."""
59
+ normalized = normalize(stem)
60
+ tokens: list[str] = []
61
+ for piece in _SEPARATOR_RE.split(normalized):
62
+ if not piece:
63
+ continue
64
+ tok = piece.casefold() if casefold else piece
65
+ if tok:
66
+ tokens.append(tok)
67
+ return tokens
68
+
69
+
70
+ def _split_camel_word(token: str) -> list[str]:
71
+ """Split a single token on camelCase / PascalCase / UPPER_to_lower boundaries.
72
+
73
+ Letters and digits are NOT split.
74
+ """
75
+ if len(token) <= 1:
76
+ return [token] if token else []
77
+
78
+ split_indices: list[int] = [0]
79
+ for i in range(1, len(token)):
80
+ prev = token[i - 1]
81
+ curr = token[i]
82
+
83
+ # Lower-to-upper boundary: 'SecLeaf' -> 'Sec', 'Leaf'
84
+ # Upper-run to Capital+lower: 'HTMLParser' -> 'HTML', 'Parser'
85
+ if (prev.islower() and curr.isupper()) or (
86
+ prev.isupper() and curr.isupper() and (i + 1 < len(token)) and token[i + 1].islower()
87
+ ):
88
+ split_indices.append(i)
89
+
90
+ split_indices.append(len(token))
91
+ return [token[split_indices[j] : split_indices[j + 1]] for j in range(len(split_indices) - 1)]
92
+
93
+
94
+ def camel_tokens(original_stem: str, *, casefold: bool = True) -> list[str]:
95
+ """Split camelCase/PascalCase/UPPER_to_lower boundaries in original-case tokens,
96
+
97
+ then casefold. Rules:
98
+ - Lower-to-upper boundary: 'SecLeaf' -> ['sec', 'leaf']
99
+ - Upper-run to Capital+lower: 'HTMLParser' -> ['html', 'parser']
100
+ - Letters and digits are NOT split: 'sl2' stays 'sl2'
101
+ Pure, never raises.
102
+ """
103
+ normalized = normalize(original_stem)
104
+ tokens: list[str] = []
105
+ # First split on separators without casefolding to get original-case tokens
106
+ for piece in _SEPARATOR_RE.split(normalized):
107
+ if not piece:
108
+ continue
109
+ for sub in _split_camel_word(piece):
110
+ tok = sub.casefold() if casefold else sub
111
+ if tok:
112
+ tokens.append(tok)
113
+ return tokens
114
+
115
+
116
+ def keyword_tokens(keyword: str, *, casefold: bool = True) -> list[str]:
117
+ """Tokenize a keyword with raw algorithm only."""
118
+ return raw_tokens(keyword, casefold=casefold)
clutterxp/safety.py ADDED
@@ -0,0 +1,111 @@
1
+ """Safety invariants and denylist enforcement (docs/09_SAFETY.md)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from pathlib import Path
7
+
8
+ from .models import SafetyRefusal
9
+
10
+ DENYLIST: frozenset[Path] = frozenset(
11
+ [
12
+ Path("/"),
13
+ Path("/bin"),
14
+ Path("/boot"),
15
+ Path("/dev"),
16
+ Path("/etc"),
17
+ Path("/lib"),
18
+ Path("/lib32"),
19
+ Path("/lib64"),
20
+ Path("/proc"),
21
+ Path("/run"),
22
+ Path("/sbin"),
23
+ Path("/sys"),
24
+ Path("/usr"),
25
+ Path("/var/lib"),
26
+ Path("/var/log"),
27
+ ]
28
+ )
29
+
30
+
31
+ def refuse_root(*, allow_root: bool = False) -> None:
32
+ """Refuse execution if running as root (UID 0) unless allow_root is True.
33
+
34
+ Raises SafetyRefusal (mapped to exit code 4 by the CLI).
35
+ """
36
+ if not allow_root and hasattr(os, "geteuid") and os.geteuid() == 0:
37
+ raise SafetyRefusal(
38
+ "Refused: running as root (UID 0) is forbidden for safety. "
39
+ "Pass --allow-root to override."
40
+ )
41
+
42
+
43
+ _SLASH_PATH = Path("/")
44
+ _ROOT_PATH = Path("/root")
45
+ _NON_ROOT_DENY: frozenset[Path] = frozenset(p for p in DENYLIST if p != _SLASH_PATH)
46
+ _NON_ROOT_DENY_WITH_ROOT: frozenset[Path] = _NON_ROOT_DENY | {_ROOT_PATH}
47
+
48
+
49
+ def is_denylisted(path: Path, *, allow_root: bool = False) -> bool:
50
+ """Check whether a path resolves into the system denylist."""
51
+ real = Path(os.path.realpath(str(path)))
52
+
53
+ if real == _SLASH_PATH:
54
+ return True
55
+
56
+ all_ancestors = set(real.parents)
57
+ all_ancestors.add(real)
58
+ target_set = _NON_ROOT_DENY if allow_root else _NON_ROOT_DENY_WITH_ROOT
59
+ return not target_set.isdisjoint(all_ancestors)
60
+
61
+
62
+ def check_source_root(path: Path, *, recursive: bool = False, allow_root: bool = False) -> None:
63
+ """Refuse source roots that are in the system denylist or recursive $HOME.
64
+
65
+ Raises SafetyRefusal if path is forbidden.
66
+ """
67
+ refuse_root(allow_root=allow_root)
68
+
69
+ real = Path(os.path.realpath(str(path)))
70
+
71
+ if is_denylisted(real, allow_root=allow_root):
72
+ raise SafetyRefusal(f"Source root '{path}' resolves to denylisted system path '{real}'.")
73
+
74
+ try:
75
+ home = Path(os.path.realpath(str(Path.home())))
76
+ if recursive and real == home:
77
+ raise SafetyRefusal(
78
+ f"Recursive watch or scan of $HOME ('{path}') is refused for safety. "
79
+ "Organizing $HOME recursively would affect system and application data."
80
+ )
81
+ except RuntimeError:
82
+ pass
83
+
84
+
85
+ def check_destination(path: Path, *, allow_root: bool = False) -> None:
86
+ """Refuse destinations that are in the system denylist or contain hidden components.
87
+
88
+ Raises SafetyRefusal if path is forbidden.
89
+ """
90
+ refuse_root(allow_root=allow_root)
91
+
92
+ # Check components of the path itself
93
+ for part in path.parts:
94
+ if part in ("/", "\\"):
95
+ continue
96
+ if part.startswith("."):
97
+ raise SafetyRefusal(f"Destination '{path}' contains hidden component '{part}'.")
98
+
99
+ real = Path(os.path.realpath(str(path)))
100
+
101
+ if is_denylisted(real, allow_root=allow_root):
102
+ raise SafetyRefusal(f"Destination '{path}' resolves to denylisted system path '{real}'.")
103
+
104
+ # Check components after resolving symlinks
105
+ for part in real.parts:
106
+ if part in ("/", "\\"):
107
+ continue
108
+ if part.startswith("."):
109
+ raise SafetyRefusal(
110
+ f"Destination '{path}' resolves to hidden component '{part}' in '{real}'."
111
+ )
clutterxp/scanner.py ADDED
@@ -0,0 +1,196 @@
1
+ """Scanner module for directory traversal and FileInfo generation.
2
+
3
+ Lists directory entries using os.scandir, applies ignore patterns and hidden
4
+ file filters, and yields FileInfo objects. Honors docs/03 and docs/09.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import contextlib
10
+ import fnmatch
11
+ import os
12
+ import stat
13
+ from collections.abc import Iterator, Sequence
14
+ from pathlib import Path
15
+
16
+ from clutterxp.config.schema import Settings
17
+ from clutterxp.models import FileInfo
18
+
19
+ BUILTIN_IGNORE_PATTERNS: tuple[str, ...] = (
20
+ "*.crdownload",
21
+ "*.part",
22
+ "*.partial",
23
+ "*.tmp",
24
+ "*.temp",
25
+ "*.download",
26
+ "*.opdownload",
27
+ "*.!qB",
28
+ "*.aria2",
29
+ "*.swp",
30
+ "*.swx",
31
+ "*~",
32
+ "~$*",
33
+ ".~lock.*#",
34
+ "*.clutterxp-partial",
35
+ )
36
+
37
+
38
+ def _matches_any_pattern(name: str, patterns: Sequence[str], *, case_sensitive: bool) -> bool:
39
+ """Check if filename matches any of the given glob patterns."""
40
+ if case_sensitive:
41
+ return any(fnmatch.fnmatchcase(name, pat) for pat in patterns)
42
+ name_folded = name.casefold()
43
+ return any(fnmatch.fnmatchcase(name_folded, pat.casefold()) for pat in patterns)
44
+
45
+
46
+ def scan(
47
+ folder: Path,
48
+ *,
49
+ recursive: bool = False,
50
+ settings: Settings | None = None,
51
+ ignore_patterns: Sequence[str] = (),
52
+ ) -> Iterator[FileInfo]:
53
+ """Scan folder and yield FileInfo for each entry.
54
+
55
+ - Uses os.scandir.
56
+ - Performs one lstat per yielded entry.
57
+ - Honors built-in ignore patterns + settings.ignore + ignore_patterns.
58
+ - If settings.skip_hidden is True (default), skips files/directories with a leading dot.
59
+ - Never descends into hidden directories.
60
+ - Never follows symlinked directories.
61
+ - Non-regular files (symlinks unless follow_symlinks, dirs when non-recursive, fifos, sockets)
62
+ are yielded with is_regular=False so the rule engine can mark them IGNORED.
63
+ - Recursion only occurs when recursive is True.
64
+ """
65
+ folder_path = Path(folder)
66
+ if not folder_path.is_dir():
67
+ return
68
+
69
+ skip_hidden = settings.skip_hidden if settings is not None else True
70
+ follow_symlinks = settings.follow_symlinks if settings is not None else False
71
+ case_sensitive = settings.case_sensitive if settings is not None else False
72
+
73
+ all_ignores: list[str] = list(BUILTIN_IGNORE_PATTERNS)
74
+ if settings is not None and settings.ignore:
75
+ all_ignores.extend(settings.ignore)
76
+ if ignore_patterns:
77
+ all_ignores.extend(ignore_patterns)
78
+
79
+ try:
80
+ with os.scandir(folder_path) as it:
81
+ entries = sorted(it, key=lambda e: e.name)
82
+ except OSError:
83
+ return
84
+
85
+ for entry in entries:
86
+ name = entry.name
87
+
88
+ # Hidden file / directory check
89
+ if skip_hidden and name.startswith("."):
90
+ continue
91
+
92
+ # Ignore patterns check
93
+ if _matches_any_pattern(name, all_ignores, case_sensitive=case_sensitive):
94
+ continue
95
+
96
+ entry_path = Path(entry.path)
97
+
98
+ is_symlink = False
99
+ with contextlib.suppress(OSError):
100
+ is_symlink = entry.is_symlink()
101
+
102
+ if is_symlink:
103
+ is_symlinked_dir = False
104
+ with contextlib.suppress(OSError):
105
+ is_symlinked_dir = entry.is_dir(follow_symlinks=True)
106
+
107
+ if is_symlinked_dir:
108
+ # Symlinked directories: NEVER descend into them
109
+ try:
110
+ st = entry_path.lstat()
111
+ except OSError:
112
+ continue
113
+ yield FileInfo(
114
+ path=entry_path,
115
+ name=entry_path.name,
116
+ stem=entry_path.stem,
117
+ ext="",
118
+ size=st.st_size,
119
+ mtime_ns=st.st_mtime_ns,
120
+ inode=st.st_ino,
121
+ device=st.st_dev,
122
+ is_regular=False,
123
+ is_symlink=True,
124
+ )
125
+ continue
126
+
127
+ is_dir = False
128
+ with contextlib.suppress(OSError):
129
+ is_dir = entry.is_dir(follow_symlinks=False)
130
+
131
+ if is_dir:
132
+ # Real directory
133
+ if recursive:
134
+ yield from scan(
135
+ entry_path,
136
+ recursive=True,
137
+ settings=settings,
138
+ ignore_patterns=ignore_patterns,
139
+ )
140
+ else:
141
+ try:
142
+ st = entry_path.lstat()
143
+ except OSError:
144
+ continue
145
+ yield FileInfo(
146
+ path=entry_path,
147
+ name=entry_path.name,
148
+ stem=entry_path.stem,
149
+ ext="",
150
+ size=st.st_size,
151
+ mtime_ns=st.st_mtime_ns,
152
+ inode=st.st_ino,
153
+ device=st.st_dev,
154
+ is_regular=False,
155
+ is_symlink=False,
156
+ )
157
+ continue
158
+
159
+ # Non-directory entries
160
+ if is_symlink:
161
+ is_reg = False
162
+ st_target = None
163
+ if follow_symlinks:
164
+ with contextlib.suppress(OSError):
165
+ st_target = entry_path.stat()
166
+ is_reg = stat.S_ISREG(st_target.st_mode)
167
+
168
+ try:
169
+ st = entry_path.lstat()
170
+ except OSError:
171
+ continue
172
+
173
+ stat_info = st_target if (is_reg and st_target is not None) else st
174
+ suffix = entry_path.suffix
175
+ yield FileInfo(
176
+ path=entry_path,
177
+ name=entry_path.name,
178
+ stem=entry_path.stem,
179
+ ext=suffix[1:].lower() if suffix else "",
180
+ size=stat_info.st_size,
181
+ mtime_ns=stat_info.st_mtime_ns,
182
+ inode=stat_info.st_ino,
183
+ device=stat_info.st_dev,
184
+ is_regular=is_reg,
185
+ is_symlink=True,
186
+ )
187
+ continue
188
+
189
+ # Regular files, FIFOs, sockets, devices
190
+ try:
191
+ yield FileInfo.from_path(entry_path)
192
+ except OSError:
193
+ continue
194
+
195
+
196
+ __all__ = ["BUILTIN_IGNORE_PATTERNS", "scan"]