clutterxp 1.1.0__py3-none-any.whl

clutterxp/cli/render.py

@@ -0,0 +1,390 @@
+"""Console rendering with Rich, safe string escaping, and JSON output formatting."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Generator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeRemainingColumn
+from rich.table import Table
+
+from clutterxp.models import (
+    BatchResult,
+    DecisionKind,
+    OperationRecord,
+    Plan,
+    PlanStatus,
+    RuleTrace,
+)
+
+
+def safe_str(val: Any) -> str:
+    """Format any object to string, safely escaping non-UTF-8 surrogate characters.
+
+    Protects against UnicodeEncodeError when paths contain non-UTF-8 sequences.
+    """
+    if val is None:
+        return ""
+    if isinstance(val, bytes):
+        return val.decode("utf-8", errors="backslashreplace")
+    s = str(val)
+    try:
+        s.encode("utf-8")
+        return s
+    except UnicodeEncodeError:
+        return s.encode("utf-8", errors="surrogateescape").decode(
+            "utf-8", errors="backslashreplace"
+        )
+
+
+def _sanitize_for_json(data: Any) -> Any:
+    """Recursively convert Paths and strings with surrogates into clean JSON types."""
+    if isinstance(data, Path):
+        return safe_str(data)
+    if isinstance(data, str):
+        return safe_str(data)
+    if isinstance(data, (int, float, bool)) or data is None:
+        return data
+    if isinstance(data, dict):
+        return {_sanitize_for_json(k): _sanitize_for_json(v) for k, v in data.items()}
+    if isinstance(data, (list, tuple, set)):
+        return [_sanitize_for_json(item) for item in data]
+    return safe_str(data)
+
+
+def print_json(data: dict[str, Any]) -> None:
+    """Emit ONLY pure valid JSON to stdout with no Rich formatting."""
+    cleaned = _sanitize_for_json(data)
+    text = json.dumps(cleaned, indent=2)
+    sys.stdout.write(text + "\n")
+    sys.stdout.flush()
+
+
+def get_console(
+    *,
+    no_color: bool = False,
+    stderr: bool = False,
+) -> Console:
+    """Get a Rich Console instance configured for color settings."""
+    env_no_color = bool(os.environ.get("NO_COLOR", "").strip())
+    force_no_color = no_color or env_no_color
+    return Console(
+        file=sys.stderr if stderr else sys.stdout,
+        no_color=force_no_color,
+        highlight=False,
+    )
+
+
+@contextmanager
+def progress_bar(
+    description: str,
+    total: int | None = None,
+    *,
+    quiet: bool = False,
+    json_mode: bool = False,
+    no_color: bool = False,
+) -> Generator[Progress | None, None, None]:
+    """Create a Rich progress bar rendered to stderr, active only when appropriate."""
+    if quiet or json_mode or not sys.stderr.isatty():
+        yield None
+        return
+
+    stderr_console = get_console(no_color=no_color, stderr=True)
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        TimeRemainingColumn(),
+        console=stderr_console,
+        transient=True,
+    ) as progress:
+        progress.add_task(description, total=total)
+        yield progress
+
+
+def render_plan(
+    plan: Plan,
+    *,
+    dry_run: bool = False,
+    show: str = "all",
+    collapse_keep_limit: int = 10,
+    no_color: bool = False,
+) -> None:
+    """Render human-readable execution plan with status words MOVE, KEEP, AMBIG, BLOCK."""
+    console = get_console(no_color=no_color)
+
+    # Header
+    folder_str = ", ".join(safe_str(f) for f in plan.folders) if plan.folders else "targets"
+    total_files = len(plan.actions)
+    console.print(f"Plan for {folder_str}  ({total_files} files)\n")
+
+    # Filter actions according to show
+    will_move_count = 0
+    unmatched_count = 0
+    ambig_count = 0
+    blocked_count = 0
+
+    actions_to_show: list[tuple[str, str]] = []
+    collapsed_keep = 0
+
+    for action in plan.actions:
+        src_name = safe_str(action.file.name)
+        if action.status in (PlanStatus.WILL_MOVE, PlanStatus.WILL_MOVE_RENAMED):
+            will_move_count += 1
+            if show in ("all", "matched"):
+                dst_dir = safe_str(action.dest_path.parent) if action.dest_path else "unknown_dest"
+                rule_name = action.decision.hit.rule_name if action.decision.hit else ""
+                matched_by = action.decision.hit.matched_by if action.decision.hit else ""
+                info = f"[{rule_name}   {matched_by}]" if rule_name else ""
+                actions_to_show.append(
+                    ("MOVE", f" {src_name:<30} ->  {dst_dir:<32} {info}".strip())
+                )
+        elif action.status == PlanStatus.AMBIGUOUS:
+            ambig_count += 1
+            if show in ("all", "ambiguous"):
+                candidates = (
+                    ", ".join(c.rule_name for c in action.decision.candidates)
+                    if action.decision.candidates
+                    else "multiple rules"
+                )
+                actions_to_show.append(
+                    ("AMBIG", f" {src_name:<30} candidates: {candidates}".strip())
+                )
+        elif action.status == PlanStatus.BLOCKED:
+            blocked_count += 1
+            if show in ("all", "blocked"):
+                msg = action.message or action.code.value
+                actions_to_show.append(("BLOCK", f" {src_name:<30} {msg}".strip()))
+        else:  # NO_MATCH or IGNORED
+            unmatched_count += 1
+            if show in ("all", "unmatched"):
+                reason = "left untouched"
+                if action.status == PlanStatus.IGNORED:
+                    reason = "ignored"
+                elif action.decision.reason:
+                    reason = f"{action.decision.reason}; left untouched"
+                else:
+                    reason = "no rule matched; left untouched"
+                actions_to_show.append(("KEEP", f" {src_name:<30} {reason}".strip()))
+
+    # Check if we should collapse KEEP lines in large plans when show == "all"
+    for status_word, line_text in actions_to_show:
+        if status_word == "KEEP" and show == "all" and unmatched_count > collapse_keep_limit:
+            collapsed_keep += 1
+            if collapsed_keep <= 3:
+                _print_action_line(console, status_word, line_text, no_color=no_color)
+            elif collapsed_keep == 4:
+                rem = unmatched_count - 3
+                console.print(f" ... ({rem} files left untouched, use --show unmatched to view)")
+            # else skip printing remainder
+        else:
+            _print_action_line(console, status_word, line_text, no_color=no_color)
+
+    # Summary
+    console.print(
+        f"\nSummary: {will_move_count} will move, {unmatched_count} unmatched (untouched), "
+        f"{ambig_count} ambiguous, {blocked_count} blocked"
+    )
+    if dry_run:
+        console.print("Nothing was changed (dry run).")
+
+
+def _print_action_line(console: Console, status_word: str, text: str, no_color: bool) -> None:
+    """Print an action line with color styling based on status word."""
+    if no_color:
+        console.print(f" {status_word:<6} {text}")
+        return
+
+    if status_word == "MOVE":
+        console.print(f" [green bold]{status_word:<6}[/] {text}")
+    elif status_word == "AMBIG":
+        console.print(f" [yellow bold]{status_word:<6}[/] {text}")
+    elif status_word == "BLOCK":
+        console.print(f" [red bold]{status_word:<6}[/] {text}")
+    else:  # KEEP
+        console.print(f" [dim]{status_word:<6}[/] [dim]{text}[/]")
+
+
+def render_organize_summary(
+    plan: Plan,
+    batch_result: BatchResult,
+    *,
+    no_color: bool = False,
+) -> None:
+    """Print summary after applying an organize plan."""
+    console = get_console(no_color=no_color)
+    unmatched = plan.count(PlanStatus.NO_MATCH) + plan.count(PlanStatus.IGNORED)
+    ambiguous = plan.count(PlanStatus.AMBIGUOUS)
+
+    console.print(
+        f"\nSummary: {batch_result.moved} moved, {unmatched} unmatched (untouched), "
+        f"{ambiguous} ambiguous, {batch_result.blocked} blocked, {batch_result.failed} failed"
+    )
+    if batch_result.batch_id is not None:
+        console.print(f"Undo with: clutterxp undo --batch {batch_result.batch_id}")
+
+
+def render_rules_table(
+    rules: Sequence[Any],
+    *,
+    no_color: bool = False,
+) -> None:
+    """Render a table of rules (list command)."""
+    console = get_console(no_color=no_color)
+    table = Table(title="Configured Rules", header_style="bold")
+    table.add_column("Name", style="bold")
+    table.add_column("Priority", justify="right")
+    table.add_column("Enabled", justify="center")
+    table.add_column("Keywords")
+    table.add_column("Extensions")
+    table.add_column("Destination")
+
+    for r in rules:
+        keywords = ", ".join(r.keywords) if getattr(r, "keywords", None) else ""
+        exts = ", ".join(r.extensions) if getattr(r, "extensions", None) else ""
+        enabled_str = "yes" if getattr(r, "enabled", True) else "no"
+        dest = safe_str(getattr(r, "destination", ""))
+        table.add_row(
+            safe_str(r.name),
+            str(r.priority),
+            enabled_str,
+            keywords,
+            exts,
+            dest,
+        )
+
+    console.print(table)
+
+
+def render_rule_trace(
+    filename: str,
+    ext: str,
+    size: int,
+    raw_toks: Sequence[str],
+    camel_toks: Sequence[str],
+    traces: Sequence[RuleTrace],
+    decision_kind: DecisionKind,
+    hit_rule: str | None,
+    hit_dest: str | None,
+    hit_reason: str,
+    *,
+    no_color: bool = False,
+) -> None:
+    """Render the explanation output for rules test command."""
+    console = get_console(no_color=no_color)
+    console.print(f"File: {filename}   (ext={ext}, {size} bytes)")
+    console.print(f"tokens(raw)   : {' '.join(raw_toks)}")
+    console.print(f"tokens(camel) : {' '.join(camel_toks)}\n")
+
+    for t in traces:
+        mark = "✓" if t.matched else "✗"
+        reasons_text = (
+            ", ".join(t.reasons) if t.reasons else ("matched" if t.matched else "no match")
+        )
+        rule_name = safe_str(t.rule_name)
+        if no_color:
+            console.print(f" {mark} {rule_name:<16} priority {t.priority:<4} {reasons_text}")
+        elif t.matched:
+            console.print(
+                f" [green]{mark}[/] [bold]{rule_name:<16}[/] "
+                f"priority {t.priority:<4} {reasons_text}"
+            )
+        else:
+            console.print(
+                f" [dim red]{mark}[/] [dim]{rule_name:<16}[/] "
+                f"[dim]priority {t.priority:<4} {reasons_text}[/]"
+            )
+
+    console.print()
+    if decision_kind == DecisionKind.MATCH:
+        dest_text = f" ->  {hit_dest}" if hit_dest else ""
+        match_line = f"Result: MATCH  {hit_rule}{dest_text}"
+        console.print(f"[green bold]{match_line}[/]" if not no_color else match_line)
+    elif decision_kind == DecisionKind.AMBIGUOUS:
+        ambig_line = f"Result: AMBIGUOUS  {hit_reason}"
+        console.print(f"[yellow bold]{ambig_line}[/]" if not no_color else ambig_line)
+    else:
+        nomatch_line = f"Result: NO_MATCH  {hit_reason or 'no rule matched'}"
+        console.print(f"[dim]{nomatch_line}[/]" if not no_color else nomatch_line)
+
+
+def render_history_table(
+    records: Sequence[OperationRecord],
+    *,
+    no_color: bool = False,
+) -> None:
+    """Render table of history operations."""
+    console = get_console(no_color=no_color)
+    table = Table(title="History Operations", header_style="bold")
+    table.add_column("ID", justify="right")
+    table.add_column("Batch", justify="right")
+    table.add_column("Status")
+    table.add_column("Rule")
+    table.add_column("Source")
+    table.add_column("Destination")
+    table.add_column("Created At")
+
+    for rec in records:
+        status_str = rec.status.value
+        table.add_row(
+            str(rec.id),
+            str(rec.batch_id),
+            status_str,
+            safe_str(rec.rule_name or ""),
+            safe_str(rec.src_path),
+            safe_str(rec.dst_path or ""),
+            safe_str(rec.created_at[:19]),
+        )
+
+    console.print(table)
+
+
+def render_doctor_results(
+    checks: list[dict[str, Any]],
+    fixes: list[dict[str, Any]],
+    *,
+    no_color: bool = False,
+) -> None:
+    """Render doctor checklist and fixes applied."""
+    console = get_console(no_color=no_color)
+    console.print("[bold]ClutterXP Doctor Diagnostics[/bold]\n")
+
+    for c in checks:
+        status = c.get("status", "ok")
+        name = c.get("name", "")
+        message = c.get("message", "")
+        if status == "ok":
+            mark = "[green]✓[/green]" if not no_color else "✓"
+            console.print(f" {mark} {name}: {message}")
+        elif status == "warning":
+            mark = "[yellow]![/yellow]" if not no_color else "!"
+            console.print(f" {mark} {name}: {message}")
+        else:  # error
+            mark = "[red]✗[/red]" if not no_color else "✗"
+            console.print(f" {mark} {name}: {message}")
+
+    if fixes:
+        console.print("\n[bold]Fixes applied:[/bold]")
+        for f in fixes:
+            console.print(f" - {f.get('check')}: {f.get('message')}")
+
+
+__all__ = [
+    "get_console",
+    "print_json",
+    "progress_bar",
+    "render_doctor_results",
+    "render_history_table",
+    "render_organize_summary",
+    "render_plan",
+    "render_rule_trace",
+    "render_rules_table",
+    "safe_str",
+]

clutterxp/config/__init__.py

@@ -0,0 +1,40 @@
+"""Configuration: schema (frozen field names/types), loader, writer, validation."""
+
+from __future__ import annotations
+
+from .jsonschema import config_json_schema
+from .loader import load
+from .placeholders import ALLOWED_PLACEHOLDERS, extract_static_root, validate_destination_template
+from .runtime import RuntimeConfig
+from .schema import Conditions, Config, HistorySettings, RuleSpec, Settings, WatchEntry
+from .validate import validate
+from .writer import (
+    add_rule,
+    disable_rule,
+    edit_rule,
+    enable_rule,
+    init_config,
+    remove_rule,
+)
+
+__all__ = [
+    "ALLOWED_PLACEHOLDERS",
+    "Conditions",
+    "Config",
+    "HistorySettings",
+    "RuleSpec",
+    "RuntimeConfig",
+    "Settings",
+    "WatchEntry",
+    "add_rule",
+    "config_json_schema",
+    "disable_rule",
+    "edit_rule",
+    "enable_rule",
+    "extract_static_root",
+    "init_config",
+    "load",
+    "remove_rule",
+    "validate",
+    "validate_destination_template",
+]

clutterxp/config/jsonschema.py

@@ -0,0 +1,12 @@
+"""JSON Schema generator for clutterxp configuration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .schema import Config
+
+
+def config_json_schema() -> dict[str, Any]:
+    """Generate and return JSON schema dictionary for Config."""
+    return Config.model_json_schema()

clutterxp/config/loader.py

@@ -0,0 +1,212 @@
+"""Configuration loader with Pydantic validation, error aggregation, and path expansion."""
+
+from __future__ import annotations
+
+import contextlib
+import difflib
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+from ..models import ConfigError
+from ..paths import expand
+from .placeholders import validate_destination_template
+from .runtime import RuntimeConfig
+from .schema import Conditions, Config, HistorySettings, RuleSpec, Settings, WatchEntry
+from .validate import validate
+
+MigrationFn = Callable[[dict[str, Any]], dict[str, Any]]
+_MIGRATION_REGISTRY: dict[int, MigrationFn] = {}
+
+
+def register_migration(from_version: int, fn: MigrationFn) -> None:
+    """Register a migration function from version N to N+1."""
+    _MIGRATION_REGISTRY[from_version] = fn
+
+
+def apply_migrations(data: dict[str, Any], target_version: int = 1) -> dict[str, Any]:
+    """Apply sequential migrations up to target_version."""
+    current_v = data.get("version", 1)
+    if not isinstance(current_v, int):
+        return data
+    while current_v < target_version:
+        if current_v not in _MIGRATION_REGISTRY:
+            raise ConfigError(
+                f"No migration registered from config version {current_v} to {current_v + 1}"
+            )
+        data = _MIGRATION_REGISTRY[current_v](data)
+        current_v += 1
+        data["version"] = current_v
+    return data
+
+
+def _format_loc(loc: tuple[int | str, ...]) -> str:
+    """Format Pydantic error loc into a YAML-style path (e.g. rules[0].destination)."""
+    parts: list[str] = []
+    for item in loc:
+        if isinstance(item, int):
+            parts.append(f"[{item}]")
+        else:
+            if parts:
+                parts.append(f".{item}")
+            else:
+                parts.append(str(item))
+    return "".join(parts)
+
+
+def _get_allowed_keys_for_loc(parent_loc: tuple[int | str, ...]) -> list[str]:
+    """Return valid field names for the model at the given loc prefix."""
+    if not parent_loc:
+        return list(Config.model_fields.keys())
+    if parent_loc[0] == "settings":
+        if len(parent_loc) > 1 and parent_loc[1] == "history":
+            return list(HistorySettings.model_fields.keys())
+        return list(Settings.model_fields.keys())
+    if parent_loc[0] == "rules":
+        if len(parent_loc) > 2 and parent_loc[2] == "conditions":
+            return list(Conditions.model_fields.keys())
+        return list(RuleSpec.model_fields.keys())
+    if parent_loc[0] == "watch":
+        return list(WatchEntry.model_fields.keys())
+    return []
+
+
+def load(path: Path) -> RuntimeConfig:
+    """Load, parse, validate, and expand configuration from path.
+
+    Returns a RuntimeConfig with accumulated errors and warnings.
+    Raises ConfigError only for fatal parse or file access errors.
+    """
+    if not path.exists():
+        raise ConfigError(f"Config file not found: {path}")
+    if not path.is_file():
+        raise ConfigError(f"Config path is not a file: {path}")
+
+    yaml = YAML(typ="safe")
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            raw_data = yaml.load(f)
+    except YAMLError as e:
+        raise ConfigError(f"YAML parse error in '{path}': {e}") from e
+    except OSError as e:
+        raise ConfigError(f"Failed to read config file '{path}': {e}") from e
+
+    if raw_data is None:
+        raw_data = {}
+
+    if not isinstance(raw_data, dict):
+        raise ConfigError(
+            f"Config root in '{path}' must be a YAML mapping, got {type(raw_data).__name__}"
+        )
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # Check version
+    raw_version = raw_data.get("version")
+    if raw_version is not None and isinstance(raw_version, int) and raw_version > 1:
+        errors.append(
+            f"version: config version {raw_version} is newer than supported (1); upgrade ClutterXP"
+        )
+
+    # Schema validation with Pydantic (collects all schema errors)
+    config_obj: Config | None = None
+    try:
+        config_obj = Config.model_validate(raw_data)
+    except ValidationError as ve:
+        for err in ve.errors():
+            loc = err["loc"]
+            yaml_path = _format_loc(loc)
+            msg = err["msg"]
+            if err.get("type") == "extra_forbidden":
+                unknown = str(loc[-1]) if loc else ""
+                allowed = _get_allowed_keys_for_loc(loc[:-1])
+                matches = difflib.get_close_matches(unknown, allowed)
+                if matches:
+                    errors.append(
+                        f"{yaml_path}: unknown key '{unknown}'; did you mean '{matches[0]}'?"
+                    )
+                else:
+                    errors.append(f"{yaml_path}: unknown key '{unknown}'")
+            else:
+                errors.append(f"{yaml_path}: {msg}")
+
+    # Check template placeholders across raw rules to report all problems at once
+    raw_rules = raw_data.get("rules", [])
+    if isinstance(raw_rules, list):
+        for i, r in enumerate(raw_rules):
+            if isinstance(r, dict) and isinstance(r.get("destination"), str):
+                dest_str = r["destination"]
+                if "$" in dest_str or dest_str.startswith("~"):
+                    with contextlib.suppress(ConfigError):
+                        dest_str = str(expand(dest_str))
+                p_errors = validate_destination_template(dest_str)
+                for pe in p_errors:
+                    err_msg = f"rules[{i}].destination: {pe}"
+                    if err_msg not in errors:
+                        errors.append(err_msg)
+
+    # Further validation if schema parsed successfully
+    if config_obj is not None:
+        # 1. Expand paths in destinations and watch entries
+        expanded_rules: list[RuleSpec] = []
+        for i, rule in enumerate(config_obj.rules):
+            if "$" in rule.destination or rule.destination.startswith("~"):
+                try:
+                    expanded_dest = str(expand(rule.destination))
+                    rule = rule.model_copy(update={"destination": expanded_dest})
+                except ConfigError as ce:
+                    err_msg = f"rules[{i}].destination: {ce.message}"
+                    if err_msg not in errors:
+                        errors.append(err_msg)
+            expanded_rules.append(rule)
+
+        expanded_watch: list[WatchEntry] = []
+        for i, entry in enumerate(config_obj.watch):
+            try:
+                expanded_p = str(expand(entry.path))
+                entry = entry.model_copy(update={"path": expanded_p})
+            except ConfigError as ce:
+                err_msg = f"watch[{i}].path: {ce.message}"
+                if err_msg not in errors:
+                    errors.append(err_msg)
+            expanded_watch.append(entry)
+
+        # 2. Cross-config checks
+        updated_config = config_obj.model_copy(
+            update={"rules": expanded_rules, "watch": expanded_watch}
+        )
+        cross_errors, cross_warnings = validate(updated_config)
+        errors.extend(cross_errors)
+        warnings.extend(cross_warnings)
+
+        enabled_rules = tuple(r for r in expanded_rules if r.enabled)
+        disabled_rules = tuple(r for r in expanded_rules if not r.enabled)
+        watch_entries = tuple(expanded_watch)
+        settings = config_obj.settings
+    else:
+        enabled_rules = ()
+        disabled_rules = ()
+        watch_entries = ()
+        settings = Settings()
+
+    try:
+        mtime_ns = path.stat().st_mtime_ns
+    except OSError:
+        mtime_ns = 0
+
+    return RuntimeConfig(
+        config_path=path,
+        mtime_ns=mtime_ns,
+        settings=settings,
+        watch_entries=watch_entries,
+        rules=enabled_rules,
+        disabled_rules=disabled_rules,
+        errors=tuple(errors),
+        warnings=tuple(warnings),
+    )