gitpane 1.0.0__py3-none-any.whl

gitpane/tool/difftool.py

@@ -0,0 +1,429 @@
+"""Prepare literal arguments for an explicitly configured historical comparison."""
+
+from __future__ import annotations
+
+import os
+import queue
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QProcess, Qt, QTimer, Signal
+
+from gitpane.config import DIFFTOOL_ACTIVE_LIMIT, DIFFTOOL_START_TIMEOUT_MS, MILLISECONDS_PER_SECOND, SHELL_SCRIPT_EXTENSION_SET, TOOL_RESULT_POLL_MS
+from gitpane.history.repository_value import FilePanel, FileReadIdentity, RequestIdentity, historical_selection
+from gitpane.system.linux_distribution import DistributionFamily, DistributionRelease
+from gitpane.system.startup_activation import NO_STARTUP_ACTIVATION, StartupActivation, no_startup_activation
+from gitpane.tool.kdiff3 import tool_program_usable
+from gitpane.tool.kdiff3_install import with_kdiff3_install_line
+from gitpane.tool.system_tool import SystemToolService
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.history.repository import GitRepository
+    from gitpane.history.repository_value import HistoricalFileSelection, RepositoryContext, RepositoryFailure, RevisionEntry
+    from gitpane.tool.system_tool import OperationResult
+
+# The only launch states _poll has to look at over time: a reading launch is cancelled once its file selection is no longer current,
+# and a starting launch reports its startup deadline. No worker event announces either change, so only these states keep the timer running.
+DIFFTOOL_WATCHED_STATE_SET = frozenset(("reading", "starting"))
+
+
+@dataclass(frozen=True)
+class DifftoolRecipe:
+    """Capture the executable separately from its Qt-quoted argument template."""
+
+    program_filename: str
+    command: str
+
+    def validate(self, *, platform: str = sys.platform, family: DistributionFamily = DistributionFamily.UNKNOWN,
+                 release: DistributionRelease = DistributionRelease.OTHER) -> None:
+        """Reject missing executables and malformed templates before publishing a draft.
+
+        The refusal of a missing tool says how to install KDiff3 on ``platform``, and under Linux on the distribution
+        ``family`` and ``release``, all received so each system's message can be checked from any of them.
+        """
+        parse_difftool_command(self.command, "before", "after")
+        if not self.program_filename:
+            return
+        if not tool_program_usable(self.program_filename):
+            raise ValueError(with_kdiff3_install_line("External diff tool executable is missing or not executable. Choose its full path.", platform, family, release))
+        if os.path.splitext(self.program_filename)[1].casefold() in SHELL_SCRIPT_EXTENSION_SET:
+            raise ValueError("Choose the real external diff executable instead of a shell script launcher.")
+
+
+def parse_difftool_command(command: str, before_filename: str, after_filename: str) -> list[str]:
+    """Split Qt double-quoted arguments before replacing only the two historical filenames."""
+    if "\0" in command:
+        raise ValueError("External diff arguments cannot contain a null character.")
+    # Qt represents a literal quote with three quotes; backslashes do not escape quotes.
+    if command.replace('"""', '').count('"') % 2:
+        raise ValueError("External diff arguments contain an unclosed double quote.")
+    arguments = QProcess.splitCommand(command)
+    replacement_by_token = {"$LOCAL": before_filename, "$REMOTE": after_filename}
+    token_set: set[str] = set()
+    results = []
+    for argument in arguments:
+        tokens = re.findall(r"\$[A-Za-z_][A-Za-z_0-9]*|\$\{[^}]*\}|\$", argument)
+        for token in tokens:
+            if token not in replacement_by_token:
+                raise ValueError("External diff arguments contain an unknown parameter. Use $LOCAL and $REMOTE only.")
+            token_set.add(token)
+        results.append(re.sub(r"\$LOCAL|\$REMOTE", lambda match: replacement_by_token[match.group()], argument))
+    if token_set != set(replacement_by_token):
+        raise ValueError("External diff arguments must include both $LOCAL and $REMOTE.")
+    return results
+
+
+@dataclass(frozen=True)
+class DifftoolLaunch:
+    """Keep each comparison's historical versions and private filenames immutable.
+
+    ``activation`` is the startup value read when the user clicked, which lets the tool's window come to the front.
+    """
+
+    request_id: str
+    selection: HistoricalFileSelection
+    entry: RevisionEntry
+    recipe: DifftoolRecipe
+    temporary_dir: str = ""
+    before_filename: str = ""
+    after_filename: str = ""
+    state: str = "preparing"
+    # Set once the tool has exited: the --log line of the close names them, and a failure reported afterwards, such as a
+    # refused cleanup, says the tool had already closed with that code.
+    return_code: int | None = None
+    run_duration_ms: int | None = None
+    activation: StartupActivation = NO_STARTUP_ACTIVATION
+
+
+@dataclass
+class PendingComparison:
+    """Track extraction and OS startup separately from the immutable comparison values."""
+
+    launch: DifftoolLaunch
+    context: RepositoryContext
+    git_filename: str
+    is_current: Callable[[], bool]
+    read_identity: FileReadIdentity | None = None
+    remaining_sides: list[str] = field(default_factory=lambda: ["before", "after"])
+    deadline: float | None = None
+    reported: bool = False
+    cancelled: bool = False
+
+
+class TemporaryComparisonStore:
+    """Create independent before and after folders for historical comparisons."""
+
+    def __init__(self) -> None:
+        """Record ownership separately from public launch values to reject altered paths."""
+        self.directory_by_request: dict[str, tuple[str, int, int]] = {}
+        self.lock = threading.Lock()
+
+    def create(self, launch: DifftoolLaunch) -> DifftoolLaunch:
+        """Preserve usable basenames while keeping raw Git paths out of local directory traversal."""
+        temporary_dir = os.path.realpath(tempfile.mkdtemp(prefix="gitpane-diff-"))
+        filenames = []
+        try:
+            for side, path in (("before", launch.entry.old_path), ("after", launch.entry.new_path)):
+                directory = os.path.join(temporary_dir, side)
+                os.mkdir(directory)
+                basename_index = -1
+                basename = os.fsdecode((path or launch.selection.path).split(b"/")[basename_index])
+                if basename in ("", ".", "..") or any(character in basename for character in ('\\', '/', '\0')):
+                    raise ValueError("The historical filename cannot be represented safely on this system.")
+                if os.name == "nt" and (os.path.isreserved(basename) or any(character in basename for character in '<>:"|?*') or basename.endswith((".", " "))):
+                    raise ValueError("The historical filename cannot be represented safely on this system.")
+                filenames.append(os.path.join(directory, basename))
+            before_filename, after_filename = filenames
+            directory_stat = os.stat(temporary_dir)
+            with self.lock:
+                self.directory_by_request[launch.request_id] = (temporary_dir, directory_stat.st_dev, directory_stat.st_ino)
+            return replace(launch, temporary_dir=temporary_dir, before_filename=before_filename, after_filename=after_filename, state="reading")
+        except (OSError, ValueError):
+            shutil.rmtree(temporary_dir)
+            raise
+
+    def cleanup(self, launch: DifftoolLaunch) -> None:
+        """Remove only the recorded directory, refusing replacements and linked descendants."""
+        with self.lock:
+            owned = self.directory_by_request.get(launch.request_id)
+            if owned is None:
+                if launch.temporary_dir and os.path.lexists(launch.temporary_dir):
+                    raise ValueError("The comparison directory is not owned by this service.")
+                return
+            directory, device, inode = owned
+            if launch.temporary_dir != directory or os.path.realpath(launch.temporary_dir) != directory:
+                raise ValueError("The comparison directory is not the owned directory.")
+            if not os.path.lexists(directory):
+                self.directory_by_request.pop(launch.request_id)
+                return
+            directory_stat = os.lstat(directory)
+            if (directory_stat.st_dev, directory_stat.st_ino) != (device, inode):
+                raise ValueError("The owned comparison directory was replaced.")
+            self._check_directory(directory, directory)
+            shutil.rmtree(directory)
+            self.directory_by_request.pop(launch.request_id)
+
+    def _check_directory(self, directory: str, owned_dir: str) -> None:
+        """Refuse symlinks and Windows reparse points before recursive deletion."""
+        directory_stat = os.lstat(directory)
+        if stat.S_ISLNK(directory_stat.st_mode) or getattr(directory_stat, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0):
+            raise ValueError("The owned comparison directory contains a link or reparse point.")
+        if os.path.commonpath((os.path.realpath(directory), owned_dir)) != owned_dir:
+            raise ValueError("The comparison path resolves outside its owned directory.")
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                entry_stat = entry.stat(follow_symlinks=False)
+                if entry.is_symlink() or getattr(entry_stat, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0):
+                    raise ValueError("The owned comparison directory contains a link or reparse point.")
+                if entry.is_dir(follow_symlinks=False):
+                    self._check_directory(entry.path, owned_dir)
+
+
+class DifftoolService(QObject):
+    """Own exact historical copies and tracked external processes independently of windows."""
+
+    started = Signal(object)
+    # The tool exited by itself, whatever its exit code: the user closed the comparison.
+    tool_exited = Signal(object)
+    finished = Signal(object)
+    failed = Signal(object, str)
+    idle = Signal()
+    event_ready = Signal()
+
+    def __init__(self, repository: GitRepository, process_factory: Callable[..., subprocess.Popen] = subprocess.Popen,
+                 temporary_store: TemporaryComparisonStore | None = None, parent: QObject | None = None, *, platform: str = sys.platform,
+                 activation: Callable[[], StartupActivation] = no_startup_activation, distribution_family: DistributionFamily = DistributionFamily.UNKNOWN,
+                 distribution_release: DistributionRelease = DistributionRelease.OTHER) -> None:
+        """Inject OS process creation, copy storage and the system whose install line refusals give, keeping Qt delivery on its owner thread.
+
+        Under Linux, the install line also follows the distribution ``distribution_family`` and ``distribution_release``
+        that the wiring read from the session once; the defaults say GitPane does not know how to install KDiff3 there.
+
+        The activation source tells the desktop that the user asked for the comparison (an X11 startup identifier or a
+        Wayland activation token), so the tool's window may come to the front; it is read on the window's thread when
+        a comparison is accepted, never for a refused one. Without a desktop, as in the tests, there is none.
+        """
+        super().__init__(parent)
+        self.repository = repository
+        self.platform = platform
+        self.distribution_family = distribution_family
+        self.distribution_release = distribution_release
+        self.activation = activation
+        self.process_factory = process_factory
+        self.temporary_store = temporary_store if temporary_store is not None else TemporaryComparisonStore()
+        self.export = SystemToolService(parent=self)
+        self.export.export_finished.connect(self._export_finished)
+        self.repository.file_failed.connect(self._read_failed)
+        self.active_by_id: dict[str, PendingComparison] = {}
+        self.event_queue: queue.SimpleQueue[tuple[str, str, object]] = queue.SimpleQueue()
+        self.closed = False
+        self.timer = QTimer(self)
+        self.timer.setInterval(TOOL_RESULT_POLL_MS)
+        self.timer.timeout.connect(self._poll)
+        self.event_ready.connect(self._poll, Qt.ConnectionType.QueuedConnection)
+
+    def compare(self, entry: RevisionEntry, identity: FileReadIdentity, recipe: DifftoolRecipe, is_current: Callable[[], bool]) -> bool:
+        """Reserve one launch and capture exact sides only while the source selection is valid.
+
+        Called by the user's click: once every refusal has passed, the click's startup value is read here, on the
+        window's thread, and travels with the launch to the tool's environment.
+        """
+        if self.closed or not is_current():
+            return False
+        owner = identity.request_identity.session_id
+        for pending in self.active_by_id.values():
+            if pending.launch.selection.selection_identity.request_identity.session_id == owner and pending.launch.state != "running":
+                self.failed.emit(pending.launch, "External comparison is still starting or finishing. Wait before launching again.")
+                return False
+        launch = DifftoolLaunch(uuid.uuid4().hex, historical_selection(entry, identity), entry, recipe)
+        try:
+            parse_difftool_command(recipe.command, "before", "after")
+            if not recipe.program_filename:
+                raise ValueError(with_kdiff3_install_line("Choose an external diff tool executable in Settings first.", self.platform, self.distribution_family, self.distribution_release))
+            # A cheap file check, made here so a saved tool that disappeared is refused with its own cause and install line.
+            recipe.validate(platform=self.platform, family=self.distribution_family, release=self.distribution_release)
+            if "160000" in (entry.old_mode, entry.new_mode):
+                raise ValueError("Submodules contain commit references, not file versions to compare.")
+            if len(self.active_by_id) >= DIFFTOOL_ACTIVE_LIMIT:
+                raise ValueError("Too many external comparisons are open. Close one before launching another.")
+        except ValueError as error:
+            self.failed.emit(launch, str(error))
+            return False
+        launch = replace(launch, activation=self.activation())
+        pending = PendingComparison(launch, self.repository.context_by_session[owner], self.repository.executable_by_session[owner], is_current)
+        self.active_by_id[launch.request_id] = pending
+        threading.Thread(target=self._prepare, args=(launch,), daemon=True).start()
+        return True
+
+    def _queue_event(self, event: tuple[str, str, object]) -> None:
+        """Let a worker thread drop one event and wake the Qt thread, the only one that touches the launches."""
+        self.event_queue.put(event)
+        self.event_ready.emit()
+
+    def _update_poll_timer(self) -> None:
+        """Run the timer only while a launch waits in a state that needs checking over time, never while a tool window is open."""
+        watched = any(pending.launch.state in DIFFTOOL_WATCHED_STATE_SET for pending in self.active_by_id.values())
+        if watched and not self.timer.isActive():
+            self.timer.start()
+        elif not watched and self.timer.isActive():
+            self.timer.stop()
+
+    def _prepare(self, launch: DifftoolLaunch) -> None:
+        """Create OS folders off the GUI thread before scheduling the Git streams; the recipe was already checked by ``compare``."""
+        try:
+            self._queue_event((launch.request_id, "prepared", self.temporary_store.create(launch)))
+        except (OSError, ValueError) as error:
+            self._queue_event((launch.request_id, "error", f"Preparing external comparison failed ({type(error).__name__})."))
+
+    def _read_next(self, pending: PendingComparison) -> None:
+        """Reuse bounded atomic export for each side, including a real empty file for absent blobs."""
+        if pending.cancelled or not pending.is_current():
+            self._discard(pending, "External comparison cancelled because the file selection changed.")
+            return
+        if not pending.remaining_sides:
+            pending.launch = replace(pending.launch, state="starting")
+            pending.deadline = time.monotonic() + DIFFTOOL_START_TIMEOUT_MS / 1000
+            threading.Thread(target=self._run, args=(pending.launch,), daemon=True).start()
+            self._update_poll_timer()
+            return
+        first_side_index = 0
+        side = pending.remaining_sides.pop(first_side_index)
+        launch = pending.launch
+        entry = launch.entry
+        blob_oid = entry.old_blob_oid if side == "before" else entry.new_blob_oid
+        filename = launch.before_filename if side == "before" else launch.after_filename
+        identity = FileReadIdentity(RequestIdentity(launch.request_id, 1, oid=entry.commit_oid), FilePanel.DIFFTOOL)
+        pending.read_identity = identity
+        self.repository.context_by_session[launch.request_id] = pending.context
+        self.repository.identity_by_session[launch.request_id] = identity.request_identity
+        self.repository.executable_by_session[launch.request_id] = pending.git_filename
+
+        def read(consume: Callable[[bytes], None], completed: Callable[[int], None]) -> None:
+            """Stream the immutable object or complete an absent side with zero bytes."""
+            if blob_oid is None:
+                completed(0)
+            else:
+                self.repository.stream_blob(blob_oid, identity, consume, completed)
+
+        self.export.save_historical_file(identity, pending.context, filename, read, lambda: self.repository.cancel(launch.request_id))
+
+    def _export_finished(self, result: OperationResult) -> None:
+        """Start the second side or the process only after complete bytes reach disk."""
+        request_id = result.request_id.request_identity.session_id
+        pending = self.active_by_id.get(request_id)
+        if pending is None:
+            return
+        pending.read_identity = None
+        if result.cause:
+            self._discard(pending, "Reading external comparison files failed: " + result.cause)
+            return
+        self._read_next(pending)
+
+    def _read_failed(self, identity: FileReadIdentity, failure: RepositoryFailure) -> None:
+        """Route Git failures to the owned writer so no partial side reaches the tool."""
+        if identity.request_identity.session_id in self.active_by_id:
+            self.export.fail_export(identity, failure.cause)
+
+    def _run(self, launch: DifftoolLaunch) -> None:
+        """Launch directly without a shell and wait off-thread without an inactivity deadline.
+
+        The tool gets GitPane's environment without any inherited startup value, plus the one read at the click.
+        """
+        try:
+            arguments = parse_difftool_command(launch.recipe.command, launch.before_filename, launch.after_filename)
+            process = self.process_factory([launch.recipe.program_filename, *arguments], cwd=launch.temporary_dir, shell=False,
+                                           stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                                           env=launch.activation.environment(os.environ),
+                                           creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+            started_at = time.monotonic()
+            self._queue_event((launch.request_id, "started", None))
+            return_code = process.wait()
+            run_duration_ms = round((time.monotonic() - started_at) * MILLISECONDS_PER_SECOND)
+            self._queue_event((launch.request_id, "exited", (return_code, run_duration_ms)))
+        except (OSError, ValueError) as error:
+            self._queue_event((launch.request_id, "error", f"Starting external comparison failed ({type(error).__name__})."))
+
+    def _discard(self, pending: PendingComparison, cause: str = "") -> None:
+        """Clean copies only after their last disk or process worker is finished."""
+        pending.launch = replace(pending.launch, state="cleaning")
+        if cause and not pending.reported:
+            pending.reported = True
+            self.failed.emit(pending.launch, cause)
+        self.repository.cancel(pending.launch.request_id)
+        self.repository.context_by_session.pop(pending.launch.request_id, None)
+        threading.Thread(target=self._cleanup, args=(pending.launch,), daemon=True).start()
+
+    def _cleanup(self, launch: DifftoolLaunch) -> None:
+        """Keep filesystem deletion outside the event loop and report a safe cause on refusal."""
+        cause = ""
+        try:
+            self.temporary_store.cleanup(launch)
+        except (OSError, ValueError) as error:
+            cause = f"External comparison cleanup failed ({type(error).__name__})."
+        self._queue_event((launch.request_id, "cleaned", cause))
+
+    def _poll(self) -> None:
+        """Deliver worker progress and keep timed-out OS creations reserved until they return.
+
+        Worker events wake it through event_ready; the timer only adds the checks over time of the watched states.
+        """
+        while True:
+            try:
+                request_id, kind, value = self.event_queue.get_nowait()
+            except queue.Empty:
+                break
+            pending = self.active_by_id.get(request_id)
+            if pending is None:
+                continue
+            if kind == "prepared":
+                pending.launch = value
+                self._read_next(pending)
+            elif kind == "started":
+                pending.launch = replace(pending.launch, state="running")
+                self.started.emit(pending.launch)
+            elif kind == "error":
+                self._discard(pending, str(value))
+            elif kind == "exited":
+                # Like git difftool, the exit code of a comparison is not judged: there is no result to save, and KDiff3
+                # returns 1 whenever it is closed without saving a merge result.
+                return_code, run_duration_ms = value
+                pending.launch = replace(pending.launch, return_code=return_code, run_duration_ms=run_duration_ms)
+                self.tool_exited.emit(pending.launch)
+                self._discard(pending)
+            elif kind == "cleaned":
+                self.active_by_id.pop(request_id)
+                if value:
+                    self.failed.emit(pending.launch, str(value))
+                self.finished.emit(pending.launch)
+        for pending in tuple(self.active_by_id.values()):
+            if pending.launch.state == "reading" and not pending.is_current() and pending.read_identity is not None:
+                pending.cancelled = True
+                self.export.cancel_export(pending.read_identity)
+            if pending.launch.state == "starting" and not pending.reported and pending.deadline is not None and time.monotonic() >= pending.deadline:
+                pending.reported = True
+                self.failed.emit(pending.launch, "External comparison startup timed out. The system may still open it; wait before launching again.")
+        self._update_poll_timer()
+        if not self.active_by_id:
+            self.idle.emit()
+
+    def close(self) -> None:
+        """Cancel unlaunched reads while preserving supervision of active or starting tools."""
+        self.closed = True
+        for pending in tuple(self.active_by_id.values()):
+            if pending.launch.state in ("preparing", "reading"):
+                pending.cancelled = True
+                if pending.read_identity is not None:
+                    self.export.cancel_export(pending.read_identity)
+        if not self.active_by_id:
+            self.idle.emit()