gitpane 1.0.0__py3-none-any.whl

gitpane/reference/reference_snapshot.py

@@ -0,0 +1,196 @@
+"""Parse a for-each-ref listing into one frozen reference snapshot, without starting Git.
+
+The listing itself is read by ``ReferenceService`` of ``gitpane.reference.reference_edit``, with the format and the
+parser defined here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from dataclasses import field as dataclass_field
+from typing import TYPE_CHECKING
+
+from gitpane.config import LOCAL_PREFIX, REMOTE_PREFIX
+from gitpane.history.repository_value import Reference, ReferenceKind, validate_oid
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.reference.stash_list import StashList
+
+# One for-each-ref line per reference: its full name, its object, the peeled object and both types, its symbolic
+# target, the marker Git prints when HEAD is that very reference, then the upstream Git resolves for a local branch
+# and the remote that upstream belongs to. Git leaves both upstream fields empty for anything but a local branch with
+# a usable upstream, and names the remote "." when the upstream is another local branch. Every reader of references
+# uses this one format and the indices below, so no second copy of the field order can drift from the parser, and the
+# upstream comes with the same single listing instead of another Git process.
+REFERENCE_FORMAT = ("%(refname)%00%(objectname)%00%(*objectname)%00%(objecttype)%00%(*objecttype)%00%(symref)%00%(HEAD)"
+                    "%00%(upstream)%00%(upstream:remotename)")
+REFERENCE_NAME_FIELD_INDEX = 0
+REFERENCE_OBJECT_OID_FIELD_INDEX = 1
+REFERENCE_PEELED_OID_FIELD_INDEX = 2
+REFERENCE_OBJECT_TYPE_FIELD_INDEX = 3
+REFERENCE_PEELED_TYPE_FIELD_INDEX = 4
+REFERENCE_SYMBOLIC_TARGET_FIELD_INDEX = 5
+REFERENCE_HEAD_MARKER_FIELD_INDEX = 6
+REFERENCE_UPSTREAM_FIELD_INDEX = 7
+REFERENCE_UPSTREAM_REMOTE_FIELD_INDEX = 8
+REFERENCE_FIELD_COUNT = 9
+
+
+# The remote name Git gives an upstream that is a branch of this very repository: no remote to push to.
+LOCAL_UPSTREAM_REMOTE_NAME = "."
+REFERENCE_FIELD_SEPARATOR = "\0"
+REFERENCE_LINE_TERMINATOR = b"\n"
+CURRENT_HEAD_MARKER = "*"
+OTHER_HEAD_MARKER = " "
+COMMIT_OBJECT_TYPE = "commit"
+TAG_OBJECT_TYPE = "tag"
+
+
+def reference_kind(full_name: str) -> ReferenceKind:
+    """Group a full reference name the way the window lists it: local, remote, and everything else with tags."""
+    if full_name.startswith(LOCAL_PREFIX):
+        return ReferenceKind.HEADS
+    if full_name.startswith(REMOTE_PREFIX):
+        return ReferenceKind.REMOTES
+    return ReferenceKind.TAGS
+
+
+def short_reference_name(full_name: str) -> str:
+    """Write a full reference name the way the window shows it: without its refs/heads/, refs/remotes/ or refs/tags/ prefix."""
+    return full_name.removeprefix(reference_kind(full_name).prefix)
+
+
+@dataclass(frozen=True)
+class ReferenceRead:
+    """Everything one for-each-ref listing written with REFERENCE_FORMAT proves, for the reference lists and the history graph.
+
+    The first four fields mean exactly what parse_reference_output answers. The commit set names every reference whose
+    own object, or the object its tag peels to, is a commit. The unresolved tags are those Git could only peel to
+    another tag: each full name is kept with its own tag object, which a separate lookup still has to follow. The two
+    upstream maps hold, for each local branch that has one, the full name of its upstream and the remote that upstream
+    belongs to; a branch without an upstream is absent from both, and one following another local branch is absent
+    from the remote map.
+    """
+
+    references: tuple[Reference, ...]
+    object_oid_by_name: dict[str, str]
+    head_oid: str | None
+    head_ref: str | None
+    commit_reference_name_set: frozenset[str]
+    unresolved_tag_oid_by_name: dict[str, str]
+    upstream_by_name: dict[str, str] = dataclass_field(default_factory=dict)
+    upstream_remote_by_name: dict[str, str] = dataclass_field(default_factory=dict)
+
+
+def parse_reference_output(output: bytes) -> tuple[tuple[Reference, ...], dict[str, str], str | None, str | None]:
+    """Read a for-each-ref listing written with REFERENCE_FORMAT: references, the object of each name, HEAD's commit and branch.
+
+    This is parse_reference_read reduced to the four values every reader of references started with.
+    """
+    read = parse_reference_read(output)
+    return read.references, read.object_oid_by_name, read.head_oid, read.head_ref
+
+
+def parse_reference_read(output: bytes) -> ReferenceRead:
+    """Read a for-each-ref listing written with REFERENCE_FORMAT, whatever the order of its lines.
+
+    Answers the references, the object each name holds, and HEAD's commit and branch when the listing itself
+    proves them: only a local branch holding a commit and carrying Git's current marker names HEAD. A detached or
+    unborn HEAD marks nothing, and a marker on anything else is not trusted either; both answer None for HEAD, so
+    the caller asks Git directly instead of guessing. A cut-off, malformed, duplicated or doubly marked listing is
+    refused, because a partial list of references would look exactly like a complete one to the window.
+    """
+    if output and not output.endswith(REFERENCE_LINE_TERMINATOR):
+        raise ValueError("Incomplete reference data returned by Git")
+    records = output.split(REFERENCE_LINE_TERMINATOR)
+    records.pop()
+    references: list[Reference] = []
+    object_oid_by_name: dict[str, str] = {}
+    commit_reference_name_set: set[str] = set()
+    unresolved_tag_oid_by_name: dict[str, str] = {}
+    upstream_by_name: dict[str, str] = {}
+    upstream_remote_by_name: dict[str, str] = {}
+    marked_name = None
+    for record in records:
+        # The HEAD marker is a single space and the upstream fields are empty for most references: the line is split as
+        # it is, never trimmed, so a blank field is never mistaken for a missing one.
+        fields = record.decode("utf-8", "surrogateescape").split(REFERENCE_FIELD_SEPARATOR)
+        if len(fields) != REFERENCE_FIELD_COUNT:
+            raise ValueError("Incomplete reference data returned by Git")
+        full_name = fields[REFERENCE_NAME_FIELD_INDEX]
+        object_oid = fields[REFERENCE_OBJECT_OID_FIELD_INDEX]
+        peeled_oid = fields[REFERENCE_PEELED_OID_FIELD_INDEX]
+        object_type = fields[REFERENCE_OBJECT_TYPE_FIELD_INDEX]
+        peeled_type = fields[REFERENCE_PEELED_TYPE_FIELD_INDEX]
+        symbolic_target = fields[REFERENCE_SYMBOLIC_TARGET_FIELD_INDEX]
+        head_marker = fields[REFERENCE_HEAD_MARKER_FIELD_INDEX]
+        if not full_name or not object_type or head_marker not in (CURRENT_HEAD_MARKER, OTHER_HEAD_MARKER):
+            raise ValueError("Incomplete reference data returned by Git")
+        validate_oid(object_oid)
+        if peeled_oid:
+            validate_oid(peeled_oid)
+        if full_name in object_oid_by_name:
+            raise ValueError("Git listed the same reference twice")
+        if head_marker == CURRENT_HEAD_MARKER:
+            if marked_name is not None:
+                raise ValueError("Git marked more than one reference as HEAD")
+            marked_name = full_name
+        target_oid = object_oid if object_type == COMMIT_OBJECT_TYPE else peeled_oid if peeled_type == COMMIT_OBJECT_TYPE and peeled_oid else None
+        object_oid_by_name[full_name] = object_oid
+        references.append(Reference(full_name, reference_kind(full_name), target_oid, symbolic_target or None, False))
+        if target_oid is not None:
+            commit_reference_name_set.add(full_name)
+        elif object_type == TAG_OBJECT_TYPE and peeled_type == TAG_OBJECT_TYPE:
+            unresolved_tag_oid_by_name[full_name] = object_oid
+        if full_name.startswith(LOCAL_PREFIX):
+            upstream = fields[REFERENCE_UPSTREAM_FIELD_INDEX]
+            upstream_remote = fields[REFERENCE_UPSTREAM_REMOTE_FIELD_INDEX]
+            if upstream:
+                upstream_by_name[full_name] = upstream
+            if upstream_remote and upstream_remote != LOCAL_UPSTREAM_REMOTE_NAME:
+                upstream_remote_by_name[full_name] = upstream_remote
+    head_oid = None
+    head_ref = None
+    if marked_name is not None:
+        marked = next(reference for reference in references if reference.full_name == marked_name)
+        if marked.kind == ReferenceKind.HEADS and marked.symbolic_target is None and marked.target_oid == object_oid_by_name[marked_name]:
+            head_oid = marked.target_oid
+            head_ref = marked_name
+    return ReferenceRead(mark_head(references, head_ref), object_oid_by_name, head_oid, head_ref, frozenset(commit_reference_name_set), unresolved_tag_oid_by_name,
+                         upstream_by_name, upstream_remote_by_name)
+
+
+def mark_head(references: list[Reference] | tuple[Reference, ...], head_ref: str | None) -> tuple[Reference, ...]:
+    """Flag the one reference HEAD is on, and only that one."""
+    marked_references: list[Reference] = []
+    for reference in references:
+        is_head = head_ref is not None and reference.full_name == head_ref
+        marked_references.append(reference if reference.is_head == is_head else replace(reference, is_head=is_head))
+    return tuple(marked_references)
+
+
+@dataclass(frozen=True)
+class ReferenceSnapshot:
+    """Freeze refs, HEAD and worktree membership from one consistent native read."""
+
+    context: RepositoryContext
+    git_filename: str
+    generation: int
+    references: tuple[Reference, ...]
+    object_oid_by_name: dict[str, str]
+    head_oid: str | None
+    head_ref: str | None
+    worktrees: bytes
+    signature: tuple
+    remote_names: tuple[str, ...] = ()
+    # The listing this capture was built from, so the history graph can use the same observation instead of listing
+    # the references again. It is derived from the fields above and never compared: two captures of the same state
+    # are equal whether or not they carry it.
+    reference_read: ReferenceRead | None = dataclass_field(default=None, compare=False)
+    # Upstream of each local branch that has one, and the remote of that upstream, from the same listing.
+    upstream_by_name: dict[str, str] = dataclass_field(default_factory=dict)
+    upstream_remote_by_name: dict[str, str] = dataclass_field(default_factory=dict)
+    # The stashes, read in the same pass for the left panel of a window. Only reads made to show a window carry it,
+    # and it never takes part in comparing two captures: the stash reflog is not one of the files the signature covers.
+    stash_list: StashList | None = dataclass_field(default=None, compare=False)