#![allow(clippy::result_large_err)]
//! Submodule plumbing and abstractions
//!
use std::{
    cell::{Ref, RefCell, RefMut},
    path::{Path, PathBuf},
};

pub use gix_submodule::*;

use crate::{
    Repository, Submodule,
    bstr::{BStr, BString},
    is_dir_to_mode,
    worktree::IndexPersistedOrInMemory,
};

pub(crate) type ModulesFileStorage = gix_features::threading::OwnShared<gix_fs::SharedFileSnapshotMut<File>>;
/// A lazily loaded and auto-updated worktree index.
pub type ModulesSnapshot = gix_fs::SharedFileSnapshot<File>;

/// The name of the file containing (sub) module information.
pub(crate) const MODULES_FILE: &str = ".gitmodules";

mod errors;
pub use errors::*;

/// A platform maintaining state needed to interact with submodules, created by [`Repository::submodules()].
pub(crate) struct SharedState<'repo> {
    pub repo: &'repo Repository,
    pub(crate) modules: ModulesSnapshot,
    is_active: RefCell<Option<IsActiveState>>,
    index: RefCell<Option<IndexPersistedOrInMemory>>,
}

impl<'repo> SharedState<'repo> {
    pub(crate) fn new(repo: &'repo Repository, modules: ModulesSnapshot) -> Self {
        SharedState {
            repo,
            modules,
            is_active: RefCell::new(None),
            index: RefCell::new(None),
        }
    }

    fn index(&self) -> Result<Ref<'_, IndexPersistedOrInMemory>, crate::repository::index_or_load_from_head::Error> {
        {
            let mut state = self.index.borrow_mut();
            if state.is_none() {
                *state = self.repo.index_or_load_from_head()?.into();
            }
        }
        Ok(Ref::map(self.index.borrow(), |opt| {
            opt.as_ref().expect("just initialized")
        }))
    }

    fn active_state_mut(
        &self,
    ) -> Result<(RefMut<'_, IsActivePlatform>, RefMut<'_, gix_worktree::Stack>), is_active::Error> {
        let mut state = self.is_active.borrow_mut();
        if state.is_none() {
            let platform = self
                .modules
                .is_active_platform(&self.repo.config.resolved, self.repo.config.pathspec_defaults()?)?;
            let index = self.index()?;
            let attributes = self
                .repo
                .attributes_only(
                    &index,
                    gix_worktree::stack::state::attributes::Source::WorktreeThenIdMapping
                        .adjust_for_bare(self.repo.is_bare()),
                )?
                .detach();
            *state = Some(IsActiveState { platform, attributes });
        }
        Ok(RefMut::map_split(state, |opt| {
            let state = opt.as_mut().expect("populated above");
            (&mut state.platform, &mut state.attributes)
        }))
    }
}

struct IsActiveState {
    platform: IsActivePlatform,
    attributes: gix_worktree::Stack,
}

///Access
impl Submodule<'_> {
    /// Return the submodule's configured name as it appears in `submodule.<name>.*`.
    ///
    /// Note that this name is not guaranteed to be valid and may contain traversal components if
    /// the configuration was crafted manually.
    ///
    /// Use [`validated_name()`](Self::validated_name()) to obtain a validated submodule name.
    pub fn name(&self) -> &BStr {
        self.name.as_ref()
    }

    /// Return the submodule's name after validating it for safe use in paths like `.git/modules/<name>`.
    pub fn validated_name(&self) -> Result<&BStr, gix_validate::submodule::name::Error> {
        gix_validate::submodule::name(self.name())
    }
    /// Return the path at which the submodule can be found, relative to the repository.
    ///
    /// For details, see [gix_submodule::File::path()].
    pub fn path(&self) -> Result<BString, config::path::Error> {
        self.state.modules.path(self.name())
    }

    /// Return the url from which to clone or update the submodule.
    ///
    /// This method takes into consideration submodule configuration overrides.
    pub fn url(&self) -> Result<gix_url::Url, config::url::Error> {
        self.state.modules.url(self.name())
    }

    /// Return the `update` field from this submodule's configuration, if present, or `None`.
    ///
    /// This method takes into consideration submodule configuration overrides.
    pub fn update(&self) -> Result<Option<config::Update>, config::update::Error> {
        self.state.modules.update(self.name())
    }

    /// Return the `branch` field from this submodule's configuration, if present, or `None`.
    ///
    /// This method takes into consideration submodule configuration overrides.
    pub fn branch(&self) -> Result<Option<config::Branch>, config::branch::Error> {
        self.state.modules.branch(self.name())
    }

    /// Return the `fetchRecurseSubmodules` field from this submodule's configuration, or retrieve the value from `fetch.recurseSubmodules` if unset.
    pub fn fetch_recurse(&self) -> Result<Option<config::FetchRecurse>, fetch_recurse::Error> {
        Ok(match self.state.modules.fetch_recurse(self.name())? {
            Some(val) => Some(val),
            None => crate::config::tree::Fetch::RECURSE_SUBMODULES
                .try_into_recurse_submodules(self.state.repo.config.resolved.boolean("fetch.recurseSubmodules"))?,
        })
    }

    /// Return the `ignore` field from this submodule's configuration, if present, or `None`.
    ///
    /// This method takes into consideration submodule configuration overrides.
    pub fn ignore(&self) -> Result<Option<config::Ignore>, config::Error> {
        self.state.modules.ignore(self.name())
    }

    /// Return the `shallow` field from this submodule's configuration, if present, or `None`.
    ///
    /// If `true`, the submodule will be checked out with `depth = 1`. If unset, `false` is assumed.
    pub fn shallow(&self) -> Result<Option<bool>, gix_config::value::Error> {
        self.state.modules.shallow(self.name())
    }

    /// Returns true if this submodule is considered active and can thus participate in an operation.
    ///
    /// Please see the [plumbing crate documentation](gix_submodule::IsActivePlatform::is_active()) for details.
    pub fn is_active(&self) -> Result<bool, is_active::Error> {
        let (mut platform, mut attributes) = self.state.active_state_mut()?;
        let is_active = platform.is_active(
            &self.state.repo.config.resolved,
            self.name.as_ref(),
            &mut |relative_path, case, is_dir, out| {
                attributes
                    .set_case(case)
                    .at_entry(relative_path, Some(is_dir_to_mode(is_dir)), &self.state.repo.objects)
                    .is_ok_and(|platform| platform.matching_attributes(out))
            },
        )?;
        Ok(is_active)
    }

    /// Return the object id of the submodule as stored in the index of the superproject,
    /// or `None` if it was deleted from the index.
    ///
    /// If `None`, but `Some()` when calling [`Self::head_id()`], then the submodule was just deleted but the change
    /// wasn't yet committed. Note that `None` is also returned if the entry at the submodule path isn't a submodule.
    /// If `Some()`, but `None` when calling [`Self::head_id()`], then the submodule was just added without having committed the change.
    pub fn index_id(&self) -> Result<Option<gix_hash::ObjectId>, index_id::Error> {
        let path = self.path()?;
        Ok(self
            .state
            .index()?
            .entry_by_path(BStr::new(&path))
            .and_then(|entry| (entry.mode == gix_index::entry::Mode::COMMIT).then_some(entry.id)))
    }

    /// Return the object id of the submodule as stored in `HEAD^{tree}` of the superproject, or `None` if it wasn't yet committed.
    ///
    /// If `Some()`, but `None` when calling [`Self::index_id()`], then the submodule was just deleted but the change
    /// wasn't yet committed. Note that `None` is also returned if the entry at the submodule path isn't a submodule.
    /// If `None`, but `Some()` when calling [`Self::index_id()`], then the submodule was just added without having committed the change.
    pub fn head_id(&self) -> Result<Option<gix_hash::ObjectId>, head_id::Error> {
        let path = self.path()?;
        Ok(self
            .state
            .repo
            .head_commit()?
            .tree()?
            .peel_to_entry_by_path(gix_path::from_bstring(path))?
            .and_then(|entry| (entry.mode().is_commit()).then_some(entry.inner.oid)))
    }

    /// Return the path at which the repository of the submodule should be located.
    ///
    /// The retunred directory might not exist yet.
    pub fn git_dir(&self) -> Result<PathBuf, gix_validate::submodule::name::Error> {
        Ok(git_dir_from_name(self.state.repo.common_dir(), self.validated_name()?))
    }

    /// Return the path to the location at which the workdir would be checked out.
    ///
    /// Note that it may be a path relative to the repository if, for some reason, the parent directory
    /// doesn't have a working dir set.
    pub fn work_dir(&self) -> Result<PathBuf, config::path::Error> {
        let worktree_git = gix_path::from_bstr(self.path()?);
        Ok(match self.state.repo.workdir() {
            None => worktree_git.into_owned(),
            Some(prefix) => prefix.join(worktree_git),
        })
    }

    /// Return the path at which the repository of the submodule should be located, or the path inside of
    /// the superproject's worktree where it actually *is* located if the submodule in the 'old-form', thus is a directory
    /// inside of the superproject's work-tree.
    ///
    /// Note that paths returned aren't fully verified, i.e. the `.git` repository might be corrupt or otherwise
    /// invalid - it's left to the caller to try to open it. `.git` files are parsed when present and their target
    /// is required to be a directory though, as a malformed gitdir file means a broken submodule checkout.
    ///
    /// Also note that the fallback path returned for uninitialized submodules may not actually exist.
    pub fn git_dir_try_old_form(&self) -> Result<PathBuf, git_dir_try_old_form::Error> {
        self.git_dir_try_old_form_inner(true)
    }

    /// Return the best-known submodule repository path, optionally parsing a `.git` file target
    /// and requiring it to be a directory if `validate_gitdir_file_target` is `true`.
    ///
    /// Validation may be skipped when callers only need coarse state, like `status_opts()` with
    /// `Ignore::All`, which returns before opening or inspecting the submodule repository.
    fn git_dir_try_old_form_inner(
        &self,
        validate_gitdir_file_target: bool,
    ) -> Result<PathBuf, git_dir_try_old_form::Error> {
        let git_dir = self.git_dir()?;
        let worktree_gitdir = self.worktree_gitdir()?;
        let git_dir = if worktree_gitdir.is_dir() {
            worktree_gitdir
        } else if worktree_gitdir.is_file() {
            if validate_gitdir_file_target {
                let git_dir = gix_discover::path::from_gitdir_file(&worktree_gitdir).map_err(|source| {
                    git_dir_try_old_form::Error::InvalidGitDirFileTarget {
                        gitdir_file: worktree_gitdir.clone(),
                        target: None,
                        source: Some(source),
                    }
                })?;
                if !git_dir.is_dir() {
                    return Err(git_dir_try_old_form::Error::InvalidGitDirFileTarget {
                        gitdir_file: worktree_gitdir,
                        target: Some(git_dir),
                        source: None,
                    });
                }
                git_dir
            } else {
                gix_discover::path::from_gitdir_file(&worktree_gitdir).unwrap_or(git_dir)
            }
        } else {
            git_dir
        };
        Ok(git_dir)
    }

    fn state_inner(&self, validate_gitdir_file_target: bool) -> Result<State, state::Error> {
        let maybe_old_path = self.git_dir_try_old_form_inner(validate_gitdir_file_target)?;
        let worktree_git = self.worktree_gitdir()?;
        let superproject_configuration = self
            .state
            .repo
            .config
            .resolved
            .sections_by_name("submodule")
            .into_iter()
            .flatten()
            .any(|section| section.header().subsection_name() == Some(self.name.as_ref()));
        Ok(State {
            repository_exists: maybe_old_path.is_dir(),
            is_old_form: worktree_git.is_dir(),
            worktree_checkout: worktree_git.exists(),
            superproject_configuration,
        })
    }

    /// Query various parts of the submodule and assemble it into state information.
    #[doc(alias = "status", alias = "git2")]
    pub fn state(&self) -> Result<State, state::Error> {
        self.state_inner(true)
    }

    /// Open the submodule as repository, or `None` if the submodule wasn't initialized yet.
    ///
    /// More states can be derived here:
    ///
    /// * *initialized* - a repository exists, i.e. `Some(repo)` and the working tree is present.
    /// * *uninitialized* - a repository does not exist, i.e. `None`
    /// * *deinitialized* - a repository does exist, i.e. `Some(repo)`, but its working tree is empty.
    ///
    /// Also see the [state()](Self::state()) method for learning about the submodule.
    /// The repository can also be used to learn about the submodule `HEAD`, i.e. where its working tree is at,
    /// which may differ compared to the superproject's index or `HEAD` commit.
    pub fn open(&self) -> Result<Option<Repository>, open::Error> {
        let mut options = self.state.repo.options.clone();
        options.git_dir_trust = None;
        match crate::open_opts(self.git_dir_try_old_form()?, options) {
            Ok(mut repo) => {
                if repo.workdir().is_none() {
                    let wd = self.work_dir()?;
                    // We should always have a workdir, as bare submodules don't exist.
                    // However, it's possible for no workdir to be accessible if there is a symlink in the way.
                    // Just setting it by hand fixes this issue effectively, even though the question remains
                    // if this should work automatically.
                    // For now, let's *not* use the `self.worktree_git()` directory which has its own edge-cases,
                    // while the current solution yields the cleanest paths (i.e. it keeps relative ones).
                    repo.set_workdir(Some(wd))?;
                }
                Ok(Some(repo))
            }
            Err(crate::open::Error::NotARepository { .. }) => Ok(None),
            Err(err) => Err(err.into()),
        }
    }

    fn worktree_gitdir(&self) -> Result<PathBuf, config::path::Error> {
        Ok(self.work_dir()?.join(gix_discover::DOT_GIT_DIR))
    }
}

/// Append the name textually, like Git's `repo_git_path_append(..., "modules/%s", name)`.
///
/// In particular, don't use `Path::join()` for `name`: absolute-looking names are valid in Git,
/// but joining them as a path would discard the `.git/modules` prefix.
fn git_dir_from_name(common_dir: &Path, name: &BStr) -> PathBuf {
    let mut git_dir = common_dir.join("modules").into_os_string();
    git_dir.push(std::path::MAIN_SEPARATOR_STR);
    git_dir.push(gix_path::from_bstr(name).as_os_str());
    git_dir.into()
}

#[cfg(test)]
mod tests {
    use std::path::Path;

    use crate::bstr::ByteSlice;

    #[test]
    fn git_dir_from_name_keeps_git_compatible_names_below_modules() {
        let common_dir = Path::new("repo").join(".git");
        let modules_dir = common_dir.join("modules");

        for name in [
            b"/etc/cron.d/x" as &[u8],
            br"\Windows\Temp\x",
            br"\\host\share\x",
            b"//host/share/x",
            br"C:\Windows\Temp\x",
            b"C:/Windows/Temp/x",
            b"C:x",
        ] {
            let actual = super::git_dir_from_name(&common_dir, name.as_bstr());
            assert!(
                actual.starts_with(&modules_dir),
                "Git-compatible name {name:?} must remain below {} instead of producing {}",
                modules_dir.display(),
                actual.display()
            );
        }
    }
}

///
#[cfg(feature = "status")]
pub mod status {
    use gix_submodule::config;

    use super::{Status, head_id, index_id, open, state};
    use crate::Submodule;

    /// The error returned by [Submodule::status()].
    #[derive(Debug, thiserror::Error)]
    #[expect(missing_docs)]
    pub enum Error {
        #[error(transparent)]
        State(#[from] state::Error),
        #[error(transparent)]
        HeadId(#[from] head_id::Error),
        #[error(transparent)]
        IndexId(#[from] index_id::Error),
        #[error(transparent)]
        OpenRepository(#[from] open::Error),
        #[error(transparent)]
        IgnoreConfiguration(#[from] config::Error),
        #[error(transparent)]
        StatusPlatform(#[from] crate::status::Error),
        #[error(transparent)]
        StatusIter(#[from] crate::status::into_iter::Error),
        #[error(transparent)]
        NextStatusItem(#[from] crate::status::iter::Error),
    }

    impl Submodule<'_> {
        /// Return the status of the submodule.
        ///
        /// Use `ignore` to control the portion of the submodule status to ignore. It can be obtained from
        /// submodule configuration using the [`ignore()`](Submodule::ignore()) method.
        /// If `check_dirty` is `true`, the computation will stop once the first in a ladder operations
        /// ordered from cheap to expensive shows that the submodule is dirty.
        /// Thus, submodules that are clean will still impose the complete set of computation, as given.
        #[doc(alias = "submodule_status", alias = "git2")]
        pub fn status(
            &self,
            ignore: config::Ignore,
            check_dirty: bool,
        ) -> Result<crate::submodule::status::types::Status, Error> {
            self.status_opts(ignore, check_dirty, &mut |s| s)
        }
        /// Return the status of the submodule, just like [`status`](Self::status), but allows to adjust options
        /// for more control over how the status is performed.
        ///
        /// If `check_dirty` is `true`, the computation will stop once the first in a ladder operations
        /// ordered from cheap to expensive shows that the submodule is dirty. When checking for detailed
        /// status information (i.e. untracked file, modifications, HEAD-index changes) only the first change
        /// will be kept to stop as early as possible.
        ///
        /// Use `&mut std::convert::identity` for `adjust_options` if no specific options are desired.
        /// A reason to change them might be to enable sorting to enjoy deterministic order of changes.
        ///
        /// The status allows to easily determine if a submodule [has changes](Status::is_dirty).
        #[doc(alias = "submodule_status", alias = "git2")]
        pub fn status_opts(
            &self,
            ignore: config::Ignore,
            check_dirty: bool,
            adjust_options: &mut dyn for<'a> FnMut(
                crate::status::Platform<'a, gix_features::progress::Discard>,
            )
                -> crate::status::Platform<'a, gix_features::progress::Discard>,
        ) -> Result<Status, Error> {
            let mut state = self.state_inner(ignore != config::Ignore::All)?;
            if ignore == config::Ignore::All {
                return Ok(Status {
                    state,
                    ..Default::default()
                });
            }

            let index_id = self.index_id()?;
            if !state.repository_exists {
                return Ok(Status {
                    state,
                    index_id,
                    ..Default::default()
                });
            }
            let sm_repo = match self.open()? {
                None => {
                    state.repository_exists = false;
                    return Ok(Status {
                        state,
                        index_id,
                        ..Default::default()
                    });
                }
                Some(repo) => repo,
            };

            let checked_out_head_id = sm_repo.head_id().ok().map(crate::Id::detach);
            let mut status = Status {
                state,
                index_id,
                checked_out_head_id,
                ..Default::default()
            };
            if ignore == config::Ignore::Dirty || check_dirty && status.is_dirty() == Some(true) {
                return Ok(status);
            }

            if !state.worktree_checkout {
                return Ok(status);
            }
            let statuses = adjust_options(sm_repo.status(gix_features::progress::Discard)?)
                .index_worktree_options_mut(|opts| {
                    if ignore == config::Ignore::Untracked {
                        opts.dirwalk_options = None;
                    }
                })
                .into_iter(None)?;
            let mut changes = Vec::new();
            for change in statuses {
                changes.push(change?);
                if check_dirty {
                    break;
                }
            }
            status.changes = Some(changes);
            Ok(status)
        }
    }

    impl Status {
        /// Return `Some(true)` if the submodule status could be determined sufficiently and
        /// if there are changes that would render this submodule dirty.
        ///
        /// Return `Some(false)` if the submodule status could be determined and it has no changes
        /// at all.
        ///
        /// Return `None` if the repository clone or the worktree are missing entirely, which would leave
        /// it to the caller to determine if that's considered dirty or not.
        pub fn is_dirty(&self) -> Option<bool> {
            if !self.state.worktree_checkout || !self.state.repository_exists {
                return None;
            }
            let is_dirty =
                self.checked_out_head_id != self.index_id || self.changes.as_ref().is_some_and(|c| !c.is_empty());
            Some(is_dirty)
        }
    }

    pub(super) mod types {
        use crate::submodule::State;

        /// A simplified status of the Submodule.
        ///
        /// As opposed to the similar-sounding [`State`], it is more exhaustive and potentially expensive to compute,
        /// particularly for submodules without changes.
        ///
        /// It's produced by [Submodule::status()](crate::Submodule::status()).
        #[derive(Default, Clone, PartialEq, Debug)]
        pub struct Status {
            /// The cheapest part of the status that is always performed, to learn if the repository is cloned
            /// and if there is a worktree checkout.
            pub state: State,
            /// The commit at which the submodule is supposed to be according to the super-project's index.
            /// `None` means the computation wasn't performed, or the submodule didn't exist in the super-project's index anymore.
            pub index_id: Option<gix_hash::ObjectId>,
            /// The commit-id of the `HEAD` at which the submodule is currently checked out.
            /// `None` if the computation wasn't performed as it was skipped early, or if no repository was available or
            /// if the HEAD could not be obtained or wasn't born.
            pub checked_out_head_id: Option<gix_hash::ObjectId>,
            /// The set of changes obtained from running something akin to `git status` in the submodule working tree.
            ///
            /// `None` if the computation wasn't performed as the computation was skipped early, or if no working tree was
            /// available or repository was available.
            pub changes: Option<Vec<crate::status::Item>>,
        }
    }
}
#[cfg(feature = "status")]
pub use status::types::Status;

/// A summary of the state of all parts forming a submodule, which allows to answer various questions about it.
///
/// Note that expensive questions about its presence in the `HEAD` or the `index` are left to the caller.
#[derive(Default, Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
pub struct State {
    /// if the submodule repository has been cloned.
    pub repository_exists: bool,
    /// if the submodule repository is located directly in the worktree of the superproject.
    pub is_old_form: bool,
    /// if the worktree is checked out.
    pub worktree_checkout: bool,
    /// If submodule configuration was found in the superproject's `.git/config` file.
    /// Note that the presence of a single section is enough, independently of the actual values.
    pub superproject_configuration: bool,
}