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,15 @@
+//! 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;
+pub use stack::{Stack, StackCommit, StackCommitFlags, StackSegment};
+
+mod workspace;
+pub use workspace::{HeadLocation, Target, Workspace};

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

@@ -0,0 +1,94 @@
+use crate::SegmentIndex;
+use bitflags::bitflags;
+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: StackCommitFlags,
+    /// 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,
+}
+
+bitflags! {
+    /// Provide more information about a commit, as gathered during traversal and as member of the stack.
+    #[derive(Default, Debug, Copy, Clone, Eq, PartialEq)]
+    pub struct StackCommitFlags: u8 {
+        /// 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.
+        const ReachableByRemote = 1 << 0;
+        /// Following the graph upward will lead to at least one tip that is a workspace.
+        ///
+        /// Note that if this flag isn't present, this means the commit isn't reachable
+        /// from a workspace.
+        const InWorkspace = 1 << 1;
+        /// The commit is reachable from either the target branch (usually `refs/remotes/origin/main`).
+        /// Note that when multiple workspaces are included in the traversal, this flag is set by
+        /// any of many target branches.
+        const Integrated = 1 << 2;
+        /// 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.
+        const has_conflicts = 1 << 3;
+    }
+}

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

@@ -0,0 +1,57 @@
+use crate::projection::Stack;
+use crate::{Graph, SegmentIndex};
+use but_core::ref_metadata;
+
+/// A workspace is a list of [Stacks](Stack).
+#[derive(Debug, Clone)]
+pub struct Workspace {
+    /// Where `HEAD` is currently pointing to.
+    pub head: HeadLocation,
+    /// One or more stacks that live in the workspace.
+    pub stacks: Vec<Stack>,
+    /// The target to integrate workspace stacks into.
+    ///
+    /// If `None`, this is a local workspace that doesn't know when possibly pushed branches are considered integrated.
+    pub target: Option<Target>,
+    /// Read-only workspace metadata with additional information, or `None` if nothing was present.
+    pub metadata: Option<ref_metadata::Workspace>,
+}
+
+/// Learn where the current `HEAD` is pointing to.
+#[derive(Debug, Clone)]
+pub enum HeadLocation {
+    /// The `HEAD` is pointing to the workspace reference, like `refs/heads/gitbutler/workspace`.
+    Workspace {
+        /// The name of the reference pointing to the workspace commit. Useful for deriving the workspace name.
+        ref_name: gix::refs::FullName,
+    },
+    /// A segment is checked out directly.
+    ///
+    /// It can be inside or outside of a workspace.
+    /// If the respective segment is not named, this means the `HEAD` id detached.
+    /// The commit that the working tree is at is always implied to be the first commit of the [`StackSegment`].
+    Segment {
+        /// The id of the segment to be found in any stack of the [workspace stacks](Workspace::stacks).
+        segment_index: SegmentIndex,
+    },
+}
+
+/// Information about the target reference.
+#[derive(Debug, Clone)]
+pub struct Target {
+    /// The name of the target branch, i.e. the branch that all [Stacks](Stack) want to get merged into.
+    pub ref_name: gix::refs::FullName,
+    /// The amount of commits that aren't reachable by any segment in the workspace, they are in its future.
+    pub commits_ahead: usize,
+}
+
+impl Graph {
+    /// Analyse the current graph starting at its [entrypoint](Self::lookup_entrypoint()).
+    ///
+    /// No matter what, each location of `HEAD1`, which corresponds to the entrypoint, can be represented as workspace.
+    /// Further, the most expensive operations we perform to query additional commit information by reading it, but we
+    /// only do so on the ones that the user can interact with.
+    pub fn to_workspace(&self) -> anyhow::Result<Workspace> {
+        todo!()
+    }
+}

crates/but-graph/tests/graph/init/mod.rs

@@ -34,6 +34,8 @@ fn unborn() -> anyhow::Result<()> {
         hard_limit_hit: false,
     }
     "#);
+
+    insta::assert_snapshot!(graph_workspace(&graph.to_workspace()?), @r"");
     Ok(())
 }
 
@@ -486,6 +488,7 @@ fn with_limits() -> anyhow::Result<()> {
 mod with_workspace;
 
 mod utils;
+use crate::utils::graph_workspace;
 pub use utils::{
     StackState, add_stack_with_segments, add_workspace, id_at, id_by_rev,
     read_only_in_memory_scenario, standard_options,

crates/but-graph/tests/graph/utils.rs

@@ -2,17 +2,22 @@ use but_graph::{EntryPoint, Graph, SegmentIndex};
 use std::collections::{BTreeMap, BTreeSet};
 use termtree::Tree;
 
-type SegmentTree = Tree<String>;
+type StringTree = Tree<String>;
 
 /// Visualize `graph` as a tree.
-pub fn graph_tree(graph: &but_graph::Graph) -> SegmentTree {
+pub fn graph_workspace(_graph: &but_graph::projection::Workspace) -> StringTree {
+    todo!()
+}
+
+/// Visualize `graph` as a tree.
+pub fn graph_tree(graph: &Graph) -> StringTree {
     fn tree_for_commit(
         commit: &but_graph::Commit,
         has_conflicts: bool,
         is_entrypoint: bool,
         is_early_end: bool,
         hard_limit_hit: bool,
-    ) -> SegmentTree {
+    ) -> StringTree {
         Graph::commit_debug_string(
             commit,
             has_conflicts,
@@ -27,7 +32,7 @@ pub fn graph_tree(graph: &but_graph::Graph) -> SegmentTree {
         graph: &but_graph::Graph,
         sidx: SegmentIndex,
         seen: &mut BTreeSet<SegmentIndex>,
-    ) -> SegmentTree {
+    ) -> StringTree {
         if seen.contains(&sidx) {
             return format!(
                 "→:{sidx}:{name}",