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
clutterxp/planner.py
ADDED
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
"""Planner module for evaluating rule decisions and building an execution Plan.
|
|
2
|
+
|
|
3
|
+
Converts FileInfo streams into PlannedAction entries, resolving destinations,
|
|
4
|
+
checking permissions and collision policies, and ensuring zero writes to disk.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import os
|
|
10
|
+
from collections.abc import Iterable, Sequence
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from clutterxp import safety
|
|
14
|
+
from clutterxp.config.runtime import RuntimeConfig
|
|
15
|
+
from clutterxp.interfaces import RuleEngine
|
|
16
|
+
from clutterxp.models import (
|
|
17
|
+
CollisionPolicy,
|
|
18
|
+
CreateDestinations,
|
|
19
|
+
DecisionKind,
|
|
20
|
+
ErrorCode,
|
|
21
|
+
FileInfo,
|
|
22
|
+
Plan,
|
|
23
|
+
PlannedAction,
|
|
24
|
+
PlanStatus,
|
|
25
|
+
SafetyRefusal,
|
|
26
|
+
)
|
|
27
|
+
from clutterxp.mover.collision import candidate_names
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def build_plan(
|
|
31
|
+
infos: Iterable[FileInfo],
|
|
32
|
+
engine: RuleEngine,
|
|
33
|
+
config: RuntimeConfig | None = None,
|
|
34
|
+
*,
|
|
35
|
+
fs_check: bool = True,
|
|
36
|
+
folder: Path | None = None,
|
|
37
|
+
folders: Sequence[Path] | None = None,
|
|
38
|
+
) -> Plan:
|
|
39
|
+
"""Build a Plan from FileInfo objects using the given RuleEngine.
|
|
40
|
+
|
|
41
|
+
- Resolves destination path for matching rules.
|
|
42
|
+
- Safety checks destination against denylist (docs/09 S11).
|
|
43
|
+
- Checks watched folder containment unless allow_chain is True (docs/09 S9).
|
|
44
|
+
- Performs collision checks (skip vs rename) when fs_check is True.
|
|
45
|
+
- Pre-checks destination directory existence per create mode (never, leaf, all).
|
|
46
|
+
- Checks writability of destination directory.
|
|
47
|
+
- Performs ZERO disk writes and ZERO file content reads (Invariants S6, S7).
|
|
48
|
+
"""
|
|
49
|
+
info_list = list(infos)
|
|
50
|
+
actions: list[PlannedAction] = []
|
|
51
|
+
|
|
52
|
+
if folders is not None:
|
|
53
|
+
plan_folders = tuple(folders)
|
|
54
|
+
elif folder is not None:
|
|
55
|
+
plan_folders = (folder,)
|
|
56
|
+
else:
|
|
57
|
+
plan_folders = tuple(sorted({fi.path.parent for fi in info_list}))
|
|
58
|
+
|
|
59
|
+
for info in info_list:
|
|
60
|
+
decision = engine.decide(info, folder=folder)
|
|
61
|
+
|
|
62
|
+
if decision.kind == DecisionKind.NO_MATCH:
|
|
63
|
+
actions.append(
|
|
64
|
+
PlannedAction(
|
|
65
|
+
file=info,
|
|
66
|
+
status=PlanStatus.NO_MATCH,
|
|
67
|
+
decision=decision,
|
|
68
|
+
dest_path=None,
|
|
69
|
+
code=ErrorCode.NONE,
|
|
70
|
+
message=decision.reason or "No rule matched",
|
|
71
|
+
)
|
|
72
|
+
)
|
|
73
|
+
continue
|
|
74
|
+
|
|
75
|
+
if decision.kind == DecisionKind.AMBIGUOUS:
|
|
76
|
+
cand_names = ", ".join(c.rule_name for c in decision.candidates)
|
|
77
|
+
actions.append(
|
|
78
|
+
PlannedAction(
|
|
79
|
+
file=info,
|
|
80
|
+
status=PlanStatus.AMBIGUOUS,
|
|
81
|
+
decision=decision,
|
|
82
|
+
dest_path=None,
|
|
83
|
+
code=ErrorCode.NONE,
|
|
84
|
+
message=f"Ambiguous match across rules: {cand_names}",
|
|
85
|
+
)
|
|
86
|
+
)
|
|
87
|
+
continue
|
|
88
|
+
|
|
89
|
+
if decision.kind == DecisionKind.IGNORED:
|
|
90
|
+
actions.append(
|
|
91
|
+
PlannedAction(
|
|
92
|
+
file=info,
|
|
93
|
+
status=PlanStatus.IGNORED,
|
|
94
|
+
decision=decision,
|
|
95
|
+
dest_path=None,
|
|
96
|
+
code=ErrorCode.NONE,
|
|
97
|
+
message=decision.reason or "Ignored",
|
|
98
|
+
)
|
|
99
|
+
)
|
|
100
|
+
continue
|
|
101
|
+
|
|
102
|
+
# DecisionKind.MATCH
|
|
103
|
+
hit = decision.hit
|
|
104
|
+
if hit is None:
|
|
105
|
+
actions.append(
|
|
106
|
+
PlannedAction(
|
|
107
|
+
file=info,
|
|
108
|
+
status=PlanStatus.BLOCKED,
|
|
109
|
+
decision=decision,
|
|
110
|
+
dest_path=None,
|
|
111
|
+
code=ErrorCode.UNKNOWN,
|
|
112
|
+
message="Match decision without rule hit",
|
|
113
|
+
)
|
|
114
|
+
)
|
|
115
|
+
continue
|
|
116
|
+
|
|
117
|
+
dest_dir = hit.dest_dir
|
|
118
|
+
dest_path = dest_dir / info.name
|
|
119
|
+
|
|
120
|
+
# Safety check destination
|
|
121
|
+
try:
|
|
122
|
+
safety.check_destination(dest_path)
|
|
123
|
+
except SafetyRefusal as e:
|
|
124
|
+
actions.append(
|
|
125
|
+
PlannedAction(
|
|
126
|
+
file=info,
|
|
127
|
+
status=PlanStatus.BLOCKED,
|
|
128
|
+
decision=decision,
|
|
129
|
+
dest_path=dest_path,
|
|
130
|
+
code=ErrorCode.DEST_INVALID,
|
|
131
|
+
message=str(e),
|
|
132
|
+
)
|
|
133
|
+
)
|
|
134
|
+
continue
|
|
135
|
+
|
|
136
|
+
# Invariant S9: Destination inside watched folder without allow_chain
|
|
137
|
+
if config is not None and not config.settings.allow_chain:
|
|
138
|
+
dest_resolved = dest_path.resolve()
|
|
139
|
+
is_inside_watch = False
|
|
140
|
+
for w in config.watch_entries:
|
|
141
|
+
try:
|
|
142
|
+
w_resolved = Path(w.path).resolve()
|
|
143
|
+
dest_resolved.relative_to(w_resolved)
|
|
144
|
+
is_inside_watch = True
|
|
145
|
+
break
|
|
146
|
+
except (ValueError, OSError):
|
|
147
|
+
pass
|
|
148
|
+
if is_inside_watch:
|
|
149
|
+
actions.append(
|
|
150
|
+
PlannedAction(
|
|
151
|
+
file=info,
|
|
152
|
+
status=PlanStatus.BLOCKED,
|
|
153
|
+
decision=decision,
|
|
154
|
+
dest_path=dest_path,
|
|
155
|
+
code=ErrorCode.DEST_INVALID,
|
|
156
|
+
message="Destination is inside a watched folder (allow_chain is False)",
|
|
157
|
+
)
|
|
158
|
+
)
|
|
159
|
+
continue
|
|
160
|
+
|
|
161
|
+
# Precondition: Destination directory is not source's own directory (no-op)
|
|
162
|
+
try:
|
|
163
|
+
if dest_path.resolve() == info.path.resolve():
|
|
164
|
+
actions.append(
|
|
165
|
+
PlannedAction(
|
|
166
|
+
file=info,
|
|
167
|
+
status=PlanStatus.BLOCKED,
|
|
168
|
+
decision=decision,
|
|
169
|
+
dest_path=dest_path,
|
|
170
|
+
code=ErrorCode.DEST_INVALID,
|
|
171
|
+
message="Destination directory is source's own directory (no-op)",
|
|
172
|
+
)
|
|
173
|
+
)
|
|
174
|
+
continue
|
|
175
|
+
except OSError:
|
|
176
|
+
pass
|
|
177
|
+
|
|
178
|
+
if not fs_check:
|
|
179
|
+
actions.append(
|
|
180
|
+
PlannedAction(
|
|
181
|
+
file=info,
|
|
182
|
+
status=PlanStatus.WILL_MOVE,
|
|
183
|
+
decision=decision,
|
|
184
|
+
dest_path=dest_path,
|
|
185
|
+
code=ErrorCode.NONE,
|
|
186
|
+
message="",
|
|
187
|
+
)
|
|
188
|
+
)
|
|
189
|
+
continue
|
|
190
|
+
|
|
191
|
+
# Check CreateDestinations policy
|
|
192
|
+
create_policy = hit.create
|
|
193
|
+
if create_policy == CreateDestinations.NEVER:
|
|
194
|
+
if not dest_dir.exists() or not dest_dir.is_dir():
|
|
195
|
+
actions.append(
|
|
196
|
+
PlannedAction(
|
|
197
|
+
file=info,
|
|
198
|
+
status=PlanStatus.BLOCKED,
|
|
199
|
+
decision=decision,
|
|
200
|
+
dest_path=dest_path,
|
|
201
|
+
code=ErrorCode.DEST_MISSING,
|
|
202
|
+
message=(
|
|
203
|
+
f"Destination directory '{dest_dir}' does not exist (create: never)"
|
|
204
|
+
),
|
|
205
|
+
)
|
|
206
|
+
)
|
|
207
|
+
continue
|
|
208
|
+
elif create_policy == CreateDestinations.LEAF:
|
|
209
|
+
static_root = hit.static_root
|
|
210
|
+
if static_root is not None:
|
|
211
|
+
if not static_root.exists() and not static_root.parent.exists():
|
|
212
|
+
actions.append(
|
|
213
|
+
PlannedAction(
|
|
214
|
+
file=info,
|
|
215
|
+
status=PlanStatus.BLOCKED,
|
|
216
|
+
decision=decision,
|
|
217
|
+
dest_path=dest_path,
|
|
218
|
+
code=ErrorCode.DEST_MISSING,
|
|
219
|
+
message=(
|
|
220
|
+
f"Static root parent '{static_root.parent}' does not exist "
|
|
221
|
+
"(create: leaf)"
|
|
222
|
+
),
|
|
223
|
+
)
|
|
224
|
+
)
|
|
225
|
+
continue
|
|
226
|
+
# If dest_dir is not relative to static_root, ensure its parent exists
|
|
227
|
+
try:
|
|
228
|
+
dest_dir.relative_to(static_root)
|
|
229
|
+
except ValueError:
|
|
230
|
+
if not dest_dir.exists() and not dest_dir.parent.exists():
|
|
231
|
+
actions.append(
|
|
232
|
+
PlannedAction(
|
|
233
|
+
file=info,
|
|
234
|
+
status=PlanStatus.BLOCKED,
|
|
235
|
+
decision=decision,
|
|
236
|
+
dest_path=dest_path,
|
|
237
|
+
code=ErrorCode.DEST_MISSING,
|
|
238
|
+
message=(
|
|
239
|
+
f"Destination parent '{dest_dir.parent}' does not exist "
|
|
240
|
+
"(create: leaf)"
|
|
241
|
+
),
|
|
242
|
+
)
|
|
243
|
+
)
|
|
244
|
+
continue
|
|
245
|
+
else:
|
|
246
|
+
if not dest_dir.exists() and not dest_dir.parent.exists():
|
|
247
|
+
actions.append(
|
|
248
|
+
PlannedAction(
|
|
249
|
+
file=info,
|
|
250
|
+
status=PlanStatus.BLOCKED,
|
|
251
|
+
decision=decision,
|
|
252
|
+
dest_path=dest_path,
|
|
253
|
+
code=ErrorCode.DEST_MISSING,
|
|
254
|
+
message=(
|
|
255
|
+
f"Destination parent '{dest_dir.parent}' does not exist "
|
|
256
|
+
"(create: leaf)"
|
|
257
|
+
),
|
|
258
|
+
)
|
|
259
|
+
)
|
|
260
|
+
continue
|
|
261
|
+
|
|
262
|
+
# Check writability of existing ancestor
|
|
263
|
+
check_dir = dest_dir
|
|
264
|
+
while not check_dir.exists() and check_dir != check_dir.parent:
|
|
265
|
+
check_dir = check_dir.parent
|
|
266
|
+
if check_dir.exists() and not os.access(check_dir, os.W_OK | os.X_OK):
|
|
267
|
+
actions.append(
|
|
268
|
+
PlannedAction(
|
|
269
|
+
file=info,
|
|
270
|
+
status=PlanStatus.BLOCKED,
|
|
271
|
+
decision=decision,
|
|
272
|
+
dest_path=dest_path,
|
|
273
|
+
code=ErrorCode.DEST_NOT_WRITABLE,
|
|
274
|
+
message=f"Destination directory '{check_dir}' is not writable",
|
|
275
|
+
)
|
|
276
|
+
)
|
|
277
|
+
continue
|
|
278
|
+
|
|
279
|
+
# Collision pre-check
|
|
280
|
+
if dest_path.exists():
|
|
281
|
+
if hit.collision == CollisionPolicy.SKIP:
|
|
282
|
+
actions.append(
|
|
283
|
+
PlannedAction(
|
|
284
|
+
file=info,
|
|
285
|
+
status=PlanStatus.BLOCKED,
|
|
286
|
+
decision=decision,
|
|
287
|
+
dest_path=dest_path,
|
|
288
|
+
code=ErrorCode.COLLISION,
|
|
289
|
+
message=f"Destination path '{dest_path}' already exists (collision: skip)",
|
|
290
|
+
)
|
|
291
|
+
)
|
|
292
|
+
continue
|
|
293
|
+
elif hit.collision == CollisionPolicy.RENAME:
|
|
294
|
+
renamed_dest: Path | None = None
|
|
295
|
+
for cand_name in candidate_names(info.name):
|
|
296
|
+
cand_path = dest_dir / cand_name
|
|
297
|
+
if not cand_path.exists():
|
|
298
|
+
renamed_dest = cand_path
|
|
299
|
+
break
|
|
300
|
+
if renamed_dest is not None:
|
|
301
|
+
actions.append(
|
|
302
|
+
PlannedAction(
|
|
303
|
+
file=info,
|
|
304
|
+
status=PlanStatus.WILL_MOVE_RENAMED,
|
|
305
|
+
decision=decision,
|
|
306
|
+
dest_path=renamed_dest,
|
|
307
|
+
code=ErrorCode.NONE,
|
|
308
|
+
message=f"Collision detected; will rename to '{renamed_dest.name}'",
|
|
309
|
+
)
|
|
310
|
+
)
|
|
311
|
+
continue
|
|
312
|
+
else:
|
|
313
|
+
actions.append(
|
|
314
|
+
PlannedAction(
|
|
315
|
+
file=info,
|
|
316
|
+
status=PlanStatus.BLOCKED,
|
|
317
|
+
decision=decision,
|
|
318
|
+
dest_path=dest_path,
|
|
319
|
+
code=ErrorCode.COLLISION,
|
|
320
|
+
message="All collision rename candidates exhausted",
|
|
321
|
+
)
|
|
322
|
+
)
|
|
323
|
+
continue
|
|
324
|
+
|
|
325
|
+
actions.append(
|
|
326
|
+
PlannedAction(
|
|
327
|
+
file=info,
|
|
328
|
+
status=PlanStatus.WILL_MOVE,
|
|
329
|
+
decision=decision,
|
|
330
|
+
dest_path=dest_path,
|
|
331
|
+
code=ErrorCode.NONE,
|
|
332
|
+
message="",
|
|
333
|
+
)
|
|
334
|
+
)
|
|
335
|
+
|
|
336
|
+
return Plan(folders=plan_folders, actions=tuple(actions))
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
__all__ = ["build_plan"]
|
clutterxp/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Rule engine: tokenization, matching, template expansion, and decision making."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
from clutterxp.config.schema import RuleSpec, Settings
|
|
8
|
+
from clutterxp.rules.engine import RuleEngineImpl
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def build_engine(rules: list[RuleSpec], settings: Settings, **kwargs: Any) -> RuleEngineImpl:
|
|
12
|
+
"""Factory. A01's RuntimeConfig will be adapted here when merged."""
|
|
13
|
+
return RuleEngineImpl(rules, settings, **kwargs)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
__all__ = ["RuleEngineImpl", "build_engine"]
|