gitpane 1.0.0__py3-none-any.whl

gitpane/recent/recent_availability.py

@@ -0,0 +1,414 @@
+"""Find out in the background whether the recent repository folders can still be reached, without ever freezing a window.
+
+Asking Windows whether a folder exists can block for a long time: a hard disk that went to sleep takes up to a minute
+to spin up before answering yes, and a disconnected network drive or an unreachable server can take as long to answer
+no. So the question is never asked on the thread that draws the windows, and a slow answer is never taken for a no:
+only a real answer marks a folder unavailable, however late it comes. No question is ever abandoned or given a time
+limit here: an owner that stops waiting shows the folder as unknown and still takes its answer when it comes.
+
+Folders are grouped by what their answer waits on, each group asked in order on its own thread, so a sleeping disk or a
+dead server only delays the folders that live on it. On Windows a group is a drive letter or a network server. On Linux
+and macOS it is a mount point, a disk or a network server, read from the system's mount table on a sorting thread of
+its own, never on the thread that asks for the checks; a table that cannot be read keeps every folder in one group, as
+before. The links on a recent's path are followed on the thread of the group whose disk holds them, and a folder whose
+path leads into another mount is handed to that mount's group without reading anything there: a link to a dead share
+only holds its own folder. The threads are daemon threads: an answer still pending when GitPane quits never holds the
+exit, since a blocked question to the system cannot be cancelled.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+import threading
+from collections import deque
+from dataclasses import dataclass
+from functools import partial
+from typing import TYPE_CHECKING
+
+from gitpane.recent.mount_table import PLATFORM_MOUNT_TABLE_READER, PLATFORM_PATH_COMPARE_KEY, follow_folder_links, mount_group_key, without_double_slash_root
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from gitpane.recent.mount_table import FolderWalk, MountEntry
+
+WORKER_THREAD_NAME = "gitpane-recent-availability"
+# Start of a network path, \\server\share\...; os.path.normpath writes it with backslashes on Windows.
+NETWORK_PATH_PREFIX = "\\\\"
+# Start of a long network path, \\?\UNC\server\share\..., the same server as \\server\share\...; compared without case.
+EXTENDED_NETWORK_PATH_PREFIX = "\\\\?\\UNC\\"
+# Starts of long local paths, \\?\C:\... and \\.\C:\..., or of a volume path, \\?\Volume{...}\...: the next part is the drive.
+EXTENDED_PATH_PREFIXES = ("\\\\?\\", "\\\\.\\")
+# Windows codes Python raises as FileNotFoundError although they only say the path could not be read as written, not
+# that the folder is gone: ERROR_BAD_PATHNAME and ERROR_FILENAME_EXCED_RANGE, a path too long for the system settings.
+ERROR_BAD_PATHNAME = 161
+ERROR_FILENAME_EXCED_RANGE = 206
+UNREADABLE_PATH_WINDOWS_ERROR_SET = frozenset({ERROR_BAD_PATHNAME, ERROR_FILENAME_EXCED_RANGE})
+# Windows code Python raises as a plain OSError although it is a definite "absent": ERROR_NO_SUCH_DEVICE, given for a
+# removed USB drive whose letter Windows still lists, with no device behind it.
+ERROR_NO_SUCH_DEVICE = 433
+GONE_DEVICE_WINDOWS_ERROR_SET = frozenset({ERROR_NO_SUCH_DEVICE})
+# Start of every line the check writes to the --log file, so a reader can find them among the other records.
+UNANSWERED_LOG_PREFIX = "Recent folder check: "
+# Reserved key of the thread that reads the mount table and sorts the folders into their groups. It never meets a group
+# key: mount table keys carry a prefix ending in a colon, Windows keys are a drive letter or \\server. Kept among the
+# groups, the sorting thread starts, releases and is waited for exactly as a group worker is.
+SORTING_GROUP = "sorting"
+
+
+@dataclass(frozen=True)
+class PendingFolder:
+    """A recent folder waiting in its group's queue.
+
+    ``folder_dir`` is the recent as saved, which the question and the answer are about; ``walked_dir`` is its absolute
+    path with the links followed so far replaced by their targets, so a group handed the folder goes on from there.
+    """
+
+    folder_dir: str
+    walked_dir: str
+    followed_link_count: int
+
+
+def start_daemon_thread(target: Callable[[], None]) -> None:
+    """Run the target on a new daemon thread, which never holds the application's exit while blocked on a disk."""
+    threading.Thread(target=target, name=WORKER_THREAD_NAME, daemon=True).start()
+
+
+def ignore_log_line(_line: str) -> None:
+    """Drop a diagnostic line, for a check whose owner writes no log."""
+
+
+def ignore_unanswered(_folder_dir: str) -> None:
+    """Drop the report of a folder whose question got no answer, for a check whose owner does not show such folders."""
+
+
+def unanswered_after_wait_log_line(folder_dir: str, waited_seconds: float) -> str:
+    """Return the --log line the window writes when it stops waiting for a folder's answer and shows it as Unknown.
+
+    The question goes on: its real answer, present or absent, still replaces Unknown whenever it comes.
+    """
+    return (f"{UNANSWERED_LOG_PREFIX}no answer about {folder_dir} after {waited_seconds:g} s; it is shown as Unknown, not marked Unavailable, "
+            "and its answer is still taken when it comes.")
+
+
+def unanswered_log_line(folder_dir: str, error: Exception) -> str:
+    """Return the --log line that tells why a recent folder got no answer, so a reader knows why its row is not marked.
+
+    Only the folder, the error class, its system code and the system's own message are written: enough to tell a drive
+    that is not ready from a refused access or a network timeout.
+    """
+    if isinstance(error, OSError):
+        windows_code = getattr(error, "winerror", None)
+        code_text = f"Windows error {windows_code}" if windows_code is not None else f"errno {error.errno}"
+        cause = f"{type(error).__name__}, {code_text}: {error.strerror or error}"
+    else:
+        cause = f"{type(error).__name__}: {error}"
+    return f"{UNANSWERED_LOG_PREFIX}cannot tell whether {folder_dir} can be reached ({cause}); it is not marked Unavailable."
+
+
+def folder_is_reachable(folder_dir: str, stat_folder: Callable[[str], os.stat_result] = os.stat) -> bool:
+    """Tell whether the folder exists now; raise OSError when the system gives no definite answer. May block for long.
+
+    Only a definite "absent" is a no: the path is not found (``FileNotFoundError``, which Windows also gives for a network
+    server that is switched off or unreachable, a share that does not exist, and a drive letter that is gone, such as an
+    unplugged USB drive), the drive letter is still listed but no device is behind it (a removed USB drive Windows has
+    not released yet), a part of it is a file (``NotADirectoryError``), or it exists but is not a folder. Any other
+    failure, such as a drive that is not ready yet, a network timeout, a refused access, or a path the system refuses to
+    read as written (too long, or invalid) even though Python names it "not found", says nothing about the folder and is
+    raised for the caller to ignore. ``os.path.isdir`` cannot be used: it turns every one of those failures into False.
+    ``stat_folder`` lets tests answer without a disk.
+    """
+    try:
+        folder_status = stat_folder(folder_dir)
+    except (FileNotFoundError, NotADirectoryError) as error:
+        if getattr(error, "winerror", None) in UNREADABLE_PATH_WINDOWS_ERROR_SET:
+            raise
+        return False
+    except OSError as error:
+        if getattr(error, "winerror", None) in GONE_DEVICE_WINDOWS_ERROR_SET:
+            return False
+        raise
+    return stat.S_ISDIR(folder_status.st_mode)
+
+
+def folder_group(folder_dir: str) -> str:
+    """Return what the folder's answer waits on, compared without case as Windows does: its drive letter or its network server.
+
+    ``c:`` for a local or mapped drive, ``\\\\server`` for a network path: every share of one server is in the same group,
+    since a server that is off blocks all of them alike. Two drive letters mapped to one server stay two groups: telling
+    them apart would mean asking the network, the very thing that may block. Empty on systems without drives, where
+    every folder is in one group.
+
+    A long path written with the ``\\\\?\\`` or ``\\\\.\\`` prefix, which a recent may keep when Windows cannot shorten it,
+    is grouped as its short form: ``\\\\?\\C:\\...`` with ``c:``, ``\\\\?\\UNC\\server\\...`` with ``\\\\server``. Grouped under
+    the prefix alone, a local folder would wait behind a dead server.
+    """
+    normalized_dir = os.path.normpath(folder_dir)
+    if normalized_dir[:len(EXTENDED_NETWORK_PATH_PREFIX)].upper() == EXTENDED_NETWORK_PATH_PREFIX:
+        normalized_dir = NETWORK_PATH_PREFIX + normalized_dir[len(EXTENDED_NETWORK_PATH_PREFIX):]
+    else:
+        for prefix in EXTENDED_PATH_PREFIXES:
+            if normalized_dir.startswith(prefix):
+                device, _separator, _rest = normalized_dir.removeprefix(prefix).partition(os.sep)
+                return device.casefold()
+    drive, _rest = os.path.splitdrive(normalized_dir)
+    if not drive.startswith(NETWORK_PATH_PREFIX):
+        return drive.casefold()
+    server, _separator, _share = drive.removeprefix(NETWORK_PATH_PREFIX).partition(os.sep)
+    return (NETWORK_PATH_PREFIX + server).casefold()
+
+
+class RecentAvailabilityCheck:
+    """Ask on background threads whether each recent folder can be reached, once per folder, and report every real answer.
+
+    ``report`` is called on a worker thread with the folder and its answer; it only ever gets real answers, and is never
+    called once ``close`` has returned, so the owner can stop listening for good by closing the check. A folder whose
+    question fails without a real answer is neither confirmed nor marked unavailable: ``log_line`` first gets the line
+    that says why, then ``report_unanswered`` gets the folder, both on a worker thread and never after ``close``, so the
+    owner can show it as unknown. The owner hands both to its own thread before acting on them.
+
+    Every group with folders waiting gets its own worker at once, never a place in a queue behind other groups: a question
+    blocked on a sleeping disk or a dead server cannot be interrupted, so any limit on the workers would let a few
+    blocked groups hold back a local drive's answer. The groups are few, one per drive letter and per network server
+    among the recents, so the threads are too.
+
+    Where a mount table reader is given (Linux and macOS), the folders are first sorted into their groups on a sorting
+    thread, since reading the table may block (the ``mount`` command of macOS asks every mount point). Without one
+    (Windows), each folder is grouped at once by its drive letter or server. Before asking about a folder, its group's
+    thread follows the links of its path on that group's own disk; when they lead into a mount of another group, the
+    folder is handed over to that group without anything read there, so a link to a slow mount only holds its own folder.
+    """
+
+    def __init__(self, report: Callable[[str, bool], None], is_reachable: Callable[[str], bool] = folder_is_reachable,
+                 start_thread: Callable[[Callable[[], None]], None] = start_daemon_thread, log_line: Callable[[str], None] = ignore_log_line,
+                 read_mount_table: Callable[[], list[MountEntry]] | None = PLATFORM_MOUNT_TABLE_READER, read_link: Callable[[str], str] = os.readlink,
+                 report_unanswered: Callable[[str], None] = ignore_unanswered, path_compare_key: Callable[[str], str] = PLATFORM_PATH_COMPARE_KEY) -> None:
+        """Keep the receivers, the injected folder question, the thread starter, the mount table reader, the link reader and the path comparison.
+
+        Tests inject them to answer without a disk, fail a start, hold and fail the mount table read, give links without
+        a disk, or compare paths without case as macOS does. A mount table reader of None groups the folders by drive
+        letter and server, as on Windows, and no link is ever read then.
+        """
+        self.report = report
+        self.is_reachable = is_reachable
+        self.start_thread = start_thread
+        self.log_line = log_line
+        self.read_mount_table = read_mount_table
+        self.read_link = read_link
+        self.report_unanswered = report_unanswered
+        self.path_compare_key = path_compare_key
+        self.requested_dir_set: set[str] = set()
+        # Folders requested and not sorted into a group yet; only used with a mount table reader.
+        self.sorting_dirs: deque[str] = deque()
+        # The mount table read last by the sorting thread.
+        self.mount_entries: list[MountEntry] = []
+        self.waiting_folders_by_group: dict[str, deque[PendingFolder]] = {}
+        # Groups a worker is asking about right now: each group has at most one, so its folders are asked in order.
+        self.active_group_set: set[str] = set()
+        self.closed = False
+        # Guards every field above. It is also held while reporting, so close() waits for an answer being delivered; it
+        # is notified when a worker leaves, for whoever waits until the check is idle.
+        self.condition = threading.Condition()
+
+    def request(self, folder_dirs: list[str]) -> None:
+        """Queue the folders never asked about before, and start a worker for each group with folders waiting and no worker.
+
+        With a mount table reader, the new folders wait for the sorting thread instead, started here when it does not run:
+        the table is never read on the calling thread, the one that draws the windows.
+        """
+        started_groups: list[str] = []
+        with self.condition:
+            if self.closed:
+                return
+            for folder_dir in folder_dirs:
+                if folder_dir in self.requested_dir_set:
+                    continue
+                self.requested_dir_set.add(folder_dir)
+                if self.read_mount_table is None:
+                    self.waiting_folders_by_group.setdefault(folder_group(folder_dir), deque()).append(PendingFolder(folder_dir, folder_dir, 0))
+                else:
+                    self.sorting_dirs.append(folder_dir)
+            if self.sorting_dirs and SORTING_GROUP not in self.active_group_set:
+                started_groups.append(SORTING_GROUP)
+            for group, waiting_folders in self.waiting_folders_by_group.items():
+                if waiting_folders and group not in self.active_group_set:
+                    started_groups.append(group)
+            for group in started_groups:
+                self.active_group_set.add(group)
+        for group in started_groups:
+            self._start_worker(group)
+
+    def close(self) -> None:
+        """Drop the folders not asked about yet and stop every later report; a question already asked ends on its own."""
+        with self.condition:
+            self.closed = True
+            self.sorting_dirs.clear()
+            self.waiting_folders_by_group.clear()
+
+    def wait_until_idle(self, timeout_seconds: float) -> bool:
+        """Wait until no worker runs any more; False when one still does after the timeout. Blocks: never call it from a window."""
+        with self.condition:
+            return self.condition.wait_for(lambda: not self.active_group_set, timeout_seconds)
+
+    def _start_worker(self, group: str) -> None:
+        """Start the worker of a group already marked active, or the sorting thread, and release the group if the thread cannot start.
+
+        Its folders stay queued, or waiting to be sorted, and the next request tries again.
+        """
+        work = self._sort if group == SORTING_GROUP else self._work
+        try:
+            self.start_thread(partial(work, group))
+        except Exception:
+            logging.getLogger(__name__).exception("Cannot start a thread to check the recent folders")
+            self._release(group)
+
+    def _release(self, group: str) -> None:
+        """Mark a group as without a worker and wake whoever waits until the check is idle."""
+        with self.condition:
+            self.active_group_set.discard(group)
+            self.condition.notify_all()
+
+    def _sort(self, group: str) -> None:
+        """Read the mount table and sort the requested folders into their groups, on its own thread, while folders keep coming.
+
+        The table is read and the groups worked out without holding the condition, so a slow read never holds a request.
+        The thread leaves only while holding the condition, in the same step that finds nothing left to sort, exactly as
+        a group worker does, and releases its key on the way out should it end on an error.
+        """
+        left = False
+        try:
+            while True:
+                with self.condition:
+                    if self.closed or not self.sorting_dirs:
+                        self.active_group_set.discard(group)
+                        self.condition.notify_all()
+                        left = True
+                        return
+                    sorting_dirs = list(self.sorting_dirs)
+                    self.sorting_dirs.clear()
+                entries = self._read_mount_table()
+                sorted_folders: list[tuple[str, PendingFolder]] = []
+                for folder_dir in sorting_dirs:
+                    walked_dir = without_double_slash_root(os.path.normpath(os.path.abspath(folder_dir)))
+                    sorted_folders.append((self._folder_group(walked_dir, entries), PendingFolder(folder_dir, walked_dir, 0)))
+                started_groups: list[str] = []
+                with self.condition:
+                    if self.closed:
+                        continue
+                    self.mount_entries = entries
+                    for folder_group_key, pending in sorted_folders:
+                        self.waiting_folders_by_group.setdefault(folder_group_key, deque()).append(pending)
+                    for waiting_group, waiting_folders in self.waiting_folders_by_group.items():
+                        if waiting_folders and waiting_group not in self.active_group_set:
+                            started_groups.append(waiting_group)
+                    for started_group in started_groups:
+                        self.active_group_set.add(started_group)
+                for started_group in started_groups:
+                    self._start_worker(started_group)
+        finally:
+            if not left:
+                self._release(group)
+
+    def _read_mount_table(self) -> list[MountEntry]:
+        """Read the mount table with the injected reader; an unexpected failure is logged and gives an empty table, so one group."""
+        try:
+            return self.read_mount_table()
+        except Exception:
+            logging.getLogger(__name__).exception("Cannot read the mount table to group the recent folder checks")
+            return []
+
+    def _folder_group(self, walked_dir: str, entries: list[MountEntry]) -> str:
+        """Return the group of a folder from the mount table, or the single group of these systems when no mount holds it.
+
+        The path was made absolute and normalized without touching the disk, so it compares with the mount points, in the
+        way the platform compares names.
+        """
+        group = mount_group_key(walked_dir, entries, self.path_compare_key)
+        if group is None:
+            return folder_group(walked_dir)
+        return group
+
+    def _work(self, group: str) -> None:
+        """Ask about the folders of one group after the other, until none is waiting.
+
+        A worker leaves only while holding the condition, in the same step that finds nothing to do, so a folder requested at that
+        moment is either seen by this worker or gets a new one. A failing question or receiver only loses its own folder;
+        should the worker still end on an error, it releases its group on the way out, so the group's next request gets
+        a new worker instead of waiting on a thread that no longer runs.
+        """
+        left = False
+        try:
+            while True:
+                with self.condition:
+                    waiting_folders = self.waiting_folders_by_group.get(group)
+                    if self.closed or not waiting_folders:
+                        self.waiting_folders_by_group.pop(group, None)
+                        self.active_group_set.discard(group)
+                        self.condition.notify_all()
+                        left = True
+                        return
+                    pending = waiting_folders.popleft()
+                    entries = self.mount_entries
+                if entries:
+                    walk = follow_folder_links(pending.walked_dir, group, pending.followed_link_count, entries, self.read_link, self.path_compare_key)
+                    if walk.group != group:
+                        self._hand_over(pending.folder_dir, walk)
+                        continue
+                reachable = self._ask(pending.folder_dir)
+                if reachable is None:
+                    self._deliver(pending.folder_dir, partial(self.report_unanswered, pending.folder_dir))
+                else:
+                    self._report(pending.folder_dir, reachable)
+        finally:
+            if not left:
+                self._release(group)
+
+    def _hand_over(self, folder_dir: str, walk: FolderWalk) -> None:
+        """Pass a folder to the group of the mount its path leads to, without reading anything on that mount.
+
+        The folder joins that group's queue, after the ones already there, and the group gets a worker if it has none.
+        """
+        with self.condition:
+            if self.closed:
+                return
+            self.waiting_folders_by_group.setdefault(walk.group, deque()).append(PendingFolder(folder_dir, walk.walked_dir, walk.followed_link_count))
+            starts_worker = walk.group not in self.active_group_set
+            self.active_group_set.add(walk.group)
+        if starts_worker:
+            self._start_worker(walk.group)
+
+    def _ask(self, folder_dir: str) -> bool | None:
+        """Ask the injected question; a question that fails gives no answer, so the folder is neither confirmed nor marked.
+
+        The question itself decides what a definite "absent" is and answers False for it; anything it raises means the
+        system did not say, which must never become an Unavailable mark. The reason goes to the log line receiver; an
+        unexpected error is also logged in full, since it points at a bug rather than at the disk.
+        """
+        try:
+            return self.is_reachable(folder_dir)
+        except (OSError, ValueError) as error:
+            self._deliver(folder_dir, partial(self.log_line, unanswered_log_line(folder_dir, error)))
+            return None
+        except Exception as error:
+            logging.getLogger(__name__).exception("The check of the recent folder %s failed", folder_dir)
+            self._deliver(folder_dir, partial(self.log_line, unanswered_log_line(folder_dir, error)))
+            return None
+
+    def _report(self, folder_dir: str, reachable: bool) -> None:
+        """Hand one answer to the receiver unless the check is closed."""
+        self._deliver(folder_dir, partial(self.report, folder_dir, reachable))
+
+    def _deliver(self, folder_dir: str, deliver: Callable[[], None]) -> None:
+        """Run one delivery to the owner unless the check is closed; a receiver that fails loses that delivery, not the next ones.
+
+        The receiver can fail when the window it forwards to was deleted without being closed first.
+        """
+        with self.condition:
+            if self.closed:
+                return
+            try:
+                deliver()
+            except Exception:
+                logging.getLogger(__name__).exception("Cannot hand over the check of the recent folder %s", folder_dir)

gitpane/recent/recent_name.py

@@ -0,0 +1,11 @@
+"""Name a recent repository the way the recent lists show it."""
+
+from __future__ import annotations
+
+import os
+
+
+def repository_display_name(repository_dir: str) -> str:
+    """Return the folder name of a repository, or the whole path when it has none, as for the root of a drive."""
+    name = os.path.basename(os.path.normpath(repository_dir))
+    return name or repository_dir

gitpane/recent/recent_search.py

@@ -0,0 +1,114 @@
+"""Rank the recent repositories against a typed search, without ever looking at the disk.
+
+The search is fuzzy: the typed letters must appear in the folder name or the path in the same order, whatever their
+case, with gaps allowed. Matches are scored so that the most likely repository comes first.
+"""
+
+from __future__ import annotations
+
+from gitpane.recent.recent_name import repository_display_name
+
+# Every typed letter found in the text counts this much, so a match always scores above nothing.
+MATCH_SCORE = 1
+# A letter right after the previous one found counts more: "pane" in "pane" beats "pane" in "plane".
+CONSECUTIVE_BONUS = 4
+# A letter at the start of the text or of a word counts more: typing the initials of a name finds it.
+WORD_START_BONUS = 6
+# A match in the folder name beats the same match somewhere in the path: the name is what the user remembers.
+NAME_BONUS = 10
+# Characters after which a new word starts, in folder names and in Windows and Linux paths.
+WORD_SEPARATOR_SET = frozenset(" -_.\\/")
+
+
+def search_key(query: str) -> str:
+    """Return the typed search without any whitespace, folded for a case-insensitive comparison.
+
+    Removing a space only widens the results, and the rule that the letters appear in order still holds: "git pane"
+    finds "GitPane-Module".
+    """
+    return "".join(query.split()).casefold()
+
+
+def _letter_starts_word(folded_text: str, position: int) -> bool:
+    """Tell whether the letter at this position starts the text or follows a word separator."""
+    if position == 0:
+        return True
+    return folded_text[position - 1] in WORD_SEPARATOR_SET
+
+
+def _score_from_start(folded_query: str, folded_text: str, start: int) -> int | None:
+    """Score the query found in order from a given position of its first letter; None when a later letter is missing.
+
+    Each following letter is taken at its next occurrence.
+    """
+    score = MATCH_SCORE
+    if _letter_starts_word(folded_text, start):
+        score += WORD_START_BONUS
+    previous_position = start
+    for letter in folded_query[1:]:
+        position = folded_text.find(letter, previous_position + 1)
+        if position < 0:
+            return None
+        score += MATCH_SCORE
+        if position == previous_position + 1:
+            score += CONSECUTIVE_BONUS
+        if _letter_starts_word(folded_text, position):
+            score += WORD_START_BONUS
+        previous_position = position
+    return score
+
+
+def subsequence_score(query: str, text: str) -> int | None:
+    """Score how well the query letters appear in order in the text, ignoring case; None when they are not all there.
+
+    Every position of the first letter is tried as a start and the best score kept. The query is never turned into a
+    regular expression: whatever the user types is only letters to find, so no input can be slow or invalid.
+    """
+    folded_query = query.casefold()
+    if not folded_query:
+        return 0
+    folded_text = text.casefold()
+    best_score: int | None = None
+    start = folded_text.find(folded_query[0])
+    while start >= 0:
+        score = _score_from_start(folded_query, folded_text, start)
+        if score is None:
+            # A later start only leaves fewer letters to search in: if this one misses a letter, every later one does too.
+            break
+        if best_score is None or score > best_score:
+            best_score = score
+        start = folded_text.find(folded_query[0], start + 1)
+    return best_score
+
+
+def _recent_score(key: str, recent_dir: str) -> int | None:
+    """Return the best score of a recent: in its folder name, with the name bonus, or in its whole path; None if neither matches."""
+    best_score = None
+    name_score = subsequence_score(key, repository_display_name(recent_dir))
+    if name_score is not None:
+        best_score = name_score + NAME_BONUS
+    path_score = subsequence_score(key, recent_dir)
+    if path_score is not None and (best_score is None or path_score > best_score):
+        best_score = path_score
+    return best_score
+
+
+def ranked_recent_dirs(query: str, recent_dirs: list[str]) -> list[str]:
+    """Return the recents that match the search, best first; equal scores keep the history order.
+
+    An empty search, or one made of spaces, returns every recent in history order, as a new list.
+    """
+    key = search_key(query)
+    if not key:
+        return list(recent_dirs)
+    scored_recents: list[tuple[int, int, str]] = []
+    for index, recent_dir in enumerate(recent_dirs):
+        score = _recent_score(key, recent_dir)
+        if score is None:
+            continue
+        scored_recents.append((-score, index, recent_dir))
+    scored_recents.sort()
+    ranked_dirs: list[str] = []
+    for _negative_score, _index, recent_dir in scored_recents:
+        ranked_dirs.append(recent_dir)
+    return ranked_dirs