gitpane 1.0.0__py3-none-any.whl

gitpane/submodule/submodule_loss.py

@@ -0,0 +1,218 @@
+"""Check that nothing would be lost before a cherry-pick or revert replaces the folder of a submodule.
+
+Git, launched without descending into submodules, removes the whole folder of a submodule whose entry the replayed
+commit turns into a file, and writes the files of a folder or a link that takes its place. That is only safe when
+every file in the folder, nested submodules included, is already recorded in the submodule's own history, and when
+that history lives in the parent's Git folder rather than inside the folder about to go. Every check here only reads.
+"""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.config import GIT_PATH_SEPARATOR, SUBMODULE_LOSS_PATH_DISPLAY_LIMIT
+from gitpane.reference.reference_edit import GITLINK_MODE
+from gitpane.system.path_identity import canonical_path
+from gitpane.worktree.command_sequence import FileTask, GitCommand, ReadBatch
+from gitpane.worktree.worktree_snapshot import parse_index_listing
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from gitpane.history.repository_value import RepositoryContext
+
+GIT_ENTRY_BASENAME = ".git"
+# The folder, inside a repository's Git folder, where Git keeps the history of each of its absorbed submodules.
+SUBMODULE_GIT_DIRS_BASENAME = "modules"
+INDEX_ENTRY_SEPARATOR = b"\0"
+INDEX_PATH_SEPARATOR = b"\t"
+INDEX_FIELD_SEPARATOR = b" "
+INDEX_MODE_POSITION = 0
+# A porcelain v1 status record is two status letters, a space, then the path.
+STATUS_SEPARATOR_POSITION = 2
+STATUS_SEPARATOR = b" "
+STATUS_PATH_OFFSET = 3
+# The two lines rev-parse answers for the location of a submodule repository: its root, then its Git folder.
+LOCATION_FIELD_COUNT = 2
+LOCATION_ROOT_POSITION = 0
+LOCATION_GIT_DIR_POSITION = 1
+# Every file that would be lost is looked for until one more than the display limit is found, which is enough to say
+# that the list goes on.
+LOST_PATH_SEARCH_LIMIT = SUBMODULE_LOSS_PATH_DISPLAY_LIMIT + 1
+SUBMODULE_UNREADABLE_CAUSE = "Git gave back an unexpected answer about a submodule. Refresh before applying a commit."
+
+
+class SubmoduleFolder(Enum):
+    """What the folder recorded for a submodule holds on disk, read without following links."""
+
+    ABSENT = "absent"
+    EMPTY = "empty"
+    NOT_A_FOLDER = "not a folder"
+    UNRECORDED_FILES = "unrecorded files"
+    EMBEDDED_HISTORY = "embedded history"
+    REPOSITORY = "repository"
+
+
+def gitlink_paths(index_entries: bytes) -> list[bytes]:
+    """Name the submodule entries of NUL-framed `ls-files --stage` records, in the order Git lists them."""
+    paths = []
+    for record in index_entries.split(INDEX_ENTRY_SEPARATOR):
+        if not record:
+            continue
+        metadata, separator, path = record.partition(INDEX_PATH_SEPARATOR)
+        if not separator or not path:
+            raise ValueError(SUBMODULE_UNREADABLE_CAUSE)
+        if metadata.split(INDEX_FIELD_SEPARATOR)[INDEX_MODE_POSITION] == GITLINK_MODE:
+            paths.append(path)
+    return paths
+
+
+def submodule_git_dirs(context: RepositoryContext) -> tuple[str, str]:
+    """Name the folders where Git keeps the history of the absorbed submodules of a worktree: its own Git folder's, then the common one's."""
+    return os.path.join(context.git_dir, SUBMODULE_GIT_DIRS_BASENAME), os.path.join(context.common_git_dir, SUBMODULE_GIT_DIRS_BASENAME)
+
+
+def join_git_path(parent_path: str, child_path: str) -> str:
+    """Join two repository paths with Git's own separator, whatever the system's."""
+    return parent_path + GIT_PATH_SEPARATOR + child_path
+
+
+def inspect_submodule_folder(directory: str) -> tuple[SubmoduleFolder, list[str]]:
+    """Say what the folder of a submodule holds, without following links, and name the first files of a folder that holds no repository.
+
+    A folder with no ".git" entry holds nothing any history records, so each of its files (up to one more than the
+    display limit, as paths relative to the folder with Git's separator) would be lost with it. Empty sub-folders
+    lose nothing.
+    """
+    if not os.path.lexists(directory):
+        return SubmoduleFolder.ABSENT, []
+    if os.path.islink(directory) or os.path.isjunction(directory) or not os.path.isdir(directory):
+        return SubmoduleFolder.NOT_A_FOLDER, []
+    git_entry_filename = os.path.join(directory, GIT_ENTRY_BASENAME)
+    if os.path.lexists(git_entry_filename):
+        if os.path.isfile(git_entry_filename) and not os.path.islink(git_entry_filename):
+            return SubmoduleFolder.REPOSITORY, []
+        return SubmoduleFolder.EMBEDDED_HISTORY, []
+    found_paths: list[str] = []
+    pending_dirs = [directory]
+    while pending_dirs and len(found_paths) < LOST_PATH_SEARCH_LIMIT:
+        current_dir = pending_dirs.pop()
+        with os.scandir(current_dir) as entries:
+            for entry in entries:
+                if entry.is_dir(follow_symlinks=False) and not entry.is_junction():
+                    pending_dirs.append(entry.path)
+                    continue
+                found_paths.append(os.path.relpath(entry.path, directory).replace(os.sep, GIT_PATH_SEPARATOR))
+                if len(found_paths) >= LOST_PATH_SEARCH_LIMIT:
+                    break
+    if not found_paths:
+        return SubmoduleFolder.EMPTY, []
+    return SubmoduleFolder.UNRECORDED_FILES, sorted(found_paths)
+
+
+def is_repository_of(directory: str, root_dir: str, git_dir: str, modules_dirs: tuple[str, ...]) -> tuple[bool, bool]:
+    """Tell whether Git found the folder's own repository rather than an enclosing one, then whether its history lives in the parent's Git folder."""
+    own_root = canonical_path(root_dir) == canonical_path(directory)
+    canonical_git_dir = canonical_path(git_dir)
+    absorbed = False
+    for modules_dir in modules_dirs:
+        if canonical_git_dir.startswith(canonical_path(modules_dir) + os.sep):
+            absorbed = True
+    return own_root, absorbed
+
+
+def status_paths(output: bytes) -> list[bytes]:
+    """Name every path of a NUL-framed porcelain v1 status listed without rename detection, in Git's order."""
+    paths = []
+    for record in output.split(INDEX_ENTRY_SEPARATOR):
+        if not record:
+            continue
+        if record[STATUS_SEPARATOR_POSITION:STATUS_PATH_OFFSET] != STATUS_SEPARATOR or len(record) <= STATUS_PATH_OFFSET:
+            raise ValueError(SUBMODULE_UNREADABLE_CAUSE)
+        paths.append(record[STATUS_PATH_OFFSET:])
+    return paths
+
+
+def existing_paths(directory: str, paths: list[bytes]) -> list[bytes]:
+    """Keep the paths, relative to a folder, that name something on disk."""
+    present_paths = []
+    for path in paths:
+        if os.path.lexists(os.path.join(directory, *os.fsdecode(path).split(GIT_PATH_SEPARATOR))):
+            present_paths.append(path)
+    return present_paths
+
+
+def submodule_loss_text(submodule_path: str, lost_paths: list[str]) -> str:
+    """Describe a refused replay that would lose files of a submodule, naming the submodule and the first of those files."""
+    shown_paths = lost_paths[:SUBMODULE_LOSS_PATH_DISPLAY_LIMIT]
+    text = f'The selected commit replaces the submodule "{submodule_path}", and these files in it would be lost: ' + ", ".join(shown_paths)
+    if len(lost_paths) > SUBMODULE_LOSS_PATH_DISPLAY_LIMIT:
+        text += ", and more"
+    return text + ". Commit, move or delete them first. It was not applied."
+
+
+def submodule_history_loss_text(submodule_path: str, repository_path: str) -> str:
+    """Describe a refused replay that would delete a Git history kept inside the folder of a submodule."""
+    return (f'The selected commit replaces the submodule "{submodule_path}", but the Git history of "{repository_path}" is kept inside that folder and '
+            'would be lost. Run "git submodule absorbgitdirs" in the parent repository first. It was not applied.')
+
+
+def submodule_loss_refusal(context: RepositoryContext, submodule_path: bytes) -> Generator:
+    """Answer why replacing the folder of one submodule of this worktree would lose something, or "" when nothing would be lost.
+
+    The folder and every populated submodule nested in it are checked one repository at a time, without Git
+    descending on its own: an absent or empty folder loses nothing; a link, a file, or files without a repository
+    would be lost; a history kept inside the folder would be lost; otherwise every changed, staged, untracked or
+    ignored file is lost, and so is any file whose changes Git was told to hide. A malformed answer raises ValueError.
+    """
+    display_path = os.fsdecode(submodule_path)
+    modules_dirs = submodule_git_dirs(context)
+    lost_paths: list[str] = []
+    pending_paths = [display_path]
+    while pending_paths and len(lost_paths) < LOST_PATH_SEARCH_LIMIT:
+        repository_path = pending_paths.pop(0)
+        directory = os.path.join(context.worktree_dir, *repository_path.split(GIT_PATH_SEPARATOR))
+        folder, found_paths = yield FileTask(lambda directory=directory: inspect_submodule_folder(directory))
+        if folder in (SubmoduleFolder.ABSENT, SubmoduleFolder.EMPTY):
+            continue
+        if folder == SubmoduleFolder.NOT_A_FOLDER:
+            lost_paths.append(repository_path)
+            continue
+        if folder == SubmoduleFolder.UNRECORDED_FILES:
+            for found_path in found_paths:
+                lost_paths.append(join_git_path(repository_path, found_path))
+            continue
+        if folder == SubmoduleFolder.EMBEDDED_HISTORY:
+            return submodule_history_loss_text(display_path, repository_path)
+        location = yield GitCommand(["-C", directory, "rev-parse", "--show-toplevel", "--absolute-git-dir"])
+        fields = os.fsdecode(location.removesuffix(b"\n")).split("\n")
+        if len(fields) != LOCATION_FIELD_COUNT:
+            raise ValueError(SUBMODULE_UNREADABLE_CAUSE)
+        own_root, absorbed = yield FileTask(lambda directory=directory, fields=fields: is_repository_of(directory, fields[LOCATION_ROOT_POSITION],
+                                                                                                        fields[LOCATION_GIT_DIR_POSITION], modules_dirs))
+        if not own_root:
+            raise ValueError(SUBMODULE_UNREADABLE_CAUSE)
+        if not absorbed:
+            return submodule_history_loss_text(display_path, repository_path)
+        # Git's own nested submodule check is turned on whatever the configuration says, so a nested submodule with
+        # local work shows up here too; its files are then listed by its own check.
+        status_output, index_output = yield ReadBatch((
+            GitCommand(["-C", directory, "status", "--porcelain=v1", "-z", "--no-renames", "--ignored", "--untracked-files=all", "--ignore-submodules=none"]),
+            GitCommand(["-C", directory, "ls-files", "--stage", "-v", "-z"]),
+        ))
+        listing = parse_index_listing(index_output)
+        nested_paths = gitlink_paths(listing.index_entries)
+        nested_path_set = set(nested_paths)
+        for path in status_paths(status_output):
+            if path not in nested_path_set:
+                lost_paths.append(join_git_path(repository_path, os.fsdecode(path)))
+        hidden_paths = yield FileTask(lambda directory=directory, listing=listing: existing_paths(directory, list(listing.hidden_index_paths)))
+        for path in hidden_paths:
+            lost_paths.append(join_git_path(repository_path, os.fsdecode(path)))
+        for nested_path in nested_paths:
+            pending_paths.append(join_git_path(repository_path, os.fsdecode(nested_path)))
+    if not lost_paths:
+        return ""
+    return submodule_loss_text(display_path, lost_paths)

gitpane/system/appearance_portal.py

@@ -0,0 +1,125 @@
+"""Read the light or dark preference the desktop's Settings portal declares, at start or when it changes.
+
+The freedesktop Settings portal publishes the preference the user picked in the desktop's settings as the
+``color-scheme`` key of the ``org.freedesktop.appearance`` namespace: 0 for no preference, 1 for dark, 2 for light,
+and any other value counts as no preference. Qt reads that portal too, but asynchronously, so GitPane reads it itself
+once, blocking and bounded, before its first window. Every failure of that read (no bus, no portal, an error, no answer
+in time, a value of another type) gives no preference, which keeps what Qt shows without it.
+
+The connection is received from the caller, so the tests read a private bus and never reach the user's session bus.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import SLOT, QObject, Signal, Slot
+from PySide6.QtDBus import QDBus, QDBusConnection, QDBusMessage, QDBusVariant
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+PORTAL_SERVICE_NAME = "org.freedesktop.portal.Desktop"
+PORTAL_OBJECT_PATH = "/org/freedesktop/portal/desktop"
+PORTAL_SETTINGS_INTERFACE = "org.freedesktop.portal.Settings"
+APPEARANCE_NAMESPACE = "org.freedesktop.appearance"
+COLOR_SCHEME_KEY = "color-scheme"
+READ_ONE_METHOD = "ReadOne"
+SETTING_CHANGED_SIGNAL = "SettingChanged"
+# A ReadOne reply carries exactly one value.
+READ_ONE_REPLY_ARGUMENT_COUNT = 1
+READ_ONE_REPLY_VALUE_INDEX = 0
+# ReadOne wraps the value in one variant; the older Read method, which a portal without ReadOne still answers, wraps it in two.
+MAXIMUM_VARIANT_LAYER_COUNT = 2
+# SettingChanged carries the namespace, the key, then the value in a variant.
+SETTING_CHANGED_ARGUMENT_COUNT = 3
+SETTING_CHANGED_NAMESPACE_INDEX = 0
+SETTING_CHANGED_KEY_INDEX = 1
+SETTING_CHANGED_VALUE_INDEX = 2
+
+
+class PortalColorScheme(Enum):
+    """The light or dark preference the Settings portal declares, with the value the portal sends for each."""
+
+    NO_PREFERENCE = 0
+    PREFER_DARK = 1
+    PREFER_LIGHT = 2
+
+    @property
+    def prefers_dark(self) -> bool:
+        """Tell whether the desktop asks applications for their dark appearance."""
+        return self == PortalColorScheme.PREFER_DARK
+
+
+def portal_color_scheme(value: object) -> PortalColorScheme:
+    """Turn a value read from the portal into a preference, unwrapping its variants first.
+
+    Only a whole number names a preference: a boolean or a text is not one, even when it would compare equal to one.
+    The specification says that an unknown value means no preference, and so does anything that is not a number.
+    """
+    for _layer in range(MAXIMUM_VARIANT_LAYER_COUNT):
+        if type(value) is not QDBusVariant:
+            break
+        value = value.variant()
+    if type(value) is not int:
+        return PortalColorScheme.NO_PREFERENCE
+    try:
+        return PortalColorScheme(value)
+    except ValueError:
+        return PortalColorScheme.NO_PREFERENCE
+
+
+def read_portal_color_scheme(connection: QDBusConnection, timeout_ms: int) -> PortalColorScheme:
+    """Ask the portal on ``connection`` for the colour scheme and wait at most ``timeout_ms`` for its answer.
+
+    The call blocks, so the preference is known before the first window is shown, when Qt's own asynchronous read has
+    not answered yet. A closed connection, an error reply (no portal, a portal without that key, no answer in time) or a
+    reply of another shape gives no preference.
+    """
+    if not connection.isConnected():
+        return PortalColorScheme.NO_PREFERENCE
+    message = QDBusMessage.createMethodCall(PORTAL_SERVICE_NAME, PORTAL_OBJECT_PATH, PORTAL_SETTINGS_INTERFACE, READ_ONE_METHOD)
+    message.setArguments([APPEARANCE_NAMESPACE, COLOR_SCHEME_KEY])
+    # D-Bus activation is left allowed, unlike the keyring read: Qt's own theme already starts the portal when the
+    # application starts, and the portal holds no secret, so starting it changes nothing the user would not expect.
+    reply = connection.call(message, QDBus.CallMode.Block, timeout_ms)
+    if reply.type() != QDBusMessage.MessageType.ReplyMessage:
+        return PortalColorScheme.NO_PREFERENCE
+    values = reply.arguments()
+    if len(values) != READ_ONE_REPLY_ARGUMENT_COUNT:
+        return PortalColorScheme.NO_PREFERENCE
+    return portal_color_scheme(values[READ_ONE_REPLY_VALUE_INDEX])
+
+
+class PortalColorSchemeWatcher(QObject):
+    """Report each change of the colour scheme the portal signals, as a ``PortalColorScheme``.
+
+    The portal signals every setting it publishes through the one ``SettingChanged`` signal; only the colour scheme of
+    the appearance namespace is reported. The change is reported inside the D-Bus delivery itself, with no timer, so a
+    receiver acts on it before Qt's own listeners of the same signal, which were subscribed earlier, rebuild anything.
+    ``connected`` says whether the subscription was made: when it is false, no change will ever be reported.
+    """
+
+    changed = Signal(object)
+
+    def __init__(self, connect: Callable[[], QDBusConnection], parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self.connection = connect()
+        self.connected = False
+        if not self.connection.isConnected():
+            return
+        # PySide6 6.11 drops the first character of a slot signature given as a bare text ("etting_changed(QDBusMessage)"),
+        # and the subscription fails; written through SLOT(), the signature reaches QtDBus whole.
+        self.connected = self.connection.connect(PORTAL_SERVICE_NAME, PORTAL_OBJECT_PATH, PORTAL_SETTINGS_INTERFACE, SETTING_CHANGED_SIGNAL, self,
+                                                 SLOT("setting_changed(QDBusMessage)"))
+
+    @Slot(QDBusMessage)
+    def setting_changed(self, message: QDBusMessage) -> None:
+        """Report the new colour scheme when the signalled setting is the appearance namespace's colour scheme, and ignore any other."""
+        arguments = message.arguments()
+        if len(arguments) != SETTING_CHANGED_ARGUMENT_COUNT:
+            return
+        if arguments[SETTING_CHANGED_NAMESPACE_INDEX] != APPEARANCE_NAMESPACE or arguments[SETTING_CHANGED_KEY_INDEX] != COLOR_SCHEME_KEY:
+            return
+        self.changed.emit(portal_color_scheme(arguments[SETTING_CHANGED_VALUE_INDEX]))

gitpane/system/application_identity.py

@@ -0,0 +1,48 @@
+"""Give GitPane its own identity in the Windows taskbar."""
+
+from __future__ import annotations
+
+import ctypes
+import logging
+import sys
+from typing import TYPE_CHECKING
+
+from gitpane.config import APPLICATION_USER_MODEL_ID, WINDOWS_PLATFORM
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# S_OK: the shell accepted the identifier; any other result is a refusal.
+SUCCESS_RESULT = 0
+# Shows a negative result as the unsigned hexadecimal code Microsoft documents, such as 0x80070057.
+RESULT_CODE_MASK = 0xFFFFFFFF
+
+
+def _shell_identity_setter() -> Callable[[str], int]:
+    """Load the Windows shell call that names the running process, typed so the identifier is passed as a wide string."""
+    shell = ctypes.WinDLL("shell32")
+    setter = shell.SetCurrentProcessExplicitAppUserModelID
+    setter.argtypes = [ctypes.c_wchar_p]
+    setter.restype = ctypes.c_int32
+    return setter
+
+
+def declare_application_identity(set_identity: Callable[[str], int] | None = None, platform: str = sys.platform) -> bool:
+    """Tell Windows that this process is GitPane, and return whether the shell accepted it.
+
+    Without it the taskbar groups GitPane under the Python interpreter and shows the Python icon. Windows only takes the
+    identifier into account when it is set before the process shows any window, so this runs before the Qt application
+    exists. A refusal only costs the taskbar icon: it is logged and start-up goes on. Other systems have no such call.
+    """
+    if platform != WINDOWS_PLATFORM:
+        return False
+    try:
+        setter = set_identity if set_identity is not None else _shell_identity_setter()
+        result = setter(APPLICATION_USER_MODEL_ID)
+    except (AttributeError, OSError) as error:
+        logging.getLogger(__name__).warning("Cannot declare the Windows application identity; the taskbar may show the Python icon: %s", error)
+        return False
+    if result != SUCCESS_RESULT:
+        logging.getLogger(__name__).warning("Windows refused the application identity (result %#x); the taskbar may show the Python icon", result & RESULT_CODE_MASK)
+        return False
+    return True

gitpane/system/command_line.py

@@ -0,0 +1,36 @@
+"""Describe the command-line options of the gitpane command.
+
+The parser answers --version and --help, and refuses an unknown option, before any Qt object exists, so these answers
+reach the terminal even when GitPane would later leave it.
+"""
+
+from __future__ import annotations
+
+import argparse
+from enum import Enum
+
+from gitpane.config import APPLICATION_VERSION_LINE
+
+ATTACH_OPTION = "--attach"
+LOG_OPTION = "--log"
+VERSION_OPTION = "--version"
+
+
+class CommandLineText(Enum):
+    """Texts the gitpane command shows in its help, one member per text so a misspelt name is an error."""
+
+    DESCRIPTION = "GitPane — browse a Git repository"
+    """The line under the usage of --help."""
+    LOG_HELP = "Write a diagnostic log with one line per Git process"
+    """The help of the --log option."""
+    ATTACH_HELP = "Stay attached to the terminal: GitPane's output and errors are shown there, and Ctrl+C stops GitPane"
+    """The help of the --attach option."""
+
+
+def command_line_parser() -> argparse.ArgumentParser:
+    """Build the parser of the gitpane command, which answers --version with the application's name and version and exits."""
+    parser = argparse.ArgumentParser(description=CommandLineText.DESCRIPTION.value)
+    parser.add_argument(LOG_OPTION, action="store_true", help=CommandLineText.LOG_HELP.value)
+    parser.add_argument(ATTACH_OPTION, action="store_true", help=CommandLineText.ATTACH_HELP.value)
+    parser.add_argument(VERSION_OPTION, action="version", version=APPLICATION_VERSION_LINE)
+    return parser

gitpane/system/desktop_icon_fact.py

@@ -0,0 +1,128 @@
+"""Read from the running session the facts the desktop icon decision needs, off the window's thread.
+
+The state of a GNOME Shell extension is read through ``gnome-extensions list``, which names the extensions the Shell
+knows, and ``gnome-extensions list --active``, which names those it really runs, each bounded by a delay of
+``config.py``; an extension the Shell does not know yet but whose ``metadata.json`` lies in an XDG data folder was
+installed during the session. A read with no answer in time, a missing tool or a refusal leave the state unknown,
+which gives no note rather than a wrong one. The program, the files and os-release are all received as parameters,
+so a test never reaches the real session.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from platform import freedesktop_os_release
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QStandardPaths
+
+from gitpane.config import LINUX_PLATFORM, MILLISECONDS_PER_SECOND, SHELL_EXTENSION_READ_TIMEOUT_MS
+from gitpane.system.desktop_icon_support import GNOME_EXTENSIONS_PROGRAM, DesktopIconFacts, ExtensionState, desktop_icon_rule
+from gitpane.system.desktop_shortcut import named_desktop_dir
+from gitpane.system.linux_distribution import read_os_release_or_nothing
+from gitpane.system.qt_folder import native_folder_path
+from gitpane.system.xdg_session import desktop_names, xdg_data_dirs, xdg_data_home
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+    ExtensionRun = Callable[..., subprocess.CompletedProcess[bytes]]
+
+GNOME_EXTENSIONS_LIST_ARGUMENT = "list"
+GNOME_EXTENSIONS_ACTIVE_OPTION = "--active"
+SHELL_EXTENSION_DIR_PARTS = ("gnome-shell", "extensions")
+EXTENSION_METADATA_BASENAME = "metadata.json"
+GNOME_EXTENSIONS_OUTPUT_ENCODING = "utf-8"
+MOST_SPECIFIC_DESKTOP_NAME_INDEX = 0
+
+
+def shell_extension_read_timeout_seconds() -> float:
+    """Return the bound of one gnome-extensions read, in the seconds ``subprocess`` counts in."""
+    return SHELL_EXTENSION_READ_TIMEOUT_MS / MILLISECONDS_PER_SECOND
+
+
+def listed_extension_uuid_set(run: ExtensionRun, options: Sequence[str], timeout_seconds: float) -> frozenset[str] | None:
+    """Return the extension identifiers ``gnome-extensions list`` names with ``options``, one per line, or None when it cannot answer in time.
+
+    The tool runs without a shell and reads no input; a missing tool, a delay passed or a non-zero exit code all give
+    None. Its output is only compared with identifiers of GitPane's own table, never shown or run.
+    """
+    try:
+        completed = run([GNOME_EXTENSIONS_PROGRAM, GNOME_EXTENSIONS_LIST_ARGUMENT, *options], shell=False, stdin=subprocess.DEVNULL, capture_output=True, check=False,
+                        timeout=timeout_seconds)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0:
+        return None
+    uuid_set = set()
+    for line in completed.stdout.decode(GNOME_EXTENSIONS_OUTPUT_ENCODING, errors="replace").splitlines():
+        uuid = line.strip()
+        if uuid:
+            uuid_set.add(uuid)
+    return frozenset(uuid_set)
+
+
+def extension_on_disk(extension_uuid: str, environment_by_name: Mapping[str, str], home_dir: str, is_file: Callable[[str], bool]) -> bool:
+    """Tell whether the extension's ``metadata.json`` lies in the user's XDG data folder or in one of the system's."""
+    for data_dir in (xdg_data_home(environment_by_name, home_dir), *xdg_data_dirs(environment_by_name)):
+        if is_file(os.path.join(data_dir, *SHELL_EXTENSION_DIR_PARTS, extension_uuid, EXTENSION_METADATA_BASENAME)):
+            return True
+    return False
+
+
+def read_extension_state(extension_uuid: str, environment_by_name: Mapping[str, str], home_dir: str, run: ExtensionRun = subprocess.run,
+                         is_file: Callable[[str], bool] = os.path.isfile) -> ExtensionState:
+    """Read what the running GNOME Shell knows of an extension: active, known but not running, on the disk only, or missing.
+
+    Runs gnome-extensions twice, so it belongs on a worker thread only. Either read without an answer gives UNKNOWN.
+    """
+    timeout_seconds = shell_extension_read_timeout_seconds()
+    known_uuid_set = listed_extension_uuid_set(run, (), timeout_seconds)
+    if known_uuid_set is None:
+        return ExtensionState.UNKNOWN
+    active_uuid_set = listed_extension_uuid_set(run, (GNOME_EXTENSIONS_ACTIVE_OPTION,), timeout_seconds)
+    if active_uuid_set is None:
+        return ExtensionState.UNKNOWN
+    if extension_uuid in active_uuid_set:
+        return ExtensionState.ACTIVE
+    if extension_uuid in known_uuid_set:
+        return ExtensionState.INACTIVE
+    if extension_on_disk(extension_uuid, environment_by_name, home_dir, is_file):
+        return ExtensionState.INSTALLED_NOT_LOADED
+    return ExtensionState.NOT_INSTALLED
+
+
+def read_desktop_icon_facts(platform: str, environment_by_name: Mapping[str, str], home_dir: str, desktop_dir: str, run: ExtensionRun = subprocess.run,
+                            is_file: Callable[[str], bool] = os.path.isfile, is_dir: Callable[[str], bool] = os.path.isdir,
+                            read_os_release: Callable[[], Mapping[str, str]] = freedesktop_os_release) -> DesktopIconFacts:
+    """Read the facts the desktop icon decision judges for ``platform``, the session ``environment_by_name`` and ``desktop_dir``.
+
+    The desktop and os-release are only read on Linux, and the extension state only for a desktop that has a row in
+    the desktop table: any other desktop or system starts no program and keeps the state unknown. A desktop folder
+    that is ``home_dir`` itself reads as no desktop folder, by the same rule the shortcut writer follows, so the note
+    says the system names none.
+    """
+    desktop_dir = named_desktop_dir(desktop_dir, home_dir)
+    desktop_name = ""
+    os_release_by_key: dict[str, str] = {}
+    extension_state = ExtensionState.UNKNOWN
+    if platform == LINUX_PLATFORM:
+        names = desktop_names(environment_by_name)
+        desktop_name = names[MOST_SPECIFIC_DESKTOP_NAME_INDEX] if names else ""
+        os_release_by_key = read_os_release_or_nothing(read_os_release)
+        rule = desktop_icon_rule(platform, desktop_name)
+        if rule is not None:
+            extension_state = read_extension_state(rule.extension_uuid, environment_by_name, home_dir, run, is_file)
+    return DesktopIconFacts(platform, desktop_name, os_release_by_key, extension_state, desktop_dir, bool(desktop_dir) and is_dir(desktop_dir))
+
+
+def read_session_desktop_icon_facts() -> DesktopIconFacts:
+    """Read the facts of the running session, with the desktop folder Qt names for the system, written with the system's own separator.
+
+    Starts gnome-extensions on GNOME, so it runs only on a worker thread; Qt only reads the system's folder settings
+    there.
+    """
+    desktop_dir = native_folder_path(QStandardPaths.writableLocation(QStandardPaths.StandardLocation.DesktopLocation), sys.platform)
+    return read_desktop_icon_facts(sys.platform, dict(os.environ), os.path.expanduser("~"), desktop_dir)