diff --git a/AGENTS.md b/AGENTS.md index 5af1408..80b4c84 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,11 @@ with quick-start examples and links to detailed documentation in `docs/`. ## Current tools +- `crates/ascii-names/` is the sequential ASCII filename cleaner: one Rust binary + with egui drag-and-drop and CLI modes. Keep renames paced and single-threaded, + preserve file contents, never overwrite collision targets, and skip symlinks. + The selected root stays unchanged; descendants are processed inside out. + - `crates/pptx-reporter/` is the Rust reporter: shared core, CLI and egui desktop interface. PDF compilation and DejaVu fonts are embedded. Discover FFprobe beside the app, under `bin/`, or on PATH. It is the sole PPTX video reporter; the Python diff --git a/Cargo.lock b/Cargo.lock index 58214b7..60c7c25 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -201,6 +201,19 @@ version = "1.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b" +[[package]] +name = "ascii-names" +version = "0.3.0" +dependencies = [ + "clap", + "eframe", + "rfd", + "rustix 1.1.5", + "tempfile", + "unicode-normalization", + "windows-sys 0.61.2", +] + [[package]] name = "ash" version = "0.38.0+1.3.281" diff --git a/Cargo.toml b/Cargo.toml index 7ad9a81..1fe1bf6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ [workspace] -members = ["crates/pptx-reporter", "crates/rundown-converter"] +members = ["crates/pptx-reporter", "crates/rundown-converter", "crates/ascii-names"] default-members = ["crates/pptx-reporter"] resolver = "3" diff --git a/README.md b/README.md index c63dc96..8e169fa 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ ![line coverage](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg) Local document and media tools: a Rust PPTX video reporter with a drag-and-drop -app, a spreadsheet rundown converter for Ontime, and Python document exports. +app, a spreadsheet rundown converter for Ontime, an ASCII filename cleaner, +and Python document exports. ## Quick start @@ -24,6 +25,7 @@ cargo run --locked --bin pptx-reporter-gui cargo run --locked --bin pptx-reporter -- presentation.pptx --report all cargo run --locked --bin pptx-reporter -- ./show --timings-only --report ontime cargo run --locked -p rundown-converter --bin rundown-converter-gui +cargo run --locked -p ascii-names python3 tools/exporter.py presentation.pptx --output pdf,images ``` @@ -42,6 +44,7 @@ opening reports, and reading video timings. - [Reporter](docs/rust-reporter.md) · [Windows quick start](docs/windows-quickstart.txt) - [Report formats and timing semantics](docs/pptx-videos.md) +- [ASCII filename cleaner](docs/ascii-names.md) - [Document exports](docs/exporter.md) - [Rundown converter](docs/rundown-converter.md) · [Sample findings](docs/rundown-corpus.md) - [Development](docs/development.md) · [CI and coverage](docs/ci.md) diff --git a/crates/ascii-names/Cargo.toml b/crates/ascii-names/Cargo.toml new file mode 100644 index 0000000..5072cc7 --- /dev/null +++ b/crates/ascii-names/Cargo.toml @@ -0,0 +1,26 @@ +[package] +name = "ascii-names" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +description = "Sequential ASCII filename cleanup for removable drives" + +[features] +default = ["desktop"] +desktop = ["dep:eframe", "dep:rfd"] + +[dependencies] +clap = { version = "4", features = ["derive"] } +unicode-normalization = "0.1" +eframe = { version = "0.31", optional = true, default-features = false, features = ["default_fonts", "glow", "x11", "wayland"] } +rfd = { version = "0.15", optional = true } + +[target.'cfg(any(target_os = "linux", target_vendor = "apple"))'.dependencies] +rustix = { version = "1", features = ["fs"] } + +[dev-dependencies] +tempfile = "3" + +[target.'cfg(windows)'.dependencies] +windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] } diff --git a/crates/ascii-names/src/gui.rs b/crates/ascii-names/src/gui.rs new file mode 100644 index 0000000..d3fbe95 --- /dev/null +++ b/crates/ascii-names/src/gui.rs @@ -0,0 +1,147 @@ +//! Small drag-and-drop interface, with one background worker and bounded progress storage. +use crate::{Options, Summary, clean}; +use eframe::egui; +use std::{ + collections::VecDeque, + path::PathBuf, + sync::{ + Arc, Mutex, + atomic::{AtomicBool, Ordering}, + }, + thread::{self, JoinHandle}, + time::Duration, +}; + +#[derive(Default)] +struct Progress { + summary: Summary, + messages: VecDeque, +} +impl Progress { + fn push(&mut self, message: String) { + if self.messages.len() == 200 { + self.messages.pop_front(); + } + self.messages.push_back(message); + } +} +#[derive(Default)] +struct App { + folder: Option, + progress: Arc>, + cancel: Arc, + worker: Option>, +} +impl App { + fn start(&mut self, dry_run: bool) { + let Some(folder) = self.folder.clone() else { + return; + }; + self.cancel.store(false, Ordering::Relaxed); + *self.progress.lock().unwrap() = Progress::default(); + let progress = self.progress.clone(); + let cancel = self.cancel.clone(); + self.worker = Some(thread::spawn(move || { + let result = clean( + &folder, + Options { + dry_run, + ..Options::default() + }, + &cancel, + |summary, message| { + let mut p = progress.lock().unwrap(); + p.summary = summary.clone(); + p.push(message); + }, + ); + let mut p = progress.lock().unwrap(); + match result { + Ok(summary) => { + p.push(format!( + "{}: {summary}", + if dry_run { + "Preview complete" + } else { + "Cleanup complete" + } + )); + p.summary = summary; + } + Err(error) => { + p.summary.errors += 1; + p.push(format!("Cannot clean {}: {error}", folder.display())); + } + } + })); + } +} +impl Drop for App { + fn drop(&mut self) { + self.cancel.store(true, Ordering::Relaxed); + } +} +impl eframe::App for App { + fn update(&mut self, ctx: &egui::Context, _: &mut eframe::Frame) { + if self.worker.as_ref().is_some_and(|w| w.is_finished()) + && self.worker.take().unwrap().join().is_err() + { + let mut p = self.progress.lock().unwrap(); + p.summary.errors += 1; + p.push("Worker stopped unexpectedly; completed renames remain in place.".into()); + } + let busy = self.worker.is_some(); + if !busy { + let dropped = ctx.input(|i| i.raw.dropped_files.clone()); + if let Some(file) = dropped.first() { + self.folder = file.path.clone(); + } + } + egui::CentralPanel::default().show(ctx, |ui| { + ui.heading("ASCII names"); + ui.label("Drop a folder here, then clean its file and subfolder names."); + ui.label("Accents become letters; unknown characters become underscores."); + ui.small("Contents stay intact. The selected folder keeps its name. Links are skipped."); + ui.small("Renaming can break playlists, shortcuts and project references. Keep the folder idle."); + ui.add_space(12.0); + ui.add_enabled_ui(!busy, |ui| { + if ui.button("Choose folder…").clicked() + && let Some(folder) = rfd::FileDialog::new().pick_folder() { self.folder = Some(folder); } + ui.label(self.folder.as_ref().map_or_else(|| "No folder selected".into(), |p| p.display().to_string())); + ui.horizontal(|ui| { + ui.add_enabled_ui(self.folder.is_some(), |ui| { + if ui.button("Preview").clicked() { self.start(true); } + if ui.button("Clean names").clicked() { self.start(false); } + }); + }); + }); + if busy { + ui.horizontal(|ui| { + ui.spinner(); ui.label("Working sequentially · 25 ms between renames"); + if ui.button("Stop").clicked() { self.cancel.store(true, Ordering::Relaxed); } + }); + ctx.request_repaint_after(Duration::from_millis(100)); + } + ui.separator(); + let p = self.progress.lock().unwrap(); + ui.label(p.summary.to_string()); + ui.small("Most recent 200 messages"); + egui::ScrollArea::vertical().stick_to_bottom(true).show(ui, |ui| { + for message in &p.messages { ui.label(message); } + }); + }); + } +} + +pub fn launch() -> eframe::Result { + eframe::run_native( + "ASCII names", + eframe::NativeOptions { + viewport: egui::ViewportBuilder::default() + .with_inner_size([760.0, 480.0]) + .with_drag_and_drop(true), + ..Default::default() + }, + Box::new(|_| Ok(Box::::default())), + ) +} diff --git a/crates/ascii-names/src/lib.rs b/crates/ascii-names/src/lib.rs new file mode 100644 index 0000000..facbb69 --- /dev/null +++ b/crates/ascii-names/src/lib.rs @@ -0,0 +1,346 @@ +//! Sequential, paced filename cleanup. File contents are never opened. +use std::{ + collections::{HashMap, HashSet}, + fs, io, + path::{Path, PathBuf}, + sync::atomic::{AtomicBool, Ordering}, + thread, + time::Duration, +}; +use unicode_normalization::{UnicodeNormalization, char::is_combining_mark}; + +#[cfg(feature = "desktop")] +pub mod gui; + +/// ASCII equivalents for accented Latin text and common punctuation; unknowns become `_`. +/// Also removes names that are unsafe on common removable-drive filesystems. +pub fn ascii_name(name: &str) -> String { + let mut result = String::new(); + for c in name.nfkd().filter(|c| !is_combining_mark(*c)) { + let replacement = match c { + 'ß' | 'ẞ' => "ss", + 'æ' => "ae", + 'Æ' => "AE", + 'œ' => "oe", + 'Œ' => "OE", + 'ø' => "o", + 'Ø' => "O", + 'ł' => "l", + 'Ł' => "L", + 'đ' | 'ð' => "d", + 'Đ' | 'Ð' => "D", + 'þ' => "th", + 'Þ' => "Th", + '‘' | '’' | '‚' | '‛' => "'", + '“' | '”' | '„' | '‟' => "'", + '–' | '—' | '−' => "-", + '…' => "...", + c if c.is_ascii() && !c.is_ascii_control() && !"<>:\"/\\|?*".contains(c) => { + result.push(c); + continue; + } + _ => "_", + }; + result.push_str(replacement); + } + result = result.trim_end_matches([' ', '.']).to_owned(); + if result.is_empty() { + result.push('_'); + } + let base = result + .split('.') + .next() + .unwrap_or("") + .trim_end() + .to_ascii_uppercase(); + if matches!(base.as_str(), "CON" | "PRN" | "AUX" | "NUL") + || (base.len() == 4 + && (base.starts_with("COM") || base.starts_with("LPT")) + && matches!(base.as_bytes()[3], b'1'..=b'9')) + { + result.insert(0, '_'); + } + // Leave room for collision suffixes and stay below common 255-byte limits. + shorten(&result, 220) +} + +fn shorten(name: &str, limit: usize) -> String { + if name.len() <= limit { + return name.to_owned(); + } + if let Some((stem, ext)) = name.rsplit_once('.') + && !stem.is_empty() + && ext.len() < 32 + { + return format!("{}.{}", &stem[..limit - ext.len() - 1], ext); + } + name[..limit].to_owned() +} + +#[derive(Clone, Copy)] +pub struct Options { + pub dry_run: bool, + pub delay: Duration, +} +impl Default for Options { + fn default() -> Self { + Self { + dry_run: false, + delay: Duration::from_millis(25), + } + } +} + +#[derive(Clone, Debug, Default)] +pub struct Summary { + pub visited: usize, + pub renamed: usize, + pub skipped: usize, + pub errors: usize, + pub cancelled: bool, +} +impl std::fmt::Display for Summary { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!( + f, + "{} visited; {} renames; {} skipped; {} errors{}", + self.visited, + self.renamed, + self.skipped, + self.errors, + if self.cancelled { "; stopped" } else { "" } + ) + } +} + +/// Clean the contents of a folder, keeping the selected root itself unchanged. +/// Symlinks and special files are skipped. No parallel I/O; stop between entries. +/// Keep the tree idle during cleanup (renaming can break links and application references). +pub fn clean( + root: &Path, + options: Options, + cancel: &AtomicBool, + mut report: impl FnMut(&Summary, String), +) -> io::Result { + if !fs::symlink_metadata(root)?.file_type().is_dir() { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "Drop a real folder, not a file or symlink", + )); + } + let mut summary = Summary::default(); + let mut targets = Targets::default(); + // Explicit stack avoids call-stack overflow in deeply nested trees. + enum Work { + Visit(PathBuf), + Rename(PathBuf, bool), + } + let mut stack = vec![Work::Visit(root.to_owned())]; + while let Some(work) = stack.pop() { + if cancel.load(Ordering::Relaxed) { + summary.cancelled = true; + break; + } + match work { + Work::Visit(dir) => { + let entries = match fs::read_dir(&dir) + .and_then(|entries| entries.collect::>>()) + { + Ok(mut entries) => { + entries.sort_by_key(|e| e.file_name()); + entries + } + Err(e) => { + summary.errors += 1; + report(&summary, format!("Cannot read {}: {e}", dir.display())); + continue; + } + }; + for entry in entries.into_iter().rev() { + let path = entry.path(); + match entry.file_type() { + Ok(kind) if kind.is_dir() => { + stack.push(Work::Rename(path.clone(), true)); + stack.push(Work::Visit(path)); + } + Ok(kind) if kind.is_file() => stack.push(Work::Rename(path, false)), + Ok(_) => { + summary.skipped += 1; + report( + &summary, + format!("Skipped link/special file: {}", path.display()), + ); + } + Err(e) => { + summary.errors += 1; + report(&summary, format!("Cannot inspect {}: {e}", path.display())); + } + } + } + } + Work::Rename(path, is_dir) => { + summary.visited += 1; + if let Err(e) = rename_one( + &path, + is_dir, + options, + &mut targets, + &mut summary, + &mut report, + ) { + summary.errors += 1; + report(&summary, format!("Cannot rename {}: {e}", path.display())); + } + } + } + } + Ok(summary) +} + +#[derive(Default)] +struct Targets { + reserved: HashSet, + next_suffix: HashMap, +} + +fn rename_one( + path: &Path, + is_dir: bool, + options: Options, + targets: &mut Targets, + summary: &mut Summary, + report: &mut impl FnMut(&Summary, String), +) -> io::Result<()> { + let original = path.file_name().unwrap(); + let name = ascii_name(&original.to_string_lossy()); + if original == name.as_str() { + return Ok(()); + } + let parent = path.parent().unwrap(); + let base_key = parent.join(name.to_ascii_lowercase()); + let mut number = targets.next_suffix.get(&base_key).copied().unwrap_or(0); + loop { + let candidate = if number == 0 { + name.clone() + } else { + let p = Path::new(&name); + match (p.file_stem(), p.extension()) { + (Some(stem), Some(ext)) if !is_dir => format!( + "{}_{number}.{}", + stem.to_string_lossy(), + ext.to_string_lossy() + ), + _ => format!("{name}_{number}"), + } + }; + let target = parent.join(candidate); + // Case-fold reservations also protect previews on case-insensitive media. + let key = parent.join( + target + .file_name() + .unwrap() + .to_string_lossy() + .to_ascii_lowercase(), + ); + // Avoid repeated metadata probes when many names normalize to the same base. + if targets.reserved.contains(&key) { + number += 1; + continue; + } + let occupied = match fs::symlink_metadata(&target) { + Ok(_) => true, + Err(e) if e.kind() == io::ErrorKind::NotFound => false, + Err(e) => return Err(e), + }; + if occupied { + number += 1; + continue; + } + if !options.dry_run { + // Pace attempts as well as successful renames. + thread::sleep(options.delay); + match rename_no_replace(path, &target) { + Ok(()) => (), + Err(e) if e.kind() == io::ErrorKind::AlreadyExists => { + number += 1; + continue; + } + Err(e) => return Err(e), + } + } + targets.reserved.insert(key); + targets.next_suffix.insert(base_key, number + 1); + summary.renamed += 1; + report( + summary, + format!( + "{}{} -> {}", + if options.dry_run { "Preview: " } else { "" }, + path.display(), + target.display() + ), + ); + return Ok(()); + } +} + +fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> { + #[cfg(any(target_os = "linux", target_vendor = "apple"))] + { + rustix::fs::renameat_with( + rustix::fs::CWD, + from, + rustix::fs::CWD, + to, + rustix::fs::RenameFlags::NOREPLACE, + ) + .map_err(Into::into) + } + #[cfg(target_os = "windows")] + { + use std::os::windows::ffi::OsStrExt; + let from: Vec = from.as_os_str().encode_wide().chain(Some(0)).collect(); + let to: Vec = to.as_os_str().encode_wide().chain(Some(0)).collect(); + // No MOVEFILE_REPLACE_EXISTING: an existing destination must survive. + let ok = unsafe { + windows_sys::Win32::Storage::FileSystem::MoveFileExW(from.as_ptr(), to.as_ptr(), 0) + }; + if ok == 0 { + Err(io::Error::last_os_error()) + } else { + Ok(()) + } + } + #[cfg(not(any(target_os = "linux", target_vendor = "apple", target_os = "windows")))] + { + let _ = (from, to); + Err(io::Error::new( + io::ErrorKind::Unsupported, + "Safe no-overwrite rename is unavailable on this platform", + )) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn atomic_rename_refuses_existing_files_and_directories() { + let tmp = tempfile::tempdir().unwrap(); + let source = tmp.path().join("source"); + let dest = tmp.path().join("dest"); + fs::write(&source, "new").unwrap(); + fs::write(&dest, "original").unwrap(); + assert!(rename_no_replace(&source, &dest).is_err()); + assert_eq!(fs::read_to_string(&dest).unwrap(), "original"); + assert_eq!(fs::read_to_string(&source).unwrap(), "new"); + fs::remove_file(&source).unwrap(); + fs::remove_file(&dest).unwrap(); + fs::create_dir(&source).unwrap(); + fs::create_dir(&dest).unwrap(); + assert!(rename_no_replace(&source, &dest).is_err()); + assert!(source.is_dir()); + assert!(dest.is_dir()); + } +} diff --git a/crates/ascii-names/src/main.rs b/crates/ascii-names/src/main.rs new file mode 100644 index 0000000..363197e --- /dev/null +++ b/crates/ascii-names/src/main.rs @@ -0,0 +1,52 @@ +use clap::Parser; +use std::{path::PathBuf, sync::atomic::AtomicBool, time::Duration}; + +#[derive(Parser)] +#[command( + version, + about = "Clean filenames recursively for ASCII-only computers. Run without arguments for drag and drop." +)] +struct Args { + /// Folder whose contents will be renamed in place (root itself stays unchanged). + folder: Option, + /// Show proposed renames without changing anything. + #[arg(long, requires = "folder")] + dry_run: bool, + /// Pause between renames, in milliseconds (one worker only). + #[arg(long, default_value_t = 25, requires = "folder", value_parser = clap::value_parser!(u64).range(0..=1000))] + delay_ms: u64, +} +fn main() { + let args = Args::parse(); + if let Some(folder) = args.folder { + let options = ascii_names::Options { + dry_run: args.dry_run, + delay: Duration::from_millis(args.delay_ms), + }; + match ascii_names::clean(&folder, options, &AtomicBool::new(false), |_, message| { + println!("{message}") + }) { + Ok(summary) => { + println!("{summary}"); + if summary.errors > 0 { + std::process::exit(1); + } + } + Err(error) => { + eprintln!("{}: {error}", folder.display()); + std::process::exit(1); + } + } + } else { + #[cfg(feature = "desktop")] + if let Err(error) = ascii_names::gui::launch() { + eprintln!("Cannot open window: {error}"); + std::process::exit(1); + } + #[cfg(not(feature = "desktop"))] + { + eprintln!("Supply a folder, or build with the default desktop feature."); + std::process::exit(2); + } + } +} diff --git a/crates/ascii-names/tests/cleanup.rs b/crates/ascii-names/tests/cleanup.rs new file mode 100644 index 0000000..7a5d911 --- /dev/null +++ b/crates/ascii-names/tests/cleanup.rs @@ -0,0 +1,249 @@ +use ascii_names::{Options, ascii_name, clean}; +use std::{ + fs, + sync::atomic::AtomicBool, + time::{Duration, Instant}, +}; + +fn options() -> Options { + Options { + delay: Duration::ZERO, + dry_run: false, + } +} + +#[test] +fn accents_punctuation_unknowns_and_portable_names() { + for (input, expected) in [ + ("Été à Noël.mov", "Ete a Noel.mov"), + ("Cafe\u{301}.txt", "Cafe.txt"), + ( + "œuf Straße Łódź Æsir Øresund", + "oeuf Strasse Lodz AEsir Oresund", + ), + ("‘Hello’—world…", "'Hello'-world"), + ("日本🎬.txt", "___.txt"), + ("a\nb:<>\"\\|?*c", "a_b________c"), + ("\u{301}", "_"), + ("..", "_"), + ("foo. ", "foo"), + ("CON.txt", "_CON.txt"), + ("LPT9", "_LPT9"), + ("COM0", "COM0"), + ("ordinary file-01.txt", "ordinary file-01.txt"), + ] { + assert_eq!(ascii_name(input), expected, "{input:?}"); + } + let name = ascii_name(&format!("{}.txt", "ffi".repeat(100))); + assert_eq!(name.len(), 220); + assert!(name.ends_with(".txt")); + assert!(name.is_ascii()); +} + +#[test] +fn nested_cleanup_preserves_all_contents_and_is_idempotent() { + let tmp = tempfile::tempdir().unwrap(); + let root = tmp.path().join("Sélection"); + fs::create_dir_all(root.join("Étage/été")).unwrap(); + fs::write(root.join("Étage/été/vidéo.mov"), b"video bytes").unwrap(); + fs::write(root.join("resume.txt"), b"original").unwrap(); + fs::write(root.join("résumé.txt"), b"accented").unwrap(); + fs::write(root.join("résume.txt"), b"another").unwrap(); + let cancel = AtomicBool::new(false); + let summary = clean(&root, options(), &cancel, |_, _| {}).unwrap(); + assert_eq!(summary.errors, 0); + assert_eq!(summary.renamed, 5); + assert_eq!( + fs::read(root.join("Etage/ete/video.mov")).unwrap(), + b"video bytes" + ); + assert_eq!(fs::read(root.join("resume.txt")).unwrap(), b"original"); + let mut contents = [ + fs::read(root.join("resume_1.txt")).unwrap(), + fs::read(root.join("resume_2.txt")).unwrap(), + ]; + contents.sort(); + assert_eq!(contents, [b"accented".to_vec(), b"another".to_vec()]); + assert_eq!( + clean(&root, options(), &cancel, |_, _| {}).unwrap().renamed, + 0 + ); +} + +#[test] +fn preview_reserves_targets_and_changes_nothing() { + let tmp = tempfile::tempdir().unwrap(); + fs::write(tmp.path().join("é.txt"), "a").unwrap(); + fs::write(tmp.path().join("è.txt"), "b").unwrap(); + let mut logs = vec![]; + let summary = clean( + tmp.path(), + Options { + dry_run: true, + ..options() + }, + &AtomicBool::new(false), + |_, msg| logs.push(msg), + ) + .unwrap(); + assert_eq!(summary.renamed, 2); + assert!(logs[0].ends_with("e.txt")); + assert!(logs[1].ends_with("e_1.txt")); + assert!(tmp.path().join("é.txt").exists()); + assert!(tmp.path().join("è.txt").exists()); + assert!(!tmp.path().join("e.txt").exists()); +} + +#[test] +fn directory_and_file_collisions_never_merge() { + let tmp = tempfile::tempdir().unwrap(); + fs::create_dir(tmp.path().join("Ete")).unwrap(); + fs::create_dir(tmp.path().join("Été")).unwrap(); + fs::write(tmp.path().join("Ete/original"), "keep").unwrap(); + fs::write(tmp.path().join("Été/new"), "new").unwrap(); + fs::write(tmp.path().join("été"), "file").unwrap(); + let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap(); + assert_eq!(result.errors, 0); + assert_eq!( + fs::read_to_string(tmp.path().join("Ete/original")).unwrap(), + "keep" + ); + assert!(tmp.path().join("Ete_1/new").is_file()); +} + +#[test] +fn cancellation_stops_between_renames_and_delay_is_applied() { + let tmp = tempfile::tempdir().unwrap(); + fs::write(tmp.path().join("é"), "a").unwrap(); + fs::write(tmp.path().join("à"), "b").unwrap(); + let cancel = AtomicBool::new(false); + let start = Instant::now(); + let result = clean( + tmp.path(), + Options { + delay: Duration::from_millis(30), + dry_run: false, + }, + &cancel, + |_, _| cancel.store(true, std::sync::atomic::Ordering::Relaxed), + ) + .unwrap(); + assert!(result.cancelled); + assert_eq!(result.renamed, 1); + assert!(start.elapsed() >= Duration::from_millis(30)); + assert!( + clean(tmp.path(), options(), &cancel, |_, _| {}) + .unwrap() + .cancelled + ); +} + +#[test] +fn missing_root_and_file_root_are_errors() { + let tmp = tempfile::tempdir().unwrap(); + let file = tmp.path().join("file"); + let cancel = AtomicBool::new(false); + assert!(clean(&file, options(), &cancel, |_, _| {}).is_err()); + fs::write(&file, "x").unwrap(); + assert!(clean(&file, options(), &cancel, |_, _| {}).is_err()); +} + +#[cfg(unix)] +#[test] +fn links_are_not_followed_and_invalid_utf8_is_cleaned() { + use std::{ + ffi::OsString, + os::unix::{ffi::OsStringExt, fs::symlink}, + }; + let tmp = tempfile::tempdir().unwrap(); + let outside = tempfile::tempdir().unwrap(); + fs::write(outside.path().join("é.txt"), "outside").unwrap(); + symlink(outside.path(), tmp.path().join("lïnk")).unwrap(); + symlink("missing", tmp.path().join("e.txt")).unwrap(); + fs::write(tmp.path().join("é.txt"), "inside").unwrap(); + fs::write( + tmp.path().join(OsString::from_vec(b"bad\xff.txt".to_vec())), + "bytes", + ) + .unwrap(); + let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap(); + assert_eq!(result.skipped, 2); + assert_eq!(result.errors, 0); + assert!(outside.path().join("é.txt").exists()); + assert_eq!( + fs::read_to_string(tmp.path().join("bad_.txt")).unwrap(), + "bytes" + ); + assert_eq!( + fs::read_to_string(tmp.path().join("e_1.txt")).unwrap(), + "inside" + ); + assert!( + clean( + &tmp.path().join("lïnk"), + options(), + &AtomicBool::new(false), + |_, _| {} + ) + .is_err() + ); +} + +#[test] +fn cli_preview_and_apply() { + let tmp = tempfile::tempdir().unwrap(); + fs::write(tmp.path().join("été.txt"), "content").unwrap(); + let bin = env!("CARGO_BIN_EXE_ascii-names"); + let output = std::process::Command::new(bin) + .arg(tmp.path()) + .arg("--dry-run") + .output() + .unwrap(); + assert!(output.status.success()); + assert!(tmp.path().join("été.txt").exists()); + assert!( + std::process::Command::new(bin) + .arg(tmp.path()) + .args(["--delay-ms", "0"]) + .output() + .unwrap() + .status + .success() + ); + assert_eq!( + fs::read_to_string(tmp.path().join("ete.txt")).unwrap(), + "content" + ); + assert!( + !std::process::Command::new(bin) + .arg(tmp.path().join("missing")) + .output() + .unwrap() + .status + .success() + ); +} + +#[test] +fn many_names_with_same_fallback_keep_every_file() { + let tmp = tempfile::tempdir().unwrap(); + for (index, character) in (0x4e00..0x4e80).filter_map(char::from_u32).enumerate() { + fs::write( + tmp.path().join(format!("{character}.txt")), + index.to_string(), + ) + .unwrap(); + } + let summary = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap(); + assert_eq!(summary.renamed, 128); + assert_eq!(summary.errors, 0); + let values: std::collections::HashSet<_> = fs::read_dir(tmp.path()) + .unwrap() + .map(|entry| { + let path = entry.unwrap().path(); + assert!(path.file_name().unwrap().to_str().unwrap().is_ascii()); + fs::read_to_string(path).unwrap() + }) + .collect(); + assert_eq!(values.len(), 128); +} diff --git a/docs/ascii-names.md b/docs/ascii-names.md new file mode 100644 index 0000000..e267917 --- /dev/null +++ b/docs/ascii-names.md @@ -0,0 +1,72 @@ +# ASCII names + +A small Rust application for cleaning filenames before using a folder on an +ASCII-only computer. Run it on your modern computer while the USB drive is plugged in. +It changes names in place; file contents are never opened or rewritten. + +```sh +cargo run --locked -p ascii-names +``` + +Drop a folder into the window (or use **Choose folder**). **Preview** lists proposed +changes without writing anything. **Clean names** processes all files and subfolders. +**Stop** stops between entries; completed renames remain in place. The window keeps +the latest 200 messages. Drop one folder at a time. + +The selected folder itself keeps its name, so selecting a drive's mount point is +safe. To clean a folder's own name too, select its parent. Symlinks and special +files are skipped, including links to other folders. Hidden files are included. +Nested mounted directories are treated as ordinary directories. + +## Naming rules + +- Accented Latin letters lose their accents, including decomposed macOS accents: + `Été.mov` → `Ete.mov`. Ligatures and common letters such as `œ`, `ß`, `ø`, `ł` + become `oe`, `ss`, `o`, `l`. +- Common Unicode quotes and dashes become ASCII punctuation. Other characters + without a supported equivalent become `_`. This is not transliteration of + every writing system: `日本.txt` becomes `__.txt`. +- ASCII control characters and `<>:"/\|?*` become `_` for filesystem compatibility. + Trailing dots/spaces are removed; empty names become `_`. Windows reserved + names such as `CON.txt` gain an underscore prefix. +- Names longer than 220 ASCII bytes are shortened, preserving short extensions. +- Existing destinations are never overwritten or merged. Collisions receive + `_1`, `_2`, etc., before a file's extension: `résumé.txt` becomes `resume_1.txt` + when `resume.txt` already exists. Directories get the suffix at the end. + +Directories are handled inside out. Filesystem work runs on one worker, with +25 ms between rename attempts (at most about 40 renames per second). There are +no parallel scans, content copies, or per-file flushes. Eject the USB drive +normally afterward so the operating system finishes any buffered writes. + +Keep the selected tree idle while running. Names referenced by playlists, +shortcuts, documents or projects are not updated inside those files. Preview +first when these references matter. There is no automatic undo. Read/rename +errors are reported and processing continues where possible; rerun after resolving +the reported cause. A failed directory rename can leave already-cleaned children. + +## Command line + +The same binary supports a folder argument, useful for terminal drag and drop: + +```sh +cargo run --locked -p ascii-names -- /path/to/folder --dry-run +cargo run --locked -p ascii-names -- /path/to/folder +cargo run --locked -p ascii-names -- /path/to/folder --delay-ms 100 +``` + +`--delay-ms` accepts 0–1000; the default is 25. Preview does not sleep. +The CLI prints every change and a summary, and exits nonzero on errors. Preview +paths show the traversal's intermediate paths before ancestor folders are renamed; +preview is not a saved plan, and cleanup scans again. + +Build a standalone desktop binary with `cargo build --locked --release -p ascii-names`. +For a smaller CLI-only build, add `--no-default-features`. No FFprobe or other +external command is required. The desktop uses the same egui dependencies as the +other Rust tools. Linux/macOS use an atomic no-replace rename and Windows uses +MoveFileExW without replacement. Filesystems that do not support safe no-replace +renames produce an error; the tool never falls back to an overwriting rename. + +The crate is included in workspace tests, Clippy, Rustdoc and coverage. Regression +tests cover collisions, nested directories, previews, cancellation, pacing, +symlinks, invalid UTF-8 filenames on Unix, and content preservation. diff --git a/docs/development.md b/docs/development.md index caeb234..9b65d0c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -56,3 +56,7 @@ The converter can run without desktop dependencies using Its tests generate synthetic XLSX inputs and never require private source files or network downloads. The existing workspace test, lint, Rustdoc and coverage commands include both tools; reporter release packaging remains separate. + +The [ASCII filename cleaner](ascii-names.md) is a separate Rust workspace member. +Run `cargo run --locked -p ascii-names` for its drag-and-drop window, or pass a +folder for CLI cleanup. It uses the same workspace checks and coverage gates.