dodot-lib 1.1.0

//! Source-path inference for `dodot adopt`.
//!
//! `adopt` accepts a deployed path (e.g. `~/.config/nvim/init.lua`,
//! `~/.vimrc`, `~/.weechat/`) and figures out:
//!
//!   1. **Which pack** the source belongs in (e.g. `nvim`, `vim`, `weechat`),
//!      so a freshly-adopted file lands in the right pack subtree without
//!      the user spelling the name out.
//!   2. **Where inside the pack** the file should live so that re-deploying
//!      via `dodot up` lands the symlink back at the original source path.
//!      This is the inverse of `handlers::symlink::resolve_target`'s
//!      priority ladder; getting it wrong breaks the round-trip property.
//!
//! The inference is *not* the resolver's inverse in the strict sense —
//! the resolver maps `(pack, in_pack_path) → deployed_path`, and there
//! are typically multiple pack-relative paths that round-trip to the
//! same deployed path (e.g. `home.vimrc` in any pack and `_home/vimrc`
//! in any pack both deploy to `~/.vimrc`). Inference picks the *most
//! ergonomic* option per source root:
//!
//! - `$XDG_CONFIG_HOME/<X>/<rest>` — pack `<X>`, in-pack `<rest>` (round-trips
//!   via the resolver's default rule, which namespaces under XDG by pack).
//! - `$HOME/.<X>` (file) — in-pack `home.<X>` (round-trips via Priority 1).
//! - `$HOME/.<X>/...` (dir) — in-pack `_home/<X>/...` (round-trips via
//!   Priority 2's `_home/` directory prefix).
//! - `~/Library/Application Support/<X>/<rest>` (macOS, future) — pack
//!   `<X>`, in-pack `_app/<X>/<rest>` (round-trips via Priority 2's
//!   `_app/` prefix per `docs/proposals/macos-paths.lex`).
//!
//! ## Override semantics (`--into <pack>`)
//!
//! When the user supplies `--into <Y>` and `<Y>` differs from the
//! naturally-inferred pack name, the in-pack path must change too — the
//! default rule (`$XDG/<pack>/<rest>`) would otherwise route the file to
//! the wrong place. Inference returns *both* the natural in-pack path
//! and the override-aware variant, so the caller can pick based on
//! whether `--into` was supplied:
//!
//! - XDG source, override differs: use `_xdg/<X>/<rest>` so the
//!   `_xdg/` prefix (Priority 2) bypasses pack-namespacing.
//! - HOME source: the `home.X` and `_home/X/` prefixes are pack-name
//!   independent already, so the override-aware path equals the natural
//!   path. Override changes only the *pack* the file lands in.
//! - AppSupport source, override differs (future): use `_app/<X>/<rest>`.
//!
//! ## Why HOME sources don't infer a pack name
//!
//! `~/.config/<X>/...` carries pack structure in the path: the first
//! segment under XDG *is* the natural pack name. `~/.<X>` does not — a
//! file like `~/.bashrc` could plausibly belong in a `shell`, `bash`, or
//! `dotfiles` pack depending on the user's organization. Rather than
//! guess (and saddle the user with pack names like `bashrc` or
//! `gitconfig`), inference declines and the caller requires `--into`.
//!
//! The only HOME-source ergonomic concession is the `force_home` list:
//! entries there get the bare pack-relative name (no `home.` or `_home/`
//! prefix) because Priority 3 routes them back without one.

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

use crate::paths::Pather;

/// Outcome of inferring how to adopt a single source path.
///
/// The `_natural` and `_override` fields encode the same target two ways:
/// once for the case where the pack name matches the source-root's
/// natural inference (no `_xdg/`/`_app/` prefix needed), and once for the
/// case where the user supplied a different pack via `--into`.
#[derive(Debug, Clone)]
pub(crate) struct InferredTarget {
    /// Pack name derived from the source path itself, if the source
    /// root carries pack structure. `None` when the caller must supply
    /// `--into <pack>` (HOME root) or when the source is at the very
    /// top of XDG with no app subdirectory.
    pub natural_pack: Option<String>,
    /// In-pack path to use when the chosen pack name equals
    /// `natural_pack` (or when override-aware encoding doesn't differ
    /// for this root, e.g. HOME).
    pub in_pack_natural: PathBuf,
    /// In-pack path to use when the chosen pack name *differs* from
    /// the source's naturally-inferred name. For XDG this prepends
    /// `_xdg/<original-pack-segment>/` to keep round-trip; for HOME this
    /// is identical to `in_pack_natural` (already prefix-encoded).
    pub in_pack_override: PathBuf,
    /// Which root the source was matched against. Drives error
    /// messages and the small set of root-specific behaviors (e.g.
    /// directory-source expansion under XDG/AppSupport).
    pub source_root: SourceRoot,
    /// `true` when the source is the *pack-root directory itself* under
    /// XDG/AppSupport (e.g. `~/.config/nvim/`) — the caller should
    /// enumerate its children and adopt each one as its own plan, so
    /// each child becomes a top-level pack entry rather than the dir
    /// becoming one big symlink-to-pack-root.
    pub expand_children: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum SourceRoot {
    /// `$HOME` (e.g. `/Users/alice` or `/home/alice`).
    Home,
    /// `$XDG_CONFIG_HOME` (e.g. `~/.config`, or whatever `XDG_CONFIG_HOME` points at).
    XdgConfig,
    /// `~/Library/Application Support`. Currently never returned —
    /// `Pather` does not yet expose `app_support_dir()` (Phase M1 of
    /// `docs/proposals/macos-paths.lex`). The variant is reserved so the
    /// inference framework is shape-stable when M1 lands.
    #[allow(dead_code)]
    AppSupport,
}

/// Why inference declined to produce a target.
#[derive(Debug)]
pub(crate) enum InferenceError {
    /// Source is not under any recognized adopt-source root.
    UnrecognizedRoot { hint_roots: Vec<PathBuf> },
    /// Source is a direct child of `$HOME` but isn't a dotfile, so
    /// there's no automatic round-trip path. The user can rename to
    /// dotted form or use `[symlink.targets]` for an explicit override.
    NonDottedHome { stripped: String },
    /// Source is a top-level entry directly under `$XDG_CONFIG_HOME`
    /// (no app subdirectory). XDG-root files have no natural pack
    /// structure to mine; require `--into` and use `_xdg/` manually.
    LooseXdgFile,
    /// Source is the XDG root itself (e.g. `~/.config/`). Too broad
    /// to adopt as a single unit.
    XdgRootItself,
    /// Source is the HOME root itself. Refused.
    HomeRootItself,
    /// macOS sandboxed-app container. Containers/<bundle>/Data/Library/...
    /// is system-managed; adoption is refused per
    /// `docs/proposals/macos-paths.lex` §7.3.
    SandboxedContainer,
}

impl std::fmt::Display for InferenceError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            InferenceError::UnrecognizedRoot { hint_roots } => {
                let roots: Vec<String> =
                    hint_roots.iter().map(|p| p.display().to_string()).collect();
                write!(
                    f,
                    "source is outside any recognized adopt root (expected under one of: {}). \
                     Move the file under one of these locations first, or copy it into a \
                     pack manually and use `[symlink.targets]` for an absolute deploy path.",
                    roots.join(", ")
                )
            }
            InferenceError::NonDottedHome { stripped } => write!(
                f,
                "a non-dotted entry in $HOME has no automatic round-trip path \
                 under the post-#48 XDG default. Either rename to a dotted name \
                 (e.g. .{stripped}) before adopting, or copy into the pack \
                 manually and add a [symlink.targets] override pinning the \
                 deploy path."
            ),
            InferenceError::LooseXdgFile => write!(
                f,
                "loose file directly under $XDG_CONFIG_HOME has no pack structure \
                 to infer. Move it into a subdirectory (recommended) or pass \
                 --into <pack> and place the file manually as `_xdg/<name>` in \
                 that pack."
            ),
            InferenceError::XdgRootItself => write!(
                f,
                "$XDG_CONFIG_HOME itself is too broad to adopt — adopt individual \
                 application subdirectories (e.g. `~/.config/nvim/`) instead."
            ),
            InferenceError::HomeRootItself => {
                write!(f, "$HOME itself is too broad to adopt.")
            }
            InferenceError::SandboxedContainer => write!(
                f,
                "this is a sandboxed app's container; its config is not \
                 intended to be edited externally. dodot does not support \
                 adopting from ~/Library/Containers/."
            ),
        }
    }
}

/// Infer pack name and pack-relative path for a single adopt source.
///
/// `abs_source` must be an absolute, lexically-normalized path (no `..`,
/// no `.`). The caller is responsible for canonicalizing where needed —
/// inference works on the *path string* primarily so that `--no-follow`
/// can preserve a symlink source as the link itself rather than resolve
/// through to its target.
///
/// `is_dir` is the post-`--no-follow` directory flag: a symlink-to-dir
/// adopted with `--no-follow` is `is_dir=false` because we'll move the
/// link, not the target.
///
/// `force_home` is the merged `[symlink] force_home` list (root config +
/// pack config) — entries here use the bare pack-relative name, no
/// `home.X` / `_home/X/` prefix, to match the resolver's Priority 3
/// routing.
pub(crate) fn infer_target(
    abs_source: &Path,
    is_dir: bool,
    pather: &dyn Pather,
    force_home: &[String],
) -> Result<InferredTarget, InferenceError> {
    // Canonicalize roots and source for prefix matching. We canonicalize
    // because on macOS `/var` and `/private/var` are equivalent symlinks,
    // and `~` may itself be a symlinked path (e.g. `/home/alice` →
    // `/var/home/alice` on some distros). Mismatching real and symbolic
    // forms would fail the strip_prefix checks below.
    //
    // For the source we canonicalize the *parent* (if any) and re-join
    // the basename. Canonicalizing the source itself would follow a
    // symlink source — breaking `--no-follow` semantics — and fails
    // outright on a dangling symlink. The parent is always a real
    // directory: even for a dangling source link, the link itself lives
    // *somewhere*, and that somewhere has a canonical form.
    let canon_source = canonicalize_parent_keep_basename(abs_source);
    let canon_home = canonicalize_for_match(pather.home_dir());
    let canon_xdg = canonicalize_for_match(pather.xdg_config_home());

    // ── Sandboxed-container refusal ──────────────────────────────────
    //
    // Check this *before* any other root match. On macOS the canonical
    // `~/Library/Containers/` prefix lives under HOME, so without an
    // early exit we'd potentially treat it as a HOME-rooted source. The
    // refusal applies regardless of platform: `dodot adopt` shouldn't
    // touch container data on any OS, and on Linux the path simply
    // won't exist (no false positives).
    let containers_root = canon_home.join("Library").join("Containers");
    if canon_source.starts_with(&containers_root) {
        return Err(InferenceError::SandboxedContainer);
    }

    // ── XDG_CONFIG_HOME root ─────────────────────────────────────────
    //
    // Match XDG *before* HOME because the default XDG config home is
    // `$HOME/.config` — it sits *inside* HOME, so longest-prefix-wins
    // requires checking the more-specific root first. Without this
    // ordering, `~/.config/nvim/init.lua` would match HOME and produce
    // a useless "nested under $HOME" inference.
    if canon_source == canon_xdg {
        return Err(InferenceError::XdgRootItself);
    }
    if let Ok(rel) = canon_source.strip_prefix(&canon_xdg) {
        return resolve_xdg_relative(rel, is_dir);
    }

    // ── HOME root ────────────────────────────────────────────────────
    if canon_source == canon_home {
        return Err(InferenceError::HomeRootItself);
    }
    if let Ok(rel) = canon_source.strip_prefix(&canon_home) {
        return resolve_home_relative(rel, is_dir, force_home);
    }

    // ── No root matched ──────────────────────────────────────────────
    Err(InferenceError::UnrecognizedRoot {
        hint_roots: vec![canon_xdg, canon_home],
    })
}

/// Build inference output for a path relative to `$XDG_CONFIG_HOME`.
///
/// `rel` is the source path minus the canonical XDG root, so its first
/// component is what we treat as the natural pack name. Examples:
///
/// - `nvim/init.lua` → pack `nvim`, in-pack `init.lua`
/// - `nvim/lua/plugins/foo.lua` → pack `nvim`, in-pack `lua/plugins/foo.lua`
/// - `nvim` (a directory, sole component) → pack `nvim`, expand children
/// - `loose-file.toml` (a file, sole component) → refused (LooseXdgFile)
fn resolve_xdg_relative(rel: &Path, is_dir: bool) -> Result<InferredTarget, InferenceError> {
    let mut comps = rel.components();
    let first = match comps.next() {
        Some(Component::Normal(s)) => s.to_string_lossy().into_owned(),
        // No first component: rel is empty (handled by the `==` check
        // upstream) or starts with something we can't treat as a name.
        // Not reachable in practice given the upstream root match, but
        // we surface a refusal rather than panic if somehow it does.
        _ => return Err(InferenceError::XdgRootItself),
    };
    let rest_path: PathBuf = comps.as_path().to_path_buf();

    if rest_path.as_os_str().is_empty() {
        // Sole component case: the source IS one of XDG's top-level
        // children. A directory is a pack root we can expand; a file is
        // loose with no pack structure.
        if is_dir {
            return Ok(InferredTarget {
                natural_pack: Some(first.clone()),
                // Empty in-pack path: not used directly because
                // `expand_children = true` triggers per-child planning,
                // each of which derives its own in-pack path.
                in_pack_natural: PathBuf::new(),
                in_pack_override: PathBuf::from("_xdg").join(&first),
                source_root: SourceRoot::XdgConfig,
                expand_children: true,
            });
        } else {
            return Err(InferenceError::LooseXdgFile);
        }
    }

    // Nested case: `<pack>/<rest>`. The natural in-pack path is `<rest>`
    // (the resolver's default rule namespaces it back under the pack).
    // The override-aware path uses `_xdg/<pack>/<rest>` so the explicit
    // `_xdg/` prefix bypasses pack-namespacing — required when the
    // user picks a different pack via `--into`.
    Ok(InferredTarget {
        natural_pack: Some(first.clone()),
        in_pack_natural: rest_path.clone(),
        in_pack_override: PathBuf::from("_xdg").join(&first).join(&rest_path),
        source_root: SourceRoot::XdgConfig,
        expand_children: false,
    })
}

/// Build inference output for a path relative to `$HOME`.
///
/// HOME-rooted sources don't carry pack structure, so this returns
/// `natural_pack = None` and the caller must require `--into <pack>`.
/// What inference *does* compute is the in-pack path: the existing
/// dotfile conventions (`home.X` for files, `_home/X/` for dirs)
/// preserve round-trip regardless of the chosen pack name.
fn resolve_home_relative(
    rel: &Path,
    is_dir: bool,
    force_home: &[String],
) -> Result<InferredTarget, InferenceError> {
    let mut comps = rel.components();
    let first = match comps.next() {
        Some(Component::Normal(s)) => s.to_string_lossy().into_owned(),
        _ => return Err(InferenceError::HomeRootItself),
    };

    if comps.next().is_some() {
        // The source is nested deeper under HOME than a direct child
        // (e.g. `~/Documents/notes.txt`). We don't have rules for these
        // — `~/Documents/`, `~/Desktop/`, etc. are user data, not
        // dotfiles. Refuse with "outside recognized roots" and seed
        // `hint_roots` with the *symbolic* root names so the rendered
        // error stays readable. Empty hint_roots produces awkward
        // "expected under one of: " text.
        return Err(InferenceError::UnrecognizedRoot {
            hint_roots: vec![PathBuf::from("$HOME"), PathBuf::from("$XDG_CONFIG_HOME")],
        });
    }

    // Delegate to the string-shaped helper so both inference and the
    // round-trip property test go through the same convention table.
    // `derive_home_in_pack` returns `force_home`-bare-name, `home.X`,
    // `_home/X`, or a "non-dotted refused" error — exactly the shape we
    // need here.
    let stripped = first.strip_prefix('.').unwrap_or(&first);
    let in_pack_str = derive_home_in_pack(&first, is_dir, force_home).map_err(|_| {
        InferenceError::NonDottedHome {
            stripped: stripped.to_string(),
        }
    })?;
    let in_pack = PathBuf::from(in_pack_str);

    Ok(InferredTarget {
        natural_pack: None,
        // HOME's `home.X` / `_home/X/` prefixes are pack-name-independent
        // — Priority 1 and 2 don't consult the pack name when routing —
        // so the override-aware in-pack path equals the natural one.
        in_pack_natural: in_pack.clone(),
        in_pack_override: in_pack,
        source_root: SourceRoot::Home,
        expand_children: false,
    })
}

/// Canonicalize a path for prefix matching, falling back to the input on
/// failure. Canonicalization may fail on a non-existent path; that's
/// fine — we want the lexical form in that case anyway.
fn canonicalize_for_match(p: &Path) -> PathBuf {
    std::fs::canonicalize(p).unwrap_or_else(|_| p.to_path_buf())
}

/// Canonicalize a source path's parent and re-join the basename, leaving
/// the source itself unfollowed.
///
/// This is the right shape for adopt's source paths: we need OS-level
/// path equivalence (e.g. macOS `/var` ↔ `/private/var`) on the
/// directory-prefix portion so root-membership checks work, but we must
/// *not* follow a symlink source — adopt's `--no-follow` mode treats
/// the link as the thing to move, not the link's target. Canonicalizing
/// only the parent gives us both: the prefix is real, and the basename
/// stays as the user wrote it.
///
/// If the parent can't be canonicalized (rare — it would mean the
/// source is at the filesystem root or the parent doesn't exist), we
/// fall back to the lexical input. The downstream prefix checks may
/// then fail to match a root, which surfaces as `UnrecognizedRoot` —
/// the same outcome the user would see for any path that genuinely
/// isn't under a recognized root.
fn canonicalize_parent_keep_basename(source: &Path) -> PathBuf {
    let parent = match source.parent() {
        Some(p) if !p.as_os_str().is_empty() => p,
        // Filesystem root or empty path: nothing to canonicalize.
        _ => return source.to_path_buf(),
    };
    let canon_parent = match std::fs::canonicalize(parent) {
        Ok(p) => p,
        Err(_) => return source.to_path_buf(),
    };
    match source.file_name() {
        Some(name) => canon_parent.join(name),
        None => canon_parent,
    }
}

/// Compute the in-pack path for a `$HOME/<file_name>` source.
///
/// Kept as a public-in-crate helper so the round-trip property test in
/// `commands::tests::pack_filename_round_trips_through_resolve_target`
/// can drive the same conventions inference uses (without paying the
/// cost of materializing a `Pather` or absolute paths).
///
/// Returns `Err(reason)` when the source has no automatic round-trip
/// path — currently the non-dotted-non-force_home case. The inference
/// entry point translates the same situation into a richer
/// `InferenceError::NonDottedHome`; this thinner string-error variant
/// matches the original `derive_pack_filename` shape.
pub(crate) fn derive_home_in_pack(
    file_name: &str,
    is_dir: bool,
    force_home: &[String],
) -> std::result::Result<String, String> {
    let stripped = file_name.strip_prefix('.').unwrap_or(file_name);
    let in_force_home = force_home
        .iter()
        .any(|entry| entry.strip_prefix('.').unwrap_or(entry) == stripped);

    if in_force_home {
        Ok(stripped.to_string())
    } else if file_name.starts_with('.') {
        if is_dir {
            Ok(format!("_home/{stripped}"))
        } else {
            Ok(format!("home.{stripped}"))
        }
    } else {
        Err(format!(
            "a non-dotted entry in $HOME has no automatic round-trip path \
             under the post-#48 XDG default. Either rename to a dotted name \
             (e.g. .{stripped}) before adopting, or copy into the pack \
             manually and add a [symlink.targets] override pinning the \
             deploy path."
        ))
    }
}

#[cfg(test)]
mod tests {
    //! Inference tests use a hand-built `XdgPather` rather than touching
    //! real env vars. The point is to exercise every branch of the
    //! decision tree on synthetic paths; integration tests in
    //! `commands::tests` cover end-to-end adopt against a real temp FS.
    //!
    //! Each test is named `<root>_<scenario>_<outcome>` so failures are
    //! self-locating in `cargo test` output.
    use super::*;
    use crate::paths::XdgPather;

    /// Build a `Pather` with HOME and XDG explicitly set to non-overlapping
    /// paths under `/tmp/<id>` so prefix matching is unambiguous. We avoid
    /// the default `$HOME/.config` layout in most tests: it's the *harder*
    /// case (XDG nested under HOME), and we cover it explicitly in
    /// `xdg_inside_home_prefers_xdg_root`.
    fn pather(home: &str, xdg: &str) -> XdgPather {
        XdgPather::builder()
            .home(home)
            .dotfiles_root(format!("{home}/dotfiles"))
            .data_dir(format!("{home}/.local/share/dodot"))
            .config_dir(format!("{home}/.config/dodot"))
            .cache_dir(format!("{home}/.cache/dodot"))
            .xdg_config_home(xdg)
            .build()
            .unwrap()
    }

    #[test]
    fn xdg_nested_file_infers_pack_and_relative_path() {
        let p = pather("/u", "/x");
        let t = infer_target(
            Path::new("/x/nvim/init.lua"),
            /*is_dir=*/ false,
            &p,
            &[],
        )
        .unwrap();
        assert_eq!(t.natural_pack.as_deref(), Some("nvim"));
        assert_eq!(t.in_pack_natural, PathBuf::from("init.lua"));
        // Override-aware: `_xdg/<pack>/<rest>` so an arbitrary `--into`
        // still round-trips via the resolver's Priority 2 `_xdg/` prefix.
        assert_eq!(t.in_pack_override, PathBuf::from("_xdg/nvim/init.lua"));
        assert_eq!(t.source_root, SourceRoot::XdgConfig);
        assert!(!t.expand_children);
    }

    #[test]
    fn xdg_deeply_nested_file_keeps_full_subpath() {
        // The first segment under XDG is always the pack; everything
        // below stays in `in_pack` verbatim. This is the case that
        // makes `dodot adopt ~/.config/nvim/lua/plugins/foo.lua` work.
        let p = pather("/u", "/x");
        let t = infer_target(Path::new("/x/nvim/lua/plugins/foo.lua"), false, &p, &[]).unwrap();
        assert_eq!(t.natural_pack.as_deref(), Some("nvim"));
        assert_eq!(t.in_pack_natural, PathBuf::from("lua/plugins/foo.lua"));
        assert_eq!(
            t.in_pack_override,
            PathBuf::from("_xdg/nvim/lua/plugins/foo.lua")
        );
    }

    #[test]
    fn xdg_pack_root_directory_triggers_expansion() {
        // `~/.config/nvim/` (the directory itself) → pack `nvim`,
        // expand_children=true. The caller enumerates entries inside
        // and adopts each as a top-level pack member, instead of
        // making `~/.config/nvim/` itself a single big symlink.
        let p = pather("/u", "/x");
        let t = infer_target(Path::new("/x/nvim"), /*is_dir=*/ true, &p, &[]).unwrap();
        assert_eq!(t.natural_pack.as_deref(), Some("nvim"));
        assert!(t.expand_children);
        assert_eq!(t.in_pack_natural, PathBuf::new());
    }

    #[test]
    fn xdg_loose_file_at_root_is_refused() {
        // `~/.config/standalone.toml` (a file, not a dir) at the very
        // top of XDG has no pack structure to mine. We refuse rather
        // than guess, and steer the user toward `--into` + manual
        // `_xdg/` placement.
        let p = pather("/u", "/x");
        let err = infer_target(
            Path::new("/x/standalone.toml"),
            /*is_dir=*/ false,
            &p,
            &[],
        )
        .unwrap_err();
        assert!(matches!(err, InferenceError::LooseXdgFile));
    }

    #[test]
    fn xdg_root_itself_is_refused() {
        let p = pather("/u", "/x");
        let err = infer_target(Path::new("/x"), true, &p, &[]).unwrap_err();
        assert!(matches!(err, InferenceError::XdgRootItself));
    }

    #[test]
    fn home_dotted_file_uses_home_prefix_no_pack_inference() {
        // `~/.vimrc` → pack name *not* inferred (HOME has no pack
        // structure), in-pack `home.vimrc` so the resolver routes back
        // to `~/.vimrc` via Priority 1.
        let p = pather("/u", "/x");
        let t = infer_target(Path::new("/u/.vimrc"), false, &p, &[]).unwrap();
        assert_eq!(t.natural_pack, None);
        assert_eq!(t.in_pack_natural, PathBuf::from("home.vimrc"));
        // HOME prefixes are pack-name-independent — override path matches.
        assert_eq!(t.in_pack_override, PathBuf::from("home.vimrc"));
        assert_eq!(t.source_root, SourceRoot::Home);
    }

    #[test]
    fn home_dotted_dir_uses_home_subtree_prefix() {
        let p = pather("/u", "/x");
        let t = infer_target(Path::new("/u/.weechat"), /*is_dir=*/ true, &p, &[]).unwrap();
        assert_eq!(t.natural_pack, None);
        assert_eq!(t.in_pack_natural, PathBuf::from("_home/weechat"));
    }

    #[test]
    fn home_force_home_uses_bare_name() {
        // `force_home` curates Unix canons (`.bashrc`, `.ssh`, …) whose
        // Priority 3 resolver rule routes the bare pack-relative name
        // straight back to `~/.X`. So adopt drops the `home.`/`_home/`
        // prefix for matches — keeps the pack tree clean and matches
        // the resolver convention.
        let force = vec!["bashrc".to_string(), "ssh".to_string()];
        let p = pather("/u", "/x");

        let t = infer_target(Path::new("/u/.bashrc"), false, &p, &force).unwrap();
        assert_eq!(t.in_pack_natural, PathBuf::from("bashrc"));

        let t = infer_target(Path::new("/u/.ssh"), true, &p, &force).unwrap();
        assert_eq!(t.in_pack_natural, PathBuf::from("ssh"));
    }

    #[test]
    fn home_non_dotted_is_refused() {
        // No automatic round-trip: a file like `~/myscript.sh` would
        // need `[symlink.targets]` for an explicit deploy path.
        let p = pather("/u", "/x");
        let err = infer_target(Path::new("/u/myscript.sh"), false, &p, &[]).unwrap_err();
        match err {
            InferenceError::NonDottedHome { stripped } => assert_eq!(stripped, "myscript.sh"),
            other => panic!("expected NonDottedHome, got {other:?}"),
        }
    }

    #[test]
    fn home_nested_outside_xdg_is_unrecognized() {
        // `~/Documents/notes.txt` isn't HOME-direct and isn't under
        // XDG either; we refuse rather than guess at user-data layout.
        let p = pather("/u", "/x");
        let err = infer_target(Path::new("/u/Documents/notes.txt"), false, &p, &[]).unwrap_err();
        assert!(matches!(err, InferenceError::UnrecognizedRoot { .. }));
    }

    #[test]
    fn home_root_itself_is_refused() {
        let p = pather("/u", "/x");
        let err = infer_target(Path::new("/u"), true, &p, &[]).unwrap_err();
        assert!(matches!(err, InferenceError::HomeRootItself));
    }

    #[test]
    fn xdg_inside_home_prefers_xdg_root() {
        // The default config has `XDG_CONFIG_HOME = $HOME/.config`, so
        // an XDG-rooted source's path also starts with HOME. Inference
        // must pick the *more specific* root (XDG) — checking HOME
        // first would produce a useless "nested under $HOME" verdict.
        // This test pins that ordering as a regression guard.
        let p = pather("/u", "/u/.config");
        let t = infer_target(Path::new("/u/.config/nvim/init.lua"), false, &p, &[]).unwrap();
        assert_eq!(t.source_root, SourceRoot::XdgConfig);
        assert_eq!(t.natural_pack.as_deref(), Some("nvim"));
        assert_eq!(t.in_pack_natural, PathBuf::from("init.lua"));
    }

    #[test]
    fn unrecognized_root_lists_known_roots() {
        // Random absolute path under neither HOME nor XDG — refused
        // with the recognized roots in the error so the user knows
        // where adopt looks.
        let p = pather("/u", "/x");
        let err = infer_target(Path::new("/etc/passwd"), false, &p, &[]).unwrap_err();
        match err {
            InferenceError::UnrecognizedRoot { hint_roots } => {
                assert!(hint_roots.iter().any(|r| r.starts_with("/x")));
                assert!(hint_roots.iter().any(|r| r.starts_with("/u")));
            }
            other => panic!("expected UnrecognizedRoot, got {other:?}"),
        }
    }

    #[test]
    fn macos_containers_path_is_refused() {
        // `~/Library/Containers/<bundle>/...` is a sandboxed-app data
        // directory — partially OS-managed and not intended for
        // external editing. Refused on every platform so no one
        // accidentally adopts a container's plist on a CI Linux box
        // by feeding it a path that mimics the macOS layout.
        let p = pather("/u", "/x");
        let err = infer_target(
            Path::new("/u/Library/Containers/com.example.app/Data/Library/Preferences/foo.plist"),
            false,
            &p,
            &[],
        )
        .unwrap_err();
        assert!(matches!(err, InferenceError::SandboxedContainer));
    }
}