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.
- clutterxp/__init__.py +4 -0
- clutterxp/cli/__init__.py +7 -0
- clutterxp/cli/app.py +251 -0
- clutterxp/cli/cmd_config.py +250 -0
- clutterxp/cli/cmd_doctor.py +449 -0
- clutterxp/cli/cmd_duplicates.py +253 -0
- clutterxp/cli/cmd_gui.py +22 -0
- clutterxp/cli/cmd_history.py +233 -0
- clutterxp/cli/cmd_init.py +76 -0
- clutterxp/cli/cmd_organize.py +226 -0
- clutterxp/cli/cmd_rules.py +540 -0
- clutterxp/cli/cmd_scan.py +109 -0
- clutterxp/cli/cmd_service.py +130 -0
- clutterxp/cli/cmd_undo.py +180 -0
- clutterxp/cli/cmd_watch.py +147 -0
- clutterxp/cli/errors.py +166 -0
- clutterxp/cli/render.py +390 -0
- clutterxp/config/__init__.py +40 -0
- clutterxp/config/jsonschema.py +12 -0
- clutterxp/config/loader.py +212 -0
- clutterxp/config/placeholders.py +79 -0
- clutterxp/config/runtime.py +30 -0
- clutterxp/config/schema.py +166 -0
- clutterxp/config/validate.py +226 -0
- clutterxp/config/writer.py +248 -0
- clutterxp/config.example.yaml +76 -0
- clutterxp/duplicates/__init__.py +22 -0
- clutterxp/duplicates/detector.py +438 -0
- clutterxp/duplicates/hashcache.py +149 -0
- clutterxp/duplicates/namenorm.py +45 -0
- clutterxp/duplicates/quarantine.py +196 -0
- clutterxp/duplicates/report.py +110 -0
- clutterxp/gui/__init__.py +1 -0
- clutterxp/gui/api.py +494 -0
- clutterxp/gui/app.py +205 -0
- clutterxp/gui/models_qt.py +544 -0
- clutterxp/gui/views/__init__.py +21 -0
- clutterxp/gui/views/dashboard.py +253 -0
- clutterxp/gui/views/duplicates.py +404 -0
- clutterxp/gui/views/folders.py +354 -0
- clutterxp/gui/views/history.py +281 -0
- clutterxp/gui/views/preview.py +277 -0
- clutterxp/gui/views/rules.py +527 -0
- clutterxp/gui/views/settings.py +172 -0
- clutterxp/gui/workers.py +147 -0
- clutterxp/history/__init__.py +23 -0
- clutterxp/history/db.py +174 -0
- clutterxp/history/pathcodec.py +42 -0
- clutterxp/history/recovery.py +318 -0
- clutterxp/history/schema.sql +43 -0
- clutterxp/history/service.py +493 -0
- clutterxp/history/undo.py +373 -0
- clutterxp/interfaces.py +164 -0
- clutterxp/locking.py +113 -0
- clutterxp/logging_setup.py +73 -0
- clutterxp/models.py +266 -0
- clutterxp/mover/__init__.py +26 -0
- clutterxp/mover/collision.py +46 -0
- clutterxp/mover/fsops.py +191 -0
- clutterxp/mover/safe_move.py +741 -0
- clutterxp/organizer.py +388 -0
- clutterxp/packaging/clutterxp.service +15 -0
- clutterxp/paths.py +112 -0
- clutterxp/planner.py +339 -0
- clutterxp/py.typed +0 -0
- clutterxp/rules/__init__.py +16 -0
- clutterxp/rules/engine.py +374 -0
- clutterxp/rules/matcher.py +222 -0
- clutterxp/rules/template.py +171 -0
- clutterxp/rules/tokenizer.py +118 -0
- clutterxp/safety.py +111 -0
- clutterxp/scanner.py +196 -0
- clutterxp/service_install.py +208 -0
- clutterxp/units.py +59 -0
- clutterxp/watch/__init__.py +37 -0
- clutterxp/watch/debounce.py +84 -0
- clutterxp/watch/events.py +259 -0
- clutterxp/watch/ignore.py +77 -0
- clutterxp/watch/service.py +662 -0
- clutterxp/watch/settle.py +170 -0
- clutterxp-1.1.0.dist-info/METADATA +149 -0
- clutterxp-1.1.0.dist-info/RECORD +84 -0
- clutterxp-1.1.0.dist-info/WHEEL +4 -0
- 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"]
|