diff --git a/AGENTS.md b/AGENTS.md index f0a98fd..b6ed506 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,9 @@ with quick-start examples and links to detailed documentation in `docs/`. - `tests/test_exporter.py` covers exporter validation, no-op behavior, conversion failures, and overwrite behavior. - `Jenkinsfile` runs Python/Rust tests, lint, docs and coverage on - `rust_no_docker`. The explicitly requested badge workflow archives exactly + `rust_no_docker` in a FreeBSD jail. ASCII cleaner tests must verify safe refusal + when the jail lacks the native no-overwrite API; exercise successful renames + on supported hosts as well. The explicitly requested badge workflow archives exactly three SVGs and publishes them only from main during cleanup. CI never creates releases or uploads release binaries. Cross and `rust_realease` are separate, manually invoked build/release preparation tools. diff --git a/Cargo.lock b/Cargo.lock index 60c7c25..3c3b84f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -207,6 +207,7 @@ version = "0.3.0" dependencies = [ "clap", "eframe", + "libc", "rfd", "rustix 1.1.5", "tempfile", diff --git a/Jenkinsfile b/Jenkinsfile index 3b8f4e9..90d1562 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -30,6 +30,7 @@ pipeline { set -eu python3 -c 'import sys; assert sys.version_info >= (3, 11), "Python 3.11+ required for CI"' test -n "${BRANCH_NAME:?Configure this job as a Multibranch Pipeline}" + uname -sr rustc --version if ! cargo llvm-cov --version | grep -Fx 'cargo-llvm-cov 0.9.1'; then cargo install cargo-llvm-cov --version 0.9.1 --locked diff --git a/crates/ascii-names/Cargo.toml b/crates/ascii-names/Cargo.toml index 5072cc7..89dfe7b 100644 --- a/crates/ascii-names/Cargo.toml +++ b/crates/ascii-names/Cargo.toml @@ -20,7 +20,11 @@ rfd = { version = "0.15", optional = true } rustix = { version = "1", features = ["fs"] } [dev-dependencies] +libc = "0.2.191" tempfile = "3" [target.'cfg(windows)'.dependencies] windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] } + +[target.'cfg(target_os = "freebsd")'.dependencies] +libc = "0.2.191" diff --git a/crates/ascii-names/src/freebsd.rs b/crates/ascii-names/src/freebsd.rs new file mode 100644 index 0000000..cc32bde --- /dev/null +++ b/crates/ascii-names/src/freebsd.rs @@ -0,0 +1,113 @@ +//! Resolve the newer FreeBSD API at runtime so older jails can still start/preview. +use std::{ffi::CString, io, os::unix::ffi::OsStrExt, path::Path, sync::OnceLock}; + +type RenameAt2 = unsafe extern "C" fn( + libc::c_int, + *const libc::c_char, + libc::c_int, + *const libc::c_char, + libc::c_uint, +) -> libc::c_int; + +fn unsupported(detail: impl std::fmt::Display) -> io::Error { + io::Error::new( + io::ErrorKind::Unsupported, + format!( + "FreeBSD no-overwrite rename unavailable ({detail}); use a host, jail userland and filesystem supporting renameat2 with AT_RENAME_NOREPLACE, or run cleanup on Linux/macOS/Windows" + ), + ) +} + +pub(super) fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> { + static RENAME: OnceLock> = OnceLock::new(); + let rename = RENAME.get_or_init(|| { + // SAFETY: static NUL-terminated symbol name; RTLD_DEFAULT searches loaded libraries. + let symbol = unsafe { libc::dlsym(libc::RTLD_DEFAULT, c"renameat2".as_ptr()) }; + if symbol.is_null() { + None + } else { + // SAFETY: the FreeBSD renameat2 ABI has precisely the signature above. + Some(unsafe { std::mem::transmute::<*mut libc::c_void, RenameAt2>(symbol) }) + } + }); + rename_with(*rename, from, to) +} + +fn rename_with(rename: Option, from: &Path, to: &Path) -> io::Result<()> { + let rename = rename.ok_or_else(|| unsupported("renameat2 is missing from the jail's libc"))?; + let from = CString::new(from.as_os_str().as_bytes())?; + let to = CString::new(to.as_os_str().as_bytes())?; + // SAFETY: both paths remain valid NUL-terminated strings throughout the call. + let status = unsafe { + rename( + libc::AT_FDCWD, + from.as_ptr(), + libc::AT_FDCWD, + to.as_ptr(), + libc::RENAME_NOREPLACE, + ) + }; + if status == 0 { + return Ok(()); + } + let error = io::Error::last_os_error(); + if matches!(error.raw_os_error(), Some(libc::ENOSYS | libc::EOPNOTSUPP)) { + Err(unsupported(error)) + } else { + Err(error) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::fs; + + #[test] + fn missing_api_preserves_files_and_directories() { + let tmp = tempfile::tempdir().unwrap(); + let from = tmp.path().join("source"); + let to = tmp.path().join("target"); + fs::write(&from, "source bytes").unwrap(); + fs::write(&to, "existing bytes").unwrap(); + let error = rename_with(None, &from, &to).unwrap_err(); + assert_eq!(error.kind(), io::ErrorKind::Unsupported); + assert!(error.to_string().contains("renameat2 is missing")); + assert_eq!(fs::read_to_string(&from).unwrap(), "source bytes"); + assert_eq!(fs::read_to_string(&to).unwrap(), "existing bytes"); + fs::remove_file(&to).unwrap(); + assert!(rename_with(None, &from, &to).is_err()); + assert!(!to.exists()); + fs::remove_file(&from).unwrap(); + fs::create_dir(&from).unwrap(); + assert!(rename_with(None, &from, &to).is_err()); + assert!(from.is_dir()); + assert!(!to.exists()); + } + + // Linux exposes the same function signature and no-replace flag, allowing + // this dynamic-lookup adapter to be exercised without a FreeBSD runtime. + #[cfg(target_os = "linux")] + #[test] + fn dynamic_api_moves_and_refuses_collisions() { + let tmp = tempfile::tempdir().unwrap(); + let from = tmp.path().join("source"); + let to = tmp.path().join("target"); + fs::write(&from, "source bytes").unwrap(); + fs::write(&to, "existing bytes").unwrap(); + assert_eq!( + rename_no_replace(&from, &to).unwrap_err().kind(), + io::ErrorKind::AlreadyExists + ); + assert_eq!(fs::read_to_string(&to).unwrap(), "existing bytes"); + fs::remove_file(&to).unwrap(); + rename_no_replace(&from, &to).unwrap(); + assert_eq!(fs::read_to_string(&to).unwrap(), "source bytes"); + assert!(!from.exists()); + fs::remove_file(&to).unwrap(); + fs::create_dir(&from).unwrap(); + rename_no_replace(&from, &to).unwrap(); + assert!(to.is_dir()); + assert!(!from.exists()); + } +} diff --git a/crates/ascii-names/src/lib.rs b/crates/ascii-names/src/lib.rs index facbb69..55ff048 100644 --- a/crates/ascii-names/src/lib.rs +++ b/crates/ascii-names/src/lib.rs @@ -12,6 +12,9 @@ use unicode_normalization::{UnicodeNormalization, char::is_combining_mark}; #[cfg(feature = "desktop")] pub mod gui; +#[cfg(any(target_os = "freebsd", all(test, target_os = "linux")))] +mod freebsd; + /// 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 { @@ -296,6 +299,10 @@ fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> { ) .map_err(Into::into) } + #[cfg(target_os = "freebsd")] + { + freebsd::rename_no_replace(from, to) + } #[cfg(target_os = "windows")] { use std::os::windows::ffi::OsStrExt; @@ -311,7 +318,12 @@ fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> { Ok(()) } } - #[cfg(not(any(target_os = "linux", target_vendor = "apple", target_os = "windows")))] + #[cfg(not(any( + target_os = "linux", + target_vendor = "apple", + target_os = "windows", + target_os = "freebsd" + )))] { let _ = (from, to); Err(io::Error::new( @@ -332,15 +344,58 @@ mod tests { let dest = tmp.path().join("dest"); fs::write(&source, "new").unwrap(); fs::write(&dest, "original").unwrap(); - assert!(rename_no_replace(&source, &dest).is_err()); + #[cfg(target_os = "freebsd")] + { + // SAFETY: static C symbol name and the default loaded-library handle. + let symbol = unsafe { libc::dlsym(libc::RTLD_DEFAULT, c"renameat2".as_ptr()) }; + if symbol.is_null() { + let error = rename_no_replace(&source, &dest).unwrap_err(); + assert_eq!(error.kind(), io::ErrorKind::Unsupported); + assert_eq!(fs::read_to_string(&source).unwrap(), "new"); + assert_eq!(fs::read_to_string(&dest).unwrap(), "original"); + return; + } + } + let error = rename_no_replace(&source, &dest).unwrap_err(); + assert_eq!( + error.kind(), + io::ErrorKind::AlreadyExists, + "Expected a destination collision in {}, got: {error}", + tmp.path().display() + ); 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()); + let error = rename_no_replace(&source, &dest).unwrap_err(); + assert_eq!( + error.kind(), + io::ErrorKind::AlreadyExists, + "Expected a destination collision in {}, got: {error}", + tmp.path().display() + ); assert!(source.is_dir()); assert!(dest.is_dir()); + let fresh = tmp.path().join("fresh"); + rename_no_replace(&source, &fresh).unwrap_or_else(|error| { + panic!( + "No-replace directory rename failed in {}: {error}", + tmp.path().display() + ) + }); + assert!(fresh.is_dir()); + assert!(!source.exists()); + fs::write(&source, "new").unwrap(); + let fresh_file = tmp.path().join("fresh-file"); + rename_no_replace(&source, &fresh_file).unwrap_or_else(|error| { + panic!( + "No-replace file rename failed in {}: {error}", + tmp.path().display() + ) + }); + assert_eq!(fs::read_to_string(fresh_file).unwrap(), "new"); + assert!(!source.exists()); } } diff --git a/crates/ascii-names/tests/cleanup.rs b/crates/ascii-names/tests/cleanup.rs index 7a5d911..48d6308 100644 --- a/crates/ascii-names/tests/cleanup.rs +++ b/crates/ascii-names/tests/cleanup.rs @@ -12,6 +12,66 @@ fn options() -> Options { } } +// Older FreeBSD jails have no atomic no-replace API. Exercise their documented +// refusal rather than expecting successful renames or accepting other OS errors. +fn rename_test_dir() -> Option { + let tmp = tempfile::tempdir().unwrap(); + #[cfg(target_os = "freebsd")] + { + // SAFETY: a static C string and the default loaded-library search handle. + let symbol = unsafe { libc::dlsym(libc::RTLD_DEFAULT, c"renameat2".as_ptr()) }; + if symbol.is_null() { + let file = tmp.path().join("été.txt"); + let directory = tmp.path().join("été"); + fs::write(&file, "unchanged").unwrap(); + fs::create_dir(&directory).unwrap(); + let mut messages = Vec::new(); + let summary = clean( + tmp.path(), + options(), + &AtomicBool::new(false), + |_, message| messages.push(message), + ) + .unwrap(); + assert_eq!(summary.errors, 2, "{messages:?}"); + assert_eq!(summary.renamed, 0); + assert_eq!(fs::read_to_string(file).unwrap(), "unchanged"); + assert!(directory.is_dir()); + assert!(!tmp.path().join("ete.txt").exists()); + assert!(!tmp.path().join("ete").exists()); + assert!( + messages + .iter() + .all(|m| m.contains("renameat2 is missing from the jail's libc")), + "{messages:?}" + ); + let output = std::process::Command::new(env!("CARGO_BIN_EXE_ascii-names")) + .arg(tmp.path()) + .args(["--delay-ms", "0"]) + .output() + .unwrap(); + assert!(!output.status.success()); + assert!( + String::from_utf8_lossy(&output.stdout) + .contains("renameat2 is missing from the jail's libc") + ); + assert_eq!( + fs::read_to_string(tmp.path().join("été.txt")).unwrap(), + "unchanged" + ); + assert!(tmp.path().join("été").is_dir()); + // Direct stderr keeps this platform limitation visible in successful CI output. + use std::io::Write; + let _ = writeln!( + std::io::stderr(), + "FreeBSD libc lacks renameat2: verified safe refusal; successful-rename assertions require a supported host." + ); + return None; + } + } + Some(tmp) +} + #[test] fn accents_punctuation_unknowns_and_portable_names() { for (input, expected) in [ @@ -42,7 +102,9 @@ fn accents_punctuation_unknowns_and_portable_names() { #[test] fn nested_cleanup_preserves_all_contents_and_is_idempotent() { - let tmp = tempfile::tempdir().unwrap(); + let Some(tmp) = rename_test_dir() else { + return; + }; 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(); @@ -50,7 +112,10 @@ fn nested_cleanup_preserves_all_contents_and_is_idempotent() { 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(); + let summary = clean(&root, options(), &cancel, |_, message| { + eprintln!("{message}") + }) + .unwrap(); assert_eq!(summary.errors, 0); assert_eq!(summary.renamed, 5); assert_eq!( @@ -65,7 +130,11 @@ fn nested_cleanup_preserves_all_contents_and_is_idempotent() { contents.sort(); assert_eq!(contents, [b"accented".to_vec(), b"another".to_vec()]); assert_eq!( - clean(&root, options(), &cancel, |_, _| {}).unwrap().renamed, + clean(&root, options(), &cancel, |_, message| eprintln!( + "{message}" + )) + .unwrap() + .renamed, 0 ); } @@ -96,13 +165,21 @@ fn preview_reserves_targets_and_changes_nothing() { #[test] fn directory_and_file_collisions_never_merge() { - let tmp = tempfile::tempdir().unwrap(); + let Some(tmp) = rename_test_dir() else { + return; + }; 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(); + let result = clean( + tmp.path(), + options(), + &AtomicBool::new(false), + |_, message| eprintln!("{message}"), + ) + .unwrap(); assert_eq!(result.errors, 0); assert_eq!( fs::read_to_string(tmp.path().join("Ete/original")).unwrap(), @@ -113,7 +190,9 @@ fn directory_and_file_collisions_never_merge() { #[test] fn cancellation_stops_between_renames_and_delay_is_applied() { - let tmp = tempfile::tempdir().unwrap(); + let Some(tmp) = rename_test_dir() else { + return; + }; fs::write(tmp.path().join("é"), "a").unwrap(); fs::write(tmp.path().join("à"), "b").unwrap(); let cancel = AtomicBool::new(false); @@ -125,16 +204,21 @@ fn cancellation_stops_between_renames_and_delay_is_applied() { dry_run: false, }, &cancel, - |_, _| cancel.store(true, std::sync::atomic::Ordering::Relaxed), + |_, message| { + eprintln!("{message}"); + 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 + clean(tmp.path(), options(), &cancel, |_, message| eprintln!( + "{message}" + )) + .unwrap() + .cancelled ); } @@ -143,9 +227,19 @@ 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()); + assert!( + clean(&file, options(), &cancel, |_, message| eprintln!( + "{message}" + )) + .is_err() + ); fs::write(&file, "x").unwrap(); - assert!(clean(&file, options(), &cancel, |_, _| {}).is_err()); + assert!( + clean(&file, options(), &cancel, |_, message| eprintln!( + "{message}" + )) + .is_err() + ); } #[cfg(unix)] @@ -155,7 +249,9 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() { ffi::OsString, os::unix::{ffi::OsStringExt, fs::symlink}, }; - let tmp = tempfile::tempdir().unwrap(); + let Some(tmp) = rename_test_dir() else { + return; + }; let outside = tempfile::tempdir().unwrap(); fs::write(outside.path().join("é.txt"), "outside").unwrap(); symlink(outside.path(), tmp.path().join("lïnk")).unwrap(); @@ -166,7 +262,13 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() { "bytes", ) .unwrap(); - let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap(); + let result = clean( + tmp.path(), + options(), + &AtomicBool::new(false), + |_, message| eprintln!("{message}"), + ) + .unwrap(); assert_eq!(result.skipped, 2); assert_eq!(result.errors, 0); assert!(outside.path().join("é.txt").exists()); @@ -183,7 +285,7 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() { &tmp.path().join("lïnk"), options(), &AtomicBool::new(false), - |_, _| {} + |_, message| eprintln!("{message}") ) .is_err() ); @@ -191,7 +293,9 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() { #[test] fn cli_preview_and_apply() { - let tmp = tempfile::tempdir().unwrap(); + let Some(tmp) = rename_test_dir() else { + return; + }; fs::write(tmp.path().join("été.txt"), "content").unwrap(); let bin = env!("CARGO_BIN_EXE_ascii-names"); let output = std::process::Command::new(bin) @@ -199,16 +303,25 @@ fn cli_preview_and_apply() { .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() + output.status.success(), + "status: {}; stdout: {}; stderr: {}", + output.status, + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); + assert!(tmp.path().join("été.txt").exists()); + let output = std::process::Command::new(bin) + .arg(tmp.path()) + .args(["--delay-ms", "0"]) + .output() + .unwrap(); + assert!( + output.status.success(), + "status: {}; stdout: {}; stderr: {}", + output.status, + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) ); assert_eq!( fs::read_to_string(tmp.path().join("ete.txt")).unwrap(), @@ -226,7 +339,9 @@ fn cli_preview_and_apply() { #[test] fn many_names_with_same_fallback_keep_every_file() { - let tmp = tempfile::tempdir().unwrap(); + let Some(tmp) = rename_test_dir() else { + return; + }; for (index, character) in (0x4e00..0x4e80).filter_map(char::from_u32).enumerate() { fs::write( tmp.path().join(format!("{character}.txt")), @@ -234,7 +349,13 @@ fn many_names_with_same_fallback_keep_every_file() { ) .unwrap(); } - let summary = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap(); + let summary = clean( + tmp.path(), + options(), + &AtomicBool::new(false), + |_, message| eprintln!("{message}"), + ) + .unwrap(); assert_eq!(summary.renamed, 128); assert_eq!(summary.errors, 0); let values: std::collections::HashSet<_> = fs::read_dir(tmp.path()) diff --git a/docs/ascii-names.md b/docs/ascii-names.md index e267917..fe0b63e 100644 --- a/docs/ascii-names.md +++ b/docs/ascii-names.md @@ -70,3 +70,21 @@ 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. + +### FreeBSD CI hosts + +FreeBSD uses `renameat2` with `AT_RENAME_NOREPLACE` when available. The symbol is +resolved at runtime, so older jail userlands (including FreeBSD 12) can still +build, launch and preview. Actual cleanup on those systems returns an actionable +unsupported-operation error without renaming anything. No overwriting fallback +is used. The kernel, jail userland and filesystem must all support the operation. +See the [FreeBSD API documentation change](https://lists.freebsd.org/archives/dev-commits-src-branches/2026-March/028297.html). + +On a FreeBSD jail whose libc lacks `renameat2`, the rename integration tests +verify safe refusal and unchanged sources instead of executing their successful +rename assertions; this limitation is printed in CI output. Preview and name +conversion tests still run normally. Hosts exposing the API run the full rename +tests; unexpected filesystem/permission/kernel errors still fail them. Successful +renames and collision protection must also be tested on a supported host (Linux, +macOS, Windows, or a FreeBSD installation with the API). Jenkins prints its OS +version, and failing tests retain the underlying rename errors and CLI output. diff --git a/docs/ci.md b/docs/ci.md index 5c68767..06f6d08 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -2,6 +2,10 @@ Jenkins must use a Multibranch Pipeline supplying `BRANCH_NAME`, with the `rust_no_docker` worker, Python 3.11+ and Rust. +The current worker runs in a FreeBSD jail; the Tools stage logs `uname -sr`. +Older jails without `renameat2` verify the ASCII cleaner's safe refusal instead +of its successful-rename paths. Those paths must also run on a supported host; +see [FreeBSD test coverage](ascii-names.md#freebsd-ci-hosts). SCM credentials, webhooks and the publication mount are administrator setup. CI checks formatting, Clippy, rustdoc, Python/Rust tests and whole-workspace Rust coverage. It never creates tags or release artifacts.