mlua_pkg/

fetcher.rs

//! Git-based package fetcher.
//!
//! The [`Fetcher`] trait abstracts over different fetch backends (git, luarocks,
//! http).  [`GitFetcher`] implements the git backend using libgit2 via the
//! [`git2`] crate.  No subprocess `git` invocations are used.
//!
//! # Cache layout
//!
//! ```text
//! <cache_root>/git/<host>/<path…>/<sha>/
//! ```
//!
//! For example, `https://github.com/ynishi/lshape` at SHA `abc123` becomes:
//!
//! ```text
//! <cache_root>/git/github.com/ynishi/lshape/abc123/
//! ```
//!
//! # Cache hit without a clone
//!
//! Before cloning, the ref is resolved cheaply:
//!
//! | pin | network needed to resolve |
//! |-----|---------------------------|
//! | `rev` = full 40-hex SHA | none |
//! | `tag` (exact or prefix) / `branch` / no pin | one `ls-remote` (ref listing, no objects) |
//! | `rev` = short SHA / revspec | falls through to a clone |
//!
//! If `<cache_root>/git/<host>/<path…>/<sha>/` already exists for the
//! resolved SHA, that directory is returned as is and **no clone happens**.
//! Only a cache miss pays for a full clone (into a temp dir, then renamed
//! into place).
//!
//! # Authentication
//!
//! `GitFetcher` uses a `RemoteCallbacks`-based credential cascade:
//!
//! 1. SSH agent (`Cred::ssh_key_from_agent`) — tried only when the remote
//!    advertises `SSH_KEY` in `allowed_types`.
//! 2. Credential helper (`Cred::credential_helper`) — tried when `USER_PASS_PLAINTEXT`
//!    is advertised.
//! 3. `Cred::default()` — last resort.
//!
//! The callback tracks attempted credential types to avoid infinite retry loops.

use std::{
    path::{Component, PathBuf},
    sync::atomic::{AtomicU64, AtomicU8, Ordering},
};

use git2::{build::RepoBuilder, CredentialType, FetchOptions, RemoteCallbacks, Repository};

use crate::{
    manifest::{Dep, Manifest},
    PkgError,
};

/// Monotonic counter for unique temp-clone directory names within one process.
static TMP_CTR: AtomicU64 = AtomicU64::new(0);

// Test-only: number of full clones performed on the current thread, so a
// test can assert that a cache hit did not clone.  Thread-local because
// the test harness runs tests in parallel.
#[cfg(test)]
thread_local! {
    static CLONE_CTR: std::cell::Cell<u64> = const { std::cell::Cell::new(0) };
}

#[cfg(test)]
fn clone_count() -> u64 {
    CLONE_CTR.with(|c| c.get())
}

// ── Fetcher trait ─────────────────────────────────────────────────────────────

/// Abstraction over package fetch backends.
///
/// Implementations are *not* required to be [`Send`] or [`Sync`] — the MVP
/// is single-threaded.
pub trait Fetcher {
    /// Fetch the package described by `dep` and return a [`FetchedPkg`].
    ///
    /// # Errors
    ///
    /// Returns [`PkgError`] on any git, I/O, or validation failure.
    fn fetch(&self, dep: &Dep) -> Result<FetchedPkg, PkgError>;
}

// ── FetchedPkg ────────────────────────────────────────────────────────────────

/// Result of a successful [`Fetcher::fetch`] call.
#[derive(Debug, Clone)]
pub struct FetchedPkg {
    /// Absolute path to the cloned repository on disk.
    pub cache_path: PathBuf,

    /// The resolved commit SHA (40-character hex string).
    pub sha: String,

    /// The parsed `mlua-pkg.toml` found at `cache_path`, if present.
    pub manifest: Option<Manifest>,

    /// The concrete tag name actually resolved.  Equals `dep.tag` for exact
    /// pins; for prefix pins (e.g. `"v0.1"`) holds the picked release
    /// (e.g. `"v0.1.0"`).  `None` when no tag pin was used (rev / branch /
    /// HEAD resolution).
    pub resolved_tag: Option<String>,
}

// ── GitFetcher ────────────────────────────────────────────────────────────────

/// [`Fetcher`] implementation backed by libgit2.
pub struct GitFetcher {
    /// Root directory under which all git caches are stored.
    cache_root: PathBuf,
}

impl GitFetcher {
    /// Create a new `GitFetcher` that stores clones under `cache_root`.
    pub fn new(cache_root: PathBuf) -> Self {
        Self { cache_root }
    }

    /// Compute the cache directory for the given URL and SHA.
    ///
    /// Layout: `<cache_root>/git/<host>/<path…>/<sha>/`
    ///
    /// # Errors
    ///
    /// Returns [`PkgError::Validation`] if the URL cannot be parsed or if any
    /// URL-derived path component contains `..` (path traversal defence).
    fn cache_dir(&self, url: &str, sha: &str) -> Result<PathBuf, PkgError> {
        // Strip protocol prefix and trailing `.git`.
        let stripped = url
            .trim_start_matches("https://")
            .trim_start_matches("http://")
            .trim_start_matches("ssh://")
            .trim_start_matches("git@")
            .replace(':', "/") // git@github.com:user/repo → github.com/user/repo
            .trim_end_matches(".git")
            .to_owned();

        if stripped.is_empty() {
            return Err(PkgError::Validation {
                message: format!("cannot derive cache path from URL: {url:?}"),
            });
        }

        // Defend against path traversal in every component.
        for component in stripped.split('/') {
            if component == ".." || component == "." {
                return Err(PkgError::Validation {
                    message: format!(
                        "URL {url:?} contains a path traversal component: {component:?}"
                    ),
                });
            }
        }

        // Validate SHA is safe (hex chars only).
        if sha.is_empty() || !sha.chars().all(|c| c.is_ascii_hexdigit()) {
            return Err(PkgError::Validation {
                message: format!("invalid SHA: {sha:?}"),
            });
        }

        let mut path = self.cache_root.join("git");
        for segment in stripped.split('/') {
            if segment.is_empty() {
                continue;
            }
            // Extra check: ensure no path component resolves to `..` via PathBuf.
            let p = path.join(segment);
            for c in p.components() {
                if c == Component::ParentDir {
                    return Err(PkgError::Validation {
                        message: format!(
                            "URL {url:?} resolves to a path with parent-dir traversal"
                        ),
                    });
                }
            }
            path = p;
        }
        path = path.join(sha);
        Ok(path)
    }

    /// Validate the URL structure before any network operation.
    ///
    /// Rejects URLs that contain `..` or `.` path components (path traversal
    /// defence).  Called at the start of [`Fetcher::fetch`] so that invalid
    /// URLs are rejected without making a network connection.
    fn validate_url(url: &str) -> Result<(), PkgError> {
        let stripped = url
            .trim_start_matches("https://")
            .trim_start_matches("http://")
            .trim_start_matches("ssh://")
            .trim_start_matches("git@")
            .replace(':', "/")
            .trim_end_matches(".git")
            .to_owned();

        if stripped.is_empty() {
            return Err(PkgError::Validation {
                message: format!("cannot derive cache path from URL: {url:?}"),
            });
        }

        for component in stripped.split('/') {
            if component == ".." || component == "." {
                return Err(PkgError::Validation {
                    message: format!(
                        "URL {url:?} contains a path traversal component: {component:?}"
                    ),
                });
            }
        }
        Ok(())
    }

    /// Return a unique temp-clone path inside `git_base` (same filesystem, so
    /// `std::fs::rename` works atomically).
    fn temp_clone_path(git_base: &std::path::Path) -> PathBuf {
        let n = TMP_CTR.fetch_add(1, Ordering::Relaxed);
        let pid = std::process::id();
        git_base.join(format!(".fetch-{pid}-{n}"))
    }

    /// Resolve the git ref from `dep` into `(sha, resolved_tag)`.
    ///
    /// Resolution order:
    /// 1. `rev` — treated as a revspec; peels to commit. `resolved_tag` = None.
    /// 2. `tag` — classified via [`crate::version::classify_tag_pin`]:
    ///    - **Exact** / unparseable → resolved literally via `refs/tags/<tag>`.
    ///    - **Prefix** (`"v1.0"` etc.) → enumerate local tags, pick the
    ///      SemVer-max release that matches the prefix, resolve that.
    ///
    ///    `resolved_tag` holds the literal tag name actually used.
    /// 3. `branch` — `refs/remotes/origin/<branch>` (peeled). `resolved_tag` = None.
    /// 4. No ref — `HEAD`. `resolved_tag` = None.
    fn resolve_ref(repo: &Repository, dep: &Dep) -> Result<(String, Option<String>), PkgError> {
        if let Some(rev) = &dep.rev {
            let oid = repo.revparse_single(rev)?.peel_to_commit()?.id();
            return Ok((oid.to_string(), None));
        }
        if let Some(tag) = &dep.tag {
            let resolved = Self::resolve_tag_pin(repo, tag)?;
            let refname = format!("refs/tags/{resolved}");
            let oid = repo.find_reference(&refname)?.peel_to_commit()?.id();
            return Ok((oid.to_string(), Some(resolved)));
        }
        if let Some(branch) = &dep.branch {
            let refname = format!("refs/remotes/origin/{branch}");
            let oid = repo.find_reference(&refname)?.peel_to_commit()?.id();
            return Ok((oid.to_string(), None));
        }
        // Default: HEAD.
        let oid = repo.head()?.peel_to_commit()?.id();
        Ok((oid.to_string(), None))
    }

    /// Resolve `tag` to a concrete local tag name in `repo`.
    ///
    /// For [`crate::version::TagPin::Exact`] (or unclassifiable) values the
    /// input is returned verbatim — callers will hit `refs/tags/<tag>` and
    /// see a NotFound error if the tag truly does not exist.  For
    /// [`crate::version::TagPin::Prefix`] values the local tag list is
    /// enumerated and the SemVer-max matching release is picked; pre-release
    /// tags are skipped.  Returns [`PkgError::Validation`] when a prefix pin
    /// has no matching release.
    fn resolve_tag_pin(repo: &Repository, tag: &str) -> Result<String, PkgError> {
        let tag_names = repo.tag_names(None)?;
        let local_tags: Vec<String> = tag_names
            .iter()
            .filter_map(|t| t.map(|s| s.to_string()))
            .collect();
        Self::pick_tag_pin(&local_tags, tag)
    }

    /// Same policy as [`resolve_tag_pin`](Self::resolve_tag_pin) over an
    /// already-collected tag list (local or from `ls-remote`).
    fn pick_tag_pin(tags: &[String], tag: &str) -> Result<String, PkgError> {
        use crate::version::{classify_tag_pin, pick_latest_for_pin, TagPin};
        let prefix = match classify_tag_pin(tag) {
            Some(TagPin::Prefix(p)) => p,
            // Exact, or unparseable: use the literal value.
            _ => return Ok(tag.to_string()),
        };
        pick_latest_for_pin(tags, &prefix).ok_or_else(|| PkgError::Validation {
            message: format!("tag prefix '{tag}' has no matching SemVer release on remote"),
        })
    }

    /// Resolve `dep` to `(sha, resolved_tag)` **without cloning**, or `None`
    /// when that is not possible (short / symbolic `rev`, or the ref is not
    /// advertised by the remote — the clone path then produces the real
    /// error).
    ///
    /// - full 40-hex `rev` → no network at all
    /// - `tag` / `branch` / no pin → one `ls-remote` via [`ls_remote_refs`](Self::ls_remote_refs)
    fn preresolve(
        &self,
        url: &str,
        dep: &Dep,
    ) -> Result<Option<(String, Option<String>)>, PkgError> {
        if let Some(rev) = &dep.rev {
            let is_full_sha = rev.len() == 40 && rev.chars().all(|c| c.is_ascii_hexdigit());
            return Ok(is_full_sha.then(|| (rev.to_ascii_lowercase(), None)));
        }

        let refs = self.ls_remote_refs(url)?;
        let lookup = |name: &str| {
            refs.iter()
                .find(|(n, _)| n == name)
                .map(|(_, oid)| oid.clone())
        };

        if let Some(tag) = &dep.tag {
            let tag_names = Self::tag_names_from_refs(&refs);
            let resolved = Self::pick_tag_pin(&tag_names, tag)?;
            // Annotated tags advertise a peeled `^{}` entry pointing at the
            // commit; lightweight tags only have the plain ref.
            let oid = lookup(&format!("refs/tags/{resolved}^{{}}"))
                .or_else(|| lookup(&format!("refs/tags/{resolved}")));
            return Ok(oid.map(|sha| (sha, Some(resolved))));
        }
        if let Some(branch) = &dep.branch {
            return Ok(lookup(&format!("refs/heads/{branch}")).map(|sha| (sha, None)));
        }
        Ok(lookup("HEAD").map(|sha| (sha, None)))
    }

    /// Tag names (de-duplicated, `^{}` stripped) from an `ls-remote` listing.
    fn tag_names_from_refs(refs: &[(String, String)]) -> Vec<String> {
        let mut tags: Vec<String> = Vec::new();
        for (name, _) in refs {
            if let Some(t) = name.strip_prefix("refs/tags/") {
                let s = t.trim_end_matches("^{}").to_string();
                if !tags.contains(&s) {
                    tags.push(s);
                }
            }
        }
        tags
    }

    /// Reset the worktree of `repo` hard to the commit named by `sha`.
    fn checkout_sha(repo: &Repository, sha: &str) -> Result<(), PkgError> {
        let oid = git2::Oid::from_str(sha).map_err(|e| PkgError::Validation {
            message: format!("invalid SHA {sha}: {e}"),
        })?;
        let obj = repo.find_object(oid, None)?;
        repo.reset(&obj, git2::ResetType::Hard, None)?;
        Ok(())
    }

    /// List remote tag names by ls-remote (no clone).
    ///
    /// Connects to `url` in fetch direction, enumerates `refs/tags/*`, strips
    /// the `refs/tags/` prefix and the `^{}` peeled-tag suffix when present,
    /// and returns a de-duplicated `Vec<String>` in arbitrary order.
    pub fn list_tags(&self, url: &str) -> Result<Vec<String>, PkgError> {
        Ok(Self::tag_names_from_refs(&self.ls_remote_refs(url)?))
    }

    /// `ls-remote`: every advertised ref as `(name, oid hex)`, e.g.
    /// `("refs/tags/v1.0.0^{}", "abc…")` / `("refs/heads/main", "…")` /
    /// `("HEAD", "…")`.  Transfers ref names only, no objects.
    pub fn ls_remote_refs(&self, url: &str) -> Result<Vec<(String, String)>, PkgError> {
        Self::validate_url(url)?;

        // Transient repo in a temp dir to host the anonymous remote.
        let scratch = self.cache_root.join("git").join(".ls-remote");
        std::fs::create_dir_all(&scratch)?;
        let tmp = Self::temp_clone_path(&scratch);
        std::fs::create_dir_all(&tmp)?;

        let result = Self::ls_remote_inner(&tmp, url);
        let _ = std::fs::remove_dir_all(&tmp);
        result
    }

    /// Resolve `dep` to its commit **without cloning**, when the pin allows
    /// it: a full 40-hex `rev` needs no network, `tag` / `branch` / no pin
    /// cost one `ls-remote`.  Returns `None` for a short / symbolic `rev`
    /// or a ref the remote does not advertise (a real fetch then produces
    /// the error).  Used by `install` to decide whether a `patch_dir` is
    /// still based on the pinned commit before touching the cache.
    ///
    /// # Errors
    ///
    /// [`PkgError::Validation`] for a malformed URL, [`PkgError::GitFetch`]
    /// when the remote cannot be listed.
    pub fn resolve_sha(&self, dep: &Dep) -> Result<Option<(String, Option<String>)>, PkgError> {
        Self::validate_url(&dep.git)?;
        self.preresolve(&dep.git, dep)
    }
}

impl FetchedPkg {
    /// Describe a package whose root directory is already on disk (a cache
    /// checkout or a `patch_dir`): read the author manifest and assemble the
    /// [`FetchedPkg`].  Shared by the cache-hit, clone and patch paths.
    ///
    /// Without an `mlua-pkg.toml`, an in-tree LuaRocks rockspec (root or
    /// `rockspecs/`, see [`rockspec::find_in_tree`](crate::rockspec::find_in_tree))
    /// is evaluated and turned into a synthesized author manifest whose
    /// `entry` is folded from `build.modules`.  A rockspec that cannot be
    /// evaluated is an error; one that yields no entry hint (C modules,
    /// irregular layout) leaves `manifest` as `None`.
    ///
    /// # Errors
    ///
    /// [`PkgError::ManifestParse`] / [`PkgError::Validation`] from the
    /// manifest or rockspec, [`PkgError::Io`] from directory listing.
    pub fn at_root(
        cache_path: PathBuf,
        sha: String,
        resolved_tag: Option<String>,
    ) -> Result<FetchedPkg, PkgError> {
        let manifest_path = cache_path.join("mlua-pkg.toml");
        let manifest = if manifest_path.exists() {
            Some(Manifest::from_path(&manifest_path)?)
        } else {
            match crate::rockspec::find_in_tree(&cache_path, resolved_tag.as_deref())? {
                Some(p) => Some(crate::rockspec::Rockspec::from_path(&p)?.to_manifest()),
                None => None,
            }
        };
        Ok(FetchedPkg {
            cache_path,
            sha,
            manifest,
            resolved_tag,
        })
    }
}

impl GitFetcher {
    fn ls_remote_inner(
        tmp: &std::path::Path,
        url: &str,
    ) -> Result<Vec<(String, String)>, PkgError> {
        let repo = Repository::init(tmp)?;
        let mut remote = repo.remote_anonymous(url)?;
        remote.connect_auth(
            git2::Direction::Fetch,
            Some(Self::make_credentials_callbacks()),
            None,
        )?;
        let refs: Vec<(String, String)> = remote
            .list()?
            .iter()
            .map(|head| (head.name().to_string(), head.oid().to_string()))
            .collect();
        let _ = remote.disconnect();
        Ok(refs)
    }

    /// Build `RemoteCallbacks` with the credential cascade (extracted so both
    /// `make_fetch_options` and `list_tags` can share it).
    fn make_credentials_callbacks() -> RemoteCallbacks<'static> {
        let mut callbacks = RemoteCallbacks::new();

        let tried = AtomicU8::new(0);
        callbacks.credentials(move |_url, username, allowed| {
            let tried_bits = tried.load(Ordering::Relaxed);

            if allowed.contains(CredentialType::SSH_KEY) && (tried_bits & 0b001 == 0) {
                tried.fetch_or(0b001, Ordering::Relaxed);
                let user = username.unwrap_or("git");
                return git2::Cred::ssh_key_from_agent(user);
            }

            if allowed.contains(CredentialType::USER_PASS_PLAINTEXT) && (tried_bits & 0b010 == 0) {
                tried.fetch_or(0b010, Ordering::Relaxed);
                if let Ok(cfg) = git2::Config::open_default() {
                    return git2::Cred::credential_helper(&cfg, _url, username);
                }
            }

            if tried_bits & 0b100 == 0 {
                tried.fetch_or(0b100, Ordering::Relaxed);
                return git2::Cred::default();
            }

            Err(git2::Error::from_str("all credential types exhausted"))
        });
        callbacks
    }

    /// Build `FetchOptions` with the credential cascade callback.
    fn make_fetch_options() -> FetchOptions<'static> {
        let mut fo = FetchOptions::new();
        fo.remote_callbacks(Self::make_credentials_callbacks());
        fo
    }
}

impl Fetcher for GitFetcher {
    fn fetch(&self, dep: &Dep) -> Result<FetchedPkg, PkgError> {
        let url = &dep.git;

        // Reject obviously malformed / traversal URLs before any I/O.
        Self::validate_url(url)?;

        // All git caches live under `<cache_root>/git/`.
        let git_base = self.cache_root.join("git");
        std::fs::create_dir_all(&git_base)?;

        // Cache hit without a clone: resolve the ref cheaply first (no
        // network for a full-SHA rev, one ls-remote otherwise) and return
        // the existing cache directory when it is already populated.
        if let Some((sha, resolved_tag)) = self.preresolve(url, dep)? {
            let cache_path = self.cache_dir(url, &sha)?;
            if cache_path.exists() {
                return FetchedPkg::at_root(cache_path, sha, resolved_tag);
            }
        }

        #[cfg(test)]
        CLONE_CTR.with(|c| c.set(c.get() + 1));

        // Clone into a temp directory that lives on the same filesystem as the
        // final cache location so that `std::fs::rename` is atomic.
        let tmp_path = Self::temp_clone_path(&git_base);

        // ── Clone ────────────────────────────────────────────────────────────
        let fo = Self::make_fetch_options();
        let repo = match RepoBuilder::new().fetch_options(fo).clone(url, &tmp_path) {
            Ok(r) => r,
            Err(e) => {
                // Best-effort cleanup on error.
                let _ = std::fs::remove_dir_all(&tmp_path);
                return Err(e.into());
            }
        };

        // ── Resolve SHA + concrete tag ───────────────────────────────────────
        let (sha, resolved_tag) = match Self::resolve_ref(&repo, dep) {
            Ok(s) => s,
            Err(e) => {
                let _ = std::fs::remove_dir_all(&tmp_path);
                return Err(e);
            }
        };

        // ── Checkout resolved commit ─────────────────────────────────────────
        // `clone()` leaves the worktree at the cloned HEAD (= default branch
        // tip), which for tag/rev/branch lookups is the wrong commit.  Reset
        // hard to the resolved SHA so the cached content matches the SHA we
        // pin in the lockfile.
        if let Err(e) = Self::checkout_sha(&repo, &sha) {
            let _ = std::fs::remove_dir_all(&tmp_path);
            return Err(e);
        }

        // ── Compute final cache path ─────────────────────────────────────────
        let cache_path = match self.cache_dir(url, &sha) {
            Ok(p) => p,
            Err(e) => {
                let _ = std::fs::remove_dir_all(&tmp_path);
                return Err(e);
            }
        };

        if cache_path.exists() {
            // Already cached — discard the temp clone.
            drop(repo);
            let _ = std::fs::remove_dir_all(&tmp_path);
        } else {
            // Ensure the parent directory exists, then rename temp → final.
            if let Some(parent) = cache_path.parent() {
                std::fs::create_dir_all(parent)?;
            }
            drop(repo); // Release file handles before rename.
            std::fs::rename(&tmp_path, &cache_path)?;
        }

        FetchedPkg::at_root(cache_path, sha, resolved_tag)
    }
}

// ── Unit tests ────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use git2::{Repository, Signature};
    use std::fs;
    use tempfile::TempDir;

    /// Create a minimal git repo in `dir` with one commit and return the SHA.
    fn init_repo_with_commit(dir: &std::path::Path) -> String {
        let repo = Repository::init(dir).unwrap();

        // Configure identity for the test repo.
        let mut config = repo.config().unwrap();
        config.set_str("user.name", "Test").unwrap();
        config.set_str("user.email", "test@example.com").unwrap();
        drop(config);

        // Create an initial file and commit.
        let file_path = dir.join("README.md");
        fs::write(&file_path, "# test\n").unwrap();

        let mut index = repo.index().unwrap();
        index.add_path(std::path::Path::new("README.md")).unwrap();
        index.write().unwrap();

        let tree_id = index.write_tree().unwrap();
        let tree = repo.find_tree(tree_id).unwrap();
        let sig = Signature::now("Test", "test@example.com").unwrap();
        let oid = repo
            .commit(Some("HEAD"), &sig, &sig, "initial commit", &tree, &[])
            .unwrap();
        oid.to_string()
    }

    /// Add an annotated tag to the HEAD commit of `repo`.
    fn add_tag(repo: &Repository, tag_name: &str) -> String {
        let head = repo.head().unwrap().peel_to_commit().unwrap();
        let sig = Signature::now("Test", "test@example.com").unwrap();
        repo.tag(tag_name, head.as_object(), &sig, tag_name, false)
            .unwrap();
        head.id().to_string()
    }

    // ── 1. clone a local file:// repo (happy path) ───────────────────────────

    #[test]
    fn clone_local_repo_happy_path() {
        let src = TempDir::new().unwrap();
        let sha = init_repo_with_commit(src.path());

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            tag: None,
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let result = fetcher.fetch(&dep).unwrap();
        assert_eq!(result.sha, sha, "SHA should match the initial commit");
        assert!(result.cache_path.exists(), "cache_path must exist on disk");
        assert!(
            result.manifest.is_none(),
            "no mlua-pkg.toml in bare test repo"
        );
    }

    // ── 2. resolve tag → SHA ──────────────────────────────────────────────────

    #[test]
    fn resolve_tag_sha() {
        let src = TempDir::new().unwrap();
        init_repo_with_commit(src.path());
        let repo = Repository::open(src.path()).unwrap();
        let expected_sha = add_tag(&repo, "v0.1.0");
        drop(repo);

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            tag: Some("v0.1.0".to_string()),
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let result = fetcher.fetch(&dep).unwrap();
        assert_eq!(result.sha, expected_sha, "tag must resolve to expected SHA");
        assert!(result.cache_path.exists());
    }

    // ── 3. resolve rev → SHA ──────────────────────────────────────────────────

    #[test]
    fn resolve_rev_sha() {
        let src = TempDir::new().unwrap();
        let sha = init_repo_with_commit(src.path());

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            rev: Some(sha.clone()),
            tag: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let result = fetcher.fetch(&dep).unwrap();
        assert_eq!(result.sha, sha, "rev should resolve to the given SHA");
    }

    // ── 4. nonexistent repo returns GitFetch error ────────────────────────────

    #[test]
    fn nonexistent_repo_returns_error() {
        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let dep = Dep {
            git: "file:///nonexistent/path/that/does/not/exist".to_string(),
            tag: None,
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let err = fetcher.fetch(&dep).unwrap_err();
        assert!(
            matches!(err, PkgError::GitFetch { .. }),
            "expected GitFetch error, got: {err}"
        );
    }

    // ── 5. second fetch of same repo uses cache (skip re-clone) ──────────────

    #[test]
    fn second_fetch_uses_cache() {
        let src = TempDir::new().unwrap();
        let sha = init_repo_with_commit(src.path());

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            rev: Some(sha.clone()),
            tag: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let first = fetcher.fetch(&dep).unwrap();
        let second = fetcher.fetch(&dep).unwrap();

        assert_eq!(
            first.cache_path, second.cache_path,
            "cache paths must be identical"
        );
        assert_eq!(first.sha, second.sha);
    }

    // ── 5b. cache hit does not clone ─────────────────────────────────────────

    #[test]
    fn rev_pin_cache_hit_needs_no_remote_and_no_clone() {
        let src = TempDir::new().unwrap();
        let sha = init_repo_with_commit(src.path());

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());
        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            rev: Some(sha.clone()),
            tag: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let first = fetcher.fetch(&dep).unwrap();
        // Remote gone: a full-SHA rev pin must still resolve from the cache.
        drop(src);
        let clones_before = clone_count();
        let second = fetcher.fetch(&dep).unwrap();

        assert_eq!(first.cache_path, second.cache_path);
        assert_eq!(second.sha, sha);
        assert!(second.cache_path.join("README.md").exists());
        assert_eq!(clone_count(), clones_before, "cache hit must not clone");
    }

    #[test]
    fn tag_pin_cache_hit_resolves_by_ls_remote_without_clone() {
        let src = TempDir::new().unwrap();
        init_repo_with_commit(src.path());
        let repo = Repository::open(src.path()).unwrap();
        add_tag(&repo, "v1.0.0");
        add_tag(&repo, "v1.0.4");

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());
        let url = format!("file://{}", src.path().display());
        // Prefix pin: resolution needs the remote tag list, not a clone.
        let dep = Dep {
            git: url,
            rev: None,
            tag: Some("v1.0".into()),
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let first = fetcher.fetch(&dep).unwrap();
        assert_eq!(first.resolved_tag.as_deref(), Some("v1.0.4"));

        let clones_before = clone_count();
        let second = fetcher.fetch(&dep).unwrap();

        assert_eq!(first.cache_path, second.cache_path);
        assert_eq!(second.resolved_tag.as_deref(), Some("v1.0.4"));
        assert_eq!(
            clone_count(),
            clones_before,
            "tag-pin cache hit must resolve via ls-remote and skip the clone"
        );
    }

    #[test]
    fn branch_pin_new_commit_is_a_cache_miss() {
        let src = TempDir::new().unwrap();
        let sha1 = init_repo_with_commit(src.path());

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());
        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            rev: None,
            tag: None,
            branch: Some("master".into()),
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };
        let repo = Repository::open(src.path()).unwrap();
        let branch = repo.head().unwrap().shorthand().unwrap().to_string();
        let dep = Dep {
            branch: Some(branch),
            ..dep
        };

        let first = fetcher.fetch(&dep).unwrap();
        assert_eq!(first.sha, sha1);

        // Advance the branch on the remote.
        std::fs::write(src.path().join("main.lua"), "return { v = 2 }\n").unwrap();
        let mut index = repo.index().unwrap();
        index.add_path(std::path::Path::new("main.lua")).unwrap();
        index.write().unwrap();
        let tree = repo.find_tree(index.write_tree().unwrap()).unwrap();
        let sig = git2::Signature::now("Test", "test@example.com").unwrap();
        let parent = repo.head().unwrap().peel_to_commit().unwrap();
        let sha2 = repo
            .commit(Some("HEAD"), &sig, &sig, "second", &tree, &[&parent])
            .unwrap()
            .to_string();

        let second = fetcher.fetch(&dep).unwrap();
        assert_eq!(second.sha, sha2, "branch pin must follow the new HEAD");
        assert_ne!(first.cache_path, second.cache_path);
    }

    // ── 5c. in-tree rockspec drives the entry ────────────────────────────────

    #[test]
    fn in_tree_rockspec_yields_synthesized_manifest_with_entry() {
        let src = TempDir::new().unwrap();
        init_repo_with_commit(src.path());
        // Layout the fallback chain would misread: a `src/` without Lua and
        // the real module under `lib/`, declared by the rockspec.
        fs::create_dir_all(src.path().join("src")).unwrap();
        fs::write(src.path().join("src/notes.txt"), "not lua\n").unwrap();
        fs::create_dir_all(src.path().join("lib")).unwrap();
        fs::write(src.path().join("lib/foo.lua"), "return { v = 1 }\n").unwrap();
        fs::write(
            src.path().join("foo-1.0.0-1.rockspec"),
            "package = \"foo\"\nversion = \"1.0.0-1\"\n\
             source = { url = \"git+https://example.invalid/foo\", tag = \"v1.0.0\" }\n\
             build = { type = \"builtin\", modules = { foo = \"lib/foo.lua\" } }\n",
        )
        .unwrap();
        let repo = Repository::open(src.path()).unwrap();
        let mut index = repo.index().unwrap();
        index
            .add_all(["*"].iter(), git2::IndexAddOption::DEFAULT, None)
            .unwrap();
        index.write().unwrap();
        let tree = repo.find_tree(index.write_tree().unwrap()).unwrap();
        let sig = Signature::now("Test", "test@example.com").unwrap();
        let parent = repo.head().unwrap().peel_to_commit().unwrap();
        repo.commit(Some("HEAD"), &sig, &sig, "rock", &tree, &[&parent])
            .unwrap();
        add_tag(&repo, "v1.0.0");

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());
        let dep = Dep {
            git: format!("file://{}", src.path().display()),
            tag: Some("v1.0.0".into()),
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let fetched = fetcher.fetch(&dep).unwrap();
        let manifest = fetched
            .manifest
            .expect("rockspec should synthesize a manifest");
        assert_eq!(manifest.package.name, "foo");
        assert_eq!(manifest.package.version, "1.0.0");
        assert_eq!(manifest.package.entry, Some(PathBuf::from("lib")));
        assert!(manifest.deps.is_empty());
        assert!(fetched.cache_path.join("lib/foo.lua").exists());
    }

    // ── 6. path traversal in URL is rejected ──────────────────────────────────

    #[test]
    fn path_traversal_in_url_is_rejected() {
        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let dep = Dep {
            git: "https://github.com/../../../etc/passwd".to_string(),
            tag: None,
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let err = fetcher.fetch(&dep).unwrap_err();
        assert!(
            matches!(err, PkgError::Validation { .. }),
            "expected Validation error for path traversal, got: {err}"
        );
    }

    // ── 7. manifest is parsed when mlua-pkg.toml is present ──────────────────

    #[test]
    fn manifest_parsed_when_present() {
        let src = TempDir::new().unwrap();

        // Write mlua-pkg.toml before the initial commit.
        let toml_path = src.path().join("mlua-pkg.toml");
        fs::write(
            &toml_path,
            r#"[package]
name = "test-lib"
version = "0.1.0"
"#,
        )
        .unwrap();

        let repo = Repository::init(src.path()).unwrap();
        let mut config = repo.config().unwrap();
        config.set_str("user.name", "Test").unwrap();
        config.set_str("user.email", "test@example.com").unwrap();
        drop(config);

        let mut index = repo.index().unwrap();
        index
            .add_path(std::path::Path::new("mlua-pkg.toml"))
            .unwrap();
        index.write().unwrap();
        let tree_id = index.write_tree().unwrap();
        let tree = repo.find_tree(tree_id).unwrap();
        let sig = Signature::now("Test", "test@example.com").unwrap();
        repo.commit(Some("HEAD"), &sig, &sig, "add manifest", &tree, &[])
            .unwrap();

        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let url = format!("file://{}", src.path().display());
        let dep = Dep {
            git: url,
            tag: None,
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };

        let result = fetcher.fetch(&dep).unwrap();
        let manifest = result.manifest.expect("manifest should be parsed");
        assert_eq!(manifest.package.name, "test-lib");
        assert_eq!(manifest.package.version, "0.1.0");
    }

    // ── 8. fetched worktree content matches the resolved ref, not HEAD ───────
    //
    // Regression for the v0.4.0 bug where fetch() resolved the SHA from
    // `tag = "v0.1.0"` and pinned it in the lockfile / cache dir name, but
    // left the worktree at the cloned HEAD (= default branch tip).  Consumers
    // therefore got the latest content with a stale SHA — reproducibility lost.

    #[test]
    fn fetched_worktree_matches_resolved_tag_not_head() {
        let src = TempDir::new().unwrap();
        let repo = Repository::init(src.path()).unwrap();
        let mut config = repo.config().unwrap();
        config.set_str("user.name", "Test").unwrap();
        config.set_str("user.email", "test@example.com").unwrap();
        drop(config);
        let sig = Signature::now("Test", "test@example.com").unwrap();

        // Commit 1: VERSION = "0.1.0", tagged v0.1.0.
        fs::write(src.path().join("VERSION"), "0.1.0").unwrap();
        let mut index = repo.index().unwrap();
        index.add_path(std::path::Path::new("VERSION")).unwrap();
        index.write().unwrap();
        let tree_id = index.write_tree().unwrap();
        let tree = repo.find_tree(tree_id).unwrap();
        let c1 = repo
            .commit(Some("HEAD"), &sig, &sig, "v0.1.0", &tree, &[])
            .unwrap();
        let c1_obj = repo.find_object(c1, None).unwrap();
        repo.tag("v0.1.0", &c1_obj, &sig, "v0.1.0", false).unwrap();
        let v010_sha = c1.to_string();

        // Commit 2: VERSION = "0.2.0", HEAD advances. No tag.
        fs::write(src.path().join("VERSION"), "0.2.0").unwrap();
        let mut index = repo.index().unwrap();
        index.add_path(std::path::Path::new("VERSION")).unwrap();
        index.write().unwrap();
        let tree_id = index.write_tree().unwrap();
        let tree = repo.find_tree(tree_id).unwrap();
        let parent = repo.find_commit(c1).unwrap();
        let c2 = repo
            .commit(Some("HEAD"), &sig, &sig, "v0.2.0", &tree, &[&parent])
            .unwrap();
        assert_ne!(c1, c2, "HEAD must have advanced past the tag");

        // Fetch tag v0.1.0.
        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());
        let dep = Dep {
            git: format!("file://{}", src.path().display()),
            tag: Some("v0.1.0".to_string()),
            rev: None,
            branch: None,
            entry: None,
            target_dir: None,
            patch_dir: None,
            patch_drift: None,
        };
        let fetched = fetcher.fetch(&dep).unwrap();

        // SHA must point at the tag commit, not HEAD.
        assert_eq!(fetched.sha, v010_sha, "SHA must resolve to tag commit");

        // Worktree content must match the tag commit content, not HEAD's.
        let version = fs::read_to_string(fetched.cache_path.join("VERSION")).unwrap();
        assert_eq!(
            version, "0.1.0",
            "fetched worktree must contain tag v0.1.0 content, got HEAD content instead"
        );
    }

    // ── 9. cache_dir rejects SHA with non-hex chars ───────────────────────────

    #[test]
    fn cache_dir_rejects_invalid_sha() {
        let cache_root = TempDir::new().unwrap();
        let fetcher = GitFetcher::new(cache_root.path().to_path_buf());

        let err = fetcher
            .cache_dir("https://github.com/x/y", "../evil")
            .unwrap_err();
        assert!(
            matches!(err, PkgError::Validation { .. }),
            "expected Validation error for invalid SHA, got: {err}"
        );
    }
}