mlua_pkg/

project.rs

//! Project context for the package-manager operations in [`crate::ops`].
//!
//! Two small value types tie an operation to the filesystem:
//!
//! | Type | Owns | Decided by |
//! |------|------|------------|
//! | [`PkgDir`] | the base directory that holds `cache/` and `vendored/` | the caller (CLI flag / env / SDK constructor) |
//! | [`Project`] | manifest path, lockfile path, and a [`PkgDir`] | the caller |
//!
//! The library never inspects the current working directory or environment
//! to pick these paths.  The CLI resolves its `--mlua-pkgs-dir` / `MLUA_PKG_DIR`
//! / `target/` precedence and hands the result in as a single [`PkgDir`];
//! an embedding application does the same with whatever policy it prefers.

use std::path::{Path, PathBuf};

/// Default base-directory name used when nothing else is configured.
pub const DEFAULT_PKG_DIR_NAME: &str = ".mlua-pkgs";

/// Manifest filename inside a project root.
pub const MANIFEST_FILE_NAME: &str = "mlua-pkg.toml";

/// Lockfile filename inside a project root.
pub const LOCKFILE_FILE_NAME: &str = "mlua-pkg.lock";

/// Base directory for cache + vendored output.
///
/// This is the single place that knows the internal layout:
///
/// ```text
/// <base>/
///   cache/      git clones, keyed by host/org/repo/sha  (GitFetcher root)
///   vendored/   <name> -> ../cache/…/<entry> symlinks    (VendoredResolver root)
/// ```
///
/// Callers pass one path; [`cache`](Self::cache) and
/// [`vendored`](Self::vendored) derive the rest so no consumer has to
/// replicate the `join("cache")` / `join("vendored")` convention.
///
/// # Example
///
/// ```rust
/// use mlua_pkg::PkgDir;
/// use std::path::Path;
///
/// let dir = PkgDir::new(".mlua-pkgs");
/// assert_eq!(dir.cache(), Path::new(".mlua-pkgs/cache"));
/// assert_eq!(dir.vendored(), Path::new(".mlua-pkgs/vendored"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PkgDir {
    base: PathBuf,
}

impl PkgDir {
    /// Wrap an explicit base directory.  No filesystem access.
    pub fn new(base: impl Into<PathBuf>) -> Self {
        Self { base: base.into() }
    }

    /// `<root>/.mlua-pkgs` — the conventional location under a project root.
    pub fn default_in(root: impl AsRef<Path>) -> Self {
        Self::new(root.as_ref().join(DEFAULT_PKG_DIR_NAME))
    }

    /// The base directory as given.
    pub fn base(&self) -> &Path {
        &self.base
    }

    /// `<base>/cache` — root handed to [`crate::fetcher::GitFetcher`].
    pub fn cache(&self) -> PathBuf {
        self.base.join("cache")
    }

    /// `<base>/vendored` — root handed to
    /// [`crate::resolvers::VendoredResolver`].
    pub fn vendored(&self) -> PathBuf {
        self.base.join("vendored")
    }

    /// `<base>/vendored/<name>` — the symlink `install` creates for a
    /// package without `target_dir`.  It points at the **package root**
    /// (upstream cache checkout or `patch_dir`); the `require` root inside
    /// it is `<root>/<entry>` with `entry` taken from the lockfile
    /// ([`LockedPkg::require_dir`](crate::lockfile::LockedPkg::require_dir)).
    pub fn vendored_root(&self, name: &str) -> PathBuf {
        self.vendored().join(name)
    }
}

impl<T: Into<PathBuf>> From<T> for PkgDir {
    fn from(p: T) -> Self {
        Self::new(p)
    }
}

/// Everything an operation in [`crate::ops`] needs to locate files.
///
/// Built once by the caller and passed by reference to `install` / `add` /
/// `update` / `clean`.  Paths are used as given (relative paths resolve
/// against the process working directory, as with any `std::fs` call).
///
/// # Example
///
/// ```rust
/// use mlua_pkg::{PkgDir, Project};
/// use std::path::Path;
///
/// // Conventional layout: <root>/mlua-pkg.toml, <root>/mlua-pkg.lock,
/// // <root>/.mlua-pkgs/{cache,vendored}
/// let p = Project::in_dir("/srv/app", PkgDir::default_in("/srv/app"));
/// assert_eq!(p.manifest_path(), Path::new("/srv/app/mlua-pkg.toml"));
/// assert_eq!(p.lock_path(), Path::new("/srv/app/mlua-pkg.lock"));
/// assert_eq!(p.pkg_dir().vendored(), Path::new("/srv/app/.mlua-pkgs/vendored"));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Project {
    manifest_path: PathBuf,
    lock_path: PathBuf,
    pkg_dir: PkgDir,
}

impl Project {
    /// Fully explicit constructor.
    pub fn new(
        manifest_path: impl Into<PathBuf>,
        lock_path: impl Into<PathBuf>,
        pkg_dir: impl Into<PkgDir>,
    ) -> Self {
        Self {
            manifest_path: manifest_path.into(),
            lock_path: lock_path.into(),
            pkg_dir: pkg_dir.into(),
        }
    }

    /// Conventional filenames under `root`, with an explicit [`PkgDir`].
    ///
    /// `manifest = <root>/mlua-pkg.toml`, `lock = <root>/mlua-pkg.lock`.
    pub fn in_dir(root: impl AsRef<Path>, pkg_dir: impl Into<PkgDir>) -> Self {
        let root = root.as_ref();
        Self::new(
            root.join(MANIFEST_FILE_NAME),
            root.join(LOCKFILE_FILE_NAME),
            pkg_dir,
        )
    }

    /// Path to `mlua-pkg.toml`.
    pub fn manifest_path(&self) -> &Path {
        &self.manifest_path
    }

    /// Path to `mlua-pkg.lock`.
    pub fn lock_path(&self) -> &Path {
        &self.lock_path
    }

    /// Base directory for cache + vendored output.
    pub fn pkg_dir(&self) -> &PkgDir {
        &self.pkg_dir
    }

    /// Directory that contains the manifest.
    ///
    /// `Dep::target_dir` values are resolved relative to this.  A bare
    /// filename (`"mlua-pkg.toml"`) yields `"."`.
    pub fn manifest_root(&self) -> PathBuf {
        match self.manifest_path.parent() {
            Some(p) if !p.as_os_str().is_empty() => p.to_path_buf(),
            _ => PathBuf::from("."),
        }
    }
}

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

    #[test]
    fn pkgdir_derives_cache_and_vendored() {
        let d = PkgDir::new("/x/.mlua-pkgs");
        assert_eq!(d.base(), Path::new("/x/.mlua-pkgs"));
        assert_eq!(d.cache(), PathBuf::from("/x/.mlua-pkgs/cache"));
        assert_eq!(d.vendored(), PathBuf::from("/x/.mlua-pkgs/vendored"));
    }

    #[test]
    fn pkgdir_default_in_uses_conventional_name() {
        assert_eq!(PkgDir::default_in("/proj"), PkgDir::new("/proj/.mlua-pkgs"));
    }

    #[test]
    fn project_in_dir_uses_conventional_filenames() {
        let p = Project::in_dir("/proj", PkgDir::new("/elsewhere"));
        assert_eq!(p.manifest_path(), Path::new("/proj/mlua-pkg.toml"));
        assert_eq!(p.lock_path(), Path::new("/proj/mlua-pkg.lock"));
        assert_eq!(p.pkg_dir().base(), Path::new("/elsewhere"));
        assert_eq!(p.manifest_root(), PathBuf::from("/proj"));
    }

    #[test]
    fn manifest_root_of_bare_filename_is_dot() {
        let p = Project::new("mlua-pkg.toml", "mlua-pkg.lock", ".mlua-pkgs");
        assert_eq!(p.manifest_root(), PathBuf::from("."));
    }
}