@lix-js/sdk 0.6.0-preview.4 → 0.6.0

package/dist-engine-src/src/commit_graph/walker.rs

@@ -1,756 +0,0 @@
-use std::collections::{BTreeMap, BTreeSet};
-
-use crate::commit_graph::{CommitGraphCommit, CommitGraphStoreReader, ReachableCommitGraphCommit};
-use crate::storage::StorageReader;
-use crate::LixError;
-
-/// Walks parent links from `head_commit_id` and returns reachable commits
-/// nearest-first.
-///
-/// The walker is intentionally storage-free. It asks `CommitGraphReader` to
-/// load parsed commit facts and owns only traversal concerns: caching, cycle
-/// detection, and nearest-depth selection.
-pub(crate) async fn walk_reachable_commits<S>(
-    reader: &mut CommitGraphStoreReader<S>,
-    head_commit_id: &str,
-) -> Result<Vec<ReachableCommitGraphCommit>, LixError>
-where
-    S: StorageReader,
-{
-    let mut loader = CommitTraversalLoader::new(reader);
-    let mut visiting = BTreeSet::new();
-    let mut nearest_depths = BTreeMap::new();
-    loader
-        .walk_commit(head_commit_id, 0, &mut visiting, &mut nearest_depths)
-        .await?;
-
-    let mut commits = nearest_depths
-        .into_iter()
-        .map(|(commit_id, depth)| {
-            let commit = loader
-                .loaded
-                .remove(&commit_id)
-                .expect("visited commit should be cached");
-            ReachableCommitGraphCommit { commit, depth }
-        })
-        .collect::<Vec<_>>();
-    commits.sort_by(|left, right| {
-        left.depth
-            .cmp(&right.depth)
-            .then_with(|| left.commit.commit_id.cmp(&right.commit.commit_id))
-    });
-    Ok(commits)
-}
-
-/// Returns the best common ancestors shared by two commit heads.
-///
-/// This is graph math, not merge policy. A commit is "best" when it is a
-/// common ancestor and no descendant of it is also a common ancestor.
-///
-/// Simple history has one best common ancestor:
-///
-/// ```text
-/// A -- B -- C   left
-///       \
-///        D      right
-/// ```
-///
-/// `best_common_ancestors(C, D)` returns `[B]`.
-///
-/// Commit history is a DAG, not a tree, so criss-cross histories can have
-/// multiple equally good answers. Callers that need one merge base should wrap
-/// this API with an explicit policy instead of pretending the graph always has
-/// a single lowest common ancestor.
-pub(crate) async fn best_common_ancestors<S>(
-    reader: &mut CommitGraphStoreReader<S>,
-    left_commit_id: &str,
-    right_commit_id: &str,
-) -> Result<Vec<CommitGraphCommit>, LixError>
-where
-    S: StorageReader,
-{
-    let left_reachable = walk_reachable_commits(reader, left_commit_id).await?;
-    let right_reachable = walk_reachable_commits(reader, right_commit_id).await?;
-    let right_ids = right_reachable
-        .iter()
-        .map(|reachable| reachable.commit.commit_id.clone())
-        .collect::<BTreeSet<_>>();
-    let common_ids = left_reachable
-        .iter()
-        .filter(|reachable| right_ids.contains(&reachable.commit.commit_id))
-        .map(|reachable| reachable.commit.commit_id.clone())
-        .collect::<BTreeSet<_>>();
-
-    let mut best = Vec::new();
-    for reachable in left_reachable {
-        let commit_id = &reachable.commit.commit_id;
-        if !common_ids.contains(commit_id) {
-            continue;
-        }
-
-        if has_descendant_in_set(reader, commit_id, &common_ids).await? {
-            continue;
-        }
-
-        best.push(reachable.commit);
-    }
-    best.sort_by(|left, right| left.commit_id.cmp(&right.commit_id));
-    Ok(best)
-}
-
-async fn has_descendant_in_set<S>(
-    reader: &mut CommitGraphStoreReader<S>,
-    commit_id: &str,
-    candidate_descendant_ids: &BTreeSet<String>,
-) -> Result<bool, LixError>
-where
-    S: StorageReader,
-{
-    for candidate_descendant_id in candidate_descendant_ids {
-        if candidate_descendant_id == commit_id {
-            continue;
-        }
-        let reachable = walk_reachable_commits(reader, candidate_descendant_id).await?;
-        if reachable
-            .iter()
-            .any(|reachable| reachable.commit.commit_id == commit_id)
-        {
-            return Ok(true);
-        }
-    }
-    Ok(false)
-}
-
-struct CommitTraversalLoader<'a, S>
-where
-    S: StorageReader,
-{
-    reader: &'a mut CommitGraphStoreReader<S>,
-    loaded: BTreeMap<String, CommitGraphCommit>,
-}
-
-impl<'a, S> CommitTraversalLoader<'a, S>
-where
-    S: StorageReader,
-{
-    fn new(reader: &'a mut CommitGraphStoreReader<S>) -> Self {
-        Self {
-            reader,
-            loaded: BTreeMap::new(),
-        }
-    }
-
-    async fn walk_commit(
-        &mut self,
-        commit_id: &str,
-        depth: u32,
-        visiting: &mut BTreeSet<String>,
-        nearest_depths: &mut BTreeMap<String, u32>,
-    ) -> Result<(), LixError> {
-        let mut stack = vec![TraversalFrame {
-            commit_id: commit_id.to_string(),
-            depth,
-            expanded: false,
-        }];
-
-        while let Some(frame) = stack.pop() {
-            if frame.expanded {
-                visiting.remove(&frame.commit_id);
-                continue;
-            }
-
-            if visiting.contains(&frame.commit_id) {
-                return Err(LixError::new(
-                    "LIX_ERROR_UNKNOWN",
-                    format!(
-                        "commit_graph cycle detected at commit '{}'",
-                        frame.commit_id
-                    ),
-                ));
-            }
-
-            if let Some(previous_depth) = nearest_depths.get(&frame.commit_id) {
-                if *previous_depth <= frame.depth {
-                    continue;
-                }
-            }
-
-            let commit = self.load_commit(&frame.commit_id).await?;
-            nearest_depths.insert(frame.commit_id.clone(), frame.depth);
-
-            visiting.insert(frame.commit_id.clone());
-            stack.push(TraversalFrame {
-                commit_id: frame.commit_id,
-                depth: frame.depth,
-                expanded: true,
-            });
-            for parent_commit_id in commit.parent_commit_ids.iter().rev() {
-                stack.push(TraversalFrame {
-                    commit_id: parent_commit_id.clone(),
-                    depth: frame.depth + 1,
-                    expanded: false,
-                });
-            }
-        }
-        Ok(())
-    }
-
-    async fn load_commit(&mut self, commit_id: &str) -> Result<CommitGraphCommit, LixError> {
-        if let Some(commit) = self.loaded.get(commit_id) {
-            return Ok(commit.clone());
-        }
-        let Some(commit) = self.reader.load_commit(commit_id).await? else {
-            return Err(LixError::new(
-                "LIX_ERROR_UNKNOWN",
-                format!("commit_graph missing commit '{commit_id}'"),
-            ));
-        };
-        self.loaded.insert(commit_id.to_string(), commit.clone());
-        Ok(commit)
-    }
-}
-
-struct TraversalFrame {
-    commit_id: String,
-    depth: u32,
-    expanded: bool,
-}
-
-#[cfg(test)]
-mod tests {
-    use std::sync::Arc;
-
-    use serde_json::json;
-
-    use crate::backend::testing::UnitTestBackend;
-    use crate::commit_graph::CommitGraphContext;
-    use crate::commit_store::{Change, CommitDraftRef, CommitStoreContext};
-    use crate::storage::{StorageContext, StorageWriteSet};
-    use crate::LixError;
-
-    #[tokio::test]
-    async fn reachable_commits_returns_commits_nearest_first() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-root-change", "commit-root", &[], &[]),
-                commit_change(
-                    "commit-parent-change",
-                    "commit-parent",
-                    &[],
-                    &["commit-root"],
-                ),
-                commit_change("commit-head-change", "commit-head", &[], &["commit-parent"]),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let commits = reader
-            .reachable_commits("commit-head")
-            .await
-            .expect("reachable commits should load");
-
-        assert_eq!(
-            commits
-                .iter()
-                .map(|reachable| (reachable.commit.commit_id.as_str(), reachable.depth))
-                .collect::<Vec<_>>(),
-            vec![("commit-head", 0), ("commit-parent", 1), ("commit-root", 2)]
-        );
-    }
-
-    #[tokio::test]
-    async fn reachable_commits_errors_on_missing_parent_commit() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[commit_change(
-                "commit-head-change",
-                "commit-head",
-                &[],
-                &["missing-parent"],
-            )],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let error = reader
-            .reachable_commits("commit-head")
-            .await
-            .expect_err("missing parent should fail");
-
-        assert!(error.message.contains("missing-parent"));
-    }
-
-    #[tokio::test]
-    async fn reachable_commits_errors_on_cycle() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-a-change", "commit-a", &[], &["commit-b"]),
-                commit_change("commit-b-change", "commit-b", &[], &["commit-a"]),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let error = reader
-            .reachable_commits("commit-a")
-            .await
-            .expect_err("cycle should fail");
-
-        assert!(error.message.contains("cycle"));
-    }
-
-    #[tokio::test]
-    async fn reachable_commits_dedupes_shared_ancestors_in_diamond() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-root-change", "commit-root", &[], &[]),
-                commit_change("commit-left-change", "commit-left", &[], &["commit-root"]),
-                commit_change("commit-right-change", "commit-right", &[], &["commit-root"]),
-                commit_change(
-                    "commit-head-change",
-                    "commit-head",
-                    &[],
-                    &["commit-left", "commit-right"],
-                ),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let commits = reader
-            .reachable_commits("commit-head")
-            .await
-            .expect("reachable commits should load");
-
-        assert_eq!(
-            commits
-                .iter()
-                .map(|reachable| (reachable.commit.commit_id.as_str(), reachable.depth))
-                .collect::<Vec<_>>(),
-            vec![
-                ("commit-head", 0),
-                ("commit-left", 1),
-                ("commit-right", 1),
-                ("commit-root", 2),
-            ]
-        );
-    }
-
-    #[tokio::test]
-    async fn reachable_commits_keeps_nearest_depth_for_multiple_paths() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-root-change", "commit-root", &[], &[]),
-                commit_change(
-                    "commit-parent-change",
-                    "commit-parent",
-                    &[],
-                    &["commit-root"],
-                ),
-                commit_change(
-                    "commit-head-change",
-                    "commit-head",
-                    &[],
-                    &["commit-root", "commit-parent"],
-                ),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let commits = reader
-            .reachable_commits("commit-head")
-            .await
-            .expect("reachable commits should load");
-
-        assert_eq!(
-            commits
-                .iter()
-                .map(|reachable| (reachable.commit.commit_id.as_str(), reachable.depth))
-                .collect::<Vec<_>>(),
-            vec![("commit-head", 0), ("commit-parent", 1), ("commit-root", 1)]
-        );
-    }
-
-    #[tokio::test]
-    async fn reachable_commits_orders_same_depth_commits_by_id() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-z-change", "commit-z", &[], &[]),
-                commit_change("commit-a-change", "commit-a", &[], &[]),
-                commit_change(
-                    "commit-head-change",
-                    "commit-head",
-                    &[],
-                    &["commit-z", "commit-a"],
-                ),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let commits = reader
-            .reachable_commits("commit-head")
-            .await
-            .expect("reachable commits should load");
-
-        assert_eq!(
-            commits
-                .iter()
-                .map(|reachable| (reachable.commit.commit_id.as_str(), reachable.depth))
-                .collect::<Vec<_>>(),
-            vec![("commit-head", 0), ("commit-a", 1), ("commit-z", 1)]
-        );
-    }
-
-    #[tokio::test]
-    async fn reachable_commits_errors_on_missing_head_commit() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-
-        let error = reader
-            .reachable_commits("missing-head")
-            .await
-            .expect_err("missing head should fail");
-
-        assert!(error.message.contains("missing-head"));
-    }
-
-    #[tokio::test]
-    async fn best_common_ancestors_returns_nearest_common_commit_in_simple_graph() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-a-change", "commit-a", &[], &[]),
-                commit_change("commit-b-change", "commit-b", &[], &["commit-a"]),
-                commit_change("commit-c-change", "commit-c", &[], &["commit-b"]),
-                commit_change("commit-d-change", "commit-d", &[], &["commit-b"]),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let ancestors = reader
-            .best_common_ancestors("commit-c", "commit-d")
-            .await
-            .expect("best common ancestors should load");
-
-        assert_eq!(
-            ancestors
-                .iter()
-                .map(|commit| commit.commit_id.as_str())
-                .collect::<Vec<_>>(),
-            vec!["commit-b"]
-        );
-    }
-
-    #[tokio::test]
-    async fn best_common_ancestors_returns_shared_fork_in_diamond_graph() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-root-change", "commit-root", &[], &[]),
-                commit_change("commit-left-change", "commit-left", &[], &["commit-root"]),
-                commit_change("commit-right-change", "commit-right", &[], &["commit-root"]),
-                commit_change(
-                    "commit-left-head-change",
-                    "commit-left-head",
-                    &[],
-                    &["commit-left"],
-                ),
-                commit_change(
-                    "commit-right-head-change",
-                    "commit-right-head",
-                    &[],
-                    &["commit-right"],
-                ),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let ancestors = reader
-            .best_common_ancestors("commit-left-head", "commit-right-head")
-            .await
-            .expect("best common ancestors should load");
-
-        assert_eq!(
-            ancestors
-                .iter()
-                .map(|commit| commit.commit_id.as_str())
-                .collect::<Vec<_>>(),
-            vec!["commit-root"]
-        );
-    }
-
-    #[tokio::test]
-    async fn best_common_ancestors_returns_parent_when_one_side_is_ancestor() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-a-change", "commit-a", &[], &[]),
-                commit_change("commit-b-change", "commit-b", &[], &["commit-a"]),
-                commit_change("commit-c-change", "commit-c", &[], &["commit-b"]),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let ancestors = reader
-            .best_common_ancestors("commit-b", "commit-c")
-            .await
-            .expect("best common ancestors should load");
-
-        assert_eq!(
-            ancestors
-                .iter()
-                .map(|commit| commit.commit_id.as_str())
-                .collect::<Vec<_>>(),
-            vec!["commit-b"]
-        );
-    }
-
-    #[tokio::test]
-    async fn best_common_ancestors_returns_multiple_bases_for_criss_cross_graph() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-root-change", "commit-root", &[], &[]),
-                commit_change("commit-left-change", "commit-left", &[], &["commit-root"]),
-                commit_change("commit-right-change", "commit-right", &[], &["commit-root"]),
-                commit_change(
-                    "commit-head-left-change",
-                    "commit-head-left",
-                    &[],
-                    &["commit-left", "commit-right"],
-                ),
-                commit_change(
-                    "commit-head-right-change",
-                    "commit-head-right",
-                    &[],
-                    &["commit-right", "commit-left"],
-                ),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let ancestors = reader
-            .best_common_ancestors("commit-head-left", "commit-head-right")
-            .await
-            .expect("best common ancestors should load");
-
-        assert_eq!(
-            ancestors
-                .iter()
-                .map(|commit| commit.commit_id.as_str())
-                .collect::<Vec<_>>(),
-            vec!["commit-left", "commit-right"]
-        );
-    }
-
-    #[tokio::test]
-    async fn merge_base_returns_single_best_common_ancestor() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-a-change", "commit-a", &[], &[]),
-                commit_change("commit-b-change", "commit-b", &[], &["commit-a"]),
-                commit_change("commit-c-change", "commit-c", &[], &["commit-b"]),
-                commit_change("commit-d-change", "commit-d", &[], &["commit-b"]),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let base = reader
-            .merge_base("commit-c", "commit-d")
-            .await
-            .expect("single merge base should resolve");
-
-        assert_eq!(base.commit_id, "commit-b");
-    }
-
-    #[tokio::test]
-    async fn merge_base_errors_when_histories_have_no_common_commit() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-left-change", "commit-left", &[], &[]),
-                commit_change("commit-right-change", "commit-right", &[], &[]),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let error = reader
-            .merge_base("commit-left", "commit-right")
-            .await
-            .expect_err("unrelated histories should not have a merge base");
-
-        assert!(error.message.contains("no common history"));
-    }
-
-    #[tokio::test]
-    async fn merge_base_errors_when_best_common_ancestor_is_ambiguous() {
-        let backend = Arc::new(UnitTestBackend::new());
-        let storage = StorageContext::new(backend.clone());
-        append_changes(
-            storage.clone(),
-            &[
-                commit_change("commit-root-change", "commit-root", &[], &[]),
-                commit_change("commit-left-change", "commit-left", &[], &["commit-root"]),
-                commit_change("commit-right-change", "commit-right", &[], &["commit-root"]),
-                commit_change(
-                    "commit-head-left-change",
-                    "commit-head-left",
-                    &[],
-                    &["commit-left", "commit-right"],
-                ),
-                commit_change(
-                    "commit-head-right-change",
-                    "commit-head-right",
-                    &[],
-                    &["commit-right", "commit-left"],
-                ),
-            ],
-        )
-        .await;
-
-        let graph = CommitGraphContext::new();
-        let mut reader = graph.reader(storage);
-        let error = reader
-            .merge_base("commit-head-left", "commit-head-right")
-            .await
-            .expect_err("ambiguous best common ancestors should fail");
-
-        assert_eq!(error.code, LixError::CODE_AMBIGUOUS_MERGE_BASE);
-        assert_eq!(
-            error
-                .details
-                .as_ref()
-                .and_then(|details| details.get("left_commit_id")),
-            Some(&json!("commit-head-left"))
-        );
-        assert_eq!(
-            error
-                .details
-                .as_ref()
-                .and_then(|details| details.get("right_commit_id")),
-            Some(&json!("commit-head-right"))
-        );
-        assert_eq!(
-            error
-                .details
-                .as_ref()
-                .and_then(|details| details.get("candidates")),
-            Some(&json!(["commit-left", "commit-right"]))
-        );
-    }
-
-    #[derive(Clone)]
-    struct TestCommitChange {
-        change: Change,
-        parent_commit_ids: Vec<String>,
-    }
-
-    async fn append_changes(storage: StorageContext, changes: &[TestCommitChange]) {
-        let mut tx = storage
-            .begin_write_transaction()
-            .await
-            .expect("transaction should open");
-        let mut writes = StorageWriteSet::new();
-        let commit_store = CommitStoreContext::new();
-        for change in changes {
-            let commit_id = change
-                .change
-                .entity_id
-                .as_single_string()
-                .expect("commit fixture should have single id")
-                .to_string();
-            let author_account_ids = Vec::new();
-            let commit = CommitDraftRef {
-                id: &commit_id,
-                change_id: &change.change.id,
-                parent_ids: &change.parent_commit_ids,
-                author_account_ids: &author_account_ids,
-                created_at: &change.change.created_at,
-            };
-            commit_store
-                .writer(tx.as_mut(), &mut writes)
-                .stage_commit_draft(commit, Vec::new(), Vec::new())
-                .await
-                .expect("commit-store fixture should append");
-        }
-        writes
-            .apply(&mut tx.as_mut())
-            .await
-            .expect("writes should apply");
-        tx.commit().await.expect("commit should succeed");
-    }
-
-    fn commit_change(
-        change_id: &str,
-        commit_id: &str,
-        change_ids: &[&str],
-        parent_commit_ids: &[&str],
-    ) -> TestCommitChange {
-        let _ = change_ids;
-        TestCommitChange {
-            change: Change {
-                id: change_id.to_string(),
-                entity_id: crate::entity_identity::EntityIdentity::single(commit_id),
-                schema_key: "lix_commit".to_string(),
-                file_id: None,
-                snapshot_ref: None,
-                metadata_ref: None,
-                created_at: "2026-01-01T00:00:00Z".to_string(),
-            },
-            parent_commit_ids: parent_commit_ids.iter().map(|id| id.to_string()).collect(),
-        }
-    }
-}