girt 0.18.0

use crate::ObjectId;

/// One candidate tree leaf or collapsed sparse directory, with a byte path and cached stat data.
///
/// Fields are editable drafts. [`super::Index::new`] and [`super::Index::replace_entries`] check
/// paths and relationships before accepting them. Paths must have nonempty `/`-separated
/// components other than `.`, `..`, or `.git`, and contain no NUL. Sparse directories add one
/// trailing slash. No UTF-8, case folding,
/// platform aliases, backslashes, drive letters or checkout-safety checks are applied.
/// IDs are preserved even when zero; object existence and type remain caller obligations.
///
/// ```
/// use girt::index::{Entry, Mode, Stage};
/// use girt::{ObjectFormat, ObjectId};
/// let entry = Entry::new(
///     b"run.sh".to_vec(),
///     Mode::Executable,
///     ObjectId::for_blob(ObjectFormat::Sha1, b"#!/bin/sh\n"),
/// );
/// assert_eq!(entry.stage, Stage::Normal);
/// assert_eq!(entry.stat.size, 0); // Constructed entries have no observed filesystem metadata.
/// ```
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub struct Entry {
    /// Repository-relative path bytes; sparse directory paths have one trailing slash.
    pub path: Vec<u8>,
    /// Canonical leaf or sparse directory mode.
    pub mode: Mode,
    /// Identity in the index's selected object format; not resolved by index operations.
    pub id: ObjectId,
    /// Normal entry or side of an unresolved conflict.
    pub stage: Stage,
    /// Git's assume-valid bit; consumers must explicitly choose how to honor it.
    pub assume_valid: bool,
    /// Git's intent-to-add bit; the entry is a placeholder until content is staged.
    pub intent_to_add: bool,
    /// Git's skip-worktree bit; this codec does not apply sparse-checkout policy.
    pub skip_worktree: bool,
    /// Cached, uninterpreted 32-bit stat words; not proof the worktree is unchanged.
    pub stat: Stat,
}

impl Entry {
    /// Sets [`Self::stage`] on this draft entry.
    #[must_use]
    pub fn with_stage(mut self, stage: Stage) -> Self {
        self.stage = stage;
        self
    }

    /// Sets [`Self::assume_valid`] on this draft entry.
    #[must_use]
    pub fn with_assume_valid(mut self, assume_valid: bool) -> Self {
        self.assume_valid = assume_valid;
        self
    }

    /// Sets [`Self::intent_to_add`] on this draft entry.
    #[must_use]
    pub fn with_intent_to_add(mut self, intent_to_add: bool) -> Self {
        self.intent_to_add = intent_to_add;
        self
    }

    /// Sets [`Self::skip_worktree`] on this draft entry.
    #[must_use]
    pub fn with_skip_worktree(mut self, skip_worktree: bool) -> Self {
        self.skip_worktree = skip_worktree;
        self
    }

    /// Sets [`Self::stat`] on this draft entry.
    #[must_use]
    pub fn with_stat(mut self, stat: Stat) -> Self {
        self.stat = stat;
        self
    }

    /// Creates a stage-zero draft with zero stat words and all three entry flags cleared.
    ///
    /// Does not validate the path; validation occurs when constructing/replacing index entries.
    pub fn new(path: Vec<u8>, mode: Mode, id: ObjectId) -> Self {
        Self {
            path,
            mode,
            id,
            stage: Stage::Normal,
            assume_valid: false,
            intent_to_add: false,
            skip_worktree: false,
            stat: Stat::default(),
        }
    }
}

/// Canonical index modes. Sparse directories name trees; gitlinks name submodule commits.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[repr(u32)]
#[non_exhaustive]
pub enum Mode {
    /// Collapsed sparse directory tree, `040000`, with a trailing slash and skip-worktree.
    SparseDirectory = 0o040000,
    /// Non-executable regular file, `100644`.
    Regular = 0o100644,
    /// Executable regular file, `100755`.
    Executable = 0o100755,
    /// Symbolic link payload, `120000`; reading does not create a symlink.
    Symlink = 0o120000,
    /// Submodule commit, `160000`; reading does not open the submodule.
    Gitlink = 0o160000,
}

/// An entry's position in a conflict, ordered by its on-disk stage number.
///
/// A path has either one normal entry or any nonempty subset of stages 1, 2 and 3. Missing
/// sides represent absent files. Duplicate stages and mixing normal/conflict entries are invalid.
/// This set is exhaustive because the on-disk stage occupies exactly two bits.
///
/// Keep each conflict side under the same path; resolving it replaces those sides with one
/// [`Stage::Normal`] entry. Stage numbers describe merge inputs, not separate working files.
///
/// ```
/// use girt::index::{Entry, Index, Limits, Mode, Stage};
/// use girt::{ObjectFormat, ObjectId};
///
/// let format = ObjectFormat::Sha1;
/// let ours = Entry::new(
///     b"file".to_vec(),
///     Mode::Regular,
///     ObjectId::for_blob(format, b"ours"),
/// )
/// .with_stage(Stage::Ours);
/// let theirs = Entry::new(
///     b"file".to_vec(),
///     Mode::Regular,
///     ObjectId::for_blob(format, b"theirs"),
/// )
/// .with_stage(Stage::Theirs);
///
/// let mut index = Index::new(format, vec![theirs, ours.clone()], Limits::default())?;
/// assert_eq!(index.entries()[0].stage, Stage::Ours);
///
/// index.replace_entries(vec![ours.with_stage(Stage::Normal)], Limits::default())?;
/// assert_eq!(index.entries().len(), 1);
/// # Ok::<(), girt::index::Error>(())
/// ```
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[repr(u16)]
pub enum Stage {
    /// Resolved entry, stage 0.
    #[default]
    Normal = 0,
    /// Common ancestor, stage 1.
    Base = 1,
    /// Our side, stage 2.
    Ours = 2,
    /// Their side, stage 3.
    Theirs = 3,
}

/// Raw seconds and nanosecond words retained exactly from the index.
///
/// These are unsigned on-disk words, not host timestamps. No range validation, clock conversion,
/// precision inference or comparison is performed, including for the nanosecond word.
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
pub struct Timestamp {
    /// Raw seconds word.
    pub seconds: u32,
    /// Raw nanosecond-fraction word.
    pub nanoseconds: u32,
}

/// Cached filesystem metadata, retaining every on-disk word exactly.
///
/// Zero is useful for constructed entries that need later refresh. Callers must account for Git's
/// racy-stat rules before trusting cached data; this API does not detect worktree modifications.
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
pub struct Stat {
    /// Metadata-change time.
    pub ctime: Timestamp,
    /// Content-change time.
    pub mtime: Timestamp,
    /// Device word.
    pub device: u32,
    /// Inode word.
    pub inode: u32,
    /// User ID word.
    pub uid: u32,
    /// Group ID word.
    pub gid: u32,
    /// File size modulo 2^32.
    pub size: u32,
}