mlua_pkg/

ops.rs

//! Package-manager operations: `install` / `add` / `update` / `clean`.
//!
//! These are the same operations the `mlua-pkg` CLI exposes, as plain
//! library functions so an embedding application can drive them directly:
//!
//! ```rust,no_run
//! use mlua_pkg::{ops, Config, PkgDir, Project};
//!
//! # fn main() -> Result<(), mlua_pkg::PkgError> {
//! let project = Project::in_dir("/srv/app", PkgDir::default_in("/srv/app"));
//! let cfg = Config::new(project);            // manifest read from mlua-pkg.toml
//! let report = ops::install(&cfg)?;
//! for pkg in &report.packages {
//!     println!("{} @ {}", pkg.name, pkg.sha);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! To supply the manifest as a value instead of a file, build the
//! [`Config`] with [`Config::with_manifest`]; see [`crate::config`] for
//! how `add` / `update` behave in that mode.
//!
//! # Contract
//!
//! - Every function takes a [`Config`] and returns a report value.  Nothing
//!   is written to stdout / stderr; the CLI renders the report.
//! - Errors are [`PkgError`].  Per-dependency fetch failures are wrapped in
//!   [`PkgError::Fetch`] so the failing name is available structurally.
//! - No function reads the process environment or the current working
//!   directory to *decide* a path.  Relative paths inside the [`Project`](crate::Project)
//!   are resolved by `std::fs` against the cwd like any other path.
//!
//! # Operation summary
//!
//! | fn | reads | writes | network |
//! |----|-------|--------|---------|
//! | [`install`] | manifest | lockfile, `<pkg_dir>/cache`, `<pkg_dir>/vendored` or `target_dir` copies | yes (fetch) |
//! | [`add`] | manifest (optional) | manifest | no |
//! | [`update`] | manifest | manifest (only `--force` tag bumps), then everything `install` writes | yes (tag listing + fetch) |
//! | [`clean`] | lockfile | removes under `<pkg_dir>/cache` | no |

use std::{
    collections::{HashMap, HashSet, VecDeque},
    path::{Path, PathBuf},
};

use crate::{
    fetcher::{FetchedPkg, Fetcher, GitFetcher},
    lockfile::{join_entry, LockedPkg, Lockfile},
    manifest::{Dep, Manifest, Package, PatchDrift},
    resolve_entry,
    version::{classify_tag_pin, pick_latest_for_pin, pick_latest_overall, TagPin},
    Config, ManifestSource, PkgError, Project,
};

// ── install ───────────────────────────────────────────────────────────────────

/// Where a dependency's **package root** was placed by [`install`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Placement {
    /// Relative symlink at `<pkg_dir>/vendored/<name>` (the default),
    /// pointing at the root (cache checkout or `patch_dir`).
    Symlink(PathBuf),
    /// Physical copy of the root into `<manifest_root>/<Dep::target_dir>`.
    Copied(PathBuf),
}

/// Requester label for a direct dependency (as opposed to a package name
/// for a transitive one).  Appears in [`InstalledPkg::requested_by`],
/// [`PkgError::Fetch`], and [`PkgError::DepConflict`].
pub const MANIFEST_REQUESTER: &str = "<manifest>";

/// One row of an [`InstallReport`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InstalledPkg {
    /// Local alias (the `[deps.<name>]` key, or the name a package's own
    /// manifest used for a transitive dep).
    pub name: String,
    /// Who asked for it: [`MANIFEST_REQUESTER`] for a direct dep, else the
    /// name of the package whose `mlua-pkg.toml` declared it.
    pub requested_by: String,
    /// Resolved commit SHA (40-char hex).
    pub sha: String,
    /// Concrete tag recorded in the lockfile (`v1.0.5` for a `v1.0` prefix
    /// pin; whatever the manifest declared otherwise).  `None` for
    /// branch / rev / unpinned deps.
    pub tag: Option<String>,
    /// Entry directory relative to the package root (`"src"`, `"."`, …).
    pub entry: PathBuf,
    /// Symlink or copy location on disk.  Either way it is the **package
    /// root**; see [`root`](Self::root) / [`require_dir`](Self::require_dir).
    pub placement: Placement,
    /// `true` when the package was resolved from its `patch_dir` (the
    /// lockfile's `patch_base` matched the pin), `false` for upstream.
    pub patched: bool,
}

impl InstalledPkg {
    /// Package root on disk: the `<vendored>/<name>` symlink or the
    /// `target_dir` copy.  Sibling directories of the entry (`types/`,
    /// docs, …) live directly under it.
    pub fn root(&self) -> &Path {
        match &self.placement {
            Placement::Symlink(p) | Placement::Copied(p) => p,
        }
    }

    /// The Lua `require` root: `root/<entry>`.
    pub fn require_dir(&self) -> PathBuf {
        join_entry(self.root(), &self.entry)
    }
}

/// Decide where the package root for `dep` comes from.
///
/// With a `patch_dir`, the pin is resolved first (no clone for a full-SHA
/// `rev`, one `ls-remote` otherwise).  When the lockfile's `patch_base`
/// equals that commit and the directory exists, the patch is the root and
/// nothing is fetched.  Otherwise the upstream is fetched, the patch is
/// left untouched, and a warning names both commits.  Returns the package
/// and whether it came from the patch.
fn resolve_root(
    fetcher: &GitFetcher,
    project: &Project,
    name: &str,
    dep: &Dep,
    requested_by: &str,
    prev: Option<&LockedPkg>,
    warnings: &mut Vec<String>,
) -> Result<(FetchedPkg, bool), PkgError> {
    let fetch_err = |e: PkgError| PkgError::Fetch {
        name: name.to_string(),
        requested_by: requested_by.to_string(),
        source: Box::new(e),
    };
    let Some(rel_patch) = &dep.patch_dir else {
        return Ok((fetcher.fetch(dep).map_err(fetch_err)?, false));
    };

    let patch_root = project.manifest_root().join(rel_patch);
    let base = prev.and_then(|p| p.patch_base.as_deref());
    // A short / symbolic rev cannot be resolved without a clone; in that
    // case the fetch happens first and its SHA is compared.
    let (sha, tag, upstream) = match fetcher.resolve_sha(dep).map_err(fetch_err)? {
        Some((sha, tag)) => (sha, tag, None),
        None => {
            let f = fetcher.fetch(dep).map_err(fetch_err)?;
            (f.sha.clone(), f.resolved_tag.clone(), Some(f))
        }
    };

    if patch_root.is_dir() && base == Some(sha.as_str()) {
        return Ok((FetchedPkg::at_root(patch_root, sha, tag)?, true));
    }

    let reason = if !patch_root.is_dir() {
        "the directory does not exist".to_string()
    } else {
        match base {
            None => "the lockfile records no patch_base for it".to_string(),
            Some(b) => format!("it was taken from {b} but the pin resolves to {sha}"),
        }
    };
    if dep.patch_drift == Some(PatchDrift::Error) {
        return Err(PkgError::PatchDrift {
            name: name.to_string(),
            patch_dir: rel_patch.clone(),
            reason,
            pinned: sha,
        });
    }

    let fetched = match upstream {
        Some(f) => f,
        None => fetcher.fetch(dep).map_err(fetch_err)?,
    };
    warnings.push(format!(
        "{name}: patch_dir '{}' not used ({reason}); using upstream {}. \
         Run `mlua-pkg patch {name} --force` to rebuild the patch from the pinned commit",
        rel_patch.display(),
        fetched.sha
    ));
    Ok((fetched, false))
}

/// Result of [`install`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct InstallReport {
    /// Every installed package, direct and transitive, sorted by name
    /// (the same order as the lockfile).
    pub packages: Vec<InstalledPkg>,
    /// Number of `[deps.<name>]` entries in the consumer manifest.
    pub direct: usize,
    /// Number of packages pulled in only through another package's
    /// `mlua-pkg.toml` (`packages.len() - direct`).
    pub transitive: usize,
    /// Non-fatal observations (e.g. requested tag vs author manifest
    /// version mismatch).  Empty when everything lined up.
    pub warnings: Vec<String>,
}

/// Fetch every dep in the manifest (and their transitive deps), place
/// them, and write the lockfile.
///
/// Resolution is a breadth-first worklist seeded with the manifest's
/// `[deps]` (sorted by name).  Every fetched package that ships its own
/// `mlua-pkg.toml` appends its `[deps]` to the worklist, so a consumer
/// declares only what it uses directly.  All packages land flat under
/// `<vendored>/<name>` and in the lockfile, which means one name maps to
/// exactly one spec: a name reached twice with an identical [`Dep`] is
/// installed once; reached with different specs the install stops with
/// [`PkgError::DepConflict`] naming both requesters.  There is no version
/// unification.
///
/// Per package:
///
/// 1. Pick the package root.  With a `patch_dir` whose lockfile
///    `patch_base` equals the pinned commit, that directory is the root and
///    nothing is fetched; otherwise fetch via [`GitFetcher`] rooted at
///    `project.pkg_dir().cache()` (a stale / missing patch is reported in
///    `warnings` and left alone).  Prefix tag pins (`tag = "v1.0"`) are
///    resolved inside the fetcher.
/// 2. Resolve the entry directory: `dep.entry` > author-manifest entry >
///    `src/` > `lua/` > `.` (see [`resolve_entry`]).
/// 3. Place the **root**: relative symlink at `<vendored>/<name>` by
///    default, or an idempotent physical copy into
///    `<manifest_root>/<target_dir>` when `target_dir` is set (a transitive
///    dep's `target_dir` / `patch_dir` is resolved against the *consumer's*
///    manifest, like a direct one).  The `require` root is `<root>/<entry>`.
/// 4. Record `(name, source, resolved tag, sha, entry, patch_dir,
///    patch_base)` for the lockfile; `patch_base` is carried over from the
///    previous lockfile, never written here.
///
/// The lockfile is written once at the end, sorted by name, so a mid-way
/// failure leaves the previous lockfile untouched and the output does not
/// depend on discovery order.
///
/// # Errors
///
/// - [`PkgError::DepConflict`] when one name carries two different specs.
/// - [`PkgError::Fetch`] wrapping the fetcher error for the failing dep.
/// - [`PkgError::EntryNotFound`] when no entry candidate exists.
/// - [`PkgError::Io`] for symlink / copy / directory creation failures.
pub fn install(cfg: &Config) -> Result<InstallReport, PkgError> {
    let project = cfg.project();
    let manifest = cfg.load_manifest()?;

    let cache_dir = project.pkg_dir().cache();
    let vendored_dir = project.pkg_dir().vendored();
    let fetcher = GitFetcher::new(cache_dir);
    std::fs::create_dir_all(&vendored_dir)?;

    let mut report = InstallReport {
        direct: manifest.deps.len(),
        ..InstallReport::default()
    };
    let mut locked_pkgs: Vec<LockedPkg> = Vec::with_capacity(manifest.deps.len());

    // The previous lockfile is consulted only for `patch_base` (which
    // `install` preserves but never writes).  A missing lockfile is the
    // first-install case; any other read failure is surfaced.
    let prev_lock: HashMap<String, LockedPkg> = match Lockfile::read(project.lock_path()) {
        Ok(lf) => lf.pkg.into_iter().map(|p| (p.name.clone(), p)).collect(),
        Err(PkgError::MissingLockfile { .. }) => HashMap::new(),
        Err(e) => return Err(e),
    };

    // Worklist over (name, dep, requested_by).  Direct deps seed it; every
    // fetched package that ships its own `mlua-pkg.toml` appends its `[deps]`.
    let mut resolved: HashMap<String, (Dep, String)> = HashMap::new();
    let mut queue: VecDeque<(String, Dep, String)> = VecDeque::new();
    let mut direct: Vec<(&String, &Dep)> = manifest.deps.iter().collect();
    direct.sort_by(|a, b| a.0.cmp(b.0));
    for (name, dep) in direct {
        queue.push_back((name.clone(), dep.clone(), MANIFEST_REQUESTER.to_string()));
    }

    while let Some((name, dep, requested_by)) = queue.pop_front() {
        if let Some((prev, prev_by)) = resolved.get(&name) {
            if *prev == dep {
                continue; // same package reached via another path
            }
            return Err(PkgError::DepConflict {
                name,
                first: prev_by.clone(),
                second: requested_by,
            });
        }
        resolved.insert(name.clone(), (dep.clone(), requested_by.clone()));
        let name = &name;
        let dep = &dep;

        // Package root: the patched copy while its recorded base still
        // matches the pin, the upstream cache checkout otherwise.
        let (fetched, patched) = resolve_root(
            &fetcher,
            project,
            name,
            dep,
            &requested_by,
            prev_lock.get(name.as_str()),
            &mut report.warnings,
        )?;

        // Transitive deps: enqueue the author's own `[deps]`, resolved later in order.
        if let Some(author) = &fetched.manifest {
            let mut sub: Vec<(&String, &Dep)> = author.deps.iter().collect();
            sub.sort_by(|a, b| a.0.cmp(b.0));
            for (sub_name, sub_dep) in sub {
                queue.push_back((sub_name.clone(), sub_dep.clone(), name.clone()));
            }
        }

        // Author manifest version-assert: warn on tag mismatch, don't hard-error.
        if let Some(author) = &fetched.manifest {
            if let Some(req_tag) = &dep.tag {
                let av = &author.package.version;
                let normalized = req_tag.strip_prefix('v').unwrap_or(req_tag.as_str());
                if av != req_tag && av != normalized {
                    report.warnings.push(format!(
                        "{name}: requested tag '{req_tag}' vs author manifest version '{av}'"
                    ));
                }
            }
        }

        // Entry resolution: dep.entry > author-manifest entry > fallback chain.
        let author_entry: Option<PathBuf> = fetched
            .manifest
            .as_ref()
            .and_then(|m| m.package.entry.clone());
        let override_entry: Option<&Path> = dep.entry.as_deref().or(author_entry.as_deref());
        let entry_abs = resolve_entry(&fetched.cache_path, override_entry)?;

        // The unit placed on disk is the package root; `entry` (relative to
        // it) is recorded so consumers can find the `require` root inside.
        let root = &fetched.cache_path;
        let placement = if let Some(rel_target_dir) = &dep.target_dir {
            // Physical vendor copy of the whole root: manifest-relative
            // directory, idempotent.
            let dest = project.manifest_root().join(rel_target_dir);
            copy_entry_into(root, &dest)?;
            Placement::Copied(dest)
        } else {
            // Default: relative symlink <vendored>/<name> → root
            // (../cache/git/… or the manifest's patch_dir).
            let symlink_path = vendored_dir.join(name);
            if symlink_path.symlink_metadata().is_ok() {
                remove_symlink(&symlink_path)?;
            }
            let rel_target = relative_path(&vendored_dir, root)?;
            create_symlink(&rel_target, &symlink_path)?;
            Placement::Symlink(symlink_path)
        };

        // Compute entry relative to the package root for the lockfile.
        let entry = entry_rel_to_pkg(root, &entry_abs);

        // Record the *resolved* tag in the lockfile (concrete release for
        // prefix pins; falls back to whatever the manifest declared).
        let locked_tag = fetched.resolved_tag.clone().or_else(|| dep.tag.clone());
        // `patch_base` is written only by `patch`; install carries it over
        // (even across a drift, so the patch is not orphaned) and drops it
        // together with `patch_dir`.
        let patch_base = dep
            .patch_dir
            .as_ref()
            .and_then(|_| prev_lock.get(name.as_str()))
            .and_then(|p| p.patch_base.clone());
        locked_pkgs.push(LockedPkg {
            name: name.clone(),
            source: format!("git+{}", dep.git),
            tag: locked_tag.clone(),
            rev: dep.rev.clone(),
            branch: dep.branch.clone(),
            sha: fetched.sha.clone(),
            entry: entry.clone(),
            patch_dir: dep.patch_dir.clone(),
            patch_base,
        });
        report.packages.push(InstalledPkg {
            name: name.clone(),
            requested_by,
            sha: fetched.sha,
            tag: locked_tag,
            entry,
            placement,
            patched,
        });
    }

    // Deterministic order regardless of HashMap iteration / discovery order.
    locked_pkgs.sort_by(|a, b| a.name.cmp(&b.name));
    report.packages.sort_by(|a, b| a.name.cmp(&b.name));
    report.transitive = report.packages.len().saturating_sub(report.direct);

    let lockfile = Lockfile {
        version: 1,
        pkg: locked_pkgs,
    };
    lockfile.write(project.lock_path())?;

    Ok(report)
}

/// Recursively copy the contents of `src` into `dest`, removing `dest` first
/// so the copy is idempotent (subsequent installs reflect upstream changes /
/// renames / deletions).
fn copy_entry_into(src: &Path, dest: &Path) -> std::io::Result<()> {
    if dest.exists() {
        std::fs::remove_dir_all(dest)?;
    }
    std::fs::create_dir_all(dest)?;
    copy_dir_contents(src, dest)
}

/// Recursively copy every entry under `src` into `dest`, materialising
/// symlinks into regular files / directories so the vendored output is
/// self-contained and never depends on the cache layout.
fn copy_dir_contents(src: &Path, dest: &Path) -> std::io::Result<()> {
    for entry in std::fs::read_dir(src)? {
        let entry = entry?;
        let from = entry.path();
        let to = dest.join(entry.file_name());
        let ft = entry.file_type()?;
        if ft.is_dir() {
            std::fs::create_dir_all(&to)?;
            copy_dir_contents(&from, &to)?;
        } else if ft.is_symlink() {
            // Materialise into a regular file/dir (vendored output should not
            // depend on the cache symlink topology).
            let resolved = std::fs::canonicalize(&from)?;
            if resolved.is_dir() {
                std::fs::create_dir_all(&to)?;
                copy_dir_contents(&resolved, &to)?;
            } else {
                std::fs::copy(&resolved, &to)?;
            }
        } else {
            std::fs::copy(&from, &to)?;
        }
    }
    Ok(())
}

/// Strip `cache_path` prefix from `entry_abs`; return `"."` for the repo root.
fn entry_rel_to_pkg(cache_path: &Path, entry_abs: &Path) -> PathBuf {
    match entry_abs.strip_prefix(cache_path) {
        Ok(rel) if rel.as_os_str().is_empty() => PathBuf::from("."),
        Ok(rel) => rel.to_path_buf(),
        Err(_) => PathBuf::from("."),
    }
}

// ── add ───────────────────────────────────────────────────────────────────────

/// What [`add`] should write into `[deps.<name>]`.
///
/// At most one of `tag` / `rev` / `branch` may be set.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct AddSpec {
    /// Local alias used in `require()`.
    pub name: String,
    /// Remote git URL.
    pub git: String,
    /// Pin to a tag (exact `v1.0.0` or prefix `v1.0`).
    pub tag: Option<String>,
    /// Pin to a commit SHA.
    pub rev: Option<String>,
    /// Track a branch (non-reproducible).
    pub branch: Option<String>,
    /// Override the Lua `require()` entry subdir.
    pub entry: Option<PathBuf>,
    /// Physically vendor the entry into this manifest-relative directory.
    pub target_dir: Option<PathBuf>,
}

impl AddSpec {
    /// Minimal spec: name + git URL, no pin.
    pub fn new(name: impl Into<String>, git: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            git: git.into(),
            ..Default::default()
        }
    }
}

/// Whether [`add`] inserted a new entry or replaced an existing one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AddOutcome {
    /// `[deps.<name>]` did not exist before.
    Added,
    /// `[deps.<name>]` existed and was overwritten.
    Replaced,
}

/// Result of [`add`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AddReport {
    /// The dep name that was written.
    pub name: String,
    /// Added vs replaced.
    pub outcome: AddOutcome,
    /// Whether the manifest file had to be created from scratch
    /// (always `false` for [`ManifestSource::Value`]).
    pub manifest_created: bool,
    /// The manifest after the insertion.  For [`ManifestSource::File`] this
    /// is what was written to `manifest_path()`; for
    /// [`ManifestSource::Value`] it is the only place the change exists.
    pub manifest: Manifest,
}

/// Insert (or replace) a `[deps.<name>]` entry in the manifest.
///
/// Performs no network I/O and never invokes the fetcher; callers run
/// [`install`] afterwards.  If the manifest file does not exist yet a
/// minimal `[package]` block is synthesised, using the manifest directory's
/// name as the package name.
///
/// The manifest is rewritten through `toml::to_string`, so comments and
/// formatting of an existing file are **not** preserved (this matches the
/// CLI's historical behaviour; `update` is the format-preserving path).
///
/// # Errors
///
/// - [`PkgError::Validation`] when more than one of `tag` / `rev` / `branch`
///   is set.
/// - [`PkgError::ManifestParse`] / [`PkgError::Io`] for an unreadable
///   existing manifest.
/// - [`PkgError::ManifestSerialize`] / [`PkgError::Io`] on write.
pub fn add(cfg: &Config, spec: AddSpec) -> Result<AddReport, PkgError> {
    let project = cfg.project();
    let ref_count = [
        spec.tag.is_some(),
        spec.rev.is_some(),
        spec.branch.is_some(),
    ]
    .into_iter()
    .filter(|&b| b)
    .count();
    if ref_count > 1 {
        return Err(PkgError::Validation {
            message: "at most one of tag, rev, branch may be specified".to_string(),
        });
    }

    let manifest_path = project.manifest_path();
    let (mut manifest, manifest_created) = match cfg.manifest_source() {
        ManifestSource::Value(m) => (m.clone(), false),
        ManifestSource::File if manifest_path.exists() => {
            (Manifest::from_path(manifest_path)?, false)
        }
        ManifestSource::File => (
            Manifest {
                package: Package {
                    name: default_package_name(&project.manifest_root()),
                    version: "0.1.0".to_string(),
                    entry: None,
                },
                deps: HashMap::new(),
            },
            true,
        ),
    };

    let AddSpec {
        name,
        git,
        tag,
        rev,
        branch,
        entry,
        target_dir,
    } = spec;
    let dep = Dep {
        git,
        tag,
        rev,
        branch,
        entry,
        target_dir,
        patch_dir: None,
        patch_drift: None,
    };
    let existed = manifest.deps.insert(name.clone(), dep).is_some();

    if !cfg.manifest_is_value() {
        let toml_str =
            toml::to_string(&manifest).map_err(|e| PkgError::ManifestSerialize { source: e })?;
        std::fs::write(manifest_path, toml_str)?;
    }

    Ok(AddReport {
        name,
        outcome: if existed {
            AddOutcome::Replaced
        } else {
            AddOutcome::Added
        },
        manifest_created,
        manifest,
    })
}

/// Package name to synthesise when `add` has to create the manifest:
/// the (canonicalised) manifest directory's basename, else `"my-project"`.
fn default_package_name(manifest_root: &Path) -> String {
    std::fs::canonicalize(manifest_root)
        .ok()
        .and_then(|p| p.file_name().map(|n| n.to_string_lossy().into_owned()))
        .unwrap_or_else(|| "my-project".to_string())
}

// ── update ────────────────────────────────────────────────────────────────────

/// Options for [`update`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct UpdateOpts {
    /// Restrict to one dep.  `None` = every `[deps.<name>]`.
    pub name: Option<String>,
    /// Compute the plan but write nothing and do not re-install.
    pub dry_run: bool,
    /// Also bump exact (full SemVer) tag pins to the SemVer-max release
    /// available on the remote.
    pub force: bool,
}

/// Per-dep decision made by [`update`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum UpdateOutcome {
    /// Exact tag pin rewritten from `old` to `new` (manifest is mutated;
    /// only emitted under `force`).
    TagBumped { old: String, new: String },
    /// Prefix tag pin re-resolves to a concrete release.  The manifest is
    /// **not** mutated — the prefix stays so it keeps auto-following future
    /// patches.  `resolved` is reported for transparency.
    PrefixResolved { pin: String, resolved: String },
    /// Branch / no-pin dep: just re-install so the lock picks up new HEAD.
    Refresh,
    /// Skipped (rev pin, exact tag without `force`, unparseable tag, no
    /// remote match).  The string is the human-readable reason.
    Skipped(String),
}

/// Result of [`update`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct UpdateReport {
    /// `(dep name, decision)` for every dep that was considered, in
    /// manifest iteration order.  Empty when `opts.name` matched nothing.
    pub entries: Vec<(String, UpdateOutcome)>,
    /// `true` when the manifest changed (only for `TagBumped` under
    /// `force`, and never under `dry_run`).  For [`ManifestSource::File`]
    /// the file was rewritten; for [`ManifestSource::Value`] nothing was
    /// written and the result is in [`manifest`](Self::manifest).
    pub manifest_modified: bool,
    /// The manifest after the update, present only when
    /// [`manifest_modified`](Self::manifest_modified) is `true`.
    pub manifest: Option<Manifest>,
    /// The re-install that followed, if any.  `None` under `dry_run` or
    /// when every entry was `Skipped`.
    pub install: Option<InstallReport>,
}

/// Refresh deps and bump tag pins as appropriate, then re-install.
///
/// Walks `[deps]` (or just `opts.name`), classifies each entry via the
/// decision table below, and — unless `opts.dry_run` — applies the
/// changes:
///
/// | dep pin              | `force` | outcome                                     |
/// | -------------------- | ------- | ------------------------------------------- |
/// | `rev = "..."`        | any     | `Skipped("rev pin")`                        |
/// | `branch = "..."`     | any     | `Refresh`                                   |
/// | `tag = "..."`, exact | `false` | `Skipped("exact tag pin …")`                |
/// | `tag = "..."`, exact | `true`  | `TagBumped` (or `Skipped("already at …")`)  |
/// | `tag = "..."`, prefix| any     | `PrefixResolved` (or `Skipped("no match")`) |
/// | `tag = "..."`, junk  | any     | `Skipped("tag '…' is not SemVer")`          |
/// | no pin               | any     | `Refresh`                                   |
///
/// `TagBumped` rewrites the manifest's `tag` value in place through
/// `toml_edit` (comments / key order preserved).  Anything other than
/// `Skipped` triggers a full [`install`] afterwards.
///
/// # Errors
///
/// - [`PkgError::UnknownDep`] when `opts.name` is not in `[deps]`.
/// - [`PkgError::ManifestEdit`] when the manifest cannot be re-parsed or
///   the `[deps.<name>]` table is not editable.
/// - Anything [`install`] can return.
pub fn update(cfg: &Config, opts: UpdateOpts) -> Result<UpdateReport, PkgError> {
    let project = cfg.project();
    let manifest_path = project.manifest_path();
    let manifest = cfg.load_manifest()?;

    if let Some(ref n) = opts.name {
        if !manifest.deps.contains_key(n) {
            return Err(PkgError::UnknownDep {
                name: n.clone(),
                manifest: manifest_path.to_path_buf(),
            });
        }
    }

    let fetcher = GitFetcher::new(project.pkg_dir().cache());
    // File mode edits through toml_edit so comments / key order survive;
    // value mode mutates a clone of the caller's Manifest instead.
    let mut doc: Option<toml_edit::DocumentMut> = if cfg.manifest_is_value() {
        None
    } else {
        Some(std::fs::read_to_string(manifest_path)?.parse()?)
    };
    let mut new_manifest = manifest.clone();

    let mut report = UpdateReport::default();
    let mut any_refresh = false;
    let mut manifest_touched = false;

    for (dep_name, dep) in &manifest.deps {
        if let Some(ref n) = opts.name {
            if dep_name != n {
                continue;
            }
        }

        let outcome = update_dep(dep_name, dep, &fetcher, opts.force)?;
        match &outcome {
            UpdateOutcome::TagBumped { new, .. } => {
                if !opts.dry_run {
                    if let Some(doc) = doc.as_mut() {
                        set_dep_tag(doc, dep_name, new)?;
                    }
                    if let Some(d) = new_manifest.deps.get_mut(dep_name) {
                        d.tag = Some(new.clone());
                    }
                    manifest_touched = true;
                }
                any_refresh = true;
            }
            UpdateOutcome::PrefixResolved { .. } | UpdateOutcome::Refresh => {
                any_refresh = true;
            }
            UpdateOutcome::Skipped(_) => {}
        }
        report.entries.push((dep_name.clone(), outcome));
    }

    if report.entries.is_empty() || opts.dry_run {
        return Ok(report);
    }

    if manifest_touched {
        if let Some(doc) = &doc {
            std::fs::write(manifest_path, doc.to_string())?;
        }
        report.manifest_modified = true;
        report.manifest = Some(new_manifest.clone());
    }

    if any_refresh {
        // Re-install against the manifest as it now is, without re-reading
        // the file (value mode has no file to re-read).
        report.install = Some(install(&cfg.replace_manifest(new_manifest))?);
    }
    Ok(report)
}

// ── patch ─────────────────────────────────────────────────────────────────────

/// Options for [`patch`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct PatchOpts {
    /// `[deps.<name>]` to materialise; it must declare `patch_dir`.
    pub name: String,
    /// Overwrite an existing `patch_dir` (local edits are discarded).
    pub force: bool,
}

/// Result of [`patch`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PatchReport {
    /// The dep name.
    pub name: String,
    /// Absolute path of the patch directory that was written.
    pub patch_dir: PathBuf,
    /// Upstream commit the directory now contains (recorded as `patch_base`).
    pub base: String,
    /// `true` when the directory did not exist before; `false` for a
    /// `--force` rebuild.
    pub created: bool,
}

/// Create (or, with `force`, rebuild) the `patch_dir` of one dep from the
/// commit its pin resolves to, and record that commit as `patch_base` in
/// the lockfile.
///
/// The whole package root is copied, so `types/` and other siblings of the
/// entry come along.  From then on [`install`] resolves the dep from the
/// patch for as long as the pin keeps resolving to `patch_base`; edit the
/// files in place and commit them with the project.  When the pin moves,
/// `install` falls back to upstream with a warning, and `patch --force`
/// rebuilds the directory from the new commit (discarding local edits —
/// re-apply them from your VCS history).
///
/// # Errors
///
/// - [`PkgError::UnknownDep`] when `name` is not in `[deps]`.
/// - [`PkgError::Validation`] when the dep has no `patch_dir`, or the
///   directory exists and `force` is not set.
/// - [`PkgError::Fetch`] wrapping the fetcher error.
/// - [`PkgError::Io`] for the copy / lockfile write.
pub fn patch(cfg: &Config, opts: PatchOpts) -> Result<PatchReport, PkgError> {
    let project = cfg.project();
    let manifest = cfg.load_manifest()?;
    let dep = manifest
        .deps
        .get(&opts.name)
        .ok_or_else(|| PkgError::UnknownDep {
            name: opts.name.clone(),
            manifest: project.manifest_path().to_path_buf(),
        })?;
    let rel_patch = dep.patch_dir.as_ref().ok_or_else(|| PkgError::Validation {
        message: format!("dep '{}' declares no patch_dir", opts.name),
    })?;
    let dest = project.manifest_root().join(rel_patch);
    let existed = dest.exists();
    if existed && !opts.force {
        return Err(PkgError::Validation {
            message: format!(
                "patch_dir '{}' already exists; pass --force to rebuild it from the pinned \
                 commit (local edits are discarded)",
                rel_patch.display()
            ),
        });
    }

    let fetcher = GitFetcher::new(project.pkg_dir().cache());
    let fetched = fetcher.fetch(dep).map_err(|e| PkgError::Fetch {
        name: opts.name.clone(),
        requested_by: MANIFEST_REQUESTER.to_string(),
        source: Box::new(e),
    })?;
    copy_entry_into(&fetched.cache_path, &dest)?;

    // Record the base in the lockfile.  A package not yet locked gets a
    // full entry so the next `install` sees a matching `patch_base`.
    let mut lock = match Lockfile::read(project.lock_path()) {
        Ok(lf) => lf,
        Err(PkgError::MissingLockfile { .. }) => Lockfile::default(),
        Err(e) => return Err(e),
    };
    match lock.pkg.iter_mut().find(|p| p.name == opts.name) {
        Some(p) => {
            p.sha = fetched.sha.clone();
            p.patch_dir = Some(rel_patch.clone());
            p.patch_base = Some(fetched.sha.clone());
        }
        None => {
            let author_entry = fetched
                .manifest
                .as_ref()
                .and_then(|m| m.package.entry.clone());
            let override_entry = dep.entry.as_deref().or(author_entry.as_deref());
            let entry_abs = resolve_entry(&fetched.cache_path, override_entry)?;
            lock.pkg.push(LockedPkg {
                name: opts.name.clone(),
                source: format!("git+{}", dep.git),
                tag: fetched.resolved_tag.clone().or_else(|| dep.tag.clone()),
                rev: dep.rev.clone(),
                branch: dep.branch.clone(),
                sha: fetched.sha.clone(),
                entry: entry_rel_to_pkg(&fetched.cache_path, &entry_abs),
                patch_dir: Some(rel_patch.clone()),
                patch_base: Some(fetched.sha.clone()),
            });
        }
    }
    lock.write(project.lock_path())?;

    Ok(PatchReport {
        name: opts.name,
        patch_dir: dest,
        base: fetched.sha,
        created: !existed,
    })
}

/// Rewrite the `tag` value for `[deps.<name>]` in `doc`, preserving formatting.
fn set_dep_tag(
    doc: &mut toml_edit::DocumentMut,
    name: &str,
    new_tag: &str,
) -> Result<(), PkgError> {
    let deps = doc
        .get_mut("deps")
        .and_then(|i| i.as_table_like_mut())
        .ok_or_else(|| PkgError::ManifestEdit {
            message: "[deps] table missing".to_string(),
        })?;
    let entry = deps.get_mut(name).ok_or_else(|| PkgError::ManifestEdit {
        message: format!("dep '{name}' missing in [deps]"),
    })?;
    if let Some(table) = entry.as_table_like_mut() {
        table.insert("tag", toml_edit::value(new_tag));
        Ok(())
    } else {
        Err(PkgError::ManifestEdit {
            message: format!("dep '{name}' is not a table-like entry"),
        })
    }
}

/// Decide what [`update`] should do for a single dep.
///
/// Pure policy: lists remote tags via the fetcher when needed but does
/// not write to disk.
fn update_dep(
    name: &str,
    dep: &Dep,
    fetcher: &GitFetcher,
    force: bool,
) -> Result<UpdateOutcome, PkgError> {
    if dep.rev.is_some() {
        return Ok(UpdateOutcome::Skipped("rev pin".into()));
    }
    if dep.branch.is_some() {
        return Ok(UpdateOutcome::Refresh);
    }
    let Some(current_tag) = &dep.tag else {
        return Ok(UpdateOutcome::Refresh);
    };

    let pin = match classify_tag_pin(current_tag) {
        Some(p) => p,
        None => {
            return Ok(UpdateOutcome::Skipped(format!(
                "tag '{current_tag}' is not SemVer"
            )))
        }
    };

    // Exact pin without force: nothing to do (without listing remote tags).
    if matches!(pin, TagPin::Exact) && !force {
        return Ok(UpdateOutcome::Skipped(
            "exact tag pin (pass --force to bump)".into(),
        ));
    }

    let tags = fetcher.list_tags(&dep.git).map_err(|e| PkgError::Fetch {
        name: name.to_string(),
        requested_by: MANIFEST_REQUESTER.to_string(),
        source: Box::new(e),
    })?;

    match pin {
        TagPin::Exact => {
            // force path: bump to the SemVer-max release on the remote.
            let Some(new_tag) = pick_latest_overall(&tags) else {
                return Ok(UpdateOutcome::Skipped(
                    "no matching SemVer release tag on remote".into(),
                ));
            };
            if &new_tag == current_tag {
                Ok(UpdateOutcome::Skipped(format!("already at {new_tag}")))
            } else {
                Ok(UpdateOutcome::TagBumped {
                    old: current_tag.clone(),
                    new: new_tag,
                })
            }
        }
        TagPin::Prefix(p) => {
            // Prefix pin: resolve to a concrete tag but leave the manifest
            // untouched so the prefix keeps auto-following future patches.
            let Some(resolved) = pick_latest_for_pin(&tags, &p) else {
                return Ok(UpdateOutcome::Skipped(
                    "no matching SemVer release tag on remote".into(),
                ));
            };
            Ok(UpdateOutcome::PrefixResolved {
                pin: current_tag.clone(),
                resolved,
            })
        }
    }
}

// ── clean ─────────────────────────────────────────────────────────────────────

/// Result of [`clean`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CleanReport {
    /// `all = true`: the whole cache directory was removed.
    CacheRemoved,
    /// No lockfile exists, so nothing was ever installed; nothing removed.
    NoLockfile,
    /// Stale-only sweep ran (or `all` on an absent cache); `removed` is the
    /// number of unreferenced SHA directories deleted (`0` = nothing to do).
    StaleRemoved { removed: usize },
}

/// Remove cached packages.
///
/// With `all = true`, removes the entire `<pkg_dir>/cache` directory.
/// Otherwise reads the lockfile, collects the set of in-use SHAs, and
/// recursively deletes any 40-hex SHA directory under `<cache>/git/` that
/// is *not* in that set.  A missing lockfile is reported, not an error.
///
/// Never touches `<pkg_dir>/vendored`; dangling symlinks there are
/// repaired by the next [`install`].
pub fn clean(cfg: &Config, all: bool) -> Result<CleanReport, PkgError> {
    let project = cfg.project();
    let cache_dir = project.pkg_dir().cache();

    if all {
        if cache_dir.exists() {
            std::fs::remove_dir_all(&cache_dir)?;
            return Ok(CleanReport::CacheRemoved);
        }
        return Ok(CleanReport::StaleRemoved { removed: 0 });
    }

    // Read lockfile — absent means nothing was ever installed.
    let lockfile = match Lockfile::read(project.lock_path()) {
        Ok(lf) => lf,
        Err(PkgError::MissingLockfile { .. }) => return Ok(CleanReport::NoLockfile),
        Err(e) => return Err(e),
    };

    let in_use: HashSet<String> = lockfile.pkg.iter().map(|p| p.sha.clone()).collect();

    let git_dir = cache_dir.join("git");
    if !git_dir.exists() {
        return Ok(CleanReport::StaleRemoved { removed: 0 });
    }

    let mut removed: usize = 0;
    remove_stale_sha_dirs(&git_dir, &in_use, &mut removed)?;
    Ok(CleanReport::StaleRemoved { removed })
}

/// Recursively walk `dir` and delete subdirectories whose name is a 40-hex
/// SHA that is absent from `in_use`.
fn remove_stale_sha_dirs(
    dir: &Path,
    in_use: &HashSet<String>,
    removed: &mut usize,
) -> std::io::Result<()> {
    for entry in std::fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();
        if !path.is_dir() {
            continue;
        }
        let file_name = entry.file_name();
        let name = file_name.to_string_lossy();
        if name.len() == 40 && name.chars().all(|c| c.is_ascii_hexdigit()) {
            if !in_use.contains(name.as_ref()) {
                std::fs::remove_dir_all(&path)?;
                *removed += 1;
            }
        } else {
            // Descend deeper (host / org / repo levels).
            remove_stale_sha_dirs(&path, in_use, removed)?;
        }
    }
    Ok(())
}

// ── symlink helpers ───────────────────────────────────────────────────────────

/// Create a directory symlink at `link` pointing to `target`.
#[cfg(unix)]
fn create_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
    std::os::unix::fs::symlink(target, link)
}

#[cfg(windows)]
fn create_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
    std::os::windows::fs::symlink_dir(target, link)
}

#[cfg(not(any(unix, windows)))]
fn create_symlink(_target: &Path, _link: &Path) -> std::io::Result<()> {
    Err(std::io::Error::new(
        std::io::ErrorKind::Unsupported,
        "symlinks not supported on this platform",
    ))
}

/// Remove a symlink at `path`.
#[cfg(unix)]
fn remove_symlink(path: &Path) -> std::io::Result<()> {
    std::fs::remove_file(path)
}

#[cfg(windows)]
fn remove_symlink(path: &Path) -> std::io::Result<()> {
    // On Windows a directory symlink is removed with remove_dir.
    if path.is_dir() {
        std::fs::remove_dir(path)
    } else {
        std::fs::remove_file(path)
    }
}

#[cfg(not(any(unix, windows)))]
fn remove_symlink(path: &Path) -> std::io::Result<()> {
    std::fs::remove_file(path)
}

/// Compute the path to `to` relative to `from_dir`.
///
/// Canonicalises both arguments so the result is correct even when the
/// process working directory is a symlinked path (e.g. macOS `/Users` →
/// `/private/Users`).  Both paths must already exist on the filesystem.
fn relative_path(from_dir: &Path, to: &Path) -> std::io::Result<PathBuf> {
    let from_abs = std::fs::canonicalize(from_dir)?;
    let to_abs = std::fs::canonicalize(to)?;

    let from_parts: Vec<_> = from_abs.components().collect();
    let to_parts: Vec<_> = to_abs.components().collect();

    let common = from_parts
        .iter()
        .zip(to_parts.iter())
        .take_while(|(a, b)| a == b)
        .count();

    let mut rel = PathBuf::new();
    for _ in &from_parts[common..] {
        rel.push("..");
    }
    for c in &to_parts[common..] {
        rel.push(c);
    }
    Ok(rel)
}

// ── tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{PkgDir, Project};
    use tempfile::TempDir;

    // ── helpers ───────────────────────────────────────────────────────────────

    /// Initialise a git repository at `dir`, write a single `main.lua`
    /// file, commit it, and return the 40-char commit SHA.
    fn init_repo_with_commit(dir: &Path) -> String {
        use git2::{Repository, Signature};

        let repo = Repository::init(dir).unwrap();
        {
            let mut cfg = repo.config().unwrap();
            cfg.set_str("user.name", "Test").unwrap();
            cfg.set_str("user.email", "test@example.com").unwrap();
        }

        std::fs::write(dir.join("main.lua"), "return {}\n").unwrap();

        let mut index = repo.index().unwrap();
        index.add_path(Path::new("main.lua")).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, "init", &tree, &[])
            .unwrap();
        oid.to_string()
    }

    /// Add an annotated tag to HEAD of the repo at `dir`.
    fn add_tag(dir: &Path, tag: &str) {
        use git2::{Repository, Signature};
        let repo = Repository::open(dir).unwrap();
        let head = repo.head().unwrap().peel_to_commit().unwrap();
        let sig = Signature::now("Test", "test@example.com").unwrap();
        repo.tag(tag, head.as_object(), &sig, tag, false).unwrap();
    }

    /// Write `content` to `path` (creating parent dirs as needed).
    fn write_file(path: &Path, content: &str) {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).unwrap();
        }
        std::fs::write(path, content).unwrap();
    }

    /// Conventional project layout inside `dir`.
    fn project_in(dir: &Path) -> Project {
        Project::in_dir(dir, PkgDir::default_in(dir))
    }

    /// File-backed config over `p` (the CLI's mode).
    fn cfg(p: &Project) -> Config {
        Config::new(p.clone())
    }

    fn manifest_with_dep(url: &str, dep_body: &str) -> String {
        format!(
            "[package]\nname = \"test\"\nversion = \"0.1.0\"\n\n\
             [deps]\nmylib = {{ git = \"{url}\", {dep_body} }}\n"
        )
    }

    // ── install ───────────────────────────────────────────────────────────────

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

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, &format!("rev = \"{sha}\"")),
        );

        let report = install(&cfg(&project)).unwrap();

        assert_eq!(report.packages.len(), 1);
        assert_eq!(report.packages[0].name, "mylib");
        assert_eq!(report.packages[0].sha, sha);
        assert!(report.warnings.is_empty());

        // Lockfile exists and has one entry.
        assert!(project.lock_path().exists(), "lockfile must be written");
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg.len(), 1, "one locked package");
        assert_eq!(lf.pkg[0].name, "mylib");
        assert_eq!(lf.pkg[0].sha, sha);
        assert_eq!(lf.pkg[0].source, format!("git+{url}"));

        // Vendored symlink exists and is reported.
        let symlink = project.pkg_dir().vendored().join("mylib");
        assert_eq!(
            report.packages[0].placement,
            Placement::Symlink(symlink.clone())
        );
        assert!(
            symlink.symlink_metadata().is_ok(),
            "symlink <vendored>/mylib must exist"
        );
        // Symlink target must be relative (not absolute).
        let target = std::fs::read_link(&symlink).unwrap();
        assert!(
            target.is_relative(),
            "symlink target must be a relative path, got: {}",
            target.display()
        );
    }

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

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(
                &url,
                &format!("rev = \"{sha}\", target_dir = \"lua/mylib\""),
            ),
        );

        let report = install(&cfg(&project)).unwrap();

        // target_dir holds a real file (not a symlink).
        let vendored_file = dir.path().join("lua/mylib/main.lua");
        assert!(
            vendored_file.exists(),
            "vendored file must exist at target_dir"
        );
        let meta = std::fs::symlink_metadata(&vendored_file).unwrap();
        assert!(
            !meta.file_type().is_symlink(),
            "vendored output must be a regular file, not a symlink"
        );
        assert_eq!(
            report.packages[0].placement,
            Placement::Copied(dir.path().join("lua/mylib"))
        );

        // Default symlink path must NOT be created when target_dir is set.
        assert!(
            project
                .pkg_dir()
                .vendored()
                .join("mylib")
                .symlink_metadata()
                .is_err(),
            "<vendored>/<name> must not be created when target_dir is set"
        );

        // Lockfile entry still recorded.
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg.len(), 1);
        assert_eq!(lf.pkg[0].sha, sha);
    }

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

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(
                &url,
                &format!("rev = \"{sha}\", target_dir = \"lua/mylib\""),
            ),
        );

        install(&cfg(&project)).unwrap();
        install(&cfg(&project)).unwrap();

        assert!(dir.path().join("lua/mylib/main.lua").exists());
    }

    // ── package root as the unit ──────────────────────────────────────────────

    /// Commit `files` (path → content) on top of HEAD in `dir`; return the SHA.
    fn commit_files(dir: &Path, files: &[(&str, &str)], msg: &str) -> String {
        use git2::{Repository, Signature};
        let repo = Repository::open(dir).unwrap();
        let mut index = repo.index().unwrap();
        for (rel, content) in files {
            write_file(&dir.join(rel), content);
            index.add_path(Path::new(rel)).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, msg, &tree, &[&parent])
            .unwrap()
            .to_string()
    }

    /// Remote with `src/main.lua` (entry) and a `types/` sibling; returns its SHA.
    fn init_repo_with_src_and_types(dir: &Path) -> String {
        init_repo_with_commit(dir);
        std::fs::remove_file(dir.join("main.lua")).unwrap();
        commit_files(
            dir,
            &[
                ("src/main.lua", "return { v = 1 }\n"),
                ("types/main.d.lua", "---@meta\n"),
            ],
            "layout",
        )
    }

    #[test]
    fn install_links_package_root_and_records_entry() {
        let remote = TempDir::new().unwrap();
        let sha = init_repo_with_src_and_types(remote.path());

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, &format!("rev = \"{sha}\"")),
        );

        let report = install(&cfg(&project)).unwrap();
        let pkg = &report.packages[0];
        assert_eq!(pkg.entry, PathBuf::from("src"));
        assert!(!pkg.patched);
        // The symlink is the package root: types/ sits directly under it.
        assert!(pkg.root().join("types/main.d.lua").exists());
        assert!(pkg.require_dir().join("main.lua").exists());
        assert_eq!(pkg.root(), project.pkg_dir().vendored_root("mylib"));

        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg[0].entry, PathBuf::from("src"));
        assert_eq!(
            lf.pkg[0].require_dir(pkg.root()),
            project.pkg_dir().vendored_root("mylib").join("src")
        );
        assert_eq!(lf.pkg[0].patch_dir, None);
        assert_eq!(lf.pkg[0].patch_base, None);
    }

    #[test]
    fn install_with_target_dir_copies_package_root() {
        let remote = TempDir::new().unwrap();
        let sha = init_repo_with_src_and_types(remote.path());

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(
                &url,
                &format!("rev = \"{sha}\", target_dir = \"lua/mylib\""),
            ),
        );

        let report = install(&cfg(&project)).unwrap();
        let pkg = &report.packages[0];
        assert_eq!(
            pkg.placement,
            Placement::Copied(dir.path().join("lua/mylib"))
        );
        assert!(dir.path().join("lua/mylib/src/main.lua").exists());
        assert!(dir.path().join("lua/mylib/types/main.d.lua").exists());
        assert_eq!(pkg.require_dir(), dir.path().join("lua/mylib/src"));
    }

    // ── patch_dir ─────────────────────────────────────────────────────────────

    fn manifest_with_patched_dep(url: &str, sha: &str) -> String {
        manifest_with_dep(
            url,
            &format!("rev = \"{sha}\", patch_dir = \"patches/mylib\""),
        )
    }

    #[test]
    fn patch_creates_dir_and_install_resolves_from_it() {
        let remote = TempDir::new().unwrap();
        let sha = init_repo_with_src_and_types(remote.path());

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_patched_dep(&url, &sha),
        );

        // Before `patch`: upstream, with a warning naming the missing dir.
        let report = install(&cfg(&project)).unwrap();
        assert!(!report.packages[0].patched);
        assert_eq!(report.warnings.len(), 1, "{:?}", report.warnings);
        assert!(report.warnings[0].contains("patches/mylib"));
        assert!(report.warnings[0].contains("does not exist"));

        let pr = patch(
            &cfg(&project),
            PatchOpts {
                name: "mylib".into(),
                force: false,
            },
        )
        .unwrap();
        assert!(pr.created);
        assert_eq!(pr.base, sha);
        let patch_root = dir.path().join("patches/mylib");
        assert_eq!(pr.patch_dir, patch_root);
        assert!(patch_root.join("src/main.lua").exists());
        assert!(patch_root.join("types/main.d.lua").exists());
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg[0].patch_base.as_deref(), Some(sha.as_str()));
        assert_eq!(lf.pkg[0].patch_dir, Some(PathBuf::from("patches/mylib")));

        // Edit the patch, then install: resolved from the patch, no warning.
        write_file(
            &patch_root.join("src/main.lua"),
            "return { v = 'patched' }\n",
        );
        let report = install(&cfg(&project)).unwrap();
        let pkg = &report.packages[0];
        assert!(pkg.patched, "{:?}", report.warnings);
        assert!(report.warnings.is_empty(), "{:?}", report.warnings);
        assert_eq!(pkg.sha, sha);
        assert_eq!(
            std::fs::canonicalize(pkg.root()).unwrap(),
            std::fs::canonicalize(&patch_root).unwrap()
        );
        assert_eq!(
            std::fs::read_to_string(pkg.require_dir().join("main.lua")).unwrap(),
            "return { v = 'patched' }\n"
        );
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg[0].patch_base.as_deref(), Some(sha.as_str()));

        // A second `patch` without --force must not clobber the edit.
        let err = patch(
            &cfg(&project),
            PatchOpts {
                name: "mylib".into(),
                force: false,
            },
        )
        .unwrap_err();
        assert!(matches!(err, PkgError::Validation { .. }), "{err}");
        assert_eq!(
            std::fs::read_to_string(patch_root.join("src/main.lua")).unwrap(),
            "return { v = 'patched' }\n"
        );
    }

    #[test]
    fn patch_drift_falls_back_to_upstream_and_keeps_dir() {
        let remote = TempDir::new().unwrap();
        let sha1 = init_repo_with_src_and_types(remote.path());

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_patched_dep(&url, &sha1),
        );
        patch(
            &cfg(&project),
            PatchOpts {
                name: "mylib".into(),
                force: false,
            },
        )
        .unwrap();
        let patch_root = dir.path().join("patches/mylib");
        write_file(
            &patch_root.join("src/main.lua"),
            "return { v = 'patched' }\n",
        );

        // Upstream moves and the pin follows it.
        let sha2 = commit_files(
            remote.path(),
            &[("src/main.lua", "return { v = 2 }\n")],
            "second",
        );
        write_file(
            project.manifest_path(),
            &manifest_with_patched_dep(&url, &sha2),
        );

        let report = install(&cfg(&project)).unwrap();
        let pkg = &report.packages[0];
        assert!(!pkg.patched);
        assert_eq!(pkg.sha, sha2);
        assert_eq!(report.warnings.len(), 1, "{:?}", report.warnings);
        assert!(report.warnings[0].contains(&sha1), "{}", report.warnings[0]);
        assert!(report.warnings[0].contains(&sha2), "{}", report.warnings[0]);
        // The patch is untouched and its base is preserved in the lockfile.
        assert_eq!(
            std::fs::read_to_string(patch_root.join("src/main.lua")).unwrap(),
            "return { v = 'patched' }\n"
        );
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg[0].sha, sha2);
        assert_eq!(lf.pkg[0].patch_base.as_deref(), Some(sha1.as_str()));
        assert_eq!(
            std::fs::read_to_string(pkg.require_dir().join("main.lua")).unwrap(),
            "return { v = 2 }\n"
        );

        // `patch --force` rebases the directory onto the new pin.
        let pr = patch(
            &cfg(&project),
            PatchOpts {
                name: "mylib".into(),
                force: true,
            },
        )
        .unwrap();
        assert!(!pr.created);
        assert_eq!(pr.base, sha2);
        assert_eq!(
            std::fs::read_to_string(patch_root.join("src/main.lua")).unwrap(),
            "return { v = 2 }\n"
        );
        let report = install(&cfg(&project)).unwrap();
        assert!(report.packages[0].patched);
        assert!(report.warnings.is_empty(), "{:?}", report.warnings);
    }

    #[test]
    fn patch_drift_error_policy_stops_install() {
        let remote = TempDir::new().unwrap();
        let sha1 = init_repo_with_src_and_types(remote.path());

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        let strict = |sha: &str| {
            manifest_with_dep(
                &url,
                &format!("rev = \"{sha}\", patch_dir = \"patches/mylib\", patch_drift = \"error\""),
            )
        };
        write_file(project.manifest_path(), &strict(&sha1));

        // No patch yet: strict install refuses instead of warning.
        let err = install(&cfg(&project)).unwrap_err();
        assert!(
            matches!(&err, PkgError::PatchDrift { name, reason, .. }
                if name == "mylib" && reason.contains("does not exist")),
            "{err}"
        );
        assert!(
            !project.lock_path().exists(),
            "lockfile must not be written"
        );

        patch(
            &cfg(&project),
            PatchOpts {
                name: "mylib".into(),
                force: false,
            },
        )
        .unwrap();
        let report = install(&cfg(&project)).unwrap();
        assert!(report.packages[0].patched);
        assert!(report.warnings.is_empty());

        // Pin moves: strict install fails, naming both commits, and neither
        // the patch nor the lockfile is touched.
        let patch_root = dir.path().join("patches/mylib");
        write_file(
            &patch_root.join("src/main.lua"),
            "return { v = 'patched' }\n",
        );
        let sha2 = commit_files(
            remote.path(),
            &[("src/main.lua", "return { v = 2 }\n")],
            "second",
        );
        write_file(project.manifest_path(), &strict(&sha2));
        let err = install(&cfg(&project)).unwrap_err();
        match &err {
            PkgError::PatchDrift { reason, pinned, .. } => {
                assert!(reason.contains(&sha1), "{reason}");
                assert_eq!(pinned, &sha2);
            }
            other => panic!("expected PatchDrift, got {other}"),
        }
        assert!(err.to_string().contains("mlua-pkg patch mylib --force"));
        assert_eq!(
            std::fs::read_to_string(patch_root.join("src/main.lua")).unwrap(),
            "return { v = 'patched' }\n"
        );
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg[0].sha, sha1);
        assert_eq!(lf.pkg[0].patch_base.as_deref(), Some(sha1.as_str()));
    }

    #[test]
    fn patch_requires_patch_dir_in_manifest() {
        let remote = TempDir::new().unwrap();
        let sha = init_repo_with_commit(remote.path());
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, &format!("rev = \"{sha}\"")),
        );
        let err = patch(
            &cfg(&project),
            PatchOpts {
                name: "mylib".into(),
                force: false,
            },
        )
        .unwrap_err();
        assert!(matches!(err, PkgError::Validation { .. }), "{err}");
        let err = patch(
            &cfg(&project),
            PatchOpts {
                name: "nope".into(),
                force: false,
            },
        )
        .unwrap_err();
        assert!(matches!(err, PkgError::UnknownDep { .. }), "{err}");
    }

    #[test]
    fn install_missing_manifest_returns_error() {
        let dir = TempDir::new().unwrap();
        let result = install(&cfg(&project_in(dir.path())));
        assert!(result.is_err(), "must fail when mlua-pkg.toml is absent");
    }

    #[test]
    fn install_is_idempotent() {
        // Running install twice must succeed (symlink replaced, lockfile overwritten).
        let remote = TempDir::new().unwrap();
        let sha = init_repo_with_commit(remote.path());

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, &format!("rev = \"{sha}\"")),
        );

        install(&cfg(&project)).unwrap();
        install(&cfg(&project)).unwrap();

        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg.len(), 1);
    }

    #[test]
    fn install_with_prefix_pin_resolves_to_concrete_tag() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v1.0.5");
        add_tag(remote.path(), "v2.0.0");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, "tag = \"v1.0\""),
        );

        let report = install(&cfg(&project)).unwrap();
        assert_eq!(report.packages[0].tag.as_deref(), Some("v1.0.5"));

        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(
            lf.pkg[0].tag.as_deref(),
            Some("v1.0.5"),
            "install must resolve prefix v1.0 to concrete v1.0.5 (excluding v2.0.0):\n{lf:?}"
        );
    }

    #[test]
    fn install_fetch_failure_names_the_dep() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        write_file(
            project.manifest_path(),
            &manifest_with_dep("file:///nonexistent/repo", "branch = \"main\""),
        );

        let err = install(&cfg(&project)).unwrap_err();
        assert!(
            matches!(&err, PkgError::Fetch { name, .. } if name == "mylib"),
            "expected Fetch {{ name: mylib }}, got: {err:?}"
        );
    }

    #[test]
    fn install_uses_pkg_dir_not_cwd_convention() {
        // The cache / vendored dirs must follow PkgDir, not any fixed name.
        let remote = TempDir::new().unwrap();
        let sha = init_repo_with_commit(remote.path());

        let dir = TempDir::new().unwrap();
        let custom = dir.path().join("elsewhere/pkgs");
        let project = Project::in_dir(dir.path(), PkgDir::new(&custom));
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, &format!("rev = \"{sha}\"")),
        );

        install(&cfg(&project)).unwrap();

        assert!(custom.join("cache").is_dir());
        assert!(custom.join("vendored/mylib").symlink_metadata().is_ok());
        assert!(!dir.path().join(".mlua-pkgs").exists());
    }

    // ── value-mode manifest (Config::with_manifest) ───────────────────────────

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

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        let manifest =
            Manifest::from_toml_str(&manifest_with_dep(&url, &format!("rev = \"{sha}\""))).unwrap();
        let vcfg = Config::with_manifest(project.clone(), manifest);

        let report = install(&vcfg).unwrap();

        assert_eq!(report.packages[0].sha, sha);
        assert!(
            !project.manifest_path().exists(),
            "value mode must not write the manifest"
        );
        assert!(project.lock_path().exists(), "lockfile is still an output");
        assert!(project
            .pkg_dir()
            .vendored()
            .join("mylib")
            .symlink_metadata()
            .is_ok());
    }

    #[test]
    fn add_value_mode_returns_manifest_without_writing() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let base =
            Manifest::from_toml_str("[package]\nname = \"v\"\nversion = \"0.1.0\"\n").unwrap();
        let vcfg = Config::with_manifest(project.clone(), base);

        let report = add(&vcfg, AddSpec::new("lib", "https://github.com/x/lib")).unwrap();

        assert_eq!(report.outcome, AddOutcome::Added);
        assert!(!report.manifest_created);
        assert_eq!(report.manifest.deps["lib"].git, "https://github.com/x/lib");
        assert!(
            !project.manifest_path().exists(),
            "value mode must not write the manifest"
        );
        // The caller's Config is untouched; the change lives only in the report.
        assert!(vcfg.load_manifest().unwrap().deps.is_empty());
    }

    #[test]
    fn update_value_mode_force_returns_new_manifest_and_installs() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v2.0.0");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        let manifest =
            Manifest::from_toml_str(&manifest_with_dep(&url, "tag = \"v1.0.0\"")).unwrap();
        let vcfg = Config::with_manifest(project.clone(), manifest);

        let report = update(
            &vcfg,
            UpdateOpts {
                force: true,
                ..Default::default()
            },
        )
        .unwrap();

        assert!(report.manifest_modified);
        let new_manifest = report.manifest.expect("new manifest returned");
        assert_eq!(new_manifest.deps["mylib"].tag.as_deref(), Some("v2.0.0"));
        assert!(
            !project.manifest_path().exists(),
            "value mode must not write the manifest"
        );
        // Re-install ran against the *new* manifest: lock records v2.0.0.
        assert!(report.install.is_some());
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg[0].tag.as_deref(), Some("v2.0.0"));
    }

    #[test]
    fn update_file_mode_reports_new_manifest_too() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v2.0.0");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, "tag = \"v1.0.0\""),
        );

        let report = update(
            &cfg(&project),
            UpdateOpts {
                force: true,
                ..Default::default()
            },
        )
        .unwrap();

        let new_manifest = report.manifest.expect("new manifest returned");
        assert_eq!(new_manifest.deps["mylib"].tag.as_deref(), Some("v2.0.0"));
        // ...and it matches what was written to disk.
        assert_eq!(
            Manifest::from_path(project.manifest_path()).unwrap(),
            new_manifest
        );
    }

    // ── transitive deps ───────────────────────────────────────────────────────

    /// Initialise a git repository at `dir` with the given files committed;
    /// return the commit SHA.
    fn init_repo_with_files(dir: &Path, files: &[(&str, &str)]) -> String {
        use git2::{Repository, Signature};

        let repo = Repository::init(dir).unwrap();
        {
            let mut cfg = repo.config().unwrap();
            cfg.set_str("user.name", "Test").unwrap();
            cfg.set_str("user.email", "test@example.com").unwrap();
        }
        let mut index = repo.index().unwrap();
        for (rel, content) in files {
            write_file(&dir.join(rel), content);
            index.add_path(Path::new(rel)).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, "init", &tree, &[])
            .unwrap()
            .to_string()
    }

    /// leaf (plain) + mid (declares leaf in its own mlua-pkg.toml).
    /// Returns `(leaf_url, leaf_sha, mid_url, mid_sha)`; the TempDirs are
    /// leaked into the returned tuple's lifetime via the caller's bindings.
    fn leaf_and_mid(leaf: &TempDir, mid: &TempDir) -> (String, String, String, String) {
        let leaf_sha =
            init_repo_with_files(leaf.path(), &[("main.lua", "return { leaf = true }\n")]);
        let leaf_url = format!("file://{}", leaf.path().display());
        let mid_manifest = format!(
            "[package]\nname = \"mid\"\nversion = \"0.1.0\"\n\n\
             [deps]\nleaf = {{ git = \"{leaf_url}\", rev = \"{leaf_sha}\" }}\n"
        );
        let mid_sha = init_repo_with_files(
            mid.path(),
            &[
                ("main.lua", "return require('leaf')\n"),
                ("mlua-pkg.toml", &mid_manifest),
            ],
        );
        let mid_url = format!("file://{}", mid.path().display());
        (leaf_url, leaf_sha, mid_url, mid_sha)
    }

    #[test]
    fn install_resolves_transitive_deps_from_author_manifest() {
        let (leaf, mid) = (TempDir::new().unwrap(), TempDir::new().unwrap());
        let (_leaf_url, leaf_sha, mid_url, mid_sha) = leaf_and_mid(&leaf, &mid);

        // root: only declares mid
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        write_file(
            project.manifest_path(),
            &format!(
                "[package]\nname = \"root\"\nversion = \"0.1.0\"\n\n\
                 [deps]\nmid = {{ git = \"{mid_url}\", rev = \"{mid_sha}\" }}\n"
            ),
        );

        let report = install(&cfg(&project)).unwrap();

        assert_eq!(report.direct, 1);
        assert_eq!(report.transitive, 1);
        let names: Vec<&str> = report.packages.iter().map(|p| p.name.as_str()).collect();
        assert_eq!(names, vec!["leaf", "mid"], "report sorted by name");
        assert_eq!(report.packages[0].requested_by, "mid");
        assert_eq!(report.packages[1].requested_by, MANIFEST_REQUESTER);

        let lf = Lockfile::read(project.lock_path()).unwrap();
        let names: Vec<&str> = lf.pkg.iter().map(|p| p.name.as_str()).collect();
        assert_eq!(
            names,
            vec!["leaf", "mid"],
            "both packages locked, sorted by name"
        );
        assert_eq!(lf.pkg[0].sha, leaf_sha);
        assert_eq!(lf.pkg[1].sha, mid_sha);
        let vendored = project.pkg_dir().vendored();
        assert!(
            vendored.join("leaf").symlink_metadata().is_ok(),
            "leaf vendored"
        );
        assert!(
            vendored.join("mid").symlink_metadata().is_ok(),
            "mid vendored"
        );

        // Idempotent.
        install(&cfg(&project)).unwrap();
        assert_eq!(Lockfile::read(project.lock_path()).unwrap().pkg.len(), 2);
    }

    #[test]
    fn install_same_dep_reached_twice_with_identical_spec_is_fine() {
        let (leaf, mid) = (TempDir::new().unwrap(), TempDir::new().unwrap());
        let (leaf_url, leaf_sha, mid_url, mid_sha) = leaf_and_mid(&leaf, &mid);

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        // root declares leaf itself with the *same* spec mid uses.
        write_file(
            project.manifest_path(),
            &format!(
                "[package]\nname = \"root\"\nversion = \"0.1.0\"\n\n\
                 [deps]\nmid = {{ git = \"{mid_url}\", rev = \"{mid_sha}\" }}\n\
                 leaf = {{ git = \"{leaf_url}\", rev = \"{leaf_sha}\" }}\n"
            ),
        );

        let report = install(&cfg(&project)).unwrap();
        assert_eq!(report.packages.len(), 2);
        assert_eq!((report.direct, report.transitive), (2, 0));
        // First requester wins the label: leaf is direct here (sorted before mid).
        assert_eq!(report.packages[0].requested_by, MANIFEST_REQUESTER);
        assert_eq!(Lockfile::read(project.lock_path()).unwrap().pkg.len(), 2);
    }

    #[test]
    fn install_conflicting_transitive_spec_fails() {
        let (leaf, mid) = (TempDir::new().unwrap(), TempDir::new().unwrap());
        let (leaf_url, leaf_sha, mid_url, mid_sha) = leaf_and_mid(&leaf, &mid);

        // mid pins leaf by rev; root pins the same rev but with an `entry`
        // override -> a different `Dep` spec, which is a conflict.
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        write_file(
            project.manifest_path(),
            &format!(
                "[package]\nname = \"root\"\nversion = \"0.1.0\"\n\n\
                 [deps]\nleaf = {{ git = \"{leaf_url}\", rev = \"{leaf_sha}\", entry = \".\" }}\n\
                 mid = {{ git = \"{mid_url}\", rev = \"{mid_sha}\" }}\n"
            ),
        );

        let err = install(&cfg(&project)).unwrap_err();
        assert!(
            matches!(&err, PkgError::DepConflict { name, first, second }
                if name == "leaf" && first == MANIFEST_REQUESTER && second == "mid"),
            "expected DepConflict for 'leaf', got: {err:?}"
        );
        assert!(
            !project.lock_path().exists(),
            "lockfile must not be written on conflict"
        );
    }

    // ── add ───────────────────────────────────────────────────────────────────

    #[test]
    fn add_creates_manifest_with_dep() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());

        let report = add(
            &cfg(&project),
            AddSpec {
                tag: Some("v1.0.0".to_string()),
                ..AddSpec::new("mylib", "https://github.com/x/mylib")
            },
        )
        .unwrap();
        assert_eq!(report.outcome, AddOutcome::Added);
        assert!(report.manifest_created);

        let manifest = Manifest::from_path(project.manifest_path()).unwrap();
        assert!(manifest.deps.contains_key("mylib"), "dep must be present");
        let dep = &manifest.deps["mylib"];
        assert_eq!(dep.git, "https://github.com/x/mylib");
        assert_eq!(dep.tag.as_deref(), Some("v1.0.0"));
        assert!(dep.rev.is_none());
        assert!(dep.branch.is_none());
        // Package name comes from the manifest directory, not the cwd.
        let expected = std::fs::canonicalize(dir.path()).unwrap();
        assert_eq!(
            manifest.package.name,
            expected.file_name().unwrap().to_string_lossy()
        );
    }

    #[test]
    fn add_to_existing_manifest_preserves_other_deps() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());

        write_file(
            project.manifest_path(),
            "[package]\nname = \"test\"\nversion = \"0.1.0\"\n\n\
             [deps]\nexisting = { git = \"https://github.com/a/b\", branch = \"main\" }\n",
        );

        let report = add(
            &cfg(&project),
            AddSpec {
                rev: Some("abc1234567890123456789012345678901234567890".to_string()),
                ..AddSpec::new("newdep", "https://github.com/x/newdep")
            },
        )
        .unwrap();
        assert_eq!(report.outcome, AddOutcome::Added);
        assert!(!report.manifest_created);

        let manifest = Manifest::from_path(project.manifest_path()).unwrap();
        assert_eq!(manifest.deps.len(), 2, "both deps must be present");
        assert!(manifest.deps.contains_key("existing"));
        assert!(manifest.deps.contains_key("newdep"));
    }

    #[test]
    fn add_existing_name_reports_replaced() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        add(
            &cfg(&project),
            AddSpec::new("lib", "https://github.com/x/lib"),
        )
        .unwrap();
        let report = add(
            &cfg(&project),
            AddSpec::new("lib", "https://github.com/y/lib"),
        )
        .unwrap();
        assert_eq!(report.outcome, AddOutcome::Replaced);
        let manifest = Manifest::from_path(project.manifest_path()).unwrap();
        assert_eq!(manifest.deps["lib"].git, "https://github.com/y/lib");
    }

    #[test]
    fn add_rejects_multiple_ref_fields() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());

        let result = add(
            &cfg(&project),
            AddSpec {
                tag: Some("v1.0.0".to_string()),
                rev: Some("abc123".to_string()),
                ..AddSpec::new("lib", "https://github.com/x/lib")
            },
        );
        assert!(
            matches!(result, Err(PkgError::Validation { .. })),
            "tag + rev together must be rejected: {result:?}"
        );
    }

    // ── update ────────────────────────────────────────────────────────────────
    // Pure helpers (classify_tag_pin / pick_latest_*) are covered in
    // crate::version unit tests.  The cases here exercise lock + manifest
    // mutation behaviour around `update`.

    #[test]
    fn set_dep_tag_preserves_inline_layout() {
        let toml = "[package]\nname = \"x\"\nversion = \"0.1.0\"\n\n\
                    [deps]\nfoo = { git = \"https://example.com/foo\", tag = \"v1.0.0\" }\n";
        let mut doc: toml_edit::DocumentMut = toml.parse().unwrap();
        set_dep_tag(&mut doc, "foo", "v1.0.5").unwrap();
        let out = doc.to_string();
        assert!(
            out.contains("tag = \"v1.0.5\""),
            "new tag must be written:\n{out}"
        );
        assert!(
            out.contains("git = \"https://example.com/foo\""),
            "git URL preserved"
        );
    }

    #[test]
    fn update_prefix_pin_refreshes_lock_without_mutating_manifest() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v1.0.1");
        add_tag(remote.path(), "v1.0.5");
        add_tag(remote.path(), "v1.1.0");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        let original = manifest_with_dep(&url, "tag = \"v1.0\"");
        write_file(project.manifest_path(), &original);

        let report = update(&cfg(&project), UpdateOpts::default()).unwrap();

        assert_eq!(report.entries.len(), 1);
        assert!(matches!(
            &report.entries[0].1,
            UpdateOutcome::PrefixResolved { pin, resolved }
                if pin == "v1.0" && resolved == "v1.0.5"
        ));
        assert!(!report.manifest_modified);
        assert!(
            report.install.is_some(),
            "prefix pin must trigger re-install"
        );

        // Manifest stays as the prefix — auto-follow intent is preserved.
        let after = std::fs::read_to_string(project.manifest_path()).unwrap();
        assert_eq!(
            after, original,
            "prefix pin manifest must not be rewritten:\n{after}"
        );

        // Lockfile records the resolved concrete tag (v1.0.5, not v1.1.0).
        let lf = Lockfile::read(project.lock_path()).unwrap();
        assert_eq!(lf.pkg.len(), 1, "one locked package");
        assert_eq!(
            lf.pkg[0].tag.as_deref(),
            Some("v1.0.5"),
            "lock must record resolved concrete tag"
        );
    }

    #[test]
    fn update_dry_run_leaves_manifest_unmodified() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v1.0.5");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        let original = manifest_with_dep(&url, "tag = \"v1.0\"");
        write_file(project.manifest_path(), &original);

        let report = update(
            &cfg(&project),
            UpdateOpts {
                dry_run: true,
                ..Default::default()
            },
        )
        .unwrap();

        assert_eq!(report.entries.len(), 1);
        assert!(report.install.is_none(), "dry-run must not install");
        assert!(!report.manifest_modified);
        let after = std::fs::read_to_string(project.manifest_path()).unwrap();
        assert_eq!(after, original, "dry-run must not modify manifest");
        assert!(!project.lock_path().exists(), "dry-run must not write lock");
    }

    #[test]
    fn update_exact_pin_without_force_is_noop() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v1.0.5");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, "tag = \"v1.0.0\""),
        );

        let report = update(&cfg(&project), UpdateOpts::default()).unwrap();

        assert!(matches!(&report.entries[0].1, UpdateOutcome::Skipped(_)));
        assert!(report.install.is_none(), "all-skipped must not install");
        let after = std::fs::read_to_string(project.manifest_path()).unwrap();
        assert!(
            after.contains("tag = \"v1.0.0\""),
            "exact pin must remain v1.0.0 without force:\n{after}"
        );
    }

    #[test]
    fn update_exact_pin_with_force_bumps_to_latest() {
        let remote = TempDir::new().unwrap();
        init_repo_with_commit(remote.path());
        add_tag(remote.path(), "v1.0.0");
        add_tag(remote.path(), "v1.0.5");
        add_tag(remote.path(), "v2.0.0");

        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let url = format!("file://{}", remote.path().display());
        write_file(
            project.manifest_path(),
            &manifest_with_dep(&url, "tag = \"v1.0.0\""),
        );

        let report = update(
            &cfg(&project),
            UpdateOpts {
                force: true,
                ..Default::default()
            },
        )
        .unwrap();

        assert!(matches!(
            &report.entries[0].1,
            UpdateOutcome::TagBumped { old, new } if old == "v1.0.0" && new == "v2.0.0"
        ));
        assert!(report.manifest_modified);
        assert!(report.install.is_some());
        let after = std::fs::read_to_string(project.manifest_path()).unwrap();
        assert!(
            after.contains("tag = \"v2.0.0\""),
            "force must bump exact pin to global max v2.0.0:\n{after}"
        );
    }

    #[test]
    fn update_unknown_name_returns_error() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        write_file(
            project.manifest_path(),
            "[package]\nname = \"test\"\nversion = \"0.1.0\"\n",
        );

        let result = update(
            &cfg(&project),
            UpdateOpts {
                name: Some("nonexistent".to_string()),
                ..Default::default()
            },
        );
        assert!(
            matches!(result, Err(PkgError::UnknownDep { ref name, .. }) if name == "nonexistent"),
            "unknown dep name must return UnknownDep: {result:?}"
        );
    }

    // ── clean ─────────────────────────────────────────────────────────────────

    #[test]
    fn clean_all_removes_cache() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let cache_dir = project.pkg_dir().cache();
        let git_dir = cache_dir.join("git/example.com/org/repo");
        std::fs::create_dir_all(&git_dir).unwrap();
        std::fs::write(git_dir.join("sentinel"), "data").unwrap();

        let report = clean(&cfg(&project), true).unwrap();

        assert_eq!(report, CleanReport::CacheRemoved);
        assert!(!cache_dir.exists(), "cache directory must be removed");
    }

    #[test]
    fn clean_all_on_empty_dir_is_noop() {
        let dir = TempDir::new().unwrap();
        // Cache does not exist — must succeed without error.
        let report = clean(&cfg(&project_in(dir.path())), true).unwrap();
        assert_eq!(report, CleanReport::StaleRemoved { removed: 0 });
    }

    #[test]
    fn clean_without_lockfile_is_noop() {
        let dir = TempDir::new().unwrap();
        let report = clean(&cfg(&project_in(dir.path())), false).unwrap();
        assert_eq!(report, CleanReport::NoLockfile);
    }

    #[test]
    fn clean_removes_stale_sha_dirs_only() {
        let dir = TempDir::new().unwrap();
        let project = project_in(dir.path());
        let git_base = project.pkg_dir().cache().join("git/gh.com/org/repo");

        let sha_in_use = "a".repeat(40);
        let sha_stale = "b".repeat(40);

        std::fs::create_dir_all(git_base.join(&sha_in_use)).unwrap();
        std::fs::create_dir_all(git_base.join(&sha_stale)).unwrap();

        // Write a lockfile that references only sha_in_use.
        let lf = Lockfile {
            version: 1,
            pkg: vec![LockedPkg {
                name: "lib".to_string(),
                source: "git+https://gh.com/org/repo".to_string(),
                tag: None,
                rev: None,
                branch: None,
                sha: sha_in_use.clone(),
                entry: PathBuf::from("."),
                patch_dir: None,
                patch_base: None,
            }],
        };
        lf.write(project.lock_path()).unwrap();

        let report = clean(&cfg(&project), false).unwrap();

        assert_eq!(report, CleanReport::StaleRemoved { removed: 1 });
        assert!(
            git_base.join(&sha_in_use).exists(),
            "in-use SHA dir must be retained"
        );
        assert!(
            !git_base.join(&sha_stale).exists(),
            "stale SHA dir must be removed"
        );
    }

    // ── relative_path ─────────────────────────────────────────────────────────

    #[test]
    fn relative_path_sibling_dirs() {
        let tmp = TempDir::new().unwrap();
        let from_dir = tmp.path().join("a/b");
        let to_dir = tmp.path().join("a/c/d");
        std::fs::create_dir_all(&from_dir).unwrap();
        std::fs::create_dir_all(&to_dir).unwrap();

        let rel = relative_path(&from_dir, &to_dir).unwrap();
        // Expect: "../c/d"
        assert_eq!(rel, PathBuf::from("../c/d"));
    }

    #[test]
    fn relative_path_vendored_to_cache() {
        let tmp = TempDir::new().unwrap();
        let vendored = tmp.path().join(".mlua-pkgs/vendored");
        let entry = tmp
            .path()
            .join(".mlua-pkgs/cache/git/gh.com/org/repo/aaaa1234/src");
        std::fs::create_dir_all(&vendored).unwrap();
        std::fs::create_dir_all(&entry).unwrap();

        let rel = relative_path(&vendored, &entry).unwrap();
        assert!(
            rel.starts_with(".."),
            "must navigate up from vendored first"
        );
        assert!(
            rel.to_string_lossy().contains("cache"),
            "must contain 'cache' segment"
        );
    }

    // ── entry_rel_to_pkg ──────────────────────────────────────────────────────

    #[test]
    fn entry_rel_to_pkg_subdir() {
        let cache = PathBuf::from("/tmp/repo");
        let entry = PathBuf::from("/tmp/repo/src");
        assert_eq!(entry_rel_to_pkg(&cache, &entry), PathBuf::from("src"));
    }

    #[test]
    fn entry_rel_to_pkg_root() {
        let cache = PathBuf::from("/tmp/repo");
        let entry = PathBuf::from("/tmp/repo");
        assert_eq!(entry_rel_to_pkg(&cache, &entry), PathBuf::from("."));
    }
}