ralph_workflow/git_helpers/

start_commit.rs

//! Starting commit tracking for incremental diff generation.
//!
//! This module manages the starting commit reference that enables incremental
//! diffs for reviewers while keeping agents isolated from git history.
//!
//! # Overview
//!
//! When a Ralph pipeline starts, the current HEAD commit is saved as the
//! "starting commit" in `.agent/start_commit`. This reference is used to:
//!
//! 1. Generate incremental diffs for reviewers (changes since pipeline start)
//! 2. Keep agents unaware of git history (no git context in prompts)
//! 3. Enable proper review of accumulated changes across iterations
//!
//! The starting commit file persists across pipeline runs unless explicitly
//! reset by the user via the `--reset-start-commit` CLI command.

use std::fs;
use std::io;
use std::path::Path;

#[cfg(any(test, feature = "test-utils"))]
use crate::workspace::Workspace;

/// Path to the starting commit file.
///
/// Stored in `.agent/start_commit`, this file contains the OID (SHA) of the
/// commit that was HEAD when the pipeline started.
const START_COMMIT_FILE: &str = ".agent/start_commit";

/// Sentinel value written to `.agent/start_commit` when the repository has no commits yet.
///
/// This enables incremental diffs to work in a single run that starts on an unborn HEAD
/// by treating the starting point as the empty tree.
const EMPTY_REPO_SENTINEL: &str = "__EMPTY_REPO__";

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StartPoint {
    /// A concrete commit OID to diff from.
    Commit(git2::Oid),
    /// An empty repository baseline (diff from the empty tree).
    EmptyRepo,
}

/// Get the current HEAD commit OID.
///
/// Returns the full SHA-1 hash of the current HEAD commit.
///
/// # Errors
///
/// Returns an error if:
/// - Not in a git repository
/// - HEAD cannot be resolved (e.g., unborn branch)
/// - HEAD is not a commit (e.g., symbolic ref to tag)
///
/// **Note:** This function uses the current working directory to discover the repo.
pub fn get_current_head_oid() -> io::Result<String> {
    let repo = git2::Repository::discover(".").map_err(|e| to_io_error(&e))?;
    get_current_head_oid_impl(&repo)
}

/// Implementation of get_current_head_oid.
fn get_current_head_oid_impl(repo: &git2::Repository) -> io::Result<String> {
    let head = repo.head().map_err(|e| {
        // Handle UnbornBranch error consistently with git_diff()
        // This provides a clearer error message for empty repositories
        if e.code() == git2::ErrorCode::UnbornBranch {
            io::Error::new(io::ErrorKind::NotFound, "No commits yet (unborn branch)")
        } else {
            to_io_error(&e)
        }
    })?;

    // Get the commit OID
    let head_commit = head.peel_to_commit().map_err(|e| to_io_error(&e))?;

    Ok(head_commit.id().to_string())
}

fn get_current_start_point(repo: &git2::Repository) -> io::Result<StartPoint> {
    let head = repo.head();
    let start_point = match head {
        Ok(head) => {
            let head_commit = head.peel_to_commit().map_err(|e| to_io_error(&e))?;
            StartPoint::Commit(head_commit.id())
        }
        Err(ref e) if e.code() == git2::ErrorCode::UnbornBranch => StartPoint::EmptyRepo,
        Err(e) => return Err(to_io_error(&e)),
    };
    Ok(start_point)
}

/// Save the current HEAD commit as the starting commit.
///
/// Writes the current HEAD OID to `.agent/start_commit` only if it doesn't
/// already exist. This ensures the `start_commit` persists across pipeline runs
/// and is only reset when explicitly requested via `--reset-start-commit`.
///
/// # Errors
///
/// Returns an error if:
/// - The current HEAD cannot be determined
/// - The `.agent` directory cannot be created
/// - The file cannot be written
///
pub fn save_start_commit() -> io::Result<()> {
    let repo = git2::Repository::discover(".").map_err(|e| to_io_error(&e))?;
    let repo_root = repo
        .workdir()
        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "No workdir for repository"))?;
    save_start_commit_impl(&repo, repo_root)
}

/// Implementation of save_start_commit.
fn save_start_commit_impl(repo: &git2::Repository, repo_root: &Path) -> io::Result<()> {
    // If a start commit exists and is valid, preserve it across runs.
    // If it exists but is invalid/corrupt, automatically repair it.
    if load_start_point_impl(repo, repo_root).is_ok() {
        return Ok(());
    }

    write_start_point(repo_root, get_current_start_point(repo)?)
}

fn write_start_commit_with_oid(repo_root: &Path, oid: &str) -> io::Result<()> {
    // Ensure .agent directory exists
    let path = repo_root.join(START_COMMIT_FILE);
    if let Some(parent) = path.parent() {
        fs::create_dir_all(parent)?;
    }

    // Write the OID to the file
    fs::write(&path, oid)?;

    Ok(())
}

fn write_start_point(repo_root: &Path, start_point: StartPoint) -> io::Result<()> {
    match start_point {
        StartPoint::Commit(oid) => write_start_commit_with_oid(repo_root, &oid.to_string()),
        StartPoint::EmptyRepo => {
            // Ensure .agent directory exists
            let path = repo_root.join(START_COMMIT_FILE);
            if let Some(parent) = path.parent() {
                fs::create_dir_all(parent)?;
            }
            fs::write(&path, EMPTY_REPO_SENTINEL)?;
            Ok(())
        }
    }
}

/// Write start point to file using workspace abstraction.
///
/// This is the workspace-aware version that should be used in pipeline code
/// where a workspace is available.
#[cfg(any(test, feature = "test-utils"))]
fn write_start_point_with_workspace(
    workspace: &dyn Workspace,
    start_point: StartPoint,
) -> io::Result<()> {
    let path = Path::new(START_COMMIT_FILE);
    let content = match start_point {
        StartPoint::Commit(oid) => oid.to_string(),
        StartPoint::EmptyRepo => EMPTY_REPO_SENTINEL.to_string(),
    };
    workspace.write(path, &content)
}

/// Load start point from file using workspace abstraction.
///
/// This version reads the file content via workspace but still validates
/// the commit exists using the provided repository.
///
/// This is the workspace-aware version for pipeline code where git operations
/// are needed for validation.
#[cfg(any(test, feature = "test-utils"))]
pub fn load_start_point_with_workspace(
    workspace: &dyn Workspace,
    repo: &git2::Repository,
) -> io::Result<StartPoint> {
    let path = Path::new(START_COMMIT_FILE);
    let content = workspace.read(path)?;
    let raw = content.trim();

    if raw.is_empty() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            "Starting commit file is empty. Run 'ralph --reset-start-commit' to fix.",
        ));
    }

    if raw == EMPTY_REPO_SENTINEL {
        return Ok(StartPoint::EmptyRepo);
    }

    // Validate OID format using libgit2.
    let oid = git2::Oid::from_str(raw).map_err(|_| {
        io::Error::new(
            io::ErrorKind::InvalidData,
            format!(
                "Invalid OID format in {}: '{}'. Run 'ralph --reset-start-commit' to fix.",
                START_COMMIT_FILE, raw
            ),
        )
    })?;

    // Ensure the commit still exists in this repository.
    repo.find_commit(oid).map_err(|e| {
        let err_msg = e.message();
        if err_msg.contains("not found") || err_msg.contains("invalid") {
            io::Error::new(
                io::ErrorKind::NotFound,
                format!(
                    "Start commit '{}' no longer exists (history rewritten). \
                     Run 'ralph --reset-start-commit' to fix.",
                    raw
                ),
            )
        } else {
            to_io_error(&e)
        }
    })?;

    Ok(StartPoint::Commit(oid))
}

/// Save start commit using workspace abstraction.
///
/// This is the workspace-aware version for pipeline code where a workspace
/// is available. If a valid start commit already exists, it is preserved.
#[cfg(any(test, feature = "test-utils"))]
pub fn save_start_commit_with_workspace(
    workspace: &dyn Workspace,
    repo: &git2::Repository,
) -> io::Result<()> {
    // If a start commit exists and is valid, preserve it across runs.
    if load_start_point_with_workspace(workspace, repo).is_ok() {
        return Ok(());
    }

    write_start_point_with_workspace(workspace, get_current_start_point(repo)?)
}

/// Load the starting commit OID from the file.
///
/// Reads the `.agent/start_commit` file and returns the stored OID.
///
/// # Errors
///
/// Returns an error if:
/// - The file does not exist
/// - The file cannot be read
/// - The file content is invalid
///
pub fn load_start_point() -> io::Result<StartPoint> {
    let repo = git2::Repository::discover(".").map_err(|e| {
        io::Error::new(
            io::ErrorKind::NotFound,
            format!("Git repository error: {e}. Run 'ralph --reset-start-commit' to fix."),
        )
    })?;
    let repo_root = repo
        .workdir()
        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "No workdir for repository"))?;
    load_start_point_impl(&repo, repo_root)
}

/// Implementation of load_start_point.
fn load_start_point_impl(repo: &git2::Repository, repo_root: &Path) -> io::Result<StartPoint> {
    let path = repo_root.join(START_COMMIT_FILE);
    let content = fs::read_to_string(&path)?;

    let raw = content.trim();

    if raw.is_empty() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            "Starting commit file is empty. Run 'ralph --reset-start-commit' to fix.",
        ));
    }

    if raw == EMPTY_REPO_SENTINEL {
        return Ok(StartPoint::EmptyRepo);
    }

    // Validate OID format using libgit2.
    // git2::Oid::from_str automatically validates both SHA-1 (40 hex chars) and
    // SHA-256 (64 hex chars) formats, as well as abbreviated forms.
    let oid = git2::Oid::from_str(raw).map_err(|_| {
        io::Error::new(
            io::ErrorKind::InvalidData,
            format!(
                "Invalid OID format in {}: '{}'. Run 'ralph --reset-start-commit' to fix.",
                START_COMMIT_FILE, raw
            ),
        )
    })?;

    // Ensure the commit still exists in this repository (history may have been rewritten).
    repo.find_commit(oid).map_err(|e| {
        let err_msg = e.message();
        if err_msg.contains("not found") || err_msg.contains("invalid") {
            io::Error::new(
                io::ErrorKind::NotFound,
                format!("Start commit '{}' no longer exists (history rewritten). Run 'ralph --reset-start-commit' to fix.", raw),
            )
        } else {
            to_io_error(&e)
        }
    })?;

    Ok(StartPoint::Commit(oid))
}

/// Result of resetting the start commit.
#[derive(Debug, Clone)]
pub struct ResetStartCommitResult {
    /// The OID that start_commit was set to.
    pub oid: String,
    /// The default branch used for merge-base calculation (if applicable).
    pub default_branch: Option<String>,
    /// Whether we fell back to HEAD (when on main/master branch).
    pub fell_back_to_head: bool,
}

/// Reset the starting commit to merge-base with the default branch.
///
/// This is a CLI command that updates `.agent/start_commit` to the merge-base
/// between HEAD and the default branch (main/master). This provides a better
/// baseline for feature branch workflows, showing only changes since branching.
///
/// If the current branch is main/master itself, falls back to current HEAD.
///
/// # Errors
///
/// Returns an error if:
/// - The current HEAD cannot be determined
/// - The default branch cannot be found
/// - No common ancestor exists between HEAD and the default branch
/// - The file cannot be written
///
pub fn reset_start_commit() -> io::Result<ResetStartCommitResult> {
    let repo = git2::Repository::discover(".").map_err(|e| to_io_error(&e))?;
    let repo_root = repo
        .workdir()
        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "No workdir for repository"))?;
    reset_start_commit_impl(&repo, repo_root)
}

/// Implementation of reset_start_commit.
fn reset_start_commit_impl(
    repo: &git2::Repository,
    repo_root: &Path,
) -> io::Result<ResetStartCommitResult> {
    // Get current HEAD
    let head = repo.head().map_err(|e| {
        if e.code() == git2::ErrorCode::UnbornBranch {
            io::Error::new(io::ErrorKind::NotFound, "No commits yet (unborn branch)")
        } else {
            to_io_error(&e)
        }
    })?;
    let head_commit = head.peel_to_commit().map_err(|e| to_io_error(&e))?;

    // Check if we're on main/master - if so, fall back to HEAD
    let current_branch = head.shorthand().unwrap_or("HEAD");
    if current_branch == "main" || current_branch == "master" {
        let oid = head_commit.id().to_string();
        write_start_commit_with_oid(repo_root, &oid)?;
        return Ok(ResetStartCommitResult {
            oid,
            default_branch: None,
            fell_back_to_head: true,
        });
    }

    // Get the default branch
    let default_branch = super::branch::get_default_branch_at(repo_root)?;

    // Find the default branch commit
    let default_ref = format!("refs/heads/{}", default_branch);
    let default_commit = match repo.find_reference(&default_ref) {
        Ok(reference) => reference.peel_to_commit().map_err(|e| to_io_error(&e))?,
        Err(_) => {
            // Try origin/<default_branch> as fallback
            let origin_ref = format!("refs/remotes/origin/{}", default_branch);
            match repo.find_reference(&origin_ref) {
                Ok(reference) => reference.peel_to_commit().map_err(|e| to_io_error(&e))?,
                Err(_) => {
                    return Err(io::Error::new(
                        io::ErrorKind::NotFound,
                        format!(
                            "Default branch '{}' not found locally or in origin. \
                             Make sure the branch exists.",
                            default_branch
                        ),
                    ));
                }
            }
        }
    };

    // Calculate merge-base
    let merge_base = repo
        .merge_base(head_commit.id(), default_commit.id())
        .map_err(|e| {
            if e.code() == git2::ErrorCode::NotFound {
                io::Error::new(
                    io::ErrorKind::NotFound,
                    format!(
                        "No common ancestor between current branch and '{}' (unrelated branches)",
                        default_branch
                    ),
                )
            } else {
                to_io_error(&e)
            }
        })?;

    let oid = merge_base.to_string();
    write_start_commit_with_oid(repo_root, &oid)?;

    Ok(ResetStartCommitResult {
        oid,
        default_branch: Some(default_branch),
        fell_back_to_head: false,
    })
}

/// Start commit summary for display.
///
/// Contains information about the start commit for user display.
#[derive(Debug, Clone)]
pub struct StartCommitSummary {
    /// The start commit OID (short form, or None if not set).
    pub start_oid: Option<String>,
    /// Number of commits since start commit.
    pub commits_since: usize,
    /// Whether the start commit is stale (>10 commits behind).
    pub is_stale: bool,
}

impl StartCommitSummary {
    /// Format a compact version for inline display.
    pub fn format_compact(&self) -> String {
        match &self.start_oid {
            Some(oid) => {
                let short_oid = &oid[..8.min(oid.len())];
                if self.is_stale {
                    format!(
                        "Start: {} (+{} commits, STALE)",
                        short_oid, self.commits_since
                    )
                } else if self.commits_since > 0 {
                    format!("Start: {} (+{} commits)", short_oid, self.commits_since)
                } else {
                    format!("Start: {}", short_oid)
                }
            }
            None => "Start: not set".to_string(),
        }
    }
}

/// Get a summary of the start commit state for display.
///
/// Returns a `StartCommitSummary` containing information about the current
/// start commit, commits since start, and staleness status.
///
pub fn get_start_commit_summary() -> io::Result<StartCommitSummary> {
    let repo = git2::Repository::discover(".").map_err(|e| to_io_error(&e))?;
    let repo_root = repo
        .workdir()
        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "No workdir for repository"))?;
    get_start_commit_summary_impl(&repo, repo_root)
}

/// Implementation of get_start_commit_summary.
fn get_start_commit_summary_impl(
    repo: &git2::Repository,
    repo_root: &Path,
) -> io::Result<StartCommitSummary> {
    let start_oid = match load_start_point_impl(repo, repo_root)? {
        StartPoint::Commit(oid) => Some(oid.to_string()),
        StartPoint::EmptyRepo => None,
    };

    let (commits_since, is_stale) = if let Some(ref oid) = start_oid {
        // Get HEAD commit
        let head_oid = get_current_head_oid_impl(repo)?;
        let head_commit = repo
            .find_commit(git2::Oid::from_str(&head_oid).map_err(|_| {
                io::Error::new(io::ErrorKind::InvalidData, "Invalid HEAD OID format")
            })?)
            .map_err(|e| to_io_error(&e))?;

        let start_commit_oid = git2::Oid::from_str(oid)
            .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "Invalid start OID format"))?;

        let start_commit = repo
            .find_commit(start_commit_oid)
            .map_err(|e| to_io_error(&e))?;

        // Count commits between start and HEAD
        let mut revwalk = repo.revwalk().map_err(|e| to_io_error(&e))?;
        revwalk
            .push(head_commit.id())
            .map_err(|e| to_io_error(&e))?;

        let mut count = 0;
        for commit_id in revwalk {
            let commit_id = commit_id.map_err(|e| to_io_error(&e))?;
            if commit_id == start_commit.id() {
                break;
            }
            count += 1;
            if count > 1000 {
                break;
            }
        }

        let is_stale = count > 10;
        (count, is_stale)
    } else {
        (0, false)
    };

    Ok(StartCommitSummary {
        start_oid,
        commits_since,
        is_stale,
    })
}

#[cfg(test)]
fn has_start_commit() -> bool {
    load_start_point().is_ok()
}

/// Convert git2 error to `io::Error`.
fn to_io_error(err: &git2::Error) -> io::Error {
    io::Error::other(err.to_string())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_start_commit_file_path_defined() {
        // Verify the constant is defined correctly
        assert_eq!(START_COMMIT_FILE, ".agent/start_commit");
    }

    #[test]
    fn test_has_start_commit_returns_bool() {
        // This test verifies the function exists and returns a bool
        let result = has_start_commit();
        // The result depends on whether we're in a Ralph pipeline
        // We don't assert either way since the test environment varies
        let _ = result;
    }

    #[test]
    fn test_get_current_head_oid_returns_result() {
        // This test verifies the function exists and returns a Result
        let result = get_current_head_oid();
        // Should succeed if we're in a git repo with commits
        // We don't assert either way since the test environment varies
        let _ = result;
    }

    #[test]
    fn test_load_start_commit_returns_result() {
        // This test verifies load_start_point returns a Result
        // It will fail if the file doesn't exist, which is expected
        let result = load_start_point();
        assert!(result.is_ok() || result.is_err());
    }

    #[test]
    fn test_reset_start_commit_returns_result() {
        // This test verifies reset_start_commit returns a Result
        // It will fail if not in a git repo, which is expected
        let result = reset_start_commit();
        assert!(result.is_ok() || result.is_err());
    }

    #[test]
    fn test_save_start_commit_returns_result() {
        // This test verifies save_start_commit returns a Result
        // It will fail if not in a git repo, which is expected
        let result = save_start_commit();
        assert!(result.is_ok() || result.is_err());
    }

    // Integration tests would require a temporary git repository
    // For full integration tests, see tests/git_workflow.rs

    // =========================================================================
    // Workspace-aware function tests
    // =========================================================================

    #[test]
    fn test_write_start_point_with_workspace_commit() {
        use crate::workspace::MemoryWorkspace;

        let workspace = MemoryWorkspace::new_test();
        let oid = git2::Oid::from_str("abcd1234abcd1234abcd1234abcd1234abcd1234").unwrap();

        write_start_point_with_workspace(&workspace, StartPoint::Commit(oid)).unwrap();

        let content = workspace.get_file(".agent/start_commit").unwrap();
        assert_eq!(content, "abcd1234abcd1234abcd1234abcd1234abcd1234");
    }

    #[test]
    fn test_write_start_point_with_workspace_empty_repo() {
        use crate::workspace::MemoryWorkspace;

        let workspace = MemoryWorkspace::new_test();

        write_start_point_with_workspace(&workspace, StartPoint::EmptyRepo).unwrap();

        let content = workspace.get_file(".agent/start_commit").unwrap();
        assert_eq!(content, EMPTY_REPO_SENTINEL);
    }
}