rakata_core/

fs.rs

//! Filesystem helpers shared across KotOR crates.
//!
//! This module provides deterministic case-insensitive file-name lookup
//! utilities for cross-platform behavior.

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

use crate::ascii::cmp_ascii_case_insensitive;

/// Suffix marking a file something in this workspace is part-way through
/// writing.
///
/// A write goes to `<name>.rakata-new` beside its target, is flushed, and is
/// then renamed over it, so a failure leaves the target untouched. One spelling
/// across the workspace is what lets a leftover be recognised as inert by
/// whatever finds it next rather than reported as an unknown file.
pub const TEMP_SUFFIX: &str = ".rakata-new";

/// Whether two files hold the same bytes.
///
/// Streamed in blocks rather than read whole, since a caller comparing game
/// content is comparing textures and movies that run to hundreds of megabytes.
///
/// Sizes are not consulted. A caller that can cheaply rule a pair out on length
/// should do so before calling this; what this answers is the exact question.
///
/// # Errors
///
/// Whatever stopped either file being opened or read.
pub fn files_have_same_bytes(one: &Path, other: &Path) -> io::Result<bool> {
    let open = |path: &Path| std::fs::File::open(path).map(io::BufReader::new);
    // Filled to the end of the buffer rather than taking one `read`, which may
    // stop short without being at the end and would leave the two readers at
    // different offsets, comparing the wrong bytes against each other.
    fn fill(reader: &mut impl io::Read, buffer: &mut [u8]) -> io::Result<usize> {
        let mut filled = 0;
        while filled < buffer.len() {
            match reader.read(&mut buffer[filled..])? {
                0 => break,
                took => filled += took,
            }
        }
        Ok(filled)
    }

    let mut ours = open(one)?;
    let mut theirs = open(other)?;
    // 64 KiB, which is arbitrary: large enough that the syscall is not the
    // cost, small enough to hold two of.
    let mut here = vec![0_u8; 64 * 1024];
    let mut there = vec![0_u8; 64 * 1024];
    loop {
        let took = fill(&mut ours, &mut here)?;
        let got = fill(&mut theirs, &mut there)?;
        if took != got || here[..took] != there[..got] {
            return Ok(false);
        }
        if took == 0 {
            return Ok(true);
        }
    }
}

/// Every file beneath `directory`, at any depth, sorted by path.
///
/// Directories are descended into and are not themselves returned, so what
/// comes back is the leaves. Symlinks are followed only where the platform's
/// metadata already resolved them, and a cycle is not guarded against: callers
/// point this at a mod payload or an install subtree rather than at an
/// arbitrary root.
///
/// The counterpart to the single-level listings above, for a caller that has to
/// see a whole tree rather than answer a name in one directory. A mod payload
/// is the case: most ship subdirectories, and what the engine loads is the
/// flattened set.
///
/// # Errors
///
/// Propagates the [`io::Error`] from reading any directory in the tree, naming
/// nothing further: a caller wanting to know which one wraps this per subtree.
pub fn files_beneath(directory: &Path) -> io::Result<Vec<PathBuf>> {
    let mut found = Vec::new();
    let mut pending = vec![directory.to_path_buf()];
    while let Some(next) = pending.pop() {
        for entry in std::fs::read_dir(&next)? {
            let path = entry?.path();
            if path.is_dir() {
                pending.push(path);
            } else {
                found.push(path);
            }
        }
    }
    found.sort();
    Ok(found)
}

/// Every file in `directory` whose name matches `expected_file_name`
/// ASCII case-insensitively.
///
/// Sorted on lowercase name then original bytes, so the order is the same
/// twice.
///
/// A caller that has to produce an answer wants
/// [`find_case_insensitive_file`], which takes the first. A caller for which
/// several matches is itself the finding wants this: on a case-sensitive
/// filesystem two entries differing only by case are two real files, and which
/// one the engine reads depends on the order a directory walk hands them back.
///
/// # Errors
///
/// Propagates the [`io::Error`] from reading `directory` or one of its entries.
pub fn find_case_insensitive_files(
    directory: &Path,
    expected_file_name: &str,
) -> io::Result<Vec<PathBuf>> {
    matching(directory, expected_file_name, Kind::File)
}

/// Every subdirectory of `directory` matching `expected_name` ASCII
/// case-insensitively.
///
/// The directory half of [`find_case_insensitive_files`], with the same reason
/// to prefer it over [`find_case_insensitive_directory`].
///
/// # Errors
///
/// Propagates the [`io::Error`] from reading `directory` or one of its entries.
pub fn find_case_insensitive_directories(
    directory: &Path,
    expected_name: &str,
) -> io::Result<Vec<PathBuf>> {
    matching(directory, expected_name, Kind::Directory)
}

/// Which of the two a walk is looking for.
#[derive(Clone, Copy)]
enum Kind {
    File,
    Directory,
}

impl Kind {
    /// Whether a path is the kind being looked for.
    fn matches(self, path: &Path) -> bool {
        match self {
            Self::File => path.is_file(),
            Self::Directory => path.is_dir(),
        }
    }
}

/// Every entry of one kind whose name matches, in a stable order.
fn matching(directory: &Path, expected: &str, kind: Kind) -> io::Result<Vec<PathBuf>> {
    let mut matches = Vec::new();
    for entry in std::fs::read_dir(directory)? {
        let entry = entry?;
        let name = entry.file_name();
        if !name
            .to_str()
            .is_some_and(|name| name.eq_ignore_ascii_case(expected))
        {
            continue;
        }
        // The kind check stats the entry, so it waits for a name match.
        let path = entry.path();
        if kind.matches(&path) {
            matches.push(path);
        }
    }
    matches.sort_by(|a, b| {
        let name_of = |path: &Path| {
            path.file_name()
                .and_then(|name| name.to_str())
                .unwrap_or_default()
                .to_owned()
        };
        let (a, b) = (name_of(a), name_of(b));
        cmp_ascii_case_insensitive(&a, &b).then(a.cmp(&b))
    });
    Ok(matches)
}

/// Finds one file in `directory` with ASCII case-insensitive name matching.
///
/// Where several entries differ only by case this takes a deterministic winner:
/// the first of [`find_case_insensitive_files`]. A caller that should report
/// rather than resolve wants that one instead.
///
/// # Errors
///
/// Propagates the [`io::Error`] from reading `directory` or one of its
/// entries. A directory that exists and holds no match is `Ok(None)`.
pub fn find_case_insensitive_file(
    directory: &Path,
    expected_file_name: &str,
) -> io::Result<Option<PathBuf>> {
    Ok(find_case_insensitive_files(directory, expected_file_name)?
        .into_iter()
        .next())
}

/// Finds one subdirectory in `directory` with ASCII case-insensitive name
/// matching.
///
/// The same deterministic tie-break as [`find_case_insensitive_file`], and the
/// same caveat: [`find_case_insensitive_directories`] is what to reach for when
/// several matches is the answer rather than a tie to break.
///
/// Used for resolving canonical install paths like `Override/`, `modules/` and
/// `lips/` that mods or platform copies frequently case-fold differently.
///
/// # Errors
///
/// Propagates the [`io::Error`] from reading `directory` or one of its
/// entries. A directory that exists and holds no match is `Ok(None)`.
pub fn find_case_insensitive_directory(
    directory: &Path,
    expected_name: &str,
) -> io::Result<Option<PathBuf>> {
    Ok(find_case_insensitive_directories(directory, expected_name)?
        .into_iter()
        .next())
}

#[cfg(test)]
mod tests {
    use super::{
        files_beneath, files_have_same_bytes, find_case_insensitive_directories,
        find_case_insensitive_directory, find_case_insensitive_file,
    };

    use std::fs;

    use tempfile::TempDir;

    #[test]
    fn resolves_case_insensitive_match() {
        let temp = TempDir::new().expect("create tempdir");
        let root = temp.path();
        let path = root.join("ChItIn.KeY");
        fs::write(&path, b"key").expect("write fixture");

        let found = find_case_insensitive_file(root, "chitin.key")
            .expect("lookup should succeed")
            .expect("file should be found");
        assert_eq!(found, path);
    }

    #[test]
    fn returns_none_when_no_match() {
        let temp = TempDir::new().expect("create tempdir");

        let found =
            find_case_insensitive_file(temp.path(), "missing.txt").expect("lookup should run");
        assert!(found.is_none());
    }

    #[test]
    fn resolves_case_insensitive_directory_match() {
        let temp = TempDir::new().expect("create tempdir");
        let root = temp.path();
        let path = root.join("OvErRiDe");
        fs::create_dir(&path).expect("create fixture dir");

        let found = find_case_insensitive_directory(root, "override")
            .expect("lookup should succeed")
            .expect("dir should be found");
        assert_eq!(found, path);
    }

    #[test]
    fn directory_lookup_ignores_files_with_matching_name() {
        // A file named "override" must not satisfy a directory lookup.
        let temp = TempDir::new().expect("create tempdir");
        let root = temp.path();
        fs::write(root.join("override"), b"not a directory").expect("write fixture");

        let found = find_case_insensitive_directory(root, "override").expect("lookup should run");
        assert!(found.is_none());
    }

    #[test]
    fn directory_lookup_returns_none_when_no_match() {
        let temp = TempDir::new().expect("create tempdir");

        let found =
            find_case_insensitive_directory(temp.path(), "missing").expect("lookup should run");
        assert!(found.is_none());
    }

    /// The tree walk reaches every depth and returns leaves only.
    #[test]
    fn files_beneath_reaches_every_depth() {
        let temp = TempDir::new().expect("tempdir");
        let deep = temp.path().join("Override").join("nested");
        fs::create_dir_all(&deep).expect("create");
        fs::write(temp.path().join("readme.txt"), b"a").expect("write");
        fs::write(temp.path().join("Override").join("heads.2da"), b"b").expect("write");
        fs::write(deep.join("appearance.2da"), b"c").expect("write");

        let found = files_beneath(temp.path()).expect("the tree reads");
        let names: Vec<&str> = found
            .iter()
            .filter_map(|path| path.file_name()?.to_str())
            .collect();

        assert_eq!(names, vec!["heads.2da", "appearance.2da", "readme.txt"]);
    }

    /// An empty tree is empty rather than an error.
    #[test]
    fn files_beneath_an_empty_directory_is_empty() {
        let temp = TempDir::new().expect("tempdir");
        fs::create_dir(temp.path().join("empty")).expect("create");
        assert!(files_beneath(temp.path()).expect("reads").is_empty());
    }

    /// Every match comes back, not just the first, which is what separates the
    /// plural finders from the singular ones.
    #[test]
    #[cfg_attr(
        any(windows, target_os = "macos"),
        ignore = "needs a filesystem that tells names apart by case"
    )]
    fn the_plural_finder_returns_both_spellings() {
        let temp = TempDir::new().expect("tempdir");
        fs::create_dir(temp.path().join("Override")).expect("create");
        fs::create_dir(temp.path().join("override")).expect("create");

        let all = find_case_insensitive_directories(temp.path(), "override").expect("reads");
        assert_eq!(all.len(), 2, "{all:?}");
        assert_eq!(
            find_case_insensitive_directory(temp.path(), "override")
                .expect("reads")
                .as_ref(),
            all.first(),
            "the singular finder is not the first of the plural"
        );
    }

    /// A difference past the first block is found.
    ///
    /// The comparison reads in blocks, so a pair agreeing for the first of them
    /// is what would pass one that stopped early.
    #[test]
    fn a_difference_past_the_first_block_is_found() {
        let temp = TempDir::new().expect("tempdir");
        let ours = vec![b'a'; 200 * 1024];
        let mut theirs = ours.clone();
        let last = theirs.len() - 1;
        theirs[last] = b'b';
        let one = temp.path().join("one");
        let other = temp.path().join("other");
        fs::write(&one, &ours).expect("write");
        fs::write(&other, &theirs).expect("write");

        assert!(!files_have_same_bytes(&one, &other).expect("both read"));
        assert!(files_have_same_bytes(&one, &one).expect("reads"));
    }
}