aede_core/copy/

names.rs

//! Making a path acceptable to the filesystem it is about to be written to.
//!
//! A music library is full of names a general-purpose filesystem takes without
//! blinking and a portable player refuses: `Where Is My Mind?`, `Symphony No. 5:
//! Allegro`, `AC/DC`. Copying to a FAT32 or exFAT card — which is what a player
//! or a cheap USB stick almost always is — fails on those, one file at a time,
//! in the middle of a run that has already taken twenty minutes.
//!
//! **Nothing here is silent.** Every component this module changes is reported
//! back so the run can say what it renamed and why. A copy whose file names
//! quietly differ from the library's is a copy nobody can compare against the
//! original afterwards.

use std::collections::BTreeSet;

/// Characters no FAT/exFAT/NTFS volume accepts in a name.
///
/// `/` is absent on purpose: it never reaches this function, being the
/// separator that split the path into the components given to it.
const FORBIDDEN: &[char] = &['?', '*', ':', '"', '<', '>', '|', '\\'];

/// What replaces a character that cannot be written.
///
/// One visible character rather than removal: `Where Is My Mind_` still reads
/// as the title, where `Where Is My Mind` claims to be a name that was never
/// there — and two titles differing only by punctuation would silently become
/// one.
const REPLACEMENT: char = '_';

/// Names DOS reserved for devices, which FAT still refuses whatever the
/// extension: `NUL.flac` cannot be created.
const RESERVED: &[&str] = &[
    "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8",
    "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
];

/// Longest component the destination is assumed to accept.
///
/// 255 is what FAT32 with long file names, exFAT, ext4, APFS and NTFS all
/// allow. The unit is **bytes**, not characters: an accented title is longer
/// on disk than it looks on screen, and a limit counted in characters would
/// pass here and fail at the write.
const MAX_COMPONENT: usize = 255;

/// Splits a name into its stem and its extension, where there is one.
///
/// **Not every dot ends a name.** `Vol. 1: Live` has two, and neither of them
/// introduces an extension — taking the last one would make the stem `Vol` and
/// the "extension" ` 1_ Live`, which is how a disambiguating counter ends up
/// inside the title as `Vol (2). 1_ Live`. A test caught exactly that. So an
/// extension is recognised rather than assumed: a short run of letters and
/// digits, no spaces, after the final dot.
///
/// The extension comes back with its dot, so `stem + extension` is always the
/// name that went in.
fn split_extension(name: &str) -> (&str, &str) {
    let Some(dot) = name.rfind('.') else {
        return (name, "");
    };
    // A leading dot makes a hidden file, not an extension on an empty stem.
    if dot == 0 {
        return (name, "");
    }
    let candidate = &name[dot + 1..];
    let plausible = !candidate.is_empty()
        && candidate.len() <= 12
        && candidate.chars().all(|c| c.is_ascii_alphanumeric());
    match plausible {
        true => (&name[..dot], &name[dot..]),
        false => (name, ""),
    }
}

/// A component made acceptable, or left exactly as it was.
///
/// Returns `None` when nothing had to change, which is what lets the caller
/// report only the names it actually touched.
pub fn adapt(component: &str) -> Option<String> {
    let adapted = rewrite(component);
    (adapted != component).then_some(adapted)
}

fn rewrite(component: &str) -> String {
    let mut out: String = component
        .chars()
        // Control characters are as unwritable as the punctuation, and far
        // more likely to come from a damaged tag than from a title.
        .map(|c| match FORBIDDEN.contains(&c) || (c as u32) < 0x20 {
            true => REPLACEMENT,
            false => c,
        })
        .collect();

    // A name ending in a dot or a space is accepted by the call and then read
    // back without it, which turns "Vol. 2 " into a file the copy can never
    // find again. Trimmed rather than replaced: the trailing space carries no
    // meaning anybody wants to keep.
    let trimmed = out.trim_end_matches([' ', '.']);
    if trimmed.len() != out.len() {
        out = match trimmed.is_empty() {
            true => REPLACEMENT.to_string(),
            false => trimmed.to_string(),
        };
    }

    // Device names stay reserved before the first dot, even with several
    // extensions or a suffix the collision counter would not call an extension.
    let (stem, extension) = out.split_at(out.find('.').unwrap_or(out.len()));
    if RESERVED.iter().any(|word| stem.eq_ignore_ascii_case(word)) {
        out = format!("{stem}{REPLACEMENT}{extension}");
    }

    if out.len() > MAX_COMPONENT {
        // Cutting can expose punctuation that was inside the original name.
        out = shorten(&out).trim_end_matches([' ', '.']).to_string();
        // Removing that ending can also leave a bare reserved device name.
        if RESERVED.iter().any(|word| out.eq_ignore_ascii_case(word)) {
            out.push(REPLACEMENT);
        }
    }
    if out.is_empty() {
        out = REPLACEMENT.to_string();
    }
    out
}

/// Cuts an overlong component down to size, keeping its extension.
///
/// The extension is what says what the file *is*, and a player that sorts by
/// it would lose the track entirely; the middle of a long title is what nobody
/// misses. Cut on a character boundary, never in the middle of one, or the
/// result is not a string at all.
fn shorten(component: &str) -> String {
    let (stem, extension) = split_extension(component);
    let room = MAX_COMPONENT.saturating_sub(extension.len());
    let mut end = room.min(stem.len());
    while end > 0 && !stem.is_char_boundary(end) {
        end -= 1;
    }
    format!("{}{extension}", &stem[..end])
}

/// Makes a name unique among those already taken, and records it.
///
/// Shortening and character replacement can both map two different names onto
/// one — `Vol. 1: Live` and `Vol. 1? Live` both become `Vol. 1_ Live` — and a
/// copy that silently merges two albums into one folder is worse than a copy
/// that refuses. A counter is appended, before the extension, so the file
/// stays playable.
pub fn make_unique(name: &str, taken: &mut BTreeSet<String>) -> String {
    unique(name, taken, false)
}

/// Reserves a component using conservative text matching for portable copies.
/// Case, common composed/decomposed accents and punctuation are folded; this
/// may distinguish more names than strictly required by the current volume.
/// The set stores matching keys rather than the displayed names.
pub(super) fn make_unique_portable(name: &str, taken: &mut BTreeSet<String>) -> String {
    unique(name, taken, true)
}

/// Conservative component identity for portable copy namespace admission.
/// This is not a claim about every alias supported by a particular filesystem.
pub fn portable_key(name: &str) -> String {
    // Remove combining marks before textual folding so an accent inside a
    // word does not become a separator. Uppercase first also joins Unicode
    // case variants such as sigma and final sigma. The filesystem preflight
    // catches aliases outside this deliberately conservative vocabulary.
    let unmarked: String = name.chars().filter(|character| !matches!(*character as u32,
        0x0300..=0x036f | 0x1ab0..=0x1aff | 0x1dc0..=0x1dff | 0x20d0..=0x20ff | 0xfe20..=0xfe2f
    )).collect();
    crate::text::normalize(&unmarked.to_uppercase())
}

fn unique(name: &str, taken: &mut BTreeSet<String>, portable: bool) -> String {
    let key = |name: &str| {
        if portable {
            portable_key(name)
        } else {
            name.to_string()
        }
    };
    if taken.insert(key(name)) {
        return name.to_string();
    }
    let (stem, extension) = split_extension(name);
    for n in 2u64.. {
        let suffix = format!(" ({n})");
        let room = MAX_COMPONENT.saturating_sub(extension.len() + suffix.len());
        let mut end = room.min(stem.len());
        while end > 0 && !stem.is_char_boundary(end) {
            end -= 1;
        }
        let candidate = format!("{}{suffix}{extension}", &stem[..end]);
        if taken.insert(key(&candidate)) {
            return candidate;
        }
    }
    unreachable!("a filesystem cannot contain u64::MAX names")
}

/// Asks the destination itself what it accepts, by trying.
///
/// Deliberately empirical. The alternative is to read the filesystem's *name*
/// and infer from it, which needs platform-specific code and is wrong exactly
/// where it matters: a FUSE mount, an SMB share of a Windows folder, or a card
/// reader all report something the table does not list, and the inference has
/// to guess. Creating one file settles the question for the volume actually
/// being written to.
///
/// A failure to probe reads as "restricted": a copy that adapts names it did
/// not have to costs a few odd characters, one that fails to adapt names it
/// should have costs the run.
pub fn restricts_names(destination: &std::path::Path) -> bool {
    // Isolate the probe so an existing file (including a symlink) is never
    // opened, replaced or removed. Its filename retains the questioned '?'.
    let Ok(temporary) = super::TemporaryOutput::new(&destination.join("aede-name-probe?.tmp"))
    else {
        return true;
    };
    let probe = temporary.path().with_file_name("name?.tmp");
    std::fs::OpenOptions::new()
        .write(true)
        .create_new(true)
        .open(probe)
        .is_err()
}

#[cfg(test)]
#[path = "names_tests.rs"]
mod tests;