use-git-ref 0.0.1

#![forbid(unsafe_code)]
#![doc = include_str!("../README.md")]

use core::{fmt, str::FromStr};
use std::error::Error;

/// Error returned while parsing ref vocabulary.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum GitRefParseError {
    /// The supplied ref text was empty.
    Empty,
    /// The supplied ref name used syntax this crate rejects.
    InvalidName,
    /// The supplied detached `HEAD` target was empty.
    EmptyDetachedTarget,
}

impl fmt::Display for GitRefParseError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => formatter.write_str("Git ref name cannot be empty"),
            Self::InvalidName => formatter.write_str("invalid Git ref name"),
            Self::EmptyDetachedTarget => {
                formatter.write_str("detached HEAD target cannot be empty")
            },
        }
    }
}

impl Error for GitRefParseError {}

/// A broad ref-name kind.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub enum GitRefKind {
    /// The `HEAD` pseudo-ref.
    Head,
    /// A branch ref under `refs/heads/`.
    Branch,
    /// A tag ref under `refs/tags/`.
    Tag,
    /// A remote-tracking ref under `refs/remotes/`.
    Remote,
    /// Another syntactically valid ref name.
    Other,
}

impl GitRefKind {
    /// Returns the stable kind label.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Head => "head",
            Self::Branch => "branch",
            Self::Tag => "tag",
            Self::Remote => "remote",
            Self::Other => "other",
        }
    }
}

impl fmt::Display for GitRefKind {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

fn ref_kind(value: &str) -> GitRefKind {
    if value == "HEAD" {
        GitRefKind::Head
    } else if value.starts_with("refs/heads/") {
        GitRefKind::Branch
    } else if value.starts_with("refs/tags/") {
        GitRefKind::Tag
    } else if value.starts_with("refs/remotes/") {
        GitRefKind::Remote
    } else {
        GitRefKind::Other
    }
}

fn has_lock_suffix(value: &str) -> bool {
    value
        .get(value.len().saturating_sub(5)..)
        .is_some_and(|suffix| suffix.eq_ignore_ascii_case(".lock"))
}

fn validate_ref_name(value: impl AsRef<str>) -> Result<String, GitRefParseError> {
    let trimmed = value.as_ref().trim();

    if trimmed.is_empty() {
        return Err(GitRefParseError::Empty);
    }

    if trimmed == "HEAD" {
        return Ok(trimmed.to_string());
    }

    let invalid = trimmed.starts_with('/')
        || trimmed.ends_with('/')
        || trimmed.starts_with('.')
        || trimmed.ends_with('.')
        || has_lock_suffix(trimmed)
        || trimmed.contains("//")
        || trimmed.contains("..")
        || trimmed.contains("@{")
        || trimmed.chars().any(|character| {
            character.is_ascii_control()
                || character.is_ascii_whitespace()
                || matches!(character, '~' | '^' | ':' | '?' | '*' | '[' | '\\')
        })
        || trimmed.split('/').any(|component| component.ends_with('.'));

    if invalid {
        Err(GitRefParseError::InvalidName)
    } else {
        Ok(trimmed.to_string())
    }
}

/// A validated ref name.
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct GitRefName {
    value: String,
    kind: GitRefKind,
}

impl GitRefName {
    /// Creates a ref name from text.
    ///
    /// # Errors
    ///
    /// Returns [`GitRefParseError`] when the name is empty or uses rejected syntax.
    pub fn new(value: impl AsRef<str>) -> Result<Self, GitRefParseError> {
        let value = validate_ref_name(value)?;
        let kind = ref_kind(&value);
        Ok(Self { value, kind })
    }

    /// Returns the broad ref kind.
    #[must_use]
    pub const fn kind(&self) -> GitRefKind {
        self.kind
    }

    /// Returns true when this is `HEAD`.
    #[must_use]
    pub const fn is_head(&self) -> bool {
        matches!(self.kind, GitRefKind::Head)
    }

    /// Returns true when this is a branch ref.
    #[must_use]
    pub const fn is_branch(&self) -> bool {
        matches!(self.kind, GitRefKind::Branch)
    }

    /// Returns true when this is a tag ref.
    #[must_use]
    pub const fn is_tag(&self) -> bool {
        matches!(self.kind, GitRefKind::Tag)
    }

    /// Returns true when this is a remote-tracking ref.
    #[must_use]
    pub const fn is_remote(&self) -> bool {
        matches!(self.kind, GitRefKind::Remote)
    }

    /// Returns the ref name text.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.value
    }
}

impl AsRef<str> for GitRefName {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl fmt::Display for GitRefName {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl FromStr for GitRefName {
    type Err = GitRefParseError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        Self::new(value)
    }
}

impl TryFrom<&str> for GitRefName {
    type Error = GitRefParseError;

    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

/// A concrete ref wrapper.
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct GitRef(GitRefName);

impl GitRef {
    /// Creates a concrete ref from a ref name.
    #[must_use]
    pub const fn from_name(name: GitRefName) -> Self {
        Self(name)
    }

    /// Parses a concrete ref from text.
    ///
    /// # Errors
    ///
    /// Returns [`GitRefParseError`] when the ref name is invalid.
    pub fn new(value: impl AsRef<str>) -> Result<Self, GitRefParseError> {
        GitRefName::new(value).map(Self)
    }

    /// Returns the ref name.
    #[must_use]
    pub const fn name(&self) -> &GitRefName {
        &self.0
    }

    /// Returns the ref kind.
    #[must_use]
    pub const fn kind(&self) -> GitRefKind {
        self.0.kind()
    }

    /// Returns the ref text.
    #[must_use]
    pub fn as_str(&self) -> &str {
        self.0.as_str()
    }
}

impl AsRef<str> for GitRef {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl fmt::Display for GitRef {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl FromStr for GitRef {
    type Err = GitRefParseError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        Self::new(value)
    }
}

/// A symbolic ref target.
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct SymbolicRef {
    target: GitRefName,
}

impl SymbolicRef {
    /// Creates a symbolic ref target from a validated ref name.
    #[must_use]
    pub const fn new(target: GitRefName) -> Self {
        Self { target }
    }

    /// Parses a symbolic ref target from text.
    ///
    /// # Errors
    ///
    /// Returns [`GitRefParseError`] when the target ref name is invalid.
    pub fn parse(value: impl AsRef<str>) -> Result<Self, GitRefParseError> {
        GitRefName::new(value).map(Self::new)
    }

    /// Returns the target ref name.
    #[must_use]
    pub const fn target(&self) -> &GitRefName {
        &self.target
    }

    /// Returns the target ref text.
    #[must_use]
    pub fn as_str(&self) -> &str {
        self.target.as_str()
    }
}

impl fmt::Display for SymbolicRef {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl FromStr for SymbolicRef {
    type Err = GitRefParseError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        Self::parse(value)
    }
}

/// A lightweight `HEAD` vocabulary value.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum GitHead {
    /// `HEAD` exists as a symbolic ref.
    Symbolic(SymbolicRef),
    /// `HEAD` names object identifier text directly.
    Detached(String),
    /// `HEAD` is known as vocabulary, but no target is modeled.
    Unborn,
}

impl GitHead {
    /// Creates symbolic `HEAD` from a target ref name.
    #[must_use]
    pub const fn symbolic(target: GitRefName) -> Self {
        Self::Symbolic(SymbolicRef::new(target))
    }

    /// Creates detached `HEAD` from object identifier text.
    ///
    /// # Errors
    ///
    /// Returns [`GitRefParseError::EmptyDetachedTarget`] when the supplied text is empty.
    pub fn detached(value: impl AsRef<str>) -> Result<Self, GitRefParseError> {
        let trimmed = value.as_ref().trim();
        if trimmed.is_empty() {
            Err(GitRefParseError::EmptyDetachedTarget)
        } else {
            Ok(Self::Detached(trimmed.to_string()))
        }
    }

    /// Returns true when `HEAD` is symbolic.
    #[must_use]
    pub const fn is_symbolic(&self) -> bool {
        matches!(self, Self::Symbolic(_))
    }

    /// Returns true when `HEAD` is detached.
    #[must_use]
    pub const fn is_detached(&self) -> bool {
        matches!(self, Self::Detached(_))
    }

    /// Returns the symbolic target when present.
    #[must_use]
    pub const fn symbolic_ref(&self) -> Option<&SymbolicRef> {
        match self {
            Self::Symbolic(symbolic) => Some(symbolic),
            Self::Detached(_) | Self::Unborn => None,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{GitHead, GitRefKind, GitRefName, GitRefParseError, SymbolicRef};

    #[test]
    fn classifies_common_refs() -> Result<(), GitRefParseError> {
        let branch = GitRefName::new("refs/heads/main")?;
        let tag = GitRefName::new("refs/tags/v1.0.0")?;
        let remote = GitRefName::new("refs/remotes/origin/main")?;

        assert_eq!(branch.kind(), GitRefKind::Branch);
        assert_eq!(tag.kind(), GitRefKind::Tag);
        assert_eq!(remote.kind(), GitRefKind::Remote);
        Ok(())
    }

    #[test]
    fn models_symbolic_head() -> Result<(), GitRefParseError> {
        let symbolic = SymbolicRef::parse("refs/heads/main")?;
        let head = GitHead::Symbolic(symbolic);

        assert!(head.is_symbolic());
        assert_eq!(
            head.symbolic_ref().map(SymbolicRef::as_str),
            Some("refs/heads/main")
        );
        Ok(())
    }

    #[test]
    fn rejects_invalid_refs() {
        assert_eq!(GitRefName::new(""), Err(GitRefParseError::Empty));
        assert_eq!(
            GitRefName::new("refs/heads/main.lock"),
            Err(GitRefParseError::InvalidName)
        );
        assert_eq!(
            GitRefName::new("refs/heads/with space"),
            Err(GitRefParseError::InvalidName)
        );
    }
}