gitpane 1.0.0__py3-none-any.whl

gitpane/history/repository_value.py

@@ -0,0 +1,341 @@
+"""Hold the values every reader of a repository shares, from its context to its commits."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+from gitpane.config import LOCAL_PREFIX, REMOTE_PREFIX, TAG_PREFIX
+
+if TYPE_CHECKING:
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+
+
+@dataclass(frozen=True)
+class RequestIdentity:
+    """Identify a window and its current read to reject superseded responses."""
+
+    session_id: str
+    generation: int = 0
+    selection_generation: int = 0
+    oid: str | None = None
+    search_generation: int = 0
+    relation_generation: int = 0
+
+
+class FilePanel(Enum):
+    """The place a read of one file or file list fills, which a new read of the same place replaces and a retry reads again.
+
+    Four are panels of a repository window: the diff, the file tree, the file content and the history of one file. The
+    last two are not panels but reads of their own: the files handed to an external comparison tool, and a file exported to disk.
+    """
+
+    DIFF = "diff"
+    TREE = "tree"
+    BLOB = "blob"
+    FILE_HISTORY = "file_history"
+    DIFFTOOL = "difftool"
+    EXPORT = "export"
+
+
+@dataclass(frozen=True)
+class FileReadIdentity:
+    """Keep a panel's comparison independent of the commit detail request."""
+
+    request_identity: RequestIdentity
+    panel_kind: FilePanel = FilePanel.DIFF
+    panel_generation: int = 0
+    parent_oid: str | None = None
+    old_path: bytes | None = None
+    new_path: bytes | None = None
+    full_context: bool = False
+
+
+class FileStatus(Enum):
+    """Change Git reports for one file, by the status letter it writes in raw diffs, name-status lists and status records."""
+
+    ADDED = "A"
+    """The file exists only on the new side, or is not tracked yet."""
+    BROKEN = "B"
+    """Git broke the pairing of a heavily rewritten file into a deletion and an addition."""
+    COPIED = "C"
+    """The file is a copy of another one."""
+    DELETED = "D"
+    """The file exists only on the old side."""
+    MODIFIED = "M"
+    """The content or the mode of the file changed."""
+    RENAMED = "R"
+    """The file moved from another path."""
+    TYPE_CHANGED = "T"
+    """The file changed type, between a regular file, a symbolic link and a submodule."""
+    UNMERGED = "U"
+    """The file is in conflict."""
+    UNKNOWN = "X"
+    """Git could not tell; it only writes this letter on an internal error."""
+
+
+# Git writes the status letter first, followed by the similarity score of a rename or a copy (R100, C075).
+STATUS_LETTER_LENGTH = 1
+
+
+def file_status(raw_status: str) -> FileStatus:
+    """Read the status Git wrote for a file by its letter, the similarity score of a rename or a copy left aside.
+
+    A letter Git does not document raises ValueError, like any other output that cannot be read.
+    """
+    return FileStatus(raw_status[:STATUS_LETTER_LENGTH])
+
+
+@dataclass(frozen=True)
+class RevisionEntry:
+    """Retain both sides of a historical change without consulting disk files."""
+
+    commit_oid: str
+    parent_oid: str | None
+    old_path: bytes | None
+    new_path: bytes | None
+    old_blob_oid: str | None
+    new_blob_oid: str | None
+    old_mode: str
+    new_mode: str
+    status: FileStatus
+
+
+@dataclass(frozen=True)
+class TreeEntry:
+    """Retain a revision's literal Git path and object identity without local paths."""
+
+    path: bytes
+    mode: str
+    object_type: str
+    oid: str
+
+
+@dataclass(frozen=True)
+class HistoricalFileSelection:
+    """Keep an immutable blob and its real historical side for file operations."""
+
+    commit_oid: str
+    parent_oid: str | None
+    path: bytes
+    blob_oid: str
+    mode: str
+    selection_identity: FileReadIdentity
+
+
+def historical_selection(entry: RevisionEntry | TreeEntry, identity: FileReadIdentity) -> HistoricalFileSelection:
+    """Choose the after side, or the selected parent's before side for a deletion."""
+    if isinstance(entry, TreeEntry):
+        if identity.request_identity.oid is None:
+            raise ValueError("No historical commit selected")
+        return HistoricalFileSelection(identity.request_identity.oid, None, entry.path, entry.oid, entry.mode, identity)
+    if entry.new_path is not None and entry.new_blob_oid is not None:
+        return HistoricalFileSelection(entry.commit_oid, entry.parent_oid, entry.new_path, entry.new_blob_oid, entry.new_mode, identity)
+    if entry.parent_oid is not None and entry.old_path is not None and entry.old_blob_oid is not None:
+        return HistoricalFileSelection(entry.commit_oid, entry.parent_oid, entry.old_path, entry.old_blob_oid, entry.old_mode, identity)
+    raise ValueError("The selected entry has no historical file")
+
+
+class BlobContentKind(Enum):
+    """What the preview of a file version holds, which decides how the reader shows it."""
+
+    TEXT = "text"
+    """Text decoded without error."""
+    EMPTY = "empty"
+    """A file of zero bytes."""
+    BINARY = "binary"
+    """Bytes with a NUL and no text byte order mark: not shown as text."""
+    ENCODING = "encoding"
+    """Text in an unknown or invalid encoding, shown with replacement characters."""
+
+
+@dataclass(frozen=True)
+class BlobContent:
+    """Keep original bytes separate from the reader's display representation."""
+
+    oid: str
+    raw_bytes: bytes
+    display_text: str
+    content_kind: BlobContentKind
+    complete: bool
+    size_bytes: int = 0
+    diagnostic: str = ""
+
+
+@dataclass(frozen=True)
+class ComparisonGroup:
+    """Associate each changed file with the real parent used for comparison."""
+
+    parent_oid: str | None
+    parent_short_oid: str
+    parent_subject: str
+    entries: list[RevisionEntry]
+
+    @property
+    def file_count(self) -> int:
+        """Count only the changes belonging to this parent comparison."""
+        return len(self.entries)
+
+
+@dataclass(frozen=True)
+class RepositoryContext:
+    """Describe Git-resolved repository locations including worktrees and bare repos."""
+
+    worktree_dir: str | None
+    git_dir: str
+    common_git_dir: str
+    is_bare: bool
+
+    @property
+    def repository_dir(self) -> str:
+        """Choose the actual repository directory even when no working tree exists."""
+        return self.worktree_dir or self.git_dir
+
+
+@dataclass(frozen=True)
+class Commit:
+    """Keep complete Git identity, ancestry and readable commit metadata together."""
+
+    oid: str
+    short_oid: str
+    parent_oids: list[str]
+    author_name: str
+    author_email: str
+    author_timestamp: int
+    committer_timestamp: int
+    encoding: str
+    message: str
+    detail_error: str | None = None
+    body_preview: str = ""
+    # Git accepts commits whose time is missing or beyond what a date can hold, as some old imported histories have;
+    # such a commit keeps its message and author, and only its dates read as unavailable.
+    time_unavailable: bool = False
+
+
+class ReferenceKind(Enum):
+    """Group of a displayed reference, in the order the history and the graph list them."""
+
+    HEAD = ("head", "", "HEAD")
+    HEADS = ("heads", LOCAL_PREFIX, "Local branches")
+    REMOTES = ("remotes", REMOTE_PREFIX, "Remote branches")
+    TAGS = ("tags", TAG_PREFIX, "Tags")
+
+    def __new__(cls, value: str, prefix: str, label: str) -> Self:
+        """Keep the group name as the value, with the namespace Git lists it under and the heading the window shows."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.prefix = prefix
+        member.label = label
+        return member
+
+    def __lt__(self, other: object) -> bool:
+        """Order kinds as they are declared: HEAD, local branches, remote branches, tags.
+
+        Sorting references on their kind keeps the order the group names had when they were plain text. Another type of
+        object is left to Python, which tries the other side of the comparison and refuses it when neither knows.
+        """
+        if not isinstance(other, ReferenceKind):
+            return NotImplemented
+        members = list(type(self))
+        return members.index(self) < members.index(other)
+
+
+@dataclass(frozen=True)
+class Reference:
+    """Keep a displayed reference and its peeled commit target, if one exists."""
+
+    full_name: str
+    kind: ReferenceKind
+    target_oid: str | None
+    symbolic_target: str | None = None
+    is_head: bool = False
+
+
+@dataclass(frozen=True)
+class CommitLink:
+    """Identify a direct relative with its Git abbreviation and full subject."""
+
+    oid: str
+    short_oid: str
+    subject: str
+    available: bool = True
+
+
+@dataclass(frozen=True)
+class CommitRelation:
+    """Separate incomplete child discovery from a proven absence of children."""
+
+    oid: str
+    parents: list[CommitLink]
+    child_links: list[CommitLink]
+    children_complete: bool
+
+
+@dataclass(frozen=True)
+class OpeningHeadRead:
+    """Remember the shallow flag and HEAD that one opening read, for the first history capture of that same request.
+
+    It is display data only and authorizes nothing. It belongs to one request of one window, with the Git and the
+    context it was read with, and is used at most once; any other opening, cancellation or closing drops it.
+    """
+
+    identity: RequestIdentity
+    context: RepositoryContext
+    git_filename: str
+    shallow: bool
+    head_oid: str | None
+    head_ref: str | None = None
+
+
+@dataclass
+class HistorySnapshot:
+    """Associate one stable reference capture with its progressively read ancestry."""
+
+    generation: int
+    references: list[Reference]
+    tip_oids: list[str]
+    head_oid: str | None
+    ordered_oids: list[str] = field(default_factory=list)
+    parent_oids_by_oid: dict[str, list[str]] = field(default_factory=dict)
+    child_oids_by_oid: dict[str, list[str]] = field(default_factory=dict)
+    complete: bool = False
+    shallow: bool = False
+    error: str | None = None
+    explicit_commits: list[Commit] = field(default_factory=list)
+    # The reference capture this history was built from, when one was shared with it; handed over to the window that
+    # finally shows this history so it does not list the same references again. Display data only.
+    reference_snapshot: ReferenceSnapshot | None = field(default=None, compare=False, repr=False)
+
+
+# A full Git object ID: 40 hexadecimal digits in a SHA-1 repository, 64 in a SHA-256 one.
+FULL_OID_PATTERN = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})")
+# Suffix that makes Git follow a revision to the commit it leads to, and fail when it leads to none.
+COMMIT_PEEL_SUFFIX = "^{commit}"
+
+
+def validate_oid(oid: str) -> str:
+    """Reject anything except a full Git object ID before using it as an argument."""
+    if FULL_OID_PATTERN.fullmatch(oid) is None:
+        raise ValueError("Invalid Git object ID")
+    return oid
+
+
+SUCCESS_EXIT_CODE = 0
+# Exit status of a cherry-pick, revert or rebase that stopped on a conflict. Any other failure status (128 for a fatal
+# error, a crash) is a real failure even when it left unmerged entries behind.
+GIT_CONFLICT_RETURN_CODE = 1
+
+
+@dataclass(frozen=True)
+class RepositoryFailure:
+    """Preserve the concrete command failure for useful error presentation."""
+
+    operation: str
+    repository_dir: str
+    program_filename: str
+    arguments: list[str]
+    cause: str
+    stderr: bytes = b""
+    return_code: int | None = None

gitpane/history/revision.py

@@ -0,0 +1,180 @@
+"""Answer questions about commits from the history graph already held in memory, without starting Git."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from gitpane.config import COMMAND_LINE_CONTROL_CHARACTER_SET, LOCAL_PREFIX, REFERENCE_ROOT_PREFIX, REMOTE_PREFIX, TAG_PREFIX
+from gitpane.history.repository_value import FULL_OID_PATTERN
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import Reference
+
+# Signs and equality text of the Git Extensions commit counter shown beside a revision field ("-13", "+2", "-3+2", "=").
+REMOVED_COMMIT_SIGN = "-"
+ADDED_COMMIT_SIGN = "+"
+SAME_COMMIT_TEXT = "="
+
+# Why a typed revision is refused before any Git process: Git would read a leading dash as an option, and a control
+# character cannot belong to a revision and could split what Git or the logs receive.
+EMPTY_REVISION_CAUSE = "Enter a revision"
+OPTION_REVISION_CAUSE = "A revision cannot start with '-'"
+CONTROL_CHARACTER_REVISION_CAUSE = "A revision cannot contain control characters"
+REVISION_OPTION_PREFIX = "-"
+HEAD_REVISION = "HEAD"
+# The symbolic reference a remote keeps for its default branch, which a bare remote name designates.
+REMOTE_DEFAULT_BRANCH_SUFFIX = "/HEAD"
+# Names Git first looks up as files beside HEAD in the repository directory (FETCH_HEAD, ORIG_HEAD, MERGE_HEAD...).
+# They are not in the reference listing, so such a name is always left to Git.
+ROOT_REFERENCE_NAME_PATTERN = re.compile(r"[A-Z_]+")
+
+
+def ancestor_oid_set(start_oid: str, parent_oids_by_oid: dict[str, list[str]]) -> set[str]:
+    """Return a commit and every ancestor reachable through the known parent links.
+
+    The walk is iterative so a long linear history cannot overflow Python's call stack; parents missing from the
+    mapping (a shallow boundary, or a graph still being read) simply end that branch of the walk.
+    """
+    visited_oid_set: set[str] = set()
+    pending_oids = [start_oid]
+    while pending_oids:
+        oid = pending_oids.pop()
+        if oid in visited_oid_set:
+            continue
+        visited_oid_set.add(oid)
+        pending_oids.extend(parent_oids_by_oid.get(oid, []))
+    return visited_oid_set
+
+
+def unmerged_branch_refs_in_memory(branch_oid_by_ref: dict[str, str], base_oid_by_ref: dict[str, str | None], parent_oids_by_oid: dict[str, list[str]],
+                                   graph_complete: bool) -> tuple[str, ...] | None:
+    """Tell which branches are not merged into their base, from the history already in memory, or None when it cannot tell.
+
+    A branch is merged when its commit is its base or one of the base's ancestors. A branch without a base is never
+    merged, as in Git. None means memory is not enough: the graph is still being read, or a base commit is not in it,
+    so the caller has to ask Git. The answer keeps the order of ``branch_oid_by_ref``. The ancestors of each distinct
+    base are walked once, however many branches share it.
+    """
+    if not graph_complete:
+        return None
+    ancestor_oid_set_by_base_oid: dict[str, set[str]] = {}
+    for base_oid in base_oid_by_ref.values():
+        if base_oid is None or base_oid in ancestor_oid_set_by_base_oid:
+            continue
+        if base_oid not in parent_oids_by_oid:
+            return None
+        ancestor_oid_set_by_base_oid[base_oid] = ancestor_oid_set(base_oid, parent_oids_by_oid)
+    unmerged_refs: list[str] = []
+    for full_ref, branch_oid in branch_oid_by_ref.items():
+        base_oid = base_oid_by_ref.get(full_ref)
+        if base_oid is None or branch_oid not in ancestor_oid_set_by_base_oid[base_oid]:
+            unmerged_refs.append(full_ref)
+    return tuple(unmerged_refs)
+
+
+def commit_difference_in_memory(target_oid: str, head_ancestor_oid_set: set[str] | None, parent_oids_by_oid: dict[str, list[str]]) -> tuple[int, int] | None:
+    """Count the commits only in HEAD and the commits only in the target, or None when memory cannot prove it.
+
+    The answer has the order of ``git rev-list --left-right --count HEAD...target``. None means the HEAD ancestry is
+    unknown (incomplete graph, or HEAD without a commit) or the target is not part of the loaded graph, so the caller
+    has to ask Git instead.
+    """
+    if head_ancestor_oid_set is None or target_oid not in parent_oids_by_oid:
+        return None
+    target_ancestor_oid_set = ancestor_oid_set(target_oid, parent_oids_by_oid)
+    return len(head_ancestor_oid_set - target_ancestor_oid_set), len(target_ancestor_oid_set - head_ancestor_oid_set)
+
+
+def commit_count_text(difference: tuple[int, int] | None) -> str:
+    """Write a commit's position relative to HEAD the way Git Extensions does: "-13", "+2", "-3+2", "=" or nothing.
+
+    The first count is the commits HEAD has that the target lacks (shown with a minus), the second the commits the
+    target adds (shown with a plus). An unknown difference, such as HEAD without any commit, shows no text.
+    """
+    if difference is None:
+        return ""
+    removed, added = difference
+    if removed == 0 and added == 0:
+        return SAME_COMMIT_TEXT
+    text = ""
+    if removed > 0:
+        text += REMOVED_COMMIT_SIGN + str(removed)
+    if added > 0:
+        text += ADDED_COMMIT_SIGN + str(added)
+    return text
+
+
+def revision_text_problem(text: str) -> str:
+    """Say why a typed revision cannot be handed to Git at all, or answer an empty text when it may be.
+
+    This only guards the command line: a text that passes still has to be resolved, in memory or by Git.
+    """
+    if not text:
+        return EMPTY_REVISION_CAUSE
+    if text.startswith(REVISION_OPTION_PREFIX):
+        return OPTION_REVISION_CAUSE
+    for character in text:
+        if character in COMMAND_LINE_CONTROL_CHARACTER_SET:
+            return CONTROL_CHARACTER_REVISION_CAUSE
+    return ""
+
+
+def reference_candidate_names(name: str) -> list[str]:
+    """List the full reference names Git tries for a short name, in Git's own order of preference.
+
+    The order is the one of the gitrevisions documentation: the name itself, then under refs/, refs/tags/,
+    refs/heads/, refs/remotes/, and finally the default branch of a remote with that name.
+    """
+    return [name, REFERENCE_ROOT_PREFIX + name, TAG_PREFIX + name, LOCAL_PREFIX + name, REMOTE_PREFIX + name,
+            REMOTE_PREFIX + name + REMOTE_DEFAULT_BRANCH_SUFFIX]
+
+
+def resolve_revision_in_memory(text: str, references: tuple[Reference, ...], head_oid: str | None, parent_oids_by_oid: dict[str, list[str]]) -> str | None:
+    """Resolve a typed revision to a full commit ID from what the window already holds, or None to ask Git.
+
+    Only answers Git would give the same way are taken: HEAD, a full commit ID already in the loaded graph, and a
+    reference name that exactly one reference matches under Git's lookup order. Everything else goes to Git: an
+    abbreviated ID (Git knows objects the window never loaded), a name several references match, a special name
+    kept beside HEAD, and any revision expression such as ``main~1`` or ``v1.0^2``.
+    """
+    if text == HEAD_REVISION:
+        return head_oid
+    if FULL_OID_PATTERN.fullmatch(text) is not None:
+        return text if text in parent_oids_by_oid else None
+    if ROOT_REFERENCE_NAME_PATTERN.fullmatch(text) is not None:
+        return None
+    reference_by_name: dict[str, Reference] = {}
+    for reference in references:
+        reference_by_name[reference.full_name] = reference
+    matched_references: list[Reference] = []
+    for candidate_name in reference_candidate_names(text):
+        reference = reference_by_name.get(candidate_name)
+        if reference is not None:
+            matched_references.append(reference)
+    if len(matched_references) != 1:
+        return None
+    return matched_references[0].target_oid
+
+
+
+def complete_ancestor_oid_set(oid: str, parent_oids_by_oid: dict[str, list[str]], graph_complete: bool) -> set[str] | None:
+    """Return a commit and all its ancestors from the graph in memory, or None when the graph cannot prove the whole set.
+
+    Only a completely read graph that holds the commit knows every one of its ancestors; a graph still being read, or
+    one that does not contain the commit, leaves the question to Git.
+    """
+    if not graph_complete or oid not in parent_oids_by_oid:
+        return None
+    return ancestor_oid_set(oid, parent_oids_by_oid)
+
+
+def is_ancestor_in_memory(ancestor_oid: str, descendant_ancestor_oid_set: set[str] | None) -> bool | None:
+    """Tell whether a commit is an ancestor of (or equal to) a descendant whose ancestry is known, or None when it is not known.
+
+    This answers ``git merge-base --is-ancestor`` from memory: ``descendant_ancestor_oid_set`` is the descendant and
+    all its ancestors, as ``complete_ancestor_oid_set`` returns it, and None sends the question to Git.
+    """
+    if descendant_ancestor_oid_set is None:
+        return None
+    return ancestor_oid in descendant_ancestor_oid_set