clutterxp 1.1.0__py3-none-any.whl

clutterxp/config/placeholders.py

@@ -0,0 +1,79 @@
+"""Allowed destination template placeholders and validator (docs/02_RULE_ENGINE.md)."""
+
+from __future__ import annotations
+
+import difflib
+import re
+
+ALLOWED_PLACEHOLDERS: frozenset[str] = frozenset(
+    [
+        "year",
+        "month",
+        "day",
+        "ext",
+        "rule",
+        "mtime",
+    ]
+)
+
+
+def extract_static_root(template: str) -> str:
+    """Extract the path portion before the first component containing a placeholder."""
+    parts = template.split("/")
+    static_parts: list[str] = []
+    for part in parts:
+        if "{" in part:
+            break
+        static_parts.append(part)
+
+    if not static_parts or (len(static_parts) == 1 and static_parts[0] == ""):
+        return "/" if template.startswith("/") else "."
+
+    res = "/".join(static_parts)
+    return res if res else ("/" if template.startswith("/") else ".")
+
+
+def validate_destination_template(template: str) -> list[str]:
+    """Validate placeholder names and formats in a destination template string.
+
+    Returns a list of error descriptions (empty if valid).
+    """
+    errors: list[str] = []
+
+    # Check for unmatched brackets
+    open_count = template.count("{")
+    close_count = template.count("}")
+    if open_count != close_count:
+        errors.append(f"Unmatched brackets in destination template '{template}'")
+        return errors
+
+    # Check for empty placeholder {}
+    if "{}" in template:
+        errors.append("Empty placeholder '{}' in destination template")
+
+    # Find all placeholder contents
+    placeholders = re.findall(r"\{([^}]*)\}", template)
+    for p in placeholders:
+        if not p:
+            continue
+        if p.startswith("mtime:"):
+            fmt = p[6:]
+            if not fmt:
+                errors.append("Empty mtime format in destination template")
+            elif "/" in fmt or "\x00" in fmt:
+                errors.append(
+                    f"mtime format '{fmt}' in destination template cannot contain '/' or NUL"
+                )
+        elif p in ALLOWED_PLACEHOLDERS:
+            continue
+        else:
+            close = difflib.get_close_matches(p, sorted(ALLOWED_PLACEHOLDERS))
+            if close:
+                errors.append(
+                    f"Unknown placeholder '{{{p}}}' in destination template; "
+                    f"did you mean '{{{close[0]}}}'?"
+                )
+            else:
+                errors.append(f"Unknown placeholder '{{{p}}}' in destination template")
+
+    return errors

clutterxp/config/runtime.py

@@ -0,0 +1,30 @@
+"""Runtime configuration representation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .schema import RuleSpec, Settings, WatchEntry
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeConfig:
+    config_path: Path
+    mtime_ns: int  # config file mtime for reload detection
+    settings: Settings  # from schema.py
+    watch_entries: tuple[WatchEntry, ...]  # from schema.py
+    rules: tuple[RuleSpec, ...]  # enabled rules only
+    disabled_rules: tuple[RuleSpec, ...]  # disabled rules
+    errors: tuple[str, ...]  # config errors (empty = valid)
+    warnings: tuple[str, ...]  # config warnings
+
+    @property
+    def is_valid(self) -> bool:
+        """True if configuration has no errors."""
+        return len(self.errors) == 0
+
+    @property
+    def all_rules(self) -> tuple[RuleSpec, ...]:
+        """All rules including disabled ones."""
+        return self.rules + self.disabled_rules

clutterxp/config/schema.py

@@ -0,0 +1,166 @@
+"""Pydantic schema for config.yaml (field names and types are FROZEN).
+
+Agents may ADD validators and error messages here, but must not rename, remove or retype a
+field without a CONTRACT_CHANGE request. Cross-config checks (loops, denylist, overlaps)
+live in config/validate.py, not here.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from ..models import CollisionPolicy, CreateDestinations, MatchMode
+from ..units import parse_duration_seconds, parse_size
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+
+class HistorySettings(_Base):
+    retention_days: int = Field(365, ge=0)
+    log_no_match: bool = False
+
+
+class Settings(_Base):
+    collision: CollisionPolicy = CollisionPolicy.SKIP
+    create_destinations: CreateDestinations = CreateDestinations.LEAF
+    match: MatchMode = MatchMode.TOKEN
+    case_sensitive: bool = False
+    skip_hidden: bool = True
+    follow_symlinks: bool = False
+    confirm_threshold: int = Field(10, ge=0)
+    settle_seconds: float = Field(3.0, ge=0, le=3600)
+    verify_copy: Literal["size", "hash"] = "size"
+    record_hash: bool = False
+    history: HistorySettings = Field(default_factory=HistorySettings)
+    ignore: list[str] = Field(default_factory=list)
+    allow_chain: bool = False
+
+    @field_validator("match")
+    @classmethod
+    def _plain_modes_only(cls, v: MatchMode) -> MatchMode:
+        if v in (MatchMode.GLOB, MatchMode.REGEX):
+            raise ValueError("use a 'glob:' or 'regex:' prefix on a keyword instead of this mode")
+        return v
+
+
+class WatchEntry(_Base):
+    path: str = Field(min_length=1)
+    recursive: bool = False
+    settle_seconds: float | None = Field(None, ge=0, le=3600)
+    ignore: list[str] = Field(default_factory=list)
+    rules: Literal["all"] | list[str] = "all"
+    initial_scan: bool = False
+
+
+class Conditions(_Base):
+    min_size: int | str | None = None
+    max_size: int | str | None = None
+    older_than: int | str | None = None
+    newer_than: int | str | None = None
+
+    @field_validator("min_size", "max_size")
+    @classmethod
+    def _size(cls, v: int | str | None) -> int | str | None:
+        if v is not None:
+            parse_size(v)  # raises ValueError -> reported by pydantic
+        return v
+
+    @field_validator("older_than", "newer_than")
+    @classmethod
+    def _duration(cls, v: int | str | None) -> int | str | None:
+        if v is not None:
+            parse_duration_seconds(v)
+        return v
+
+    @model_validator(mode="after")
+    def _ranges(self) -> "Conditions":
+        if self.min_size is not None and self.max_size is not None:
+            if parse_size(self.min_size) > parse_size(self.max_size):
+                raise ValueError("min_size is larger than max_size")
+        if self.older_than is not None and self.newer_than is not None:
+            if parse_duration_seconds(self.older_than) >= parse_duration_seconds(self.newer_than):
+                raise ValueError("older_than must be less than newer_than, or no file can match")
+        return self
+
+    def any_set(self) -> bool:
+        return any(
+            v is not None for v in (self.min_size, self.max_size, self.older_than, self.newer_than)
+        )
+
+
+class RuleSpec(_Base):
+    name: str = Field(min_length=1)
+    enabled: bool = True
+    priority: int = Field(100, ge=0, le=100_000)
+    destination: str = Field(min_length=1)
+    keywords: list[str] = Field(default_factory=list)
+    all_of: list[str] = Field(default_factory=list)
+    exclude: list[str] = Field(default_factory=list)
+    match: MatchMode | None = None  # None means "use settings.match"
+    extensions: list[str] = Field(default_factory=list)
+    conditions: Conditions = Field(default_factory=Conditions)
+    collision: CollisionPolicy | None = None
+    create_destinations: CreateDestinations | None = None
+
+    @field_validator("name")
+    @classmethod
+    def _name(cls, v: str) -> str:
+        if "/" in v or "\x00" in v:
+            raise ValueError("rule name must not contain '/' or NUL")
+        return v
+
+    @field_validator("keywords", "all_of", "exclude")
+    @classmethod
+    def _non_empty_strings(cls, v: list[str]) -> list[str]:
+        out = [s.strip() for s in v]
+        if any(not s for s in out):
+            raise ValueError("empty keyword")
+        return out
+
+    @field_validator("match")
+    @classmethod
+    def _plain_mode(cls, v: MatchMode | None) -> MatchMode | None:
+        if v in (MatchMode.GLOB, MatchMode.REGEX):
+            raise ValueError("use a 'glob:' or 'regex:' prefix on a keyword instead of this mode")
+        return v
+
+    @field_validator("extensions")
+    @classmethod
+    def _extensions(cls, v: list[str]) -> list[str]:
+        out: list[str] = []
+        for e in v:
+            e = e.strip().lstrip(".").lower()
+            if not e or "/" in e:
+                raise ValueError(f"invalid extension {e!r}")
+            out.append(e)
+        return out
+
+    @model_validator(mode="after")
+    def _needs_positive_criterion(self) -> "RuleSpec":
+        if not (self.keywords or self.all_of or self.extensions or self.conditions.any_set()):
+            raise ValueError(
+                "rule needs at least one of: keywords, all_of, extensions, conditions "
+                "(a rule with only 'exclude' would match every file)"
+            )
+        return self
+
+
+class Config(_Base):
+    version: Literal[1]
+    settings: Settings = Field(default_factory=Settings)
+    watch: list[WatchEntry] = Field(default_factory=list)
+    rules: list[RuleSpec] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _unique_rule_names(self) -> "Config":
+        seen: dict[str, str] = {}
+        for r in self.rules:
+            key = r.name.casefold()
+            if key in seen:
+                raise ValueError(f"duplicate rule name {r.name!r} (also {seen[key]!r})")
+            seen[key] = r.name
+        return self

clutterxp/config/validate.py

@@ -0,0 +1,226 @@
+"""Cross-configuration validation (docs/03_CONFIG.md section 4)."""
+
+from __future__ import annotations
+
+import difflib
+import os
+from pathlib import Path
+
+from ..models import CreateDestinations, MatchMode
+from ..paths import expand
+from ..safety import is_denylisted
+from .placeholders import extract_static_root
+from .schema import Config, RuleSpec
+
+
+def validate(config: Config, *, warn_only: bool = False) -> tuple[list[str], list[str]]:
+    """Perform cross-configuration validation on a Config model.
+
+    Checks:
+    - Errors:
+      1. Destination equals or is inside a watched folder (unless allow_chain is True).
+      2. Watch folder or destination is in the system denylist or contains hidden component.
+      3. Recursive watch of $HOME is rejected.
+      4. Per-folder rules list references unknown rules.
+    - Warnings:
+      1. Watch folder does not exist.
+      2. Two enabled rules share keyword at same priority with different destinations.
+      3. Substring keyword shorter than 4 characters.
+      4. Destination static root does not exist when create_destinations is 'never'.
+      5. Destination on a different filesystem than a watched folder.
+
+    Returns:
+        (errors, warnings) lists of human-readable issues with YAML paths.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # 1. Expand paths and check watch folders
+    expanded_watch_paths: dict[int, Path] = {}
+    for w_idx, w in enumerate(config.watch):
+        try:
+            w_path = expand(w.path)
+            expanded_watch_paths[w_idx] = w_path
+        except Exception as e:
+            errors.append(f"watch[{w_idx}].path: failed to expand path '{w.path}': {e}")
+            continue
+
+        # Denylist check for watch folder
+        if is_denylisted(w_path):
+            errors.append(f"watch[{w_idx}].path: path '{w.path}' is in the system denylist")
+
+        # Recursive $HOME check
+        try:
+            home = Path(os.path.realpath(str(Path.home())))
+            real_w = Path(os.path.realpath(str(w_path)))
+            if w.recursive and real_w == home:
+                errors.append(
+                    f"watch[{w_idx}].path: recursive watch of $HOME ('{w.path}') "
+                    "is refused for safety"
+                )
+        except RuntimeError:
+            pass
+
+        # Watch folder existence check (warning for config validate)
+        if not w_path.exists():
+            warnings.append(f"watch[{w_idx}].path: watched folder '{w.path}' does not exist")
+
+    real_watch_paths: dict[int, Path] = {
+        w_idx: Path(os.path.realpath(str(w_p))) for w_idx, w_p in expanded_watch_paths.items()
+    }
+
+    # 2. Check rule destinations (denylist, hidden components, loop guard)
+    expanded_rule_roots: dict[int, Path] = {}
+    for r_idx, r in enumerate(config.rules):
+        static_root_str = extract_static_root(r.destination)
+        try:
+            dest_root = expand(static_root_str)
+            expanded_rule_roots[r_idx] = dest_root
+        except Exception as e:
+            errors.append(
+                f"rules[{r_idx}].destination: failed to expand destination '{r.destination}': {e}"
+            )
+            continue
+
+        # System denylist check
+        if is_denylisted(dest_root):
+            errors.append(
+                f"rules[{r_idx}].destination: destination '{r.destination}' "
+                "is in the system denylist"
+            )
+
+        # Hidden component check in static root path
+        for part in dest_root.parts:
+            if part in ("/", "\\"):
+                continue
+            if part.startswith("."):
+                errors.append(
+                    f"rules[{r_idx}].destination: destination '{r.destination}' "
+                    f"contains hidden component '{part}'"
+                )
+                break
+
+        real_dest = Path(os.path.realpath(str(dest_root)))
+        for part in real_dest.parts:
+            if part in ("/", "\\"):
+                continue
+            if part.startswith("."):
+                errors.append(
+                    f"rules[{r_idx}].destination: destination '{r.destination}' "
+                    f"resolves to hidden component '{part}' in '{real_dest}'"
+                )
+                break
+
+        # Infinite loop guard: destination equals or is inside a watched folder
+        if not config.settings.allow_chain:
+            for w_idx, w_real in real_watch_paths.items():
+                if dest_real_in_watch(dest_real=real_dest, watch_real=w_real):
+                    errors.append(
+                        f"rules[{r_idx}].destination: destination '{r.destination}' is inside "
+                        f"watched folder '{config.watch[w_idx].path}' "
+                        "(settings.allow_chain is false)"
+                    )
+
+    # 3. Per-folder rules list references unknown rules
+    known_rule_names = {r.name for r in config.rules}
+    for w_idx, w in enumerate(config.watch):
+        if isinstance(w.rules, list):
+            for rname in w.rules:
+                if rname not in known_rule_names:
+                    close = difflib.get_close_matches(rname, sorted(known_rule_names))
+                    hint = f"; did you mean '{close[0]}'?" if close else ""
+                    errors.append(f"watch[{w_idx}].rules: unknown rule '{rname}'{hint}")
+
+    # 4. Overlapping keywords at same priority with different destinations
+    by_priority: dict[int, list[RuleSpec]] = {}
+    for r in config.rules:
+        if r.enabled:
+            by_priority.setdefault(r.priority, []).append(r)
+
+    for priority_rules in by_priority.values():
+        if len(priority_rules) < 2:
+            continue
+        for i in range(len(priority_rules)):
+            for j in range(i + 1, len(priority_rules)):
+                r1 = priority_rules[i]
+                r2 = priority_rules[j]
+                if r1.destination != r2.destination:
+                    kws1 = {
+                        k.casefold() for k in r1.keywords if not k.startswith(("glob:", "regex:"))
+                    }
+                    kws2 = {
+                        k.casefold() for k in r2.keywords if not k.startswith(("glob:", "regex:"))
+                    }
+                    shared = kws1 & kws2
+                    for kw in sorted(shared):
+                        warnings.append(
+                            f"rules: enabled rules '{r1.name}' and '{r2.name}' "
+                            f"share keyword '{kw}' at priority {r1.priority} "
+                            f"with different destinations "
+                            f"('{r1.destination}' vs '{r2.destination}')"
+                        )
+
+    # 5. Substring keyword < 4 chars
+    for r_idx, r in enumerate(config.rules):
+        rule_mode = r.match or config.settings.match
+        if rule_mode == MatchMode.SUBSTRING:
+            for kw in r.keywords:
+                if not kw.startswith(("glob:", "regex:")) and len(kw) < 4:
+                    warnings.append(
+                        f"rules[{r_idx}].keywords: substring keyword '{kw}' is shorter than "
+                        "4 characters (risk of false positives)"
+                    )
+
+    # 6. Destination static root missing (when create_destinations is 'never')
+    for r_idx, r in enumerate(config.rules):
+        create_policy = r.create_destinations or config.settings.create_destinations
+        if create_policy == CreateDestinations.NEVER:
+            dest_p = expanded_rule_roots.get(r_idx)
+            if dest_p is not None and not dest_p.exists():
+                warnings.append(
+                    f"rules[{r_idx}].destination: static root '{dest_p}' does not exist "
+                    "and create_destinations is 'never'"
+                )
+
+    # 7. Cross-filesystem warning
+    seen_cross_fs: set[tuple[str, str]] = set()
+    for w_idx, w_path in expanded_watch_paths.items():
+        if not w_path.exists():
+            continue
+        try:
+            w_dev = w_path.stat().st_dev
+        except OSError:
+            continue
+
+        for r_idx, r in enumerate(config.rules):
+            if not r.enabled:
+                continue
+            dest_p = expanded_rule_roots.get(r_idx)
+            if dest_p is None:
+                continue
+            # Traverse parents to find existing ancestor
+            check_p = dest_p
+            while not check_p.exists() and check_p.parent != check_p:
+                check_p = check_p.parent
+            if check_p.exists():
+                try:
+                    if check_p.stat().st_dev != w_dev:
+                        pair = (str(w_path), str(dest_p))
+                        if pair not in seen_cross_fs:
+                            seen_cross_fs.add(pair)
+                            warnings.append(
+                                f"rules[{r_idx}].destination: destination '{r.destination}' "
+                                f"is on a different filesystem than watched folder "
+                                f"'{config.watch[w_idx].path}' (cross-filesystem moves will copy)"
+                            )
+                except OSError:
+                    pass
+
+    if warn_only:
+        return ([], errors + warnings)
+    return (errors, warnings)
+
+
+def dest_real_in_watch(*, dest_real: Path, watch_real: Path) -> bool:
+    """Return True if dest_real equals watch_real or is inside watch_real."""
+    return dest_real == watch_real or watch_real in dest_real.parents