lattice_core/

home.rs

//! `~` expansion, in one place.
//!
//! ## Why this exists rather than a local helper per consumer
//!
//! There were four, and they disagreed in the way that matters. The agenda's,
//! the completion generator's, the dispatcher's and the org guest's were each a
//! private `expand_tilde`, and the first three resolved the home directory as
//! `std::env::var_os("HOME")` — which is POSIX-only. On Windows that returns
//! `None`, so `~/notes` was left verbatim and every lookup silently found
//! nothing. `org.agenda-files`' own documentation says "`~` is expanded", and
//! on Windows it did not.
//!
//! Silent is the operative word. A path that fails to expand does not error; it
//! becomes a path that does not exist, and every consumer here reports "no
//! files" rather than "that is not a real directory". The user is then told
//! their corpus is empty.
//!
//! [`dirs::home_dir`] answers on Windows too (`%USERPROFILE%`, then the
//! known-folder API), which is the whole reason to converge rather than to fix
//! four copies of the `HOME` lookup.
//!
//! ## What it deliberately is not
//!
//! Not shell expansion. No `$VAR`, no `~other-user`, no globbing. The one thing
//! a user types by hand that a `PathBuf` will not resolve is a leading tilde,
//! and every step past that is a parser with its own quoting rules — which a
//! config value is not asking for. A `$HOME/notes` that stayed verbatim would
//! be visible and fixable; guessing at it would not.

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

/// Expand a leading `~` against the user's home directory.
///
/// `~` alone and `~/rest` both expand; `~user` does not (there is no lookup for
/// another user's home that works across platforms). Anything else is returned
/// unchanged, so this is safe to call on a path that is already absolute.
///
/// Unresolvable home → the input, verbatim. That keeps the failure visible as a
/// path with a `~` still in it rather than as a silently-wrong location.
pub fn expand_tilde(raw: &str) -> String {
    let Some(rest) = raw.strip_prefix('~') else {
        return raw.to_string();
    };
    // `~user` is not ours to resolve, and mangling it into `<home>user` would
    // be worse than leaving it: the result is a plausible path to the wrong
    // place, which is exactly the failure this module exists to end.
    if !rest.is_empty() && !rest.starts_with('/') && !rest.starts_with('\\') {
        return raw.to_string();
    }
    let Some(home) = dirs::home_dir() else {
        return raw.to_string();
    };
    let rest = rest.trim_start_matches(['/', '\\']);
    if rest.is_empty() {
        return home.display().to_string();
    }
    home.join(rest).display().to_string()
}

/// [`expand_tilde`] for a `Path`, returning a `PathBuf`.
pub fn expand_tilde_path(raw: &Path) -> PathBuf {
    match raw.to_str() {
        // Non-UTF-8 cannot contain a leading ASCII `~` we could act on without
        // re-encoding, and a path is never worth mangling to expand one.
        None => raw.to_path_buf(),
        Some(s) => PathBuf::from(expand_tilde(s)),
    }
}

/// [`expand_tilde`]'s inverse: put the `~` back for DISPLAY.
///
/// `/Users/dhruva/src/lattice` → `~/src/lattice`. For showing a path in a
/// prompt, a status line or any other one-line surface where the home prefix is
/// the least informative part of it and the part that squeezes out the rest.
///
/// **Display only.** The result is not a path to hand to anything that opens
/// files — that is what the expanding direction is for, and round-tripping
/// through here would be a way to lose a path whose home resolution changed
/// underneath it.
///
/// Home itself contracts to `~`, not `~/`. Anything outside home, a
/// non-UTF-8 path, or an unresolvable home is returned verbatim, so the
/// failure is a path that reads slightly long rather than one that reads wrong.
pub fn contract_tilde(raw: &Path) -> String {
    // Windows only: `canonicalize` returns the verbatim form,
    // `\\?\C:\Users\me\src`, and `home_dir` the ordinary one, so the two never
    // share a prefix and a canonical path under home was shown in full —
    // `\\?\` and all. Drop the marker first; this is display, and nobody reads
    // it.
    let shown;
    let raw = match raw.to_str().and_then(without_verbatim_prefix) {
        Some(plain) if cfg!(windows) => {
            shown = PathBuf::from(plain);
            shown.as_path()
        }
        _ => raw,
    };
    let Some(home) = dirs::home_dir() else {
        return raw.display().to_string();
    };
    match raw.strip_prefix(&home) {
        Ok(rest) if rest.as_os_str().is_empty() => "~".to_string(),
        // `Path::join` rather than string concatenation so the separator is the
        // platform's. `strip_prefix` is component-wise, so `/Users/dhruvax`
        // cannot match a home of `/Users/dhruva` the way a `starts_with` on the
        // string would.
        Ok(rest) => Path::new("~").join(rest).display().to_string(),
        Err(_) => raw.display().to_string(),
    }
}

/// `\\?\C:\x` → `C:\x`. `None` when there is no verbatim marker, and for the
/// UNC form (`\\?\UNC\server\share`), whose plain spelling is `\\server\share`
/// rather than what follows the marker.
///
/// Pure and unconditional so it is tested on every platform; only
/// [`contract_tilde`] decides it applies, and only on Windows.
fn without_verbatim_prefix(path: &str) -> Option<&str> {
    let rest = path.strip_prefix(r"\\?\")?;
    (!rest.starts_with(r"UNC\")).then_some(rest)
}

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

    #[test]
    fn the_verbatim_marker_is_dropped_but_a_unc_path_is_left_alone() {
        assert_eq!(
            without_verbatim_prefix(r"\\?\C:\Users\me\src"),
            Some(r"C:\Users\me\src")
        );
        assert_eq!(without_verbatim_prefix(r"C:\Users\me"), None);
        assert_eq!(without_verbatim_prefix("/home/me"), None);
        assert_eq!(without_verbatim_prefix(r"\\?\UNC\server\share"), None);
    }

    #[test]
    fn a_path_without_a_tilde_is_untouched() {
        assert_eq!(expand_tilde("/abs/path"), "/abs/path");
        assert_eq!(expand_tilde("relative/path"), "relative/path");
        assert_eq!(expand_tilde(""), "");
        assert_eq!(expand_tilde("a~b"), "a~b", "a tilde must LEAD to count");
    }

    #[test]
    fn a_leading_tilde_becomes_the_home_directory() {
        let Some(home) = dirs::home_dir() else {
            eprintln!("SKIP: no home directory on this machine");
            return;
        };
        assert_eq!(expand_tilde("~"), home.display().to_string());
        assert_eq!(
            expand_tilde("~/notes"),
            home.join("notes").display().to_string()
        );
    }

    /// `~user` is left alone. Expanding it against OUR home would produce a
    /// plausible path to the wrong place, which is worse than not expanding.
    #[test]
    fn another_users_home_is_left_verbatim() {
        assert_eq!(expand_tilde("~alice/notes"), "~alice/notes");
        assert_eq!(expand_tilde("~alice"), "~alice");
    }

    /// No `$VAR`, deliberately — a config value is not a shell command line,
    /// and a half-implemented expansion is worse than none.
    #[test]
    fn shell_variables_are_not_expanded() {
        assert_eq!(expand_tilde("$HOME/notes"), "$HOME/notes");
        assert_eq!(expand_tilde("~/$FOO"), {
            let home = dirs::home_dir().map(|h| h.join("$FOO").display().to_string());
            home.unwrap_or_else(|| "~/$FOO".to_string())
        });
    }

    /// The display direction, and the round trip that says the two agree.
    #[test]
    fn a_path_under_home_contracts_back_to_a_tilde() {
        let Some(home) = dirs::home_dir() else {
            eprintln!("SKIP: no home directory on this machine");
            return;
        };
        assert_eq!(contract_tilde(&home.join("src").join("lattice")), {
            let sep = std::path::MAIN_SEPARATOR;
            format!("~{sep}src{sep}lattice")
        });
        assert_eq!(contract_tilde(&home), "~", "home itself is `~`, not `~/`");
        assert_eq!(
            expand_tilde(&contract_tilde(&home.join("src"))),
            home.join("src").display().to_string(),
            "the two directions round-trip"
        );
    }

    /// Outside home is left alone — contracting it would have to invent a
    /// prefix, and a shortened path to the wrong place is the failure the
    /// expanding direction already refuses to produce.
    #[test]
    fn a_path_outside_home_is_left_verbatim() {
        assert_eq!(contract_tilde(Path::new("/etc/hosts")), "/etc/hosts");
    }

    /// Component-wise, not a string prefix. A sibling whose name merely starts
    /// with the home directory's must not contract — the result would name a
    /// directory that does not exist.
    #[test]
    fn a_sibling_sharing_homes_prefix_does_not_contract() {
        let Some(home) = dirs::home_dir() else {
            return;
        };
        let Some(name) = home.file_name().and_then(|n| n.to_str()) else {
            return;
        };
        let Some(parent) = home.parent() else {
            return;
        };
        let sibling = parent.join(format!("{name}x"));
        assert_eq!(contract_tilde(&sibling), sibling.display().to_string());
    }

    #[test]
    fn the_path_form_agrees_with_the_string_form() {
        let Some(home) = dirs::home_dir() else {
            return;
        };
        assert_eq!(expand_tilde_path(Path::new("~/x")), home.join("x"));
        assert_eq!(expand_tilde_path(Path::new("/x")), PathBuf::from("/x"));
    }
}