gitpane 1.0.0__py3-none-any.whl

gitpane/worktree/trash.py

@@ -0,0 +1,302 @@
+"""Move confirmed working files through the OS trash service without permanent removal."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QFile, QObject, QTimer, Signal
+
+from gitpane.config import TRASH_TIMEOUT_MS
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.operation.repository_operation import OperationAction
+from gitpane.worktree.command_sequence import FileTask, GitCommand
+from gitpane.worktree.worktree_file import FileImage, capture_image, validate_destination, validate_image
+from gitpane.worktree.worktree_snapshot import WorktreeKey, conflict_side_by_path, verify_local_state
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.worktree.mutation import MutationService
+    from gitpane.worktree.worktree_service import WorktreeService
+    from gitpane.worktree.worktree_snapshot import LocalEntry, WorktreeSnapshot
+
+
+def move_file_to_trash(target_filename: str) -> None:
+    """Use one QFile instance so a failed OS move retains its actual error cause."""
+    target = QFile(target_filename)
+    if not target.moveToTrash():
+        raise OSError(target.errorString())
+
+
+def trash_filename(context: RepositoryContext, path: bytes) -> str:
+    """Require a lossless OS and QString path before handing a name to Qt."""
+    try:
+        decoded = os.fsdecode(path)
+        decoded.encode("utf-8", "strict")
+        if os.fsencode(decoded) != path or "\ufffd" in decoded:
+            raise ValueError("The file name cannot be represented exactly by the trash service")
+    except UnicodeError as error:
+        raise ValueError("The file name cannot be represented exactly by the trash service") from error
+    filename, _parents = validate_destination(context, path)
+    try:
+        filename.encode("utf-8", "strict")
+    except UnicodeError as error:
+        raise ValueError("The absolute file name cannot be represented by the trash service") from error
+    return filename
+
+
+def tracked_trash_path_set(index_entries: bytes) -> set[bytes]:
+    """Name every path the index records, each stage of a conflict included, from `ls-files --stage -z` records.
+
+    The records go through the same validation as the conflict reader first, so a malformed listing is refused instead
+    of turning into a wrong tracked or untracked label in the confirmation.
+    """
+    try:
+        conflict_side_by_path(index_entries)
+    except ValueError as error:
+        raise ValueError("Git returned malformed index entries; refresh and select the files again") from error
+    tracked_path_set: set[bytes] = set()
+    for record in index_entries.split(b"\0"):
+        if not record:
+            continue
+        _metadata, _separator, path = record.partition(b"\t")
+        tracked_path_set.add(path)
+    return tracked_path_set
+
+
+class TrashTargetState(Enum):
+    """Where one confirmed file stands in a move to the Trash; the value is the word the per-file details show."""
+
+    NOT_STARTED = "not_started"
+    """The file was not handed to the system, because the move stopped before it."""
+    PENDING = "pending"
+    """The system is moving the file and has not answered yet."""
+    MOVED = "moved"
+    """The system moved the file to the Trash."""
+    FAILED = "failed"
+    """The system refused the move, and the file is still in place."""
+    UNKNOWN = "unknown"
+    """The system reported an error but the file is gone, so whether it reached the Trash is not known."""
+
+
+@dataclass(frozen=True)
+class TrashTarget:
+    """Retain the confirmed identity alongside each observed OS result."""
+
+    path: bytes
+    filename: str
+    image: FileImage
+    tracked: bool
+    status: TrashTargetState = TrashTargetState.NOT_STARTED
+    cause: str = ""
+
+
+@dataclass(frozen=True)
+class TrashRequest:
+    """Freeze the selected paths and their file images before asking for confirmation."""
+
+    operation_id: str
+    snapshot: WorktreeSnapshot
+    targets: tuple[TrashTarget, ...]
+
+
+@dataclass(frozen=True)
+class TrashOutcome:
+    """Keep per-file results and the real completion state beyond the view lifetime."""
+
+    operation_id: str
+    key: WorktreeKey
+    status: OperationStatus
+    targets: tuple[TrashTarget, ...]
+    finished: bool
+    snapshot: WorktreeSnapshot | None = None
+    diagnostic: PreparedDiagnostic | None = None
+
+
+class TrashService(QObject):
+    """Share mutation reservations and the existing file worker with a replaceable OS service."""
+
+    finished = Signal(object)
+    waiting = Signal(object)
+
+    def __init__(self, worktree_service: WorktreeService, mutation: MutationService, move_file_to_trash: Callable[[str], None] = move_file_to_trash, parent: QObject | None = None) -> None:
+        """Inject the trash primitive and keep all file work under application ownership."""
+        super().__init__(parent)
+        self.worktree_service = worktree_service
+        self.mutation = mutation
+        self.move_file_to_trash = move_file_to_trash
+        self.prepared_by_id: dict[str, TrashRequest] = {}
+        self.active_by_id: dict[str, TrashRequest] = {}
+        self.outcome_by_id: dict[str, TrashOutcome] = {}
+
+    def prepare(self, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...], callback: Callable[[TrashRequest | None, Exception | None], None]) -> str:
+        """Capture validated file identities while holding a shared preparation reservation.
+
+        A refused reservation gives the real reason, worked out right away so it describes the state that refused it:
+        another operation is named only when a write really holds the repository.
+        """
+        operation_id = uuid.uuid4().hex
+        if not self.mutation.acquire(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT):
+            cause = self.mutation.acquire_refusal_cause(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT)
+            QTimer.singleShot(0, lambda: callback(None, ValueError(cause)))
+            return operation_id
+
+        def complete(request: TrashRequest | None, error: Exception | None) -> None:
+            """Release calculation ownership while the user reviews the captured paths."""
+            self.mutation.release(snapshot.key, operation_id)
+            if error is None:
+                self.prepared_by_id[operation_id] = request
+            callback(request, error)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self._prepare(operation_id, snapshot, entries), complete, operation_id=operation_id)
+        return operation_id
+
+    def _prepare(self, operation_id: str, snapshot: WorktreeSnapshot, entries: tuple[LocalEntry, ...]) -> Generator:
+        """Check the selection against the index bytes and files of the displayed read, then capture each file to move.
+
+        This only prepares the confirmation: the index bytes and selected files are compared without a process before
+        and after, the tracked paths come from the index records of the read, and Git itself checks HEAD, configuration
+        and attributes again before the first move.
+        """
+        if not snapshot.fresh or not entries or any(entry not in snapshot.entries for entry in entries):
+            raise ValueError("The selected changes are stale; Refresh and select them again")
+        paths = tuple(dict.fromkeys(entry.path for entry in entries))
+        yield FileTask(lambda: verify_local_state(snapshot, paths))
+        index_entries = snapshot.index_entries
+        if index_entries is None:
+            # A read that kept no index records lists the index once. The local checks before and after tie that
+            # listing to the index bytes of the read.
+            index_entries = yield GitCommand(["ls-files", "--stage", "-z"])
+        tracked_path_set = tracked_trash_path_set(index_entries)
+        targets: list[TrashTarget] = []
+        entry_by_path: dict[bytes, LocalEntry] = {}
+        for entry in entries:
+            entry_by_path[entry.path] = entry
+        for path in sorted(entry_by_path):
+            entry = entry_by_path[path]
+            if entry.old_mode == "160000" or entry.new_mode == "160000":
+                raise ValueError("A submodule directory cannot be moved to Trash as a file")
+            filename = yield FileTask(lambda path=entry.path: trash_filename(snapshot.context, path))
+            image = yield FileTask(lambda path=entry.path: capture_image(snapshot.context, path))
+            if not image.exists:
+                raise ValueError("The selected file is absent; Refresh and select the changes again")
+            targets.append(TrashTarget(entry.path, filename, image, entry.path in tracked_path_set))
+        yield FileTask(lambda: verify_local_state(snapshot, paths))
+        return TrashRequest(operation_id, snapshot, tuple(targets))
+
+    def cancel(self, request: TrashRequest) -> None:
+        """Forget a declined confirmation without touching any working path."""
+        self.prepared_by_id.pop(request.operation_id, None)
+
+    def submit(self, request: TrashRequest) -> str:
+        """Accept each captured intention at most once and reserve until the actual result.
+
+        A refused reservation moves nothing and gives the real reason, worked out right away so it describes the state
+        that refused it.
+        """
+        operation_id = request.operation_id
+        if operation_id in self.active_by_id or operation_id in self.outcome_by_id:
+            return operation_id
+        if self.prepared_by_id.pop(operation_id, None) is not request:
+            raise ValueError("This trash confirmation is no longer current")
+        snapshot = request.snapshot
+        if not self.mutation.acquire(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT):
+            cause = self.mutation.acquire_refusal_cause(snapshot, operation_id, action=OperationAction.WORKTREE_EDIT)
+            outcome = self._outcome(request, OperationStatus.REFUSED, request.targets, None, cause)
+            self.outcome_by_id[operation_id] = outcome
+            QTimer.singleShot(0, lambda: self.finished.emit(outcome))
+            return operation_id
+        self.active_by_id[operation_id] = request
+
+        def complete(outcome: TrashOutcome | None, error: Exception | None) -> None:
+            """Release ownership only once both OS work and the final read have returned."""
+            if error is not None:
+                outcome = self._outcome(request, OperationStatus.UNKNOWN, request.targets, None, str(error))
+            self.active_by_id.pop(operation_id, None)
+            self.outcome_by_id[operation_id] = outcome
+            self.mutation.release(snapshot.key, operation_id)
+            self.finished.emit(outcome)
+            self.mutation.reread_requested.emit(snapshot.key)
+
+        self.worktree_service.run(snapshot.context, snapshot.git_filename, self._execute(request), complete, operation_id=operation_id)
+        return operation_id
+
+    def _execute(self, request: TrashRequest) -> Generator:
+        """Have Git verify the confirmed state, move in a worker, and report the complete state read afterwards.
+
+        The verification needs no complete read: it compares HEAD, index, configuration and attributes with fresh Git
+        reads, and each file is checked again immediately before its own move.
+        """
+        snapshot = request.snapshot
+        targets = request.targets
+        cause = ""
+        status = OperationStatus.REFUSED
+        try:
+            yield from self.worktree_service.verify(snapshot, tuple(target.path for target in targets))
+            for target in targets:
+                yield FileTask(lambda target=target: validate_image(snapshot.context, target.path, target.image))
+            results: list[TrashTarget] = []
+            status = OperationStatus.SUCCESS
+            for target in targets:
+                waiting_targets = tuple(results) + (replace(target, status=TrashTargetState.PENDING),) + targets[len(results) + 1:]
+                timer = QTimer(self)
+                timer.setSingleShot(True)
+                timer.timeout.connect(lambda waiting_targets=waiting_targets: self._waiting(request, waiting_targets))
+                timer.start(TRASH_TIMEOUT_MS)
+                try:
+                    result = yield FileTask(lambda target=target: self._move(snapshot.context, target))
+                finally:
+                    timer.stop()
+                    timer.deleteLater()
+                results.append(result)
+                if result.status != TrashTargetState.MOVED:
+                    cause = result.cause
+                    status = OperationStatus.PARTIAL if any(previous.status == TrashTargetState.MOVED for previous in results) else OperationStatus.FAILED
+                    results.extend(targets[len(results):])
+                    break
+            targets = tuple(results)
+        except (OSError, ValueError, RuntimeError) as error:
+            cause = str(error)
+        after = None
+        try:
+            after = yield from self.worktree_service.capture(snapshot.context, snapshot.git_filename)
+        except (OSError, ValueError, RuntimeError) as error:
+            cause += " The result could not be refreshed: " + str(error)
+            status = OperationStatus.UNKNOWN
+        return self._outcome(request, status, targets, after, cause)
+
+    def _move(self, context: RepositoryContext, target: TrashTarget) -> TrashTarget:
+        """Validate immediately before the native call without following a leaf symlink."""
+        started = False
+        try:
+            self.mutation.validate_write(WorktreeKey.from_context(context))
+            validate_image(context, target.path, target.image)
+            started = True
+            self.move_file_to_trash(target.filename)
+            return replace(target, status=TrashTargetState.MOVED)
+        except (OSError, ValueError, RuntimeError) as error:
+            # A failed native response cannot prove that a now-absent path was never moved.
+            state = TrashTargetState.UNKNOWN if started and not os.path.lexists(target.filename) else TrashTargetState.FAILED
+            return replace(target, status=state, cause=str(error))
+
+    def _waiting(self, request: TrashRequest, targets: tuple[TrashTarget, ...]) -> None:
+        """Report a presentation deadline while leaving the OS call and reservation active."""
+        if request.operation_id not in self.active_by_id:
+            return
+        outcome = self._outcome(request, OperationStatus.PENDING, targets, None, "Waiting for the OS Trash operation to finish. Its result is still unknown; do not repeat the operation.")
+        self.waiting.emit(replace(outcome, finished=False))
+
+    def _outcome(self, request: TrashRequest, status: OperationStatus, targets: tuple[TrashTarget, ...], snapshot: WorktreeSnapshot | None, cause: str) -> TrashOutcome:
+        """Prepare a readable per-path result without claiming that a batch can be undone."""
+        diagnostic = None
+        if cause:
+            details = "\n".join(target.path.decode("utf-8", "replace") + ": " + target.status.value + (" — " + target.cause if target.cause else "") for target in targets)
+            diagnostic = Diagnostic("Move to Trash", request.snapshot.context.repository_dir, request.snapshot.git_filename, [], cause + "\n" + details).prepare()
+        return TrashOutcome(request.operation_id, request.snapshot.key, status, targets, True, snapshot, diagnostic)