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,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