A first shot at producing stacks from a graph

Author: Byron

crates/but-graph/src/lib.rs

@@ -43,6 +43,7 @@ pub use segment::{Commit, CommitDetails, CommitFlags, Segment, SegmentMetadata};
 mod api;
 /// Produce a graph from a Git repository.
 pub mod init;
+pub mod projection;
 
 mod ref_metadata_legacy;
 pub use ref_metadata_legacy::{VirtualBranchesTomlMetadata, is_workspace_ref_name};

crates/but-graph/src/projection/mod.rs

@@ -0,0 +1,23 @@
+//! A way to represent the graph in a simplified (but more usable) form.
+//!
+//! This is the current default way of GitButler to perceive its world, but most inexpensively generated to stay
+//! close to the source of truth, [The Graph](crate::Graph).
+//!
+//! These types are not for direct consumption, but should be processed further for consumption by the user.
+
+/// Types related to the stack representation for graphs.
+///
+/// Note that these are always a simplification, degenerating information, while maintaining a link back to the graph.
+mod stack;
+
+use but_core::ref_metadata;
+pub use stack::{Stack, StackCommit, StackSegment};
+
+/// A workspace is a list of [Stacks](Stack).
+#[derive(Debug, Clone)]
+pub struct Workspace {
+    /// One or more stacks that live in the workspace.
+    pub stacks: Vec<Stack>,
+    /// Read-only workspace metadata with additional information, or `None` if nothing was present.
+    pub metadata: Option<ref_metadata::Workspace>,
+}

crates/but-graph/src/projection/stack.rs

@@ -0,0 +1,77 @@
+use crate::{CommitFlags, SegmentIndex, SegmentMetadata};
+use bstr::BString;
+use but_core::ref_metadata;
+
+/// A list of segments that together represent a list of dependent branches, stacked on top of each other.
+#[derive(Debug, Clone)]
+pub struct Stack {
+    /// If there is an integration branch, we know a base commit shared with the integration branch from
+    /// which we branched off.
+    /// It is `None` if this is a stack derived from a branch without relation to any other branch.
+    pub base: Option<gix::ObjectId>,
+    /// The branch-name denoted segments of the stack from its tip to the point of reference, typically a merge-base.
+    /// This array is never empty.
+    pub segments: Vec<StackSegment>,
+}
+
+/// A typically named set of linearized commits, obtained by first-parent-only traversal.
+///
+/// Note that this maybe an aggregation of multiple [graph segments](crate::Segment).
+#[derive(Debug, Clone)]
+pub struct StackSegment {
+    /// The unambiguous or disambiguated name of the branch at the tip of the segment, i.e. at the first commit.
+    ///
+    /// It is `None` if this branch is the top-most stack segment and the `ref_name` wasn't pointing to
+    /// a commit anymore that was reached by our rev-walk.
+    /// This can happen if the ref is deleted, or if it was advanced by other means.
+    /// Alternatively, the naming could have been ambiguous while this is the first segment in the stack.
+    /// named segment.
+    pub ref_name: Option<gix::refs::FullName>,
+    /// An ID which uniquely identifies the first [graph segment](crate::Segment) that is contained
+    /// in this instance.
+    /// Note that it's not suitable to permanently identify the segment, so should not be persisted.
+    pub id: SegmentIndex,
+    /// The name of the remote tracking branch of this segment, if present, i.e. `refs/remotes/origin/main`.
+    /// Its presence means [`commits_unique_in_remote_tracking_branch`] are possibly available.
+    pub remote_tracking_ref_name: Option<gix::refs::FullName>,
+    /// The portion of commits that can be reached from the tip of the *branch* downwards to the next [StackSegment],
+    /// so that they are unique for this stack segment and not included in any other stack or stack segment.
+    ///
+    /// The list could be empty for when this is a dedicated empty segment as insertion position of commits.
+    pub commits: Vec<StackCommit>,
+    /// Commits that are reachable from the remote-tracking branch that is associated with this branch,
+    /// but are not reachable from this branch or duplicated by a commit in it if comparing their hash-identity.
+    ///
+    /// No further processing was done to deduplicate these.
+    pub commits_unique_in_remote_tracking_branch: Vec<StackCommit>,
+    /// Read-only branch metadata with additional information, or `None` if nothing was present.
+    pub metadata: Option<ref_metadata::Branch>,
+}
+
+/// A combination of [Commits](crate::Commit) and [CommitDetails](crate::CommitDetails).
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct StackCommit {
+    /// The hash of the commit.
+    pub id: gix::ObjectId,
+    /// The IDs of the parent commits, but may be empty if this is the first commit.
+    pub parent_ids: Vec<gix::ObjectId>,
+    /// Additional properties to help classify this commit.
+    pub flags: CommitFlags,
+    /// The references pointing to this commit, even after dereferencing tag objects.
+    /// These can be names of tags and branches.
+    pub refs: Vec<gix::refs::FullName>,
+    /// The complete message, verbatim.
+    pub message: BString,
+    /// The signature at which the commit was authored.
+    pub author: gix::actor::Signature,
+    /// Whether the commit is in a conflicted state, a GitButler concept.
+    /// GitButler will perform rebasing/reordering etc. without interruptions and flag commits as conflicted if needed.
+    /// Conflicts are resolved via the Edit Mode mechanism.
+    ///
+    /// Note that even though GitButler won't push branches with conflicts, the user can still push such branches at will.
+    pub has_conflicts: bool,
+    /// If `true`, the commit was pushed and is included in a [remote tracking branch](StackSegment::remote_tracking_ref_name).
+    ///
+    /// These commits should be considered frozen and not be manipulated casually.
+    pub is_reachable_by_remote: bool,
+}