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,374 @@
|
|
|
1
|
+
"""Rule engine implementation for ClutterXP.
|
|
2
|
+
|
|
3
|
+
Implements RuleEngine protocol: compiles rules, tokenizes file names once,
|
|
4
|
+
evaluates rule criteria (extensions, conditions, keywords, all_of, exclude),
|
|
5
|
+
resolves priority and ambiguity, and produces RuleTraces per docs/02_RULE_ENGINE.md.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
import time
|
|
12
|
+
from collections.abc import Callable, Sequence
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Literal
|
|
16
|
+
|
|
17
|
+
from clutterxp.config.schema import RuleSpec, Settings, WatchEntry
|
|
18
|
+
from clutterxp.interfaces import RuleEngine
|
|
19
|
+
from clutterxp.models import (
|
|
20
|
+
CollisionPolicy,
|
|
21
|
+
CreateDestinations,
|
|
22
|
+
Decision,
|
|
23
|
+
DecisionKind,
|
|
24
|
+
FileInfo,
|
|
25
|
+
RuleHit,
|
|
26
|
+
RuleTrace,
|
|
27
|
+
)
|
|
28
|
+
from clutterxp.rules.matcher import MatchContext, compile_keyword
|
|
29
|
+
from clutterxp.rules.template import _expand_env_and_tilde, expand, static_root
|
|
30
|
+
from clutterxp.rules.tokenizer import camel_tokens, is_hidden, raw_tokens, split_stem
|
|
31
|
+
from clutterxp.units import parse_duration_seconds, parse_size
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class _CompiledRule:
|
|
36
|
+
spec: RuleSpec
|
|
37
|
+
name: str
|
|
38
|
+
enabled: bool
|
|
39
|
+
priority: int
|
|
40
|
+
destination_template: str
|
|
41
|
+
collision: CollisionPolicy
|
|
42
|
+
create: CreateDestinations
|
|
43
|
+
extensions: tuple[str, ...]
|
|
44
|
+
keywords_matchers: tuple[tuple[str, Callable[[MatchContext], str | None]], ...]
|
|
45
|
+
all_of_matchers: tuple[tuple[str, Callable[[MatchContext], str | None]], ...]
|
|
46
|
+
exclude_matchers: tuple[tuple[str, Callable[[MatchContext], str | None]], ...]
|
|
47
|
+
min_size: int | None
|
|
48
|
+
max_size: int | None
|
|
49
|
+
older_than_s: int | None
|
|
50
|
+
newer_than_s: int | None
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class RuleEngineImpl(RuleEngine):
|
|
54
|
+
"""Implements RuleEngine Protocol."""
|
|
55
|
+
|
|
56
|
+
def __init__(
|
|
57
|
+
self,
|
|
58
|
+
rules: list[RuleSpec],
|
|
59
|
+
settings: Settings,
|
|
60
|
+
*,
|
|
61
|
+
now_ns: int | None = None,
|
|
62
|
+
environ: dict[str, str] | None = None,
|
|
63
|
+
folder_rules: dict[Path | str, Sequence[str] | Literal["all"]] | None = None,
|
|
64
|
+
watch: list[WatchEntry] | None = None,
|
|
65
|
+
) -> None:
|
|
66
|
+
"""Precompile all rules at construction. Compile matchers, extension tuples, etc."""
|
|
67
|
+
self.rules: list[RuleSpec] = rules
|
|
68
|
+
self.settings: Settings = settings
|
|
69
|
+
self.now_ns: int | None = now_ns
|
|
70
|
+
self.environ: dict[str, str] | None = environ
|
|
71
|
+
|
|
72
|
+
# Build folder rule restrictions mapping
|
|
73
|
+
self._folder_rules: dict[Path, frozenset[str]] = {}
|
|
74
|
+
if watch is not None:
|
|
75
|
+
for entry in watch:
|
|
76
|
+
if entry.rules != "all":
|
|
77
|
+
expanded_p = _expand_env_and_tilde(entry.path, environ)
|
|
78
|
+
norm_p = Path(os.path.normpath(expanded_p))
|
|
79
|
+
self._folder_rules[norm_p] = frozenset(r.casefold() for r in entry.rules)
|
|
80
|
+
|
|
81
|
+
if folder_rules is not None:
|
|
82
|
+
for folder_key, rule_names in folder_rules.items():
|
|
83
|
+
if rule_names != "all":
|
|
84
|
+
expanded_p = _expand_env_and_tilde(str(folder_key), environ)
|
|
85
|
+
norm_p = Path(os.path.normpath(expanded_p))
|
|
86
|
+
self._folder_rules[norm_p] = frozenset(r.casefold() for r in rule_names)
|
|
87
|
+
|
|
88
|
+
# Precompile rules
|
|
89
|
+
self._compiled_rules: list[_CompiledRule] = []
|
|
90
|
+
for r in rules:
|
|
91
|
+
eff_mode = r.match if r.match is not None else settings.match
|
|
92
|
+
eff_collision = r.collision if r.collision is not None else settings.collision
|
|
93
|
+
eff_create = (
|
|
94
|
+
r.create_destinations
|
|
95
|
+
if r.create_destinations is not None
|
|
96
|
+
else settings.create_destinations
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
# Extension filters (case-insensitive, strip leading dot)
|
|
100
|
+
exts = tuple(e.casefold() for e in r.extensions)
|
|
101
|
+
|
|
102
|
+
# Keyword matchers
|
|
103
|
+
kw_matchers = tuple(
|
|
104
|
+
(kw, compile_keyword(kw, eff_mode, settings.case_sensitive)) for kw in r.keywords
|
|
105
|
+
)
|
|
106
|
+
all_of_matchers = tuple(
|
|
107
|
+
(kw, compile_keyword(kw, eff_mode, settings.case_sensitive)) for kw in r.all_of
|
|
108
|
+
)
|
|
109
|
+
exclude_matchers = tuple(
|
|
110
|
+
(kw, compile_keyword(kw, eff_mode, settings.case_sensitive)) for kw in r.exclude
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
# Conditions
|
|
114
|
+
min_size = (
|
|
115
|
+
parse_size(r.conditions.min_size) if r.conditions.min_size is not None else None
|
|
116
|
+
)
|
|
117
|
+
max_size = (
|
|
118
|
+
parse_size(r.conditions.max_size) if r.conditions.max_size is not None else None
|
|
119
|
+
)
|
|
120
|
+
older_than_s = (
|
|
121
|
+
parse_duration_seconds(r.conditions.older_than)
|
|
122
|
+
if r.conditions.older_than is not None
|
|
123
|
+
else None
|
|
124
|
+
)
|
|
125
|
+
newer_than_s = (
|
|
126
|
+
parse_duration_seconds(r.conditions.newer_than)
|
|
127
|
+
if r.conditions.newer_than is not None
|
|
128
|
+
else None
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
self._compiled_rules.append(
|
|
132
|
+
_CompiledRule(
|
|
133
|
+
spec=r,
|
|
134
|
+
name=r.name,
|
|
135
|
+
enabled=r.enabled,
|
|
136
|
+
priority=r.priority,
|
|
137
|
+
destination_template=r.destination,
|
|
138
|
+
collision=eff_collision,
|
|
139
|
+
create=eff_create,
|
|
140
|
+
extensions=exts,
|
|
141
|
+
keywords_matchers=kw_matchers,
|
|
142
|
+
all_of_matchers=all_of_matchers,
|
|
143
|
+
exclude_matchers=exclude_matchers,
|
|
144
|
+
min_size=min_size,
|
|
145
|
+
max_size=max_size,
|
|
146
|
+
older_than_s=older_than_s,
|
|
147
|
+
newer_than_s=newer_than_s,
|
|
148
|
+
)
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
def _build_context(self, file: FileInfo) -> MatchContext:
|
|
152
|
+
"""Tokenize file name once and build MatchContext."""
|
|
153
|
+
stem, ext = split_stem(file.name)
|
|
154
|
+
casefolded_name = file.name.casefold()
|
|
155
|
+
raw_toks = raw_tokens(stem, casefold=not self.settings.case_sensitive)
|
|
156
|
+
camel_toks = camel_tokens(stem, casefold=not self.settings.case_sensitive)
|
|
157
|
+
|
|
158
|
+
return MatchContext(
|
|
159
|
+
name=file.name,
|
|
160
|
+
casefolded_name=casefolded_name,
|
|
161
|
+
stem=stem,
|
|
162
|
+
ext=ext,
|
|
163
|
+
raw_toks=raw_toks,
|
|
164
|
+
camel_toks=camel_toks,
|
|
165
|
+
case_sensitive=self.settings.case_sensitive,
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
def _evaluate_rule(
|
|
169
|
+
self,
|
|
170
|
+
rule: _CompiledRule,
|
|
171
|
+
ctx: MatchContext,
|
|
172
|
+
file: FileInfo,
|
|
173
|
+
) -> tuple[bool, str, list[str]]:
|
|
174
|
+
"""Evaluate a single rule against context and file stat data.
|
|
175
|
+
|
|
176
|
+
Returns (matched, matched_by, reasons).
|
|
177
|
+
"""
|
|
178
|
+
if not rule.enabled:
|
|
179
|
+
return False, "", ["rule is disabled"]
|
|
180
|
+
|
|
181
|
+
# 1. Extensions check: file name ends with .<ext> (case-insensitive)
|
|
182
|
+
if rule.extensions:
|
|
183
|
+
name_to_check = ctx.name if self.settings.case_sensitive else ctx.casefolded_name
|
|
184
|
+
ext_match = False
|
|
185
|
+
for e in rule.extensions:
|
|
186
|
+
target_suffix = "." + e if self.settings.case_sensitive else "." + e.casefold()
|
|
187
|
+
if name_to_check.endswith(target_suffix):
|
|
188
|
+
ext_match = True
|
|
189
|
+
break
|
|
190
|
+
if not ext_match:
|
|
191
|
+
return (
|
|
192
|
+
False,
|
|
193
|
+
"",
|
|
194
|
+
[f"extension '{file.ext}' does not match {list(rule.extensions)}"],
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
# 2. Conditions check (cheap stat-based)
|
|
198
|
+
if rule.min_size is not None and file.size < rule.min_size:
|
|
199
|
+
return False, "", [f"size {file.size} < min_size {rule.min_size}"]
|
|
200
|
+
if rule.max_size is not None and file.size > rule.max_size:
|
|
201
|
+
return False, "", [f"size {file.size} > max_size {rule.max_size}"]
|
|
202
|
+
|
|
203
|
+
ref_now_ns = self.now_ns if self.now_ns is not None else time.time_ns()
|
|
204
|
+
age_s = (ref_now_ns - file.mtime_ns) / 1_000_000_000
|
|
205
|
+
|
|
206
|
+
if rule.older_than_s is not None and age_s <= rule.older_than_s:
|
|
207
|
+
return False, "", [f"file age {age_s:.1f}s <= older_than {rule.older_than_s}s"]
|
|
208
|
+
if rule.newer_than_s is not None and age_s >= rule.newer_than_s:
|
|
209
|
+
return False, "", [f"file age {age_s:.1f}s >= newer_than {rule.newer_than_s}s"]
|
|
210
|
+
|
|
211
|
+
# 3. Exclude check: if any matches, rule does not apply
|
|
212
|
+
for kw, matcher in rule.exclude_matchers:
|
|
213
|
+
if matcher(ctx) is not None:
|
|
214
|
+
return False, "", [f"excluded by keyword '{kw}'"]
|
|
215
|
+
|
|
216
|
+
# 4. all_of check: every entry must match
|
|
217
|
+
all_reasons: list[str] = []
|
|
218
|
+
for kw, matcher in rule.all_of_matchers:
|
|
219
|
+
reason = matcher(ctx)
|
|
220
|
+
if reason is None:
|
|
221
|
+
return False, "", [f"keyword '{kw}' not found"]
|
|
222
|
+
all_reasons.append(reason)
|
|
223
|
+
|
|
224
|
+
# 5. Keywords check: at least one must match if non-empty
|
|
225
|
+
kw_reason: str | None = None
|
|
226
|
+
if rule.keywords_matchers:
|
|
227
|
+
for _kw, matcher in rule.keywords_matchers:
|
|
228
|
+
reason = matcher(ctx)
|
|
229
|
+
if reason is not None:
|
|
230
|
+
kw_reason = reason
|
|
231
|
+
break
|
|
232
|
+
if kw_reason is None:
|
|
233
|
+
return False, "", ["no keyword matched"]
|
|
234
|
+
|
|
235
|
+
# Determine matched_by description
|
|
236
|
+
if kw_reason is not None:
|
|
237
|
+
matched_by = kw_reason
|
|
238
|
+
elif all_reasons:
|
|
239
|
+
matched_by = f"all_of ({', '.join(all_reasons)})"
|
|
240
|
+
elif rule.extensions:
|
|
241
|
+
matched_by = f"extension '{file.ext}'"
|
|
242
|
+
else:
|
|
243
|
+
matched_by = "conditions matched"
|
|
244
|
+
|
|
245
|
+
return True, matched_by, [matched_by]
|
|
246
|
+
|
|
247
|
+
def decide(self, file: FileInfo, *, folder: Path | None = None) -> Decision:
|
|
248
|
+
"""Per docs/02 sections 1 and 6. Per-folder rule subsets via folder."""
|
|
249
|
+
# 0. Check ignored files per docs/02 section 2
|
|
250
|
+
if file.is_symlink and not self.settings.follow_symlinks:
|
|
251
|
+
return Decision(
|
|
252
|
+
file=file,
|
|
253
|
+
kind=DecisionKind.IGNORED,
|
|
254
|
+
reason="symlink ignored (follow_symlinks is False)",
|
|
255
|
+
)
|
|
256
|
+
if not file.is_regular:
|
|
257
|
+
return Decision(file=file, kind=DecisionKind.IGNORED, reason="not a regular file")
|
|
258
|
+
if self.settings.skip_hidden and is_hidden(file.name):
|
|
259
|
+
return Decision(
|
|
260
|
+
file=file,
|
|
261
|
+
kind=DecisionKind.IGNORED,
|
|
262
|
+
reason="hidden file (skip_hidden is True)",
|
|
263
|
+
)
|
|
264
|
+
|
|
265
|
+
# 1. Filter rules by folder subset if applicable
|
|
266
|
+
allowed_rule_names: frozenset[str] | None = None
|
|
267
|
+
if folder is not None and self._folder_rules:
|
|
268
|
+
norm_folder = Path(os.path.normpath(str(folder)))
|
|
269
|
+
if norm_folder in self._folder_rules:
|
|
270
|
+
allowed_rule_names = self._folder_rules[norm_folder]
|
|
271
|
+
|
|
272
|
+
active_rules = self._compiled_rules
|
|
273
|
+
if allowed_rule_names is not None:
|
|
274
|
+
active_rules = [r for r in active_rules if r.name.casefold() in allowed_rule_names]
|
|
275
|
+
|
|
276
|
+
# 2. Tokenize once
|
|
277
|
+
ctx = self._build_context(file)
|
|
278
|
+
|
|
279
|
+
# 3. Collect matching rules
|
|
280
|
+
matching_hits: list[RuleHit] = []
|
|
281
|
+
for r in active_rules:
|
|
282
|
+
matched, matched_by, _ = self._evaluate_rule(r, ctx, file)
|
|
283
|
+
if matched:
|
|
284
|
+
dest_dir = expand(
|
|
285
|
+
r.destination_template,
|
|
286
|
+
file,
|
|
287
|
+
r.name,
|
|
288
|
+
now_ns=self.now_ns,
|
|
289
|
+
environ=self.environ,
|
|
290
|
+
)
|
|
291
|
+
raw_st = static_root(r.destination_template)
|
|
292
|
+
expanded_st = _expand_env_and_tilde(raw_st, self.environ)
|
|
293
|
+
static_root_path = Path(os.path.normpath(expanded_st))
|
|
294
|
+
|
|
295
|
+
hit = RuleHit(
|
|
296
|
+
rule_name=r.name,
|
|
297
|
+
priority=r.priority,
|
|
298
|
+
dest_dir=dest_dir,
|
|
299
|
+
static_root=static_root_path,
|
|
300
|
+
matched_by=matched_by,
|
|
301
|
+
collision=r.collision,
|
|
302
|
+
create=r.create,
|
|
303
|
+
also_matched=(),
|
|
304
|
+
)
|
|
305
|
+
matching_hits.append(hit)
|
|
306
|
+
|
|
307
|
+
if not matching_hits:
|
|
308
|
+
return Decision(file=file, kind=DecisionKind.NO_MATCH, reason="no rule matched")
|
|
309
|
+
|
|
310
|
+
# 4. Find lowest priority number (lower wins)
|
|
311
|
+
min_priority = min(h.priority for h in matching_hits)
|
|
312
|
+
top_matches = [h for h in matching_hits if h.priority == min_priority]
|
|
313
|
+
lower_matches = [h for h in matching_hits if h.priority > min_priority]
|
|
314
|
+
lower_names = tuple(h.rule_name for h in lower_matches)
|
|
315
|
+
|
|
316
|
+
# 5. Single top match
|
|
317
|
+
if len(top_matches) == 1:
|
|
318
|
+
top = top_matches[0]
|
|
319
|
+
hit = RuleHit(
|
|
320
|
+
rule_name=top.rule_name,
|
|
321
|
+
priority=top.priority,
|
|
322
|
+
dest_dir=top.dest_dir,
|
|
323
|
+
static_root=top.static_root,
|
|
324
|
+
matched_by=top.matched_by,
|
|
325
|
+
collision=top.collision,
|
|
326
|
+
create=top.create,
|
|
327
|
+
also_matched=lower_names,
|
|
328
|
+
)
|
|
329
|
+
return Decision(file=file, kind=DecisionKind.MATCH, hit=hit)
|
|
330
|
+
|
|
331
|
+
# Multiple top matches: check if destinations match
|
|
332
|
+
destinations = {h.dest_dir for h in top_matches}
|
|
333
|
+
if len(destinations) == 1:
|
|
334
|
+
top = top_matches[0]
|
|
335
|
+
other_top_names = tuple(h.rule_name for h in top_matches[1:])
|
|
336
|
+
all_also = other_top_names + lower_names
|
|
337
|
+
hit = RuleHit(
|
|
338
|
+
rule_name=top.rule_name,
|
|
339
|
+
priority=top.priority,
|
|
340
|
+
dest_dir=top.dest_dir,
|
|
341
|
+
static_root=top.static_root,
|
|
342
|
+
matched_by=top.matched_by,
|
|
343
|
+
collision=top.collision,
|
|
344
|
+
create=top.create,
|
|
345
|
+
also_matched=all_also,
|
|
346
|
+
)
|
|
347
|
+
return Decision(file=file, kind=DecisionKind.MATCH, hit=hit)
|
|
348
|
+
|
|
349
|
+
# Different destinations: AMBIGUOUS
|
|
350
|
+
return Decision(
|
|
351
|
+
file=file,
|
|
352
|
+
kind=DecisionKind.AMBIGUOUS,
|
|
353
|
+
candidates=tuple(top_matches),
|
|
354
|
+
reason=(
|
|
355
|
+
f"ambiguous: {len(top_matches)} rules matched with priority {min_priority} "
|
|
356
|
+
"resolving to different destinations"
|
|
357
|
+
),
|
|
358
|
+
)
|
|
359
|
+
|
|
360
|
+
def trace(self, file: FileInfo) -> list[RuleTrace]:
|
|
361
|
+
"""One RuleTrace per rule (all rules, not filtered by folder)."""
|
|
362
|
+
ctx = self._build_context(file)
|
|
363
|
+
traces: list[RuleTrace] = []
|
|
364
|
+
for r in self._compiled_rules:
|
|
365
|
+
matched, _matched_by, reasons = self._evaluate_rule(r, ctx, file)
|
|
366
|
+
traces.append(
|
|
367
|
+
RuleTrace(
|
|
368
|
+
rule_name=r.name,
|
|
369
|
+
matched=matched,
|
|
370
|
+
priority=r.priority,
|
|
371
|
+
reasons=tuple(reasons),
|
|
372
|
+
)
|
|
373
|
+
)
|
|
374
|
+
return traces
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
"""Keyword compilation and matching module for ClutterXP rule engine.
|
|
2
|
+
|
|
3
|
+
Implements token, prefix, substring, glob, and regex match modes,
|
|
4
|
+
as well as catastrophic backtracking detection per docs/02_RULE_ENGINE.md section 4.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import fnmatch
|
|
10
|
+
import re
|
|
11
|
+
from collections.abc import Callable
|
|
12
|
+
from dataclasses import dataclass
|
|
13
|
+
|
|
14
|
+
from clutterxp.models import MatchMode
|
|
15
|
+
from clutterxp.rules.tokenizer import keyword_tokens
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass(frozen=True)
|
|
19
|
+
class MatchContext:
|
|
20
|
+
"""Pre-computed per-file data passed to matchers."""
|
|
21
|
+
|
|
22
|
+
name: str # original name
|
|
23
|
+
casefolded_name: str
|
|
24
|
+
stem: str # from split_stem
|
|
25
|
+
ext: str
|
|
26
|
+
raw_toks: list[str] # from raw_tokens
|
|
27
|
+
camel_toks: list[str] # from camel_tokens
|
|
28
|
+
case_sensitive: bool
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def check_catastrophic_regex(pattern: str) -> bool:
|
|
32
|
+
"""Returns True if pattern has nested unbounded quantifiers like (a+)+."""
|
|
33
|
+
i = 0
|
|
34
|
+
n = len(pattern)
|
|
35
|
+
in_char_class = False
|
|
36
|
+
|
|
37
|
+
class Frame:
|
|
38
|
+
def __init__(self) -> None:
|
|
39
|
+
self.has_unbounded = False
|
|
40
|
+
|
|
41
|
+
stack: list[Frame] = []
|
|
42
|
+
|
|
43
|
+
def is_unbounded_quantifier_at(idx: int) -> tuple[bool, int]:
|
|
44
|
+
"""Returns (is_unbounded, next_idx)."""
|
|
45
|
+
if idx >= n:
|
|
46
|
+
return False, idx
|
|
47
|
+
ch = pattern[idx]
|
|
48
|
+
if ch in ("*", "+"):
|
|
49
|
+
next_idx = idx + 1
|
|
50
|
+
if next_idx < n and pattern[next_idx] in ("?", "+"):
|
|
51
|
+
next_idx += 1
|
|
52
|
+
return True, next_idx
|
|
53
|
+
if ch == "{":
|
|
54
|
+
end = pattern.find("}", idx)
|
|
55
|
+
if end != -1:
|
|
56
|
+
content = pattern[idx + 1 : end].strip()
|
|
57
|
+
if "," in content:
|
|
58
|
+
parts = content.split(",", 1)
|
|
59
|
+
lower, upper = parts[0].strip(), parts[1].strip()
|
|
60
|
+
if (lower == "" or lower.isdigit()) and upper == "":
|
|
61
|
+
next_idx = end + 1
|
|
62
|
+
if next_idx < n and pattern[next_idx] in ("?", "+"):
|
|
63
|
+
next_idx += 1
|
|
64
|
+
return True, next_idx
|
|
65
|
+
return False, idx
|
|
66
|
+
|
|
67
|
+
while i < n:
|
|
68
|
+
ch = pattern[i]
|
|
69
|
+
if ch == "\\":
|
|
70
|
+
i += 2
|
|
71
|
+
continue
|
|
72
|
+
|
|
73
|
+
if in_char_class:
|
|
74
|
+
if ch == "]":
|
|
75
|
+
in_char_class = False
|
|
76
|
+
i += 1
|
|
77
|
+
continue
|
|
78
|
+
|
|
79
|
+
if ch == "[":
|
|
80
|
+
in_char_class = True
|
|
81
|
+
i += 1
|
|
82
|
+
continue
|
|
83
|
+
|
|
84
|
+
if ch == "(":
|
|
85
|
+
stack.append(Frame())
|
|
86
|
+
if i + 1 < n and pattern[i + 1] == "?":
|
|
87
|
+
i += 2
|
|
88
|
+
if i < n and pattern[i] in (":", "=", "!", ">"):
|
|
89
|
+
i += 1
|
|
90
|
+
elif i < n and pattern[i] == "<":
|
|
91
|
+
end_name = pattern.find(">", i)
|
|
92
|
+
if end_name != -1:
|
|
93
|
+
i = end_name + 1
|
|
94
|
+
else:
|
|
95
|
+
i += 1
|
|
96
|
+
continue
|
|
97
|
+
|
|
98
|
+
if ch == ")":
|
|
99
|
+
popped = stack.pop() if stack else None
|
|
100
|
+
is_unbounded, next_i = is_unbounded_quantifier_at(i + 1)
|
|
101
|
+
if is_unbounded:
|
|
102
|
+
if popped is not None and popped.has_unbounded:
|
|
103
|
+
return True
|
|
104
|
+
if stack:
|
|
105
|
+
stack[-1].has_unbounded = True
|
|
106
|
+
i = next_i
|
|
107
|
+
continue
|
|
108
|
+
if popped is not None and popped.has_unbounded and stack:
|
|
109
|
+
stack[-1].has_unbounded = True
|
|
110
|
+
i += 1
|
|
111
|
+
continue
|
|
112
|
+
|
|
113
|
+
is_unbounded, next_i = is_unbounded_quantifier_at(i)
|
|
114
|
+
if is_unbounded:
|
|
115
|
+
if stack:
|
|
116
|
+
stack[-1].has_unbounded = True
|
|
117
|
+
i = next_i
|
|
118
|
+
continue
|
|
119
|
+
|
|
120
|
+
i += 1
|
|
121
|
+
|
|
122
|
+
return False
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _is_contiguous_subsequence(sub: list[str], target: list[str]) -> bool:
|
|
126
|
+
"""Check if sub list appears as a contiguous run in target list."""
|
|
127
|
+
if not sub or len(sub) > len(target):
|
|
128
|
+
return False
|
|
129
|
+
n = len(sub)
|
|
130
|
+
return any(target[i : i + n] == sub for i in range(len(target) - n + 1))
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def compile_keyword(
|
|
134
|
+
keyword: str,
|
|
135
|
+
mode: MatchMode,
|
|
136
|
+
case_sensitive: bool,
|
|
137
|
+
) -> Callable[[MatchContext], str | None]:
|
|
138
|
+
"""Returns a matcher function: ctx -> reason string or None.
|
|
139
|
+
|
|
140
|
+
reason is a human string like "keyword 'sl' (token)".
|
|
141
|
+
Raises ValueError for invalid regex.
|
|
142
|
+
Does static check for catastrophic backtracking (nested unbounded quantifiers).
|
|
143
|
+
"""
|
|
144
|
+
original_keyword = keyword
|
|
145
|
+
effective_mode = mode
|
|
146
|
+
|
|
147
|
+
if keyword.startswith("glob:"):
|
|
148
|
+
effective_mode = MatchMode.GLOB
|
|
149
|
+
pattern_str = keyword[5:]
|
|
150
|
+
elif keyword.startswith("regex:"):
|
|
151
|
+
effective_mode = MatchMode.REGEX
|
|
152
|
+
pattern_str = keyword[6:]
|
|
153
|
+
else:
|
|
154
|
+
pattern_str = keyword
|
|
155
|
+
|
|
156
|
+
if effective_mode == MatchMode.REGEX:
|
|
157
|
+
if check_catastrophic_regex(pattern_str):
|
|
158
|
+
raise ValueError(f"catastrophic backtracking regex: {pattern_str!r}")
|
|
159
|
+
flags = 0 if case_sensitive else re.IGNORECASE
|
|
160
|
+
try:
|
|
161
|
+
rx = re.compile(pattern_str, flags)
|
|
162
|
+
except re.error as e:
|
|
163
|
+
raise ValueError(f"invalid regex {pattern_str!r}: {e}") from e
|
|
164
|
+
|
|
165
|
+
reason = f"keyword '{original_keyword}' (regex)"
|
|
166
|
+
|
|
167
|
+
def match_regex(ctx: MatchContext) -> str | None:
|
|
168
|
+
# Applied to full name (max 255 chars)
|
|
169
|
+
return reason if rx.search(ctx.name) else None
|
|
170
|
+
|
|
171
|
+
return match_regex
|
|
172
|
+
|
|
173
|
+
if effective_mode == MatchMode.GLOB:
|
|
174
|
+
glob_pat = pattern_str if case_sensitive else pattern_str.casefold()
|
|
175
|
+
reason = f"keyword '{original_keyword}' (glob)"
|
|
176
|
+
|
|
177
|
+
def match_glob(ctx: MatchContext) -> str | None:
|
|
178
|
+
target = ctx.name if case_sensitive else ctx.casefolded_name
|
|
179
|
+
return reason if fnmatch.fnmatchcase(target, glob_pat) else None
|
|
180
|
+
|
|
181
|
+
return match_glob
|
|
182
|
+
|
|
183
|
+
if effective_mode == MatchMode.SUBSTRING:
|
|
184
|
+
sub = pattern_str if case_sensitive else pattern_str.casefold()
|
|
185
|
+
reason = f"keyword '{original_keyword}' (substring)"
|
|
186
|
+
|
|
187
|
+
def match_substring(ctx: MatchContext) -> str | None:
|
|
188
|
+
target = ctx.stem if case_sensitive else ctx.stem.casefold()
|
|
189
|
+
return reason if sub in target else None
|
|
190
|
+
|
|
191
|
+
return match_substring
|
|
192
|
+
|
|
193
|
+
if effective_mode == MatchMode.PREFIX:
|
|
194
|
+
kw_toks = keyword_tokens(pattern_str, casefold=not case_sensitive)
|
|
195
|
+
prefix = (
|
|
196
|
+
kw_toks[0] if kw_toks else (pattern_str if case_sensitive else pattern_str.casefold())
|
|
197
|
+
)
|
|
198
|
+
reason = f"keyword '{original_keyword}' (prefix)"
|
|
199
|
+
|
|
200
|
+
def match_prefix(ctx: MatchContext) -> str | None:
|
|
201
|
+
for tok in ctx.raw_toks:
|
|
202
|
+
if tok.startswith(prefix):
|
|
203
|
+
return reason
|
|
204
|
+
return None
|
|
205
|
+
|
|
206
|
+
return match_prefix
|
|
207
|
+
|
|
208
|
+
# MatchMode.TOKEN (default)
|
|
209
|
+
kw_toks = keyword_tokens(pattern_str, casefold=not case_sensitive)
|
|
210
|
+
if not kw_toks:
|
|
211
|
+
return lambda ctx: None
|
|
212
|
+
|
|
213
|
+
reason = f"keyword '{original_keyword}' (token)"
|
|
214
|
+
|
|
215
|
+
def match_token(ctx: MatchContext) -> str | None:
|
|
216
|
+
if _is_contiguous_subsequence(kw_toks, ctx.raw_toks):
|
|
217
|
+
return reason
|
|
218
|
+
if _is_contiguous_subsequence(kw_toks, ctx.camel_toks):
|
|
219
|
+
return reason
|
|
220
|
+
return None
|
|
221
|
+
|
|
222
|
+
return match_token
|